# turkananation/pqcrypto architecture

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

- Interactive diagram: https://gitdiagram.com/turkananation/pqcrypto
- Repository: https://github.com/turkananation/pqcrypto

## Overview

- **Library/module architecture** (public API → algorithm implementation → math/primitives → external dependency)
- **Cryptographic dataflow** (KeyGen / Encaps / Decaps call chains)
- **Verification harness** (KAT runner + unit/statistical tests)

##### Read the repo structure as architectural boundaries
From the file tree + README, the natural component boundaries are already encoded:

##### Public entrypoints / consumer-facing
- `lib/pqcrypto.dart` — package entrypoint (what end users import)
- `example/main.dart` — usage example (acts like an integration sample)

##### Algorithm implementation (ML‑KEM / Kyber)
- `lib/src/algos/kyber/kem.dart` — **high-level ML‑KEM API** (Algorithms 16–19; uses FO transform / implicit rejection)
- `lib/src/algos/kyber/indcpa.dart` — **K-PKE / IND‑CPA** (Algorithms 12–14)
- `lib/src/algos/kyber/pack.dart` — **compression + serialization** (ByteEncode/Decode; Compress/Decompress)
- `lib/src/algos/kyber/params.dart` — **parameter sets** (ML‑KEM‑512/768/1024 constants)

##### Shared math & primitives
- `lib/src/common/poly.dart` — polynomial ring ops, NTT/InvNTT, base multiplication, reductions, sampling helpers
- `lib/src/common/shake.dart` — SHAKE-128/256 wrappers (and likely SHA3-256/512 usage paths via dependency)

##### Verification / tests
- `test/kat_evaluator.dart` + `test/data/*.rsp` — NIST KAT runner + vector files
- `test/pack_test.dart`, `test/cbd_test.dart` — correctness + statistical tests

##### Public API Layer
- `pqcrypto.dart` (exports/types)
##### ML‑KEM Orchestration Layer
- `kem.dart` (KeyGen/Encaps/Decaps + FO transform + implicit rejection logic)
##### IND‑CPA (K‑PKE) Layer
- `indcpa.dart` (Encrypt/Decrypt; keygen)
##### Encoding/Serialization Layer
- `pack.dart` (ByteEncode/Decode; Compress/Decompress)
##### Math Layer
- `poly.dart` (NTT/InvNTT, base mult, poly ops)
##### Hash/XOF/PRF Layer
- `shake.dart` (SHAKE wrappers)
##### Params
- `params.dart` (constants per security level)
##### Test Harness
- KAT runner + vector files + unit tests

- `pqcrypto.dart` → `kem.dart`
- `kem.dart` → `indcpa.dart`, `pack.dart`, `params.dart`, `shake.dart`, `poly.dart`
- `indcpa.dart` → `poly.dart`, `shake.dart`, `params.dart`, `pack.dart` (as applicable)
- `pack.dart` → `params.dart` (bit widths/du/dv), possibly `poly.dart` types
- `shake.dart` → `pointycastle`
- Tests → all internal modules + `test/data/*.rsp`

This is where accuracy matters most. Break ML‑KEM into “as many components as possible” aligned to FIPS 203 stages.

- Key derivation: `(rho, sigma) := G(d)`
- FO transform steps:
- hash of pk / ct
- re-encryption check
- implicit rejection path (derive `K` from `z` when invalid)
- API operations:
- `KeyGen`
- `Encaps`
- `Decaps`

**Within `indcpa.dart`:**
- `K-PKE.KeyGen`
- `K-PKE.Encrypt`
- `K-PKE.Decrypt`
- Noise sampling (CBD) + matrix generation calls (via SHAKE)

**Within `poly.dart`:**
- NTT
- InvNTT
- BaseMul (NTT-domain multiplication)
- PolyAdd/Sub/Reduce
- Parse/SampleNTT (as referenced in README)

**Within `pack.dart`:**
- ByteEncode/ByteDecode
- Compress/Decompress (d = 1,4,5,10,11,12)

**Within `shake.dart`:**
- SHAKE-128 (XOF)
- SHAKE-256 (PRF)
- SHA3-256 / SHA3-512 (hashing/KDF) if used

##### ML‑KEM KeyGen (Server-side)
Participants: `App(Server)` → `PqcKem`/`pqcrypto.dart` → `kem.dart` → `shake.dart` → `indcpa.dart` → `poly.dart` / `pack.dart`

Outputs:
- `pk` and `sk`
- internal derivations (rho/sigma, hashed pk, z stored in sk for implicit rejection)

##### Encaps/Decaps (Client ↔ Server)
Encaps:
- Client uses `pk` → outputs `(ct, ssAlice)`
Decaps:
- Server uses `sk, ct` → outputs `ssBob`
- branch: valid ct → ss derived normally; invalid ct → ss derived from `z` (implicit rejection)

This is where you explicitly annotate **IND‑CCA2 hardening** and the “re-encryption check” dependency.

- **Layered design**: API → orchestration → K-PKE → math/primitives → external hash provider
- **Pure Dart portability boundary**: no native code; only depends on `pointycastle`

This set is detailed, spec-aligned, and matches how engineers actually reason about cryptographic libraries: *call graph + trust boundaries + correctness harness*.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ========= CONTEXT =========
  subgraph "C4: Context (How pqcrypto is used)"
    direction TB

    ClientApp["Flutter/Dart App (Client)\n(mobile/web)"]:::external
    ServerApp["Dart Server App\n(Dart VM)"]:::external

    subgraph "pqcrypto (Dart package)"
      direction TB
      PkgEntry["Public API\n(pqcrypto.dart)"]:::api
    end

    Pointy["External dependency:\npointycastle\n(SHA3/SHAKE primitives)"]:::external

    Net(("Network / Transport")):::boundary

    ClientApp -->|"imports+calls"| PkgEntry
    ServerApp -->|"imports+calls"| PkgEntry

    ClientApp -.->|"pk/ct exchange"| Net
    Net -.->|"pk/ct exchange"| ServerApp

    PkgEntry -->|"uses"| Pointy
  end

  %% ========= CONTAINERS / MODULES =========
  subgraph "C4: Container / Module view (Library layers)"
    direction TB

    subgraph "Public API Layer"
      direction TB
      PQ["pqcrypto.dart\n(exports/types)"]:::api
    end

    subgraph "ML-KEM Orchestration Layer (FIPS 203 Alg 16–19)"
      direction TB
      KEM["ML-KEM API\nkem.dart\n(KeyGen/Encaps/Decaps)\nFO transform + implicit rejection"]:::orchestrator
    end

    subgraph "IND-CPA K-PKE Layer (FIPS 203 Alg 12–14)"
      direction TB
      INDCPA["IND-CPA K-PKE\nindcpa.dart\n(KeyGen/Encrypt/Decrypt)"]:::crypto
    end

    subgraph "Encoding / Serialization Layer"
      direction TB
      PACK["pack.dart\n(ByteEncode/Decode;\nCompress/Decompress)"]:::crypto
    end

    subgraph "Math Layer"
      direction TB
      POLY["poly.dart\n(Poly ops; NTT/InvNTT;\nreductions; sampling helpers)"]:::primitive
    end

    subgraph "Hash / XOF / PRF Layer"
      direction TB
      SHAKE["shake.dart\n(SHAKE-128/256 wrappers;\nSHA3 paths)"]:::primitive
    end

    subgraph "Parameter Sets"
      direction TB
      PARAMS["params.dart\n(ML-KEM-512/768/1024 constants)"]:::params
    end

    subgraph "External Crypto Provider"
      direction TB
      PC["pointycastle\n(SHA3/SHAKE impl)"]:::external
    end

    %% Dependencies (solid arrows)
    PQ -->|"calls"| KEM
    KEM -->|"calls"| INDCPA
    KEM -->|"calls"| PACK
    KEM -->|"reads"| PARAMS
    KEM -->|"hash/xof"| SHAKE
    KEM -->|"poly math"| POLY

    INDCPA -->|"poly math"| POLY
    INDCPA -->|"xof/prf"| SHAKE
    INDCPA -->|"reads"| PARAMS
    INDCPA -->|"encode/decode"| PACK

    PACK -->|"reads widths"| PARAMS

    SHAKE -->|"delegates to"| PC
  end

  %% ========= COMPONENTS (ML-KEM internals) =========
  subgraph "C4: Component view (ML-KEM internals, spec-aligned)"
    direction TB

    subgraph "kem.dart components (Alg 16–19)"
      direction TB
      KeyGen["KeyGen()"]:::orchestrator
      Encaps["Encaps()"]:::orchestrator
      Decaps["Decaps()"]:::orchestrator

      subgraph "FO transform + CCA hardening boundary"
        direction TB
        GDerive["Key derivation: (rho,sigma) := G(d)"]:::secure
        HashPk["Hash(pk)"]:::secure
        HashCt["Hash(ct)"]:::secure
        ReEncCheck["Re-encryption check\n(compare ct vs re-encrypt)"]:::secure
        ImpReject["Implicit rejection\n(derive K from z when invalid)"]:::secure
      end
    end

    subgraph "indcpa.dart components (Alg 12–14)"
      direction TB
      PKEKeyGen["K-PKE.KeyGen()"]:::crypto
      PKEEnc["K-PKE.Encrypt()"]:::crypto
      PKEDec["K-PKE.Decrypt()"]:::crypto
      NoiseCBD["Noise sampling (CBD)"]:::crypto
      MatrixGen["Matrix generation (via SHAKE)"]:::crypto
    end

    subgraph "pack.dart components"
      direction TB
      ByteEnc["ByteEncode()"]:::crypto
      ByteDec["ByteDecode()"]:::crypto
      Compress["Compress(d)"]:::crypto
      Decompress["Decompress(d)"]:::crypto
    end

    subgraph "poly.dart components"
      direction TB
      NTT["NTT()"]:::primitive
      InvNTT["InvNTT()"]:::primitive
      BaseMul["BaseMul()"]:::primitive
      AddSubReduce["PolyAdd/Sub/Reduce()"]:::primitive
      SampleParse["Parse/Sample helpers"]:::primitive
    end

    subgraph "shake.dart components"
      direction TB
      S128["SHAKE-128 (XOF)"]:::primitive
      S256["SHAKE-256 (PRF)"]:::primitive
      SHA3["SHA3-256/512 (hash/KDF)"]:::primitive
    end

    %% Call graph / data flow inside library (solid)
    KeyGen -->|"uses"| GDerive
    KeyGen -->|"calls"| PKEKeyGen
    KeyGen -->|"stores"| HashPk

    Encaps -->|"uses"| HashPk
    Encaps -->|"calls"| PKEEnc
    Encaps -->|"outputs"| HashCt

    Decaps -->|"calls"| PKEDec
    Decaps -->|"calls"| ReEncCheck
    Decaps -->|"branch(valid)"| HashCt
    Decaps -->|"branch(invalid)"| ImpReject

    %% INDCPA internals
    PKEKeyGen -->|"uses"| MatrixGen
    PKEKeyGen -->|"uses"| NoiseCBD
    PKEEnc -->|"uses"| MatrixGen
    PKEEnc -->|"uses"| NoiseCBD
    PKEEnc -->|"poly ops"| NTT
    PKEEnc -->|"poly ops"| BaseMul
    PKEEnc -->|"poly ops"| AddSubReduce
    PKEDec -->|"poly ops"| InvNTT
    PKEDec -->|"poly ops"| AddSubReduce

    %% Packing & hashes
    PKEEnc -->|"encode"| ByteEnc
    PKEDec -->|"decode"| ByteDec
    ByteEnc -->|"compress"| Compress
    ByteDec -->|"decompress"| Decompress

    MatrixGen -->|"XOF"| S128
    NoiseCBD -->|"PRF"| S256
    HashPk -->|"hash"| SHA3
    HashCt -->|"hash"| SHA3
    ReEncCheck -->|"rehash"| SHA3

    %% Poly sampling helpers
    MatrixGen -->|"parse"| SampleParse
    NoiseCBD -->|"sample"| SampleParse
  end

  %% ========= SEQUENCE (Encaps/Decaps) =========
  subgraph "Sequence: ML-KEM Encaps/Decaps (CCA hardening + implicit rejection)"
    direction TB

    A1["Client App"]:::external
    A2["pqcrypto.dart"]:::api
    A3["kem.dart"]:::orchestrator
    A4["indcpa.dart"]:::crypto
    A5["pack.dart"]:::crypto
    A6["shake.dart"]:::primitive
    A7["Server App"]:::external

    A1 -->|"Encaps(pk)"| A2
    A2 -->|"Encaps()"| A3
    A3 -->|"K-PKE.Encrypt()"| A4
    A4 -->|"encode ct"| A5
    A3 -->|"hash/KDF"| A6
    A3 -->|"returns (ct,ssAlice)"| A2
    A2 -->|"ct,ssAlice"| A1

    A1 -.->|"send ct"| A7
    A7 -->|"Decaps(sk,ct)"| A2
    A2 -->|"Decaps()"| A3
    A3 -->|"decode ct"| A5
    A3 -->|"K-PKE.Decrypt()"| A4
    A3 -->|"re-encrypt check"| A4
    A3 -->|"valid? derive ssBob via KDF"| A6
    A3 -->|"invalid? derive ssBob from z (implicit rejection)"| A6
    A3 -->|"returns ssBob"| A2
    A2 -->|"ssBob"| A7
  end

  %% ========= TESTING / VERIFICATION =========
  subgraph "Verification architecture (KAT runner + unit/statistical tests)"
    direction TB

    subgraph "KAT Harness"
      direction TB
      KAT["kat_evaluator.dart\n(NIST KAT runner)"]:::test
      RSP512["kat_MLKEM_512.rsp"]:::data
      RSP768["kat_MLKEM_768.rsp"]:::data
      RSP1024["kat_MLKEM_1024.rsp"]:::data
    end

    subgraph "Unit / Statistical Tests"
      direction TB
      PackTest["pack_test.dart\n(round-trip encode/compress)"]:::test
      CbdTest["cbd_test.dart\n(CBD/noise sampling correctness)"]:::test
    end

    %% KAT reads vectors then calls API
    RSP512 -->|"read vectors"| KAT
    RSP768 -->|"read vectors"| KAT
    RSP1024 -->|"read vectors"| KAT
    KAT -->|"calls KeyGen/Encaps/Decaps"| PQ

    %% Tests target modules
    PackTest -->|"tests"| PACK
    CbdTest -->|"tests"| INDCPA
    CbdTest -->|"exercises"| POLY
    KAT -->|"uses"| KEM
  end

  %% ========= EXAMPLE =========
  subgraph "Example / Integration sample"
    direction TB
    Example["example/main.dart\n(sample usage)"]:::example
    Example -->|"imports+calls"| PQ
  end

  %% ========= CLICK EVENTS (from component_mapping) =========
  click PkgEntry "https://github.com/turkananation/pqcrypto/blob/main/lib/pqcrypto.dart"
  click PQ "https://github.com/turkananation/pqcrypto/blob/main/lib/pqcrypto.dart"
  click Example "https://github.com/turkananation/pqcrypto/blob/main/example/main.dart"
  click KEM "https://github.com/turkananation/pqcrypto/blob/main/lib/src/algos/kyber/kem.dart"
  click INDCPA "https://github.com/turkananation/pqcrypto/blob/main/lib/src/algos/kyber/indcpa.dart"
  click PACK "https://github.com/turkananation/pqcrypto/blob/main/lib/src/algos/kyber/pack.dart"
  click PARAMS "https://github.com/turkananation/pqcrypto/blob/main/lib/src/algos/kyber/params.dart"
  click POLY "https://github.com/turkananation/pqcrypto/blob/main/lib/src/common/poly.dart"
  click SHAKE "https://github.com/turkananation/pqcrypto/blob/main/lib/src/common/shake.dart"
  click PC "https://github.com/turkananation/pqcrypto/blob/main/pubspec.yaml"
  click Pointy "https://github.com/turkananation/pqcrypto/blob/main/pubspec.yaml"
  click KAT "https://github.com/turkananation/pqcrypto/blob/main/test/kat_evaluator.dart"
  click RSP512 "https://github.com/turkananation/pqcrypto/blob/main/test/data/kat_MLKEM_512.rsp"
  click RSP768 "https://github.com/turkananation/pqcrypto/blob/main/test/data/kat_MLKEM_768.rsp"
  click RSP1024 "https://github.com/turkananation/pqcrypto/blob/main/test/data/kat_MLKEM_1024.rsp"
  click PackTest "https://github.com/turkananation/pqcrypto/blob/main/test/pack_test.dart"
  click CbdTest "https://github.com/turkananation/pqcrypto/blob/main/test/cbd_test.dart"

  %% ========= STYLES =========
  classDef api fill:#1f77b4,stroke:#0b3d91,color:#ffffff,stroke-width:1.5px
  classDef orchestrator fill:#2b6cb0,stroke:#1a365d,color:#ffffff,stroke-width:1.5px
  classDef crypto fill:#6b46c1,stroke:#3c1a86,color:#ffffff,stroke-width:1.5px
  classDef primitive fill:#2f855a,stroke:#14532d,color:#ffffff,stroke-width:1.5px
  classDef params fill:#4a5568,stroke:#1a202c,color:#ffffff,stroke-width:1.5px
  classDef external fill:#718096,stroke:#2d3748,color:#ffffff,stroke-width:1.5px
  classDef test fill:#dd6b20,stroke:#7b341e,color:#ffffff,stroke-width:1.5px
  classDef data fill:#ed8936,stroke:#7b341e,color:#1a202c,stroke-width:1.5px
  classDef example fill:#3182ce,stroke:#1a365d,color:#ffffff,stroke-width:1.5px
  classDef boundary fill:#a0aec0,stroke:#2d3748,color:#1a202c,stroke-width:2px,stroke-dasharray: 6 4
  classDef secure fill:#c05621,stroke:#7b341e,color:#ffffff,stroke-width:2px
```
