fips-collection 1.0.0

Educational implementations of NIST FIPS cryptographic standard.

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.

Licenses

This project is licensed under the License MIT.

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:

from fips import MLDSA_44, MLDSA_65, MLDSA_87

Example Use Case

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.