pqforge library
High-level post-quantum composition helpers for Dart, Flutter, and Serverpod.
pqforge exposes its entire public API through this single entrypoint:
import 'package:pqforge/pqforge.dart';
From here you get the full stack:
- the PqForge facade — key generation (ML-KEM, ML-DSA, SLH-DSA), KEM-DEM envelopes, document/artifact signing, key custody, and recipes;
- hybrid key derivation — PqForgeCombiner (raw bytes) and the
PqForgeCryptographyExtensions
SecretKey.deriveHybridSecretKeyergonomic; - batteries-included classical + post-quantum hybrid —
PqForgeHybridKeyAgreement (X25519 + ML-KEM), PqForgeHybridSigner
(ML-DSA + Ed25519), and hybrid KEM-DEM envelopes (PqForgeAsync
encryptAsync/decryptAsyncwith PqHybridKemDem); - AEAD wire packets — PqForgeSecureSession over AES-256-GCM or
ChaCha20-Poly1305, on either the pure-Dart PointyCastle or the native
package:cryptographybackend (PqForgeEngineProvider).
The pure-Dart pieces (PqForgeCombiner, PqForgePointyCastleAeadEngine) use
only PointyCastle internally; the hybrid, native-AEAD, and SecretKey pieces
use package:cryptography. Unused backends are tree-shaken from release
builds, so you only pay for the APIs you actually call.
Lattice primitives and PointyCastle types are not re-exported from this
library. Import package:pqcrypto/pqcrypto.dart and
package:pointycastle/api.dart when you need those APIs directly. That keeps
dart doc (and pub.dev documentation points) on the pqforge surface.
Classes
- Argon2Limits
- Authoritative Argon2id parameter bounds.
- PqAeadSuite
- The AEAD-suite container marker (R3).
- PqArtifactSignature
- PqBytes
- PqCallbackKeyCustodyStore
- PqClassical
- Process-wide registry for the active PqClassicalProvider.
- PqClassicalProvider
- The raw classical operations behind the hybrid layer. Implementations own only the cryptography; the callers keep their own length/validation checks.
- PqClassicalSignatureKeyPair
-
A classical signature key pair as raw bytes, so both backends — Ed25519 via
package:cryptographyand ECDSA-P256 via PqEcdsaP256 — share one type. - PqDualSignature
- PqEcdsaP256
- ECDSA over NIST P-256, byte-oriented and self-contained.
- PqEnvelope
- PqExportedKey
- PqFipsMode
- Process-wide FIPS policy switch. Enable once at startup, before any crypto.
- PqForge
- PqForgeAeadEngine
-
Low-level AEAD contract: raw seal/open over a
ciphertext || tagbody. - PqForgeBytes
- Backward-compatible byte utility name from the V0.1 facade.
- PqForgeCombiner
- Core hybrid KEM shared-secret combiner (Option A — pure byte ingestion).
- PqForgeCryptographyAeadEngine
-
PqForgeAeadEngine implemented with
package:cryptography. - PqForgeHybridKeyAgreement
- PqForgeHybridSigner
- PqForgePointyCastleAeadEngine
- PqForgeAeadEngine implemented entirely in Dart via PointyCastle.
- PqForgeProfile
- A named composition profile for common post-quantum choices.
- PqForgeSecureSession
- Encrypts and decrypts application payloads into self-describing AEAD wire packets, with an explicit choice of cipher suite and backend engine.
- PqHybridKemDem
- The hybrid (classical + post-quantum) KEM-DEM key schedule.
- PqHybridKeyAgreementRequest
- PqHybridKeyAgreementResult
- PqHybridSignature
- PqIdentityBinding
- PqKdf
-
KDF identifiers stored in wrapped-key JSON (
PqWrappedKey.kdf). - PqKemEncapsulation
- PqKemPrimitives
- PqKeyBundle
- PqKeyCustodyStore
- PqKeyKind
- PqKeyPair
- PqKeyResolver
- PqKeyStore
- PqLattice
- Process-wide registry for the active PqLatticeProvider.
- PqLatticeProvider
- The raw lattice operations behind PqKemPrimitives / PqSignaturePrimitives.
- PqMemoryKeyCustodyStore
- PqMultiRecipient
-
Builds and opens the
recipients[]key-wrap entries. - PqNistEcdh
- NIST-curve ECDH with a TLS/SP 800-56A byte contract.
- PqOffloadRequest
- PqOffloadResponse
- PqPassphraseKeyCustody
- PqPureDartClassicalProvider
-
The built-in pure-Dart backend:
package:cryptographyfor X25519/Ed25519 and PqEcdsaP256 (PointyCastle, RFC-6979) for ECDSA-P256. Always present; the fallback when no native provider is registered. - PqPureDartLatticeProvider
-
The built-in pure-Dart backend (
pqcryptoon PointyCastle). Always present; the fallback when no native provider is registered. - PqRandom
- Process-wide source of cryptographic randomness.
- PqRecipeMessages
- PqRecipientSpec
- One additional recipient of a multi-recipient encryption: their ML-KEM public key, an optional X25519 public key (making their key wrap hybrid), and an optional key id recorded in the entry for fast unwrap routing.
- PqSignaturePrimitives
- PqSignedLogEntry
- PqSignedToken
- PqSlhDsaPrimitives
-
FIPS 205 SLH-DSA adapters over
pqcrypto. Hash-based, not lattice — this is a sibling of PqSignaturePrimitives, not a PqLatticeProvider surface. - PqStreamingEnvelope
-
Pure framing for the
.pqfsstreaming envelope. - PqStreamingHeader
-
The fixed, canonical, signed part of a
.pqfsstreaming-envelope header. - PqSymmetricPrimitives
- PqWrappedKey
Enums
- PqClassicalKeyAgreementAlgorithm
- PqClassicalSignatureAlgorithm
- PqDualSignaturePolicy
- PqForgeCipherSuite
- Authenticated Encryption with Associated Data (AEAD) suites offered by PqForgeSecureSession.
- PqForgeEngineProvider
- The backend that performs the low-level AEAD computation.
- PqHybridConcatOrder
- Join order for PqForgeCombiner.concatenateSharedSecrets.
- PqHybridProfile
- Hash digest engine + security-profile pairing used by PqForgeCombiner.
- PqKemAlgorithm
- ML-KEM parameter sets supported by pqforge.
- PqSignatureAlgorithm
- ML-DSA parameter sets supported by pqforge.
- PqSlhDsaAlgorithm
- FIPS 205 SLH-DSA parameter sets composed by pqforge.
- PqSlhDsaPreHash
- Pre-hash for HashSLH-DSA (FIPS 205 Algorithm 23).
Extensions
- PqForgeAsync on PqForge
- Engine-pluggable (and optionally hybrid) one-shot envelope encryption.
- PqForgeCryptographyExtensions on SecretKey
-
Hybrid combining for the modern
package:cryptographycrypto.SecretKeytype.
Constants
- pqForgeAeadSuiteMetadataKey → const String
-
Metadata key recording a non-default AEAD suite (
chacha20-poly1305). Absent means AES-256-GCM, so default containers carry no marker. Reserved: the encrypt paths reject caller metadata that already contains it. - pqForgeDefaultAeadNonceBytes → const int
- pqForgeDefaultDeploymentSaltBytes → const int
- pqForgeDefaultSessionKeyBytes → const int
- pqForgeEnvelopeMagic → const String
- pqForgeEnvelopeVersion → const int
-
Envelope format version. Signatures are computed over a pre-hashed digest —
SHA-256(headerFields ‖ SHA-256(payload))signed withpreHash:true— so signing cost and memory are independent of payload size (defect M1). The library is pre-release, so there is no prior wire format to interoperate with. - pqForgeHybridKexMetadataKey → const String
- Metadata key whose presence marks an envelope/container as hybrid (ML-KEM + classical) KEM-DEM. The canonical constant lives here so both the sync service (which must reject hybrid inputs with a clear error) and the async/streaming hybrid paths share it without an import cycle.
- pqForgeInfoPrefix → const String
- pqForgeRecipientKeyIdMetadataKey → const String
- Metadata key naming the primary recipient's key id on multi-recipient envelopes, letting a decryptor pick the right unwrap path without trials.
- pqForgeRecipientsMetadataKey → const String
- Metadata key holding the additional-recipient key-wrap entries of a multi-recipient envelope/container (the payload is sealed once; the DEM key is wrapped per extra recipient). Reserved like pqForgeHybridKexMetadataKey.
-
pqForgeReservedMetadataKeys
→ const List<
String> - Every metadata key pqforge writes itself and therefore refuses from callers, so user metadata can never spoof a container marker.
Functions
-
aeadEngineForProvider(
PqForgeEngineProvider provider, {PqForgeCipherSuite cipherSuite = PqForgeCipherSuite.aes256Gcm}) → PqForgeAeadEngine -
Builds an AEAD engine instance for
provider— the one mapping shared by the one-shot async path, the streaming cipher, and the CLI. -
requireDsaContext(
Uint8List? context) → void -
requireLength(
String name, Uint8List value, int expected) → void -
requireWritableEnvelopeMetadata(
Map< String, Object?> metadata) → void -
Throws PqForgeException when caller-supplied
metadataalready contains one of the pqForgeReservedMetadataKeys. Every encrypt path (sync, async, streaming) runs this before merging its own markers in.
Typedefs
- PqClassicalSignatureVerifier = bool Function(Uint8List message, Uint8List signature)
-
PqKeyCustodyDelete
= FutureOr<
void> Function(String storageId) -
PqKeyCustodyGet
= FutureOr<
Map< Function(String storageId)String, Object?> ?> -
PqKeyCustodyPut
= FutureOr<
void> Function(String storageId, Map<String, Object?> document)
Exceptions / Errors
- PqForgeAuthTagException
- Thrown when AEAD authentication-tag verification fails during decryption.
- PqForgeException