fips203 Python module

This Python module provides an implementation of FIPS 203, the Module-Lattice-based Key Encapsulation Mechanism Standard.

The underlying mechanism is intended to offer "post-quantum" key establishment.

Example

The following example shows using the standard ML-KEM algorithm to produce identical 32-byte shared secrets:

from fips203 import ML_KEM_512

(encapsulation_key, decapsulation_key) = ML_KEM_512.keygen()
(ciphertext, shared_secret_1) = encapsulation_key.encaps()
shared_secret_2 = decapsulation_key.decaps(ciphertext)
assert(shared_secret_1 == shared_secret_2)

Key generation can also be done deterministically, by passing a SEED_SIZE-byte seed (the concatenation of d and z) to keygen:

from fips203 import ML_KEM_512, Seed

seed1 = Seed()  # Generate a random seed
(ek1, dk1) = ML_KEM_512.keygen(seed1)

seed2 = Seed(b'\x00'*ML_KEM_512.SEED_SIZE)  # This seed is clearly not a secret!
(ek2, dk2) = ML_KEM_512.keygen(seed2)

Encapsulation keys, decapsulation keys, seeds, and ciphertexts can all be serialized by accessing them as bytes, and deserialized by initializing them with the appropriate size bytes object.

A serialization example:

from fips203 import ML_KEM_768, Seed

seed = Seed()
(ek,dk) = ML_KEM_768.keygen(seed)
with open('encapskey.bin', 'wb') as f:
    f.write(bytes(ek))
with open('decapskey.bin', 'wb') as f:
    f.write(bytes(dk))
with open('seed.bin', 'wb') as f:
    f.write(bytes(seed))

A deserialization example, followed by use:

import fips203

with open('encapskey.bin', 'rb') as f:
    ekdata = f.read()

ek = fips203.EncapsulationKey(ekdata)
(ct, ss) = ek.encaps()

The expected sizes (in bytes) of the different objects in each parameter set can be accessed with EK_SIZE, DK_SIZE, CT_SIZE, SEED_SIZE, and SS_SIZE:

from fips203 import ML_KEM_768

print(f"ML-KEM-768 Ciphertext size (in bytes) is {ML_KEM_768.CT_SIZE}")

Implementation Notes

This is a wrapper around libfips203, built from the Rust fips203-ffi crate.

If that library is not installed in the expected path for libraries on your system, importing this module will fail. For in-tree tests, set FIPS203_PYTHON_TESTING_LIBRARY to the built libfips203.so (libfips203.dylib on macOS). On macOS, Python searches DYLD_LIBRARY_PATH, then ~/lib, /usr/local/lib, /lib and /usr/lib, so a library installed elsewhere, such as MacPorts' /opt/local/lib or Homebrew's /opt/homebrew/lib, also needs FIPS203_PYTHON_TESTING_LIBRARY.

The NIST tests under test/ read vectors from ../../tests/nist_vectors in a source checkout, or from the directory named by FIPS203_NIST_VECTORS. The published fips203 crate includes the keyGen vectors, under tests/nist_vectors/.

This module should have reasonable type annotations and docstrings for the public interface. If you discover a problem with type annotations, or see a way that this kind of documentation could be improved, please report it!

See Also

• https://doi.org/10.6028/NIST.FIPS.203
• https://github.com/integritychain/fips203

Bug Reporting

Please report issues at https://github.com/integritychain/fips203/issues