Metadata-Version: 2.4
Name: fips-collection
Version: 1.0.0
Summary: Educational implementations of NIST FIPS cryptographic standard.
Author: Aditya Pratap Singh
License-Expression: MIT
Project-URL: Homepage, https://github.com/kyuuaditya/fips-collection-python
Project-URL: Documentation, https://kyuuaditya.github.io/fips-collection-python/
Project-URL: Repository, https://github.com/kyuuaditya/fips-collection-python
Keywords: cryptography,fips,nist,ml-dsa,mldsa,post-quantum,pqc
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

[![License MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://github.com/kyuuaditya/fips-collection-python/blob/main/LICENSE)

# FIPS Standards Implementations

> [!CAUTION]
> :warning: **Under no circumstances should this be used for cryptographic
applications.** :warning:
>
> This is an educational resource and has not been designed to be secure against any form of side-channel attack. The intended use of this project is for learning and experimenting with FIPS Algorithms.

This repository contains a **python** implementation of:

1. **ML-DSA** the NIST Module-Lattice-Based Digital Signature Standard following
   the [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final).

## Licenses

This project is licensed under the [License MIT](https://github.com/kyuuaditya/fips-collection-python/blob/main/LICENSE).

## Disclaimer

This implementation follows instructions given in FIPS 204 as it is for all algorithms.

With sole exception of Algorithm 43 BitRev as zeta values are precomputed and hardcoded.

## Documentation

Complete documentation of this repository is available at https://kyuuaditya.github.io/fips-collection-python/

## Using fips

### FIPS 204 - MLDSA

The `MLDSA` class contains 3 main functions:

- `MLDSAKeyGen()`: generates a public-private keypair `(public_key, secret_key)`
- `MLDSASign(secret_key, Message, ctx)`: generates an MLDSA signature `sigature`
from the message `message` and bit-packed secret key `secret_key`.
- `MLDSAVerify(public_key, message, signature)`: verifies a `signature` rho for a `message` M.

To use `FIPS 204 - MLDSA` simply import as follows:

```python
from fips import MLDSA_44, MLDSA_65, MLDSA_87
```

#### Example Use Case

```python
from fips import MLDSA_44

mldsa128 = MLDSA_44

# Generate the public-private key pair.
public_key, secret_key = mldsa128.MLDSAKeyGen()

context = b'ab'
message = "du bis gut"
message_spoof = "you are good"

# Generate the signature.
signature = mldsa128.MLDSASign(secret_key, mldsa128.auxilary.BytesToBits(message.encode()), context)

# Verification will only pass with the correct corresponding public key.
assert mldsa128.MLDSAVerify(public_key, mldsa128.auxilary.BytesToBits(message.encode()), signature, context)

# Verification will fail with an altered message.
assert not MLDSA_44.MLDSAVerify(public_key, MLDSA_44.auxilary.BytesToBits(message_spoof.encode()), signature, context)

# Verification will fail with any other public key.
public_key_new, secret_key_new = MLDSA_44.MLDSAKeyGen()
assert not MLDSA_44.MLDSAVerify(public_key_new, MLDSA_44.auxilary.BytesToBits(message.encode()), signature, context)
```

The above example would also work with the other NIST levels
`MLDSA_65` and `MLDSA_87`.

#### Hash ML-DSA

Algorithm 4 and 5 of FIPS 204 are not yet added to this implementation.

## Benchmarks

`FIPS 204 - MLDSA` Performance:

|                          | `MLDSA_44` | `MLDSA_65` | `MLDSA_87` |
|--------------------------|------------|------------|------------|
| `KeyGen()` Average Time  |   8.4 ms   |   14.1 ms  |   22.3 ms  |
| `Sign()`   Average Time  |   78.0 ms  |  127.1 ms  |  144.3 ms  |
| `Verify()` Average Time  |   20.9 ms  |   29.9 ms  |   43.6 ms  |

Data recorded using a Ryzen 7 4800H CPU averaged over 1000 calls.

## Colaborations

Feel free to modify and share improvements.
