ChaCha20¶

How to use the crypto_condor.primitives.ChaCha20 module to test implementations of ChaCha20.

Test ChaCha20¶

crypto_condor.primitives.ChaCha20.test_encrypt(encrypt, compliance, resilience)¶

Tests a function that encrypts with ChaCha20.

Calls encrypt to encrypt messages with valid keys and nonces. The test passes if all resulting ciphertexts match the test vectors’.

Parameters:

encrypt (Encrypt) – The function to test.
compliance (bool) – Whether to use compliance test vectors.
resilience (bool) – Whether to use resilience test vectors.

Returns:

A dictionary of results, with a single Results per test vectors file.

Return type:

ResultsDict

crypto_condor.primitives.ChaCha20.test_decrypt(decrypt, compliance, resilience)¶

Tests a function that decrypts with ChaCha20.

Calls decrypt to decrypt ciphertexts with valid keys and nonces. The test passes if all messages are correctly decrypted.

Parameters:

decrypt (Decrypt) – The function to test.
compliance (bool) – Whether to use compliance test vectors.
resilience (bool) – Whether to use resilience test vectors.

Returns:

A dictionary of results, with a single Results per test vectors file.

Return type:

ResultsDict

crypto_condor.primitives.ChaCha20.test_output_encrypt(output)¶

Tests the output of ChaCha20 encryption.

Reads operations from a plaintext file, uses the inputs with an internal implementation of ChaCha20 encryption, and compares the outputs to see if they match.

Parsing errors are considered as test failures.

Parameters:: output (Path) – The plaintext file to read.
Returns:: A dictionary of results, containing one Results. If the file does not exist or reading from it failed, the dictionary will be empty.
Return type:: ResultsDict

Note

The format is as follows:

One line per operation.
Lines are separated by newlines.
Lines that start with # are counted as comments and ignored.
Arguments are written in hexadecimal, except init_counter which is interpreted as an int.
Arguments are separated by slashes, no spaces.
Arguments in brackets are optional. If omitted, do not include the trailing slash.
The order of arguments is:

key / plaintext / ciphertext / nonce [/init_counter]
The arguments are:
- key is the symmetric key.
- plaintext is the input plaintext.
- ciphertext is the output ciphertext.
- nonce is the nonce used.
- init_counter is the optional initial position in the keystream to seek before encrypting. The value is in bytes.

crypto_condor.primitives.ChaCha20.test_output_decrypt(output)¶

Tests the output of ChaCha20 encryption.

Reads operations from a plaintext file, uses the inputs with an internal implementation of ChaCha20 decryption, and compares the outputs to see if they match.

Parsing errors are considered as test failures.

Parameters:: output (Path) – The plaintext file to read.
Returns:: A dictionary of results, containing one Results. If the file does not exist or reading from it failed, the dictionary will be empty.
Return type:: ResultsDict

Note

The format is as follows:

One line per operation.
Lines are separated by newlines.
Lines that start with # are counted as comments and ignored.
Arguments are written in hexadecimal, except init_counter which is interpreted as an int.
Arguments are separated by slashes, no spaces.
Arguments in brackets are optional. If omitted, do not include the trailing slash.
The order of arguments is:

key / ciphertext / plaintext / nonce [/init_counter]
The arguments are:
- key is the symmetric key.
- ciphertext is the input ciphertext.
- plaintext is the output plaintext.
- nonce is the nonce used.
- init_counter is the optional initial position in the keystream to seek before encrypting. The value is in bytes.

Test ChaCha20-Poly1305¶

crypto_condor.primitives.ChaCha20.test_encrypt_poly(encrypt, compliance, resilience)¶

Tests a function that encrypts with ChaCha20-Poly1305.

Calls encrypt to encrypt messages. The resulting ciphertext and tag are compared to those in the test vectors. The test passes if all values match.

Implementations must follow EncryptPoly and are expected to check that the inputs, notably the nonce, are the correct size, or raise ValueError if not. All other exceptions are marked as failures.

Parameters:

encrypt (EncryptPoly) – The function to test.
compliance (bool) – Whether to use compliance test vectors.
resilience (bool) – Whether to use resilience test vectors.

Returns:

A dictionary of results, with a single Results per test vectors file.

Return type:

ResultsDict

crypto_condor.primitives.ChaCha20.test_decrypt_poly(decrypt, compliance, resilience)¶

Tests a function that decrypts with ChaCha20-Poly1305.

Calls decrypt to decrypt ciphertexts with their authentication tags. Resilience test vectors contain invalid values: both invalid nonces and invalid tags. Implementations must follow DecryptPoly and raise ValueError if needed. The test passes if all valid ciphertexts are correctly decrypted, and all invalid tests are rejected.

Parameters:

decrypt (DecryptPoly) – The function to test.
compliance (bool) – Whether to use compliance test vectors.
resilience (bool) – Whether to use resilience test vectors.

Returns:

A dictionary of results, with a single Results per test vectors file.

Return type:

ResultsDict

crypto_condor.primitives.ChaCha20.test_output_encrypt_poly(output)¶

Tests the output of ChaCha20-Poly1305 encryption.

Reads operations from a plaintext file, uses the inputs with an internal implementation of ChaCha20-Poly1305 encryption, and compares the outputs to see if they match.

Parsing errors are considered as test failures.

Parameters:: output (Path) – The plaintext file to read.
Returns:: A dictionary of results, containing one Results. If the file does not exist or reading from it failed, the dictionary will be empty.
Return type:: ResultsDict

Note

The format is as follows:

One line per operation.
Lines are separated by newlines.
Lines that start with # are counted as comments and ignored.
Arguments are written in hexadecimal, except init_counter which is interpreted as an int.
Arguments are separated by slashes, no spaces.
Arguments in brackets are optional. If omitted, do not include the trailing slash.
The order of arguments is:

key / plaintext / ciphertext / nonce / tag [/ aad]
The arguments are:
- key is the symmetric key.
- plaintext is the input plaintext.
- ciphertext is the output ciphertext.
- nonce is the nonce used.
- tag is the MAC tag.
- aad is the optional additional data.

crypto_condor.primitives.ChaCha20.test_output_decrypt_poly(output)¶

Tests the output of ChaCha20-Poly1305 decryption.

Reads operations from a plaintext file, uses the inputs with an internal implementation of ChaCha20-Poly1305 decryption, and compares the outputs to see if they match.

Parsing errors are considered as test failures.

Parameters:: output (Path) – The plaintext file to read.
Returns:: A dictionary of results, containing one Results. If the file does not exist or reading from it failed, the dictionary will be empty.
Return type:: ResultsDict

Note

The format is as follows:

One line per operation.
Lines are separated by newlines.
Lines that start with # are counted as comments and ignored.
Arguments are written in hexadecimal, except init_counter which is interpreted as an int.
Arguments are separated by slashes, no spaces.
Arguments in brackets are optional. If omitted, do not include the trailing slash.
The order of arguments is:

key / ciphertext / plaintext / nonce / tag [/ aad]
The arguments are:
- key is the symmetric key.
- ciphertext is the output ciphertext.
- plaintext is the input plaintext.
- nonce is the nonce used.
- tag is the MAC tag.
- aad is the optional additional data.

Protocols¶

protocol crypto_condor.primitives.ChaCha20.Encrypt¶

Represents a function that encrypts with ChaCha20.

Classes that implement this protocol must have the following methods / attributes:

__call__(key, pt, nonce, init_counter=0)¶

Encrypts with ChaCha20.

Parameters:

key (bytes) – The symmetric key.
pt (bytes) – The plaintext to encrypt.
nonce (bytes) – The nonce.
init_counter (int) – A position to seek in the keystream before encrypting, in bytes.

Returns:

The ciphertext.

Return type:

bytes

protocol crypto_condor.primitives.ChaCha20.Decrypt¶

Represents a function that decrypts with ChaCha20.

Classes that implement this protocol must have the following methods / attributes:

__call__(key, ct, nonce, init_counter=0)¶

Decrypts with ChaCha20.

Parameters:

key (bytes) – The symmetric key.
ct (bytes) – The ciphertext to decrypt.
nonce (bytes) – The nonce.

Keyword Arguments:

init_counter – A position to seek in the keystream before encrypting, in bytes.

Returns:

The plaintext.

Return type:

bytes

protocol crypto_condor.primitives.ChaCha20.EncryptPoly¶

Represents a function that encrypts with ChaCha20-Poly1305.

Classes that implement this protocol must have the following methods / attributes:

__call__(key, pt, nonce, aad)¶

Encrypts with ChaCha20-Poly1305.

Parameters:

key (bytes) – The symmetric key.
pt (bytes) – The plaintext to encrypt.
nonce (bytes) – The nonce.
aad (bytes) – The associated data.

Returns:

A tuple containing the ciphertext and the MAC tag.

Raises:

ValueError – If an input is incorrect (e.g. the nonce size is invalid).

Return type:

tuple[bytes, bytes]

protocol crypto_condor.primitives.ChaCha20.DecryptPoly¶

Represents a function that decrypts with ChaCha20-Poly1305.

Classes that implement this protocol must have the following methods / attributes:

__call__(key, ct, nonce, tag, aad)¶

Decrypts with ChaCha20-Poly1305.

Parameters:

key (bytes) – The symmetric key.
ct (bytes) – The ciphertext to decrypt.
nonce (bytes) – The 12-byte nonce.
tag (bytes) – The MAC tag.
aad (bytes) – The associated data.

Returns:

The decrypted plaintext.

Raises:

ValueError – If an input is incorrect (e.g. the nonce size is not 12 bytes) or if the MAC verification failed.

Return type:

bytes | None