# pq-crystals/dilithium architecture

> Architecture diagram of the GitHub repository pq-crystals/dilithium, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pq-crystals/dilithium
- Repository: https://github.com/pq-crystals/dilithium

## Overview

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

Main entry points: [`ref/sign.c`](https://github.com/pq-crystals/dilithium/blob/master/ref/sign.c) (Reference signing protocol), [`avx2/sign.c`](https://github.com/pq-crystals/dilithium/blob/master/avx2/sign.c) (AVX2 signing protocol), [`ref/api.h`](https://github.com/pq-crystals/dilithium/blob/master/ref/api.h) (Reference API), [`ref/Makefile`](https://github.com/pq-crystals/dilithium/blob/master/ref/Makefile) (Per-variant builds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public interfaces"]
  node_callers(("Application callers<br/>consumer"))
end

subgraph group_reference["Portable reference"]
  node_ref_api["Reference API<br/>C API<br/>[api.h]"]
  node_ref_sign["Reference signing protocol<br/>protocol orchestration<br/>[sign.c]"]
  node_ref_params["Reference parameters<br/>compile-time selection<br/>[params.h]"]
  node_ref_packing["Reference serialization<br/>byte encoding<br/>[packing.c]"]
  node_ref_poly["Reference polynomial layer<br/>ring arithmetic<br/>[poly.c]"]
  node_ref_ntt["Portable NTT and reduction<br/>arithmetic backend<br/>[ntt.c]"]
  node_ref_shake["Reference SHAKE<br/>symmetric crypto<br/>[symmetric-shake.c]"]
  node_ref_rng(("Reference randomness<br/>entropy source<br/>[randombytes.c]"))
end

subgraph group_avx2["AVX2 optimized"]
  node_avx2_api["AVX2 API<br/>C API<br/>[api.h]"]
  node_avx2_sign["AVX2 signing protocol<br/>protocol orchestration<br/>[sign.c]"]
  node_avx2_params["AVX2 parameters<br/>compile-time selection<br/>[params.h]"]
  node_avx2_packing["AVX2 serialization<br/>byte encoding<br/>[packing.c]"]
  node_avx2_poly["AVX2 polynomial layer<br/>ring arithmetic<br/>[poly.c]"]
  node_avx2_asm{{"AVX2 arithmetic assembly<br/>assembly backend<br/>[ntt.S]"}}
  node_avx2_shake["AVX2 SHAKE x4<br/>vectorized symmetric crypto<br/>[fips202x4.c]"]
  node_avx2_rng(("AVX2 randomness<br/>entropy source<br/>[randombytes.c]"))
end

subgraph group_validation["Build and validation"]
  node_builds["Per-variant builds<br/>Make targets"]
  node_tests["API and vector validation<br/>test programs<br/>[test_dilithium.c]"]
  node_nist_kat["NIST KAT generation<br/>KAT program<br/>[PQCgenKAT_sign.c]"]
end

node_callers -->|"portable API"| node_ref_api
node_callers -->|"AVX2 API"| node_avx2_api
node_ref_api -->|"keygen / sign / verify"| node_ref_sign
node_avx2_api -->|"keygen / sign / verify"| node_avx2_sign
node_ref_params -.->|"selects Dilithium 2/3/5"| node_ref_sign
node_avx2_params -.->|"selects Dilithium 2/3/5"| node_avx2_sign
node_ref_sign -->|"pack and unpack"| node_ref_packing
node_avx2_sign -->|"pack and unpack"| node_avx2_packing
node_ref_sign -->|"matrix and vector operations"| node_ref_poly
node_avx2_sign -->|"matrix and vector operations"| node_avx2_poly
node_ref_poly -->|"transforms and reduction"| node_ref_ntt
node_avx2_poly -->|"optimized transforms"| node_avx2_asm
node_ref_sign -->|"expand and derive challenge"| node_ref_shake
node_avx2_sign -->|"expand and derive challenge"| node_avx2_shake
node_ref_rng -->|"keygen and hedged signing"| node_ref_sign
node_avx2_rng -->|"keygen and hedged signing"| node_avx2_sign
node_builds -->|"builds"| node_tests
node_builds -->|"builds"| node_nist_kat
node_tests -.->|"exercises"| node_ref_api
node_nist_kat -.->|"generates deterministic vectors"| node_ref_sign

click node_ref_api "https://github.com/pq-crystals/dilithium/blob/master/ref/api.h"
click node_avx2_api "https://github.com/pq-crystals/dilithium/blob/master/avx2/api.h"
click node_ref_sign "https://github.com/pq-crystals/dilithium/blob/master/ref/sign.c"
click node_avx2_sign "https://github.com/pq-crystals/dilithium/blob/master/avx2/sign.c"
click node_ref_params "https://github.com/pq-crystals/dilithium/blob/master/ref/params.h"
click node_avx2_params "https://github.com/pq-crystals/dilithium/blob/master/avx2/params.h"
click node_ref_packing "https://github.com/pq-crystals/dilithium/blob/master/ref/packing.c"
click node_avx2_packing "https://github.com/pq-crystals/dilithium/blob/master/avx2/packing.c"
click node_ref_poly "https://github.com/pq-crystals/dilithium/blob/master/ref/poly.c"
click node_avx2_poly "https://github.com/pq-crystals/dilithium/blob/master/avx2/poly.c"
click node_ref_ntt "https://github.com/pq-crystals/dilithium/blob/master/ref/ntt.c"
click node_avx2_asm "https://github.com/pq-crystals/dilithium/blob/master/avx2/ntt.S"
click node_ref_shake "https://github.com/pq-crystals/dilithium/blob/master/ref/symmetric-shake.c"
click node_avx2_shake "https://github.com/pq-crystals/dilithium/blob/master/avx2/fips202x4.c"
click node_ref_rng "https://github.com/pq-crystals/dilithium/blob/master/ref/randombytes.c"
click node_avx2_rng "https://github.com/pq-crystals/dilithium/blob/master/avx2/randombytes.c"
click node_builds "https://github.com/pq-crystals/dilithium/blob/master/ref/Makefile"
click node_tests "https://github.com/pq-crystals/dilithium/blob/master/ref/test/test_dilithium.c"
click node_nist_kat "https://github.com/pq-crystals/dilithium/blob/master/ref/nistkat/PQCgenKAT_sign.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_callers toneBlue
class node_ref_api,node_ref_sign,node_ref_params,node_ref_packing,node_ref_poly,node_ref_ntt,node_ref_shake,node_ref_rng toneAmber
class node_avx2_api,node_avx2_sign,node_avx2_params,node_avx2_packing,node_avx2_poly,node_avx2_asm,node_avx2_shake,node_avx2_rng toneMint
class node_builds,node_tests,node_nist_kat toneRose
```

## Components

### Public interfaces

- **Application callers**: consumer

### Portable reference

- [Reference API](https://github.com/pq-crystals/dilithium/blob/master/ref/api.h): C API · `ref/api.h`
- [Reference signing protocol](https://github.com/pq-crystals/dilithium/blob/master/ref/sign.c): protocol orchestration · Keygen, signing, and verification flows. · `ref/sign.c`
- [Reference parameters](https://github.com/pq-crystals/dilithium/blob/master/ref/params.h): compile-time selection · `ref/params.h`
- [Reference serialization](https://github.com/pq-crystals/dilithium/blob/master/ref/packing.c): byte encoding · Converts keys and signatures to and from byte arrays. · `ref/packing.c`
- [Reference polynomial layer](https://github.com/pq-crystals/dilithium/blob/master/ref/poly.c): ring arithmetic · Polynomial and vector operations over the Dilithium ring. · `ref/poly.c`
- [Portable NTT and reduction](https://github.com/pq-crystals/dilithium/blob/master/ref/ntt.c): arithmetic backend · `ref/ntt.c`
- [Reference SHAKE](https://github.com/pq-crystals/dilithium/blob/master/ref/symmetric-shake.c): symmetric crypto · Hashing, expansion, challenge derivation, and sampling. · `ref/symmetric-shake.c`
- [Reference randomness](https://github.com/pq-crystals/dilithium/blob/master/ref/randombytes.c): entropy source · Used by key generation and hedged signing. · `ref/randombytes.c`

### AVX2 optimized

- [AVX2 API](https://github.com/pq-crystals/dilithium/blob/master/avx2/api.h): C API · `avx2/api.h`
- [AVX2 signing protocol](https://github.com/pq-crystals/dilithium/blob/master/avx2/sign.c): protocol orchestration · Compatible optimized keygen, signing, and verification. · `avx2/sign.c`
- [AVX2 parameters](https://github.com/pq-crystals/dilithium/blob/master/avx2/params.h): compile-time selection · `avx2/params.h`
- [AVX2 serialization](https://github.com/pq-crystals/dilithium/blob/master/avx2/packing.c): byte encoding · `avx2/packing.c`
- [AVX2 polynomial layer](https://github.com/pq-crystals/dilithium/blob/master/avx2/poly.c): ring arithmetic · Shared high-level polynomial interface for optimized arithmetic. · `avx2/poly.c`
- [AVX2 arithmetic assembly](https://github.com/pq-crystals/dilithium/blob/master/avx2/ntt.S): assembly backend · NTT, inverse NTT, and pointwise operations. · `avx2/ntt.S`
- [AVX2 SHAKE x4](https://github.com/pq-crystals/dilithium/blob/master/avx2/fips202x4.c): vectorized symmetric crypto · Four-lane Keccak acceleration. · `avx2/fips202x4.c`
- [AVX2 randomness](https://github.com/pq-crystals/dilithium/blob/master/avx2/randombytes.c): entropy source · Used by key generation and hedged signing. · `avx2/randombytes.c`

### Build and validation

- [Per-variant builds](https://github.com/pq-crystals/dilithium/blob/master/ref/Makefile): Make targets · Build parameter-set tests, benchmarks, and shared libraries. · `ref/Makefile`
- [API and vector validation](https://github.com/pq-crystals/dilithium/blob/master/ref/test/test_dilithium.c): test programs · Checks signing behavior, malformed signatures, and interoperability vectors. · `ref/test/test_dilithium.c`
- [NIST KAT generation](https://github.com/pq-crystals/dilithium/blob/master/ref/nistkat/PQCgenKAT_sign.c): KAT program · Isolated deterministic KAT generation path. · `ref/nistkat/PQCgenKAT_sign.c`

## Connections

- Application callers → Reference API: portable API
- Application callers → AVX2 API: AVX2 API
- Reference API → Reference signing protocol: keygen / sign / verify
- AVX2 API → AVX2 signing protocol: keygen / sign / verify
- Reference parameters → Reference signing protocol: selects Dilithium 2/3/5
- AVX2 parameters → AVX2 signing protocol: selects Dilithium 2/3/5
- Reference signing protocol → Reference serialization: pack and unpack
- AVX2 signing protocol → AVX2 serialization: pack and unpack
- Reference signing protocol → Reference polynomial layer: matrix and vector operations
- AVX2 signing protocol → AVX2 polynomial layer: matrix and vector operations
- Reference polynomial layer → Portable NTT and reduction: transforms and reduction
- AVX2 polynomial layer → AVX2 arithmetic assembly: optimized transforms
- Reference signing protocol → Reference SHAKE: expand and derive challenge
- AVX2 signing protocol → AVX2 SHAKE x4: expand and derive challenge
- Reference randomness → Reference signing protocol: keygen and hedged signing
- AVX2 randomness → AVX2 signing protocol: keygen and hedged signing
- Per-variant builds → API and vector validation: builds
- Per-variant builds → NIST KAT generation: builds
- API and vector validation → Reference API: exercises
- NIST KAT generation → Reference signing protocol: generates deterministic vectors