How turkananation/pqcrypto works
• 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*.