pq-crystals/dilithium

Purpose and variants

This is the official C implementation of the FIPS 204 Dilithium post-quantum signature scheme. It ships two parallel implementations: portable reference code in ref/ and x86-64 AVX2-optimized code in avx2/, each supporting parameter sets Dilithium2, 3, and 5.

Public signing boundary

The public API exposes key generation, detached/attached signing, and verification with parameter-set-specific sizes and namespacing. Core entry points and scheme orchestration are in:

• ref/api.h, ref/sign.c, ref/sign.h

• avx2/api.h, avx2/sign.c, avx2/sign.h

Compile-time parameter selection is encoded in each implementation’s params.h; config.h controls hedged versus deterministic signing.

Signing and verification pipeline

sign.c coordinates the protocol: derive seeds and secrets during key generation; expand the public matrix; sample masking vectors; compute matrix-vector products; decompose/round coefficients; derive a Fiat–Shamir challenge; and pack outputs. Verification reverses the public relation, reconstructs the challenge input, and compares it to the signature challenge.

The principal data boundary is serialized byte arrays versus internal polynomial/vector structures:

• Serialization: ref/packing.c, ref/packing.h; avx2/packing.c, avx2/packing.h

• Polynomial vectors: ref/polyvec.c, ref/polyvec.h; avx2/polyvec.c, avx2/polyvec.h

• Polynomial primitives: ref/poly.c, ref/poly.h; avx2/poly.c, avx2/poly.h

Lattice arithmetic layer

Polynomial operations operate modulo Dilithium’s ring and modulus. The reference implementation expresses transforms and reduction in portable C:

• ref/ntt.c, ref/reduce.c, ref/rounding.c

The AVX2 path retains compatible high-level C interfaces but implements performance-critical transforms and pointwise arithmetic in assembly:

• avx2/ntt.S, avx2/invntt.S, avx2/pointwise.S

• avx2/rounding.c, avx2/rejsample.c

This is the primary portability/performance boundary; callers should use the shared polynomial and signing interfaces rather than architecture-specific assembly.

Symmetric cryptography and entropy

SHAKE/FIPS 202 provides hashing, matrix expansion, challenge derivation, and pseudorandom sampling:

• ref/fips202.c, ref/symmetric-shake.c, ref/symmetric.h

• avx2/fips202.c, avx2/fips202x4.c, avx2/symmetric-shake.c

AVX2 adds four-lane Keccak processing, including assembly permutation support in avx2/f1600x4.S. Randomness enters through randombytes for key generation and, by default, hedged signing:

• ref/randombytes.c, ref/config.h

• avx2/randombytes.c, avx2/config.h

Build, artifacts, and runtime assumptions

ref/Makefile and avx2/Makefile build per-parameter-set tests, benchmarks, and shared libraries. The AVX2 build requires an x86 CPU supporting AVX2; the reference build is the portable baseline. OpenSSL is an external dependency for some test/KAT-related programs, not the Dilithium cryptographic core.

Validation and interoperability

Functional tests exercise repeated API keygen/sign/verify and malformed signatures; deterministic-vector programs expose intermediate algorithm values for cross-implementation compatibility:

• ref/test/test_dilithium.c, ref/test/test_vectors.c

• avx2/test/test_dilithium.c, avx2/test/test_vectors.c

NIST KAT generation is isolated under ref/nistkat/, including its RNG adapter and PQCgenKAT_sign.c.