Streams

Streams classes are used for managing test vectors, their generation, saving, and loading.

Streams are identified by type in CryptoStreams configuration file. Every stream has to be inherited from abstract stream interface and provide implementation at least to method next() and osize(). Streams may be encapsulated to other streams, such as "plaintext generator" stream or post-processed by output modification stream.

The generalization of data generation allows higher customizability and code reduction due to re-usage of commonly used streams (like counter plaintext).

Cryptographical function streams

Specific streams are dedicated to cryptographical primitives as block ciphers, stream ciphers, and hash functions. These streams are described in dedicated pages.

• Block ciphers with config keyword block.
• Stream ciphers with config keyword stream-cipher.
• Hash functions with config keyword hash.
• PRNGs with config keyword prng
• CAESAR competition candidates are currently not supported.

Streams for generation of the input (keys, plaintexts...)

Trivial streams

• dummy_stream: a stream that does nothing. It is controlled externally using set_data(vec_cview data) function.
• tuple_stream: a stream consisting of multiple streams printed in given order. The internal streams are defined as JSON array in argument sources ("sources":[{source1},{source2}...]).

Source only streams

• file_stream: contains path to file, which is read as input.
• true_stream and false_stream: generate vectors of ones, zeros respectively.
• const_stream provides a given vector from the hex-coded config {"value":"f0f1f2f3"} on the output
• mt19937_stream and pcg32-stream: PRNG Mersenne Twister MT19937-64, PCG (faster and more statistically random, preferred)

Types of plaintext (also only sources)

• counter: generates increasing numbers. The first generated number vector is 1 (zero is omitted).
• random_start_counter: same as counter, but starts with random initial value.
• sac (Strict avalanche criterion): generates firstly random vector (source is PCG32); secondly the copy of the first vector with exactly one bit flipped. The position of the flipped bit is random.
• sac_fixed_position: similar to SAC, but the position of bit flip is given by argument position (requires number).
• sac_2d_all_positions: the first vector is random and then follows (size * 8) - 1 copies of the original vector, with one bit flipped per copy.
• hw_counter: generates all vectors with given hamming weight.
  • hw (unsigned) sets-up target hamming weight.
  • increase_hw (Boolean) allows increase after generating all possible vectors (the number of vectors of length l with hamming weight at most h is (l over h).
  • randomize_overflow (Boolean) generates a new base random vector (from which is counted the target hamming weight) after generating all possible combinations.
  • randomize_start (Boolean). If set, randomly generates the underlying mask which is XORer with the HW coutner on each next() call. False by default, thus the mask is zeros. The randomize_start enables generate different sequences with fixed hamming distance from the origin block.
  • initial_state (array of integers). If set, specifies initial counter state. Has length of the Hamming weight, specifies indices of the enabled bits.
    • Helps with generating various different sequences with low hamming weight. User can control the starting offset and thus partition the combination space precisely.
    • It forms strictly increasing sequence, with minimum index 0 and maximum index (size * 8 - 1).
    • Initial state for HW4 is [0, 1, 2, 3].
    • Example: the HW4 on size=2 goes from state [0, 13, 14, 15] to [1, 2, 3, 4]

Sources with a statistical distribution

• bernoulli_distribution biased stream, that generates a binary vector, where "0" has probability given by argument p.
• binomial_distribution outputs vector of the binomial distribution. How many "1" flipped on a coin with p probability and max_value trials?
• normal_distribution similar to binomial_distribution using normal distribution with mean and std_dev arguments. The generated real value is cut to 4 sigmas and this value is projected to the byte value.
• poisson_distribution Poisson distribution has an argument mean. If an event occurs mean times a minute on average, how often is it that it occurs N times in one minute? Output N
• exponential_distribution with argument lambda. If particles decay lambda times per second on average, how much time, in seconds, until the next one?

Pipes

• pipe_in_stream: the beginning of the pipe - passes data from the source via next() and allows the other end of pipe to read these data. Identification is by string in argument id. The source id has to be unique, else the behavior is undefined.
• pipe_out_stream: the end of pipe - copies data from the pipe source. Identified by id, there can be multiple pipe_out_streams with same id. The id of pipe output has to fit some input, else the behavior is undefined.

Modifiers streams

These stream modifiers always contain inner JSON subtree with usually some cipher.

Modifiers used as cryptoprimitive's input

• single_value_stream: passes repeatedly same value. Initialized by the internal stream. Useful for repeating passing single value of other random streams.
• repeating_stream: repeats the same vector for period of calls.

Cryptoprimitives' postprocessing streams

• xor_stream: splits the input into two halves and XOR these two parts. Fits for checking sac and rnd_plt_ctx_stream.
• column: the ciphertext is transposed, and vectors are created from the ith bit of the ciphertext for i in range size.
• column_fixed_position: every vector is created from the positionth bit of the ciphertext. The position is a number argument in interval (0, size-1).