ML-KEM#

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

Test encapsulation#

crypto_condor.primitives.MLKEM.test_encaps(encaps, paramset)#

Tests encapsulation.

ML-KEM encapsulation is not deterministic: it generates a random shared secret and encapsulates it using the peer’s public key, so crypto-condor cannot simply compare the ciphertext returned by the implementation with the test vector’s ciphertext. Instead, it calls the encaps method to generate a shared secret and ciphertext, decapsulates the ciphertext with its internal decapsulation function, and compares the resulting shared secret with the one returned by the implementation. The test passes if the secrets match.

Attention

crypto-condor uses the reference C implementation of ML-KEM, which is bundled with the package but has to be compiled and installed locally. This is done automatically when the internal implementation is needed, but if the compilation fails this test cannot be run. Please report problems by opening an issue.

Parameters:

  • encaps (Encaps) – The encapsulation implementation.

  • paramset (Paramset) – The parameter set to test.

Returns:

A dictionary of results. It is empty if the internal decapsulation failed to run, or the implementation raised NotImplementedError.

Return type:

ResultsDict

crypto_condor.primitives.MLKEM.test_output_encaps(output, paramset)#

Tests output of encapsulation.

To test the output of ML-KEM Encaps(), the secret key is used to decapsulate the ciphertext and compare the shared secrets.

Parameters:

  • output (Path) – A path to the output file.

  • paramset (Paramset) – The parameter set of the output.

Returns:

A dictionary of results.

Return type:

ResultsDict

Format:

  • One line per hashing operation, separated by newlines \n.

  • Lines starting with # are considered comments and ignored.

  • Values are written in hexadecimal.

  • Values are separated by forward slashes /.

  • The order of the values is:

pk/sk/ct/ss
  • Where:

    • pk is the public encapsulation key.

    • sk is the secret decapsulation key.

    • ct is the ciphertext.

    • ss is the shared secret.

Test decapsulation#

crypto_condor.primitives.MLKEM.test_decaps(decaps, paramset)#

Tests decapsulation.

Uses the given function to decapsulate ciphertexts and compares the results with the test vectors’ shared secrets. The test passes if the secrets match.

Parameters:

  • decaps (Decaps) – The decapsulation implementation.

  • paramset (Paramset) – The parameter set to test.

Returns:

A dictionary of results. It is empty if the internal decapsulation failed to run, or the implementation raised NotImplementedError.

Return type:

ResultsDict

Parameters#

enum crypto_condor.primitives.MLKEM.Paramset(value)#

The parameter sets for ML-KEM.

Member Type:

str

Valid values are as follows:

MLKEM512 = <Paramset.MLKEM512: 'ML-KEM-512'>#
MLKEM768 = <Paramset.MLKEM768: 'ML-KEM-768'>#
MLKEM1024 = <Paramset.MLKEM1024: 'ML-KEM-1024'>#

The Enum and its members also have the following methods:

property sk_size#

The secret key size of the parameter set in bytes.

property pk_size#

The public key size of the parameter set in bytes.

property ct_size#

The ciphertext size of the parameter set in bytes.

Protocols#

protocol crypto_condor.primitives.MLKEM.Encaps#

Represents an ML-KEM encapsulation function.

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

__call__(pk)#

Generates and encapsulates a shared secret.

Parameters:

pk (bytes) – The public key to encapsulate the secret with.

Returns:

A tuple (ct, ss) containing the shared secret (ss) and ciphertext (ct).

Return type:

tuple[bytes, bytes]

protocol crypto_condor.primitives.MLKEM.Decaps#

Represents an ML-KEM decapsulation function.

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

__call__(sk, ct)#

Decapsulates a shared secret.

Parameters:

  • sk (bytes) – The secret key to use.

  • ct (bytes) – The ciphertext to decapsulate.

Returns:

The decapsulated shared secret.

Return type:

bytes

Test vectors#

The following section describes the internal test vectors classes, which are protobuf Python classes.

Hint

The autodoc extension can’t properly document these clases so we include the .proto file to show the different fields each class has. IDEs should be able to use the included .pyi files to provide auto-completion and type checking.

class crypto_condor.primitives.MLKEM.MlkemVectors#

Protobuf class that stores test vectors. See the description below.

syntax = "proto3";

package crypto_condor;

// A single ML-KEM test vector. Can be used for testing encapsulation (uses pk, sk, ct,
// and ss) or decapsulation (uses sk, ct, and ss).
message MlkemTest {
	// The test ID, unique in its set of vectors.
	int32 id = 1;
	// The type of test. One of: valid, invalid, acceptable.
	string type = 2;
	// A comment on the test.
	string comment = 3;
	// Flags that categorize this test.
	repeated string flags = 4;

	// The public (encapsulation) key.
	bytes pk = 5;
	// The secret (decapsulation) key.
	bytes sk = 6;
	// The ciphertext resulting from ML-KEM.Encaps().
	bytes ct = 7;
	// The shared secret resulting from ML-KEM.Encaps().
	bytes ss = 8;
}

// A set of ML-KEM test vectors.
message MlkemVectors {
	// The source of the test vectors.
	string source = 1;
	// Description of the source.
	string source_desc = 2;
	// The URL of the source.
	string source_url = 3;
	// Whether these are compliance test vectors or not.
	bool compliance = 4;
	// A dictionary of test flags and their description.
    map<string, string> notes = 5;

	// The ML-KEM parameter set.
	string paramset = 6;
	// The test vectors.
	repeated MlkemTest tests = 7;
}