VernamVeil Class

class vernamveil.VernamVeil(fx, chunk_size=32, delimiter_size=8, padding_range=(5, 15), decoy_ratio=0.1, siv_seed_initialisation=True, auth_encrypt=True, hash_name='blake2b')

Bases: _Cypher

VernamVeil is a modular, symmetric stream cypher.

Inspired by One-Time Pad principles, it features customisable keystream generation, synthetic IV seed initialisation, stateful seed evolution for avalanche effects, authenticated encryption, and layered message obfuscation (chunk shuffling, padding, decoy injection). Supports vectorised operations (NumPy) and optional C-backed hashing for performance. Designed for educational and experimental use.

Initialise the VernamVeil encryption cypher with configurable parameters.

Parameters:

  • fx (FX) – A callable object that generates keystream bytes. This function is critical for the encryption process and should be carefully designed to ensure cryptographic security.

  • chunk_size (int) – Size of message chunks. Defaults to 32.

  • delimiter_size (int) – The delimiter size in bytes used for separating chunks; must be at least 4. Defaults to 8.

  • padding_range (tuple[int, int]) – Range for padding length before and after chunks. Defaults to (5, 15).

  • decoy_ratio (float) – Proportion of decoy chunks to insert. Must not be negative. Defaults to 0.1.

  • siv_seed_initialisation (bool) – Enables synthetic IV seed initialisation based on the message to resist seed reuse. Defaults to True.

  • auth_encrypt (bool) – Enables authenticated encryption with integrity check. Defaults to True.

  • hash_name (Literal["blake2b", "blake3", "sha256"]) – Hash function to use (“blake2b”, “blake3” or “sha256”) for keyed hashing and HMAC. The blake3 is only available if the C extension is installed. Defaults to “blake2b”.

Raises:

  • ValueError – If chunk_size is less than 8.

  • ValueError – If delimiter_size is less than 4.

  • TypeError – If padding_range is not a tuple of two integers.

  • ValueError – If padding_range values are negative.

  • ValueError – If padding_range values are not in ascending order.

  • ValueError – If decoy_ratio is negative.

  • ValueError – If hash_name is not “blake2b”, “blake3” or “sha256”.

decode(cyphertext, seed)

Decrypt an encoded message.

Return type:

tuple[memoryview, bytes | bytearray]

Parameters:

  • cyphertext (bytes or bytearray or memoryview) – Encrypted and obfuscated message.

  • seed (bytes or bytearray) – Initial seed for decryption.

Returns:

Decrypted message and final seed.

Return type:

tuple[memoryview, bytes or bytearray]

Raises:

ValueError – If the authentication tag does not match.

encode(message, seed)

Encrypt a message.

Return type:

tuple[memoryview, bytes | bytearray]

Parameters:

  • message (bytes or bytearray or memoryview) – Message to encode.

  • seed (bytes or bytearray) – Initial seed for encryption.

Returns:

Encrypted message and final seed.

Return type:

tuple[memoryview, bytes or bytearray]

Raises:

ValueError – If the delimiter appears in the message.

classmethod get_initial_seed(num_bytes=64)

Generate a cryptographically secure initial random seed.

This method uses the secrets module to generate a random sequence of bytes suitable for cryptographic use. It returns a byte string of the specified length.

Return type:

bytes

Parameters:

num_bytes (int) – The number of bytes to generate for the seed. Defaults to 64 bytes if not provided.

Returns:

A random byte string of the specified length.

Return type:

bytes

Raises:

  • TypeError – If num_bytes is not an integer.

  • ValueError – If num_bytes is not a positive integer.

process_file(mode, input_file, output_file, seed, buffer_size=1048576, read_queue_size=4, write_queue_size=4, progress_callback=None)

Processes a file or stream in blocks using the provided Cypher for encryption or decryption.

Return type:

None

Parameters:

  • mode (Literal["encode", "decode"]) – Operation mode (“encode” for encryption, “decode” for decryption).

  • input_file (str or Path or IO[bytes]) – Path or file-like object for input.

  • output_file (str or Path or IO[bytes]) – Path or file-like object for output.

  • seed (bytes) – Initial seed for processing.

  • buffer_size (int) – Bytes to read at a time. Defaults to 1024 * 1024 (1MB).

  • read_queue_size (int) – Maximum number of data blocks buffered in the queue between the IO reader thread and the main processing thread. Defaults to 4.

  • write_queue_size (int) – Maximum number of data blocks buffered in the queue between the main processing thread and the IO writer thread. Defaults to 4.

  • progress_callback (Callable, optional) – Callback for progress reporting. Receives two arguments: bytes_processed and total_size. Defaults to None.

Raises:

  • ValueError – If mode is not “encode” or “decode”.

  • TypeError – If buffer_size, read_queue_size, or write_queue_size is not an integer.

  • ValueError – If buffer_size, read_queue_size, or write_queue_size is not a positive integer.

  • exception – If an unexpected error occurs in the reader or writer threads.