Metadata-Version: 2.4
Name: fips204
Version: 0.5.0
Summary: ML-DSA (FIPS204) -- asymmetric, quantum-secure digital signatures
Author-email: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/integritychain/fips204/tree/main/ffi/python
Project-URL: Repository, https://github.com/integritychain/fips204.git
Project-URL: Issues, https://github.com/integritychain/fips204/issues
Keywords: cryptography,signing,FIPS,FIPS204,DSA,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: 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

# `fips204` Python module

This Python module provides an implementation of FIPS 204, the
Module-Lattice-based Digital Signature Standard.

The underlying mechanism is intended to offer "post-quantum"
data integrity, authenticity, and non-repudiation.

## Example

The following example shows using the standard ML-DSA algorithm to
sign a message:

```
from fips204 import ML_DSA_65

(public_key, private_key) = ML_DSA_65.keygen()
message = b"this is a test"
context = b""
sig = private_key.sign(message, context)
assert(public_key.verify(sig, message, context))
```

Key generation can also be done deterministically, by passing a
`SEED_SIZE`-byte seed to `keygen`:

```
from fips204 import ML_DSA_65, Seed

seed1 = Seed()  # Generate a random seed
(pub, priv) = ML_DSA_65.keygen(seed1)

seed2 = Seed(b'\x00'*ML_DSA_65.SEED_SIZE)  # This seed is clearly not a secret!
(pub, priv) = ML_DSA_65.keygen(seed2)
```

public keys, private keys, and seeds can all
be serialized by accessing them as `bytes`, and deserialized by
initializing them with the appropriate size bytes object.

A signature itself is already just a bytes object.

A serialization example:

```
from fips204 import ML_DSA_65, Seed

seed = Seed()
(pub,priv) = ML_DSA_65.keygen(seed)
with open('pub.bin', 'wb') as f:
    f.write(bytes(pub))
with open('priv.bin', 'wb') as f:
    f.write(bytes(priv))
with open('seed.bin', 'wb') as f:
    f.write(bytes(seed))
```

A deserialization example, followed by use:

```
import fips204

with open('priv.bin', 'rb') as f:
    privdata = f.read()

context = b'abc'
priv = fips204.PrivateKey(privdata)
with open('msg', 'rb') as m:
    with open ('msg.sig', 'wb') as s:
        s.write(priv.sign(m.read(), context))
```

The expected sizes (in bytes) of the different objects in each
parameter set can be accessed with `PUBKEY_SIZE`, `PRIVKEY_SIZE`, `SIG_SIZE`,
`SEED_SIZE`:

```
from fips204 import ML_DSA_65

print(f"ML-DSA-65 Signature size (in bytes) is {ML_DSA_65.SIG_SIZE}")
```

## Implementation Notes

This is a wrapper around libfips204, built from the Rust fips204-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
`FIPS204_PYTHON_TESTING_LIBRARY` to the built `libfips204.so` (`libfips204.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 `FIPS204_PYTHON_TESTING_LIBRARY`.

The NIST tests under `test/` read vectors from `../../tests/nist_vectors` in a source checkout,
or from the directory named by `FIPS204_NIST_VECTORS`. The published `fips204` 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.204
- https://github.com/integritychain/fips204

## Bug Reporting

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