Metadata-Version: 2.4
Name: fips203
Version: 0.5.0
Summary: ML-KEM (FIPS203) -- asymmetric, quantum-secure encryption
Author-email: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
Project-URL: Homepage, https://github.com/integritychain/fips203/tree/main/ffi/python
Project-URL: Repository, https://github.com/integritychain/fips203.git
Project-URL: Issues, https://github.com/integritychain/fips203/issues
Keywords: cryptography,encryption,FIPS,FIPS203,KEM,lattice,module-lattice,post-quantum
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security :: Cryptography
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: DFSG approved
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# `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
