pqforge_io library

dart:io extensions for pqforge: bounded-memory streaming file encryption.

Import this instead of package:pqforge/pqforge.dart on native, server, and mobile targets that need to encrypt or decrypt large files without holding them in memory:

import 'package:pqforge/pqforge_io.dart';

final cipher = PqForgeStreamCipher();
await cipher.encryptFile(
  recipientPublicKey: recipientKemPublicKey,
  input: File('movie.mp4'),
  output: File('movie.mp4.pqf'),
  profile: PqForgeProfile.maximum,
);

It re-exports the full core API, so a single import is enough. The core package:pqforge/pqforge.dart library stays free of dart:io and therefore web-compatible; everything that touches the filesystem lives here.

Classes

Argon2Limits
Authoritative Argon2id parameter bounds.
DoubleRatchet
Signal Double Ratchet over X25519 and one pqforge AEAD.
DoubleRatchetMessage
One Double Ratchet message: a 40-byte header and ciphertext || tag.
HpkeContext
An HPKE encryption context (RFC 9180 §5.2).
HpkeKeyPair
A KEM key pair. secretKey is the RFC 9180 serialized private key: an X25519 or X448 seed, or a big-endian NIST scalar. The public key is uncompressed SEC1 for P-256, P-384, and P-521.
HpkeSuite
One HPKE ciphersuite: KEM, KDF, and AEAD.
PqAeadSuite
The AEAD-suite container marker (R3).
PqArtifactSignature
PqBrainpool
Brainpool ECDH with the TLS byte contract.
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:cryptography and ECDSA-P256 via PqEcdsaP256 — share one type.
PqCompositeLeg
One algorithm's signature inside a PqCompositeSignature.
PqCompositeSignature
Two or three signatures over one bound message.
PqDualSignature
PqEcdsaP256
ECDSA over NIST P-256, byte-oriented and self-contained.
PqEcdsaP384
ECDSA over NIST P-384, byte-oriented and self-contained.
PqEcdsaP521
ECDSA over NIST P-521, byte-oriented and self-contained.
PqEd25519
Ed25519 signatures. Secret keys are 32-byte seeds.
PqEd448
Ed448 signatures. Secret keys are 57-byte seeds.
PqEnvelope
PqExportedKey
PqFfdhe
RFC 7919 key agreement. Generator is 2.
PqFipsMode
Process-wide FIPS policy switch. Enable once at startup, before any crypto.
PqFolderPack
Bounded-memory sequential packer/unpacker for folder trees.
PqForge
PqForgeAeadEngine
Low-level AEAD contract: raw seal/open over a ciphertext || tag body.
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.
PqForgeSignatureComposer
Signs and verifies an explicit set of signature legs.
PqForgeStreamCipher
Encrypts and decrypts files in bounded memory using the .pqfs streaming envelope. Construct once and reuse; the engine is the hardware-acceleration lever.
PqHpke
RFC 9180 HPKE setup, seal, and open.
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
PqPackEntry
One file to pack: its archive-relative path and its on-disk source path.
PqPassphraseKeyCustody
PqPureDartClassicalProvider
The built-in pure-Dart backend: package:cryptography for 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 (pqcrypto on PointyCastle). Always present; the fallback when no native provider is registered.
PqRandom
Process-wide source of cryptographic randomness.
PqRatchetSecrets
Copies a 32-byte secret and refuses an expanded ML-KEM private key.
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.
PqRsa
PKCS#1 v1.5 and PSS signatures. Byte-oriented.
PqRsaPrivateKey
RSA private key as unsigned big-endian integers.
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 .pqfs streaming envelope.
PqStreamingHeader
The fixed, canonical, signed part of a .pqfs streaming-envelope header.
PqStreamingStats
Outcome of a streaming encrypt/decrypt: byte and frame counts for logging.
PqSymmetricPrimitives
PqWrappedKey
PqX448
X448 key agreement (RFC 7748 §5).
PqX509
X.509 certificates (RFC 5280) and the signature algorithms pqforge can check. No sockets, no trust store, no TLS alerts.
PqX509Addext
One -addext line, or several. This is the subset openssl req uses for a name, a key usage, an extended key usage, and basic constraints.
PqX509Certificate
PqX509DirectoryName
directoryName, the DER Name.
PqX509DnsName
PqX509EcdsaP256Key
PqX509EcdsaP384Key
PqX509Ed25519Key
PqX509EmailName
RFC 822 mailbox. The domain comparison is case-insensitive.
PqX509Extension
PqX509GeneralName
PqX509Ip4Name
PqX509Ip6Name
PqX509MlDsaKey
PqX509Name
DER Name. Equality is the encoding, not a string.
PqX509OtherName
A GeneralName this validator does not implement.
PqX509Parsed
A parsed certificate, or the first reason parsing stopped.
PqX509Path
A path check against caller-supplied anchors.
PqX509PrivateKey
A private key read from an OpenSSL PEM block.
PqX509PublicKey
PqX509Request
A PKCS#10 request. info is the exact bytes the signature covers.
PqX509RequestParsed
PqX509RsaKey
PqX509UriName
Uniform resource identifier. Name constraints apply to the host.
Pqxdh
PQXDH entry points. Both throw. The types are ready for the next release.
PqxdhBundle
Bob's prekey bundle. The caller fetched it. There is no server here.
PqxdhResult
What a finished handshake will return. Implemented with the handshake.
PqXWing
X-Wing key encapsulation.
PqXWingMessage
Bytes written by pqforge hpke seal and read by pqforge hpke open.
RatchetKeyPair
X25519 ratchet key pair. secretKey is 32 bytes and is the scalar seed.
RatchetPublicKey
X25519 ratchet public key. 32 bytes. Not an X-Wing key.
SharedSecret32
32-byte root secret. Not a public key, not a ciphertext, not a transcript.
TripleRatchet
Triple Ratchet entry point. The session type lands with the braid.

Enums

DoubleRatchetHash
SHA-256 or SHA-512, fixed for the life of a session.
HpkeAead
RFC 9180 AEAD identifier.
HpkeKdf
RFC 9180 KDF identifier. nh is the hash output length.
HpkeKem
RFC 9180 KEM identifier.
HpkeMode
RFC 9180 HPKE mode identifier.
HpkeRole
Which side of an HPKE context this is.
PqClassicalKeyAgreementAlgorithm
PqClassicalSignatureAlgorithm
PqCompositePolicy
How many legs must verify.
PqDualSignaturePolicy
PqFfdheGroup
One RFC 7919 group.
PqForgeCipherSuite
Authenticated Encryption with Associated Data (AEAD) suites offered by PqForgeSecureSession.
PqForgeEngineProvider
The backend that performs the low-level AEAD computation.
PqHybridAgreementMode
Which hybrid PqForgeHybridKeyAgreement runs.
PqHybridConcatOrder
Join order for PqForgeCombiner.concatenateSharedSecrets.
PqHybridProfile
Hash digest engine + security-profile pairing used by PqForgeCombiner.
PqKemAlgorithm
ML-KEM parameter sets supported by pqforge.
PqRsaHash
Digest used by PqRsa. The signer hashes the message.
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).
PqX509Algorithm
PqX509Failure
PqxdhKem
The KEM named by the PQXDH specification's example. Not X-Wing.
SpqrKem
The braid's KEM. Not X-Wing.

Extensions

PqForgeAsync on PqForge
Engine-pluggable (and optionally hybrid) one-shot envelope encryption.
PqForgeCryptographyExtensions on SecretKey
Hybrid combining for the modern package:cryptography crypto.SecretKey type.

Constants

mlKemPrivateKeyLengths → const Set<int>
ML-KEM private-key sizes (FIPS 203). None of them is a ratchet secret.
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 with preHash: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.
compositeSignatureLength(String algorithmId) → int
Raw signature length for an ML-DSA, SLH-DSA, or classical signature id.
compositeSignatureMessage(Uint8List message, Uint8List? context) → Uint8List
Domain-separated message every composite leg signs.
requireDsaContext(Uint8List? context) → void
requireLength(String name, Uint8List value, int expected) → void
requireWritableEnvelopeMetadata(Map<String, Object?> metadata) → void
Throws PqForgeException when caller-supplied metadata already contains one of the pqForgeReservedMetadataKeys. Every encrypt path (sync, async, streaming) runs this before merging its own markers in.
signClassicalLeg(PqClassicalSignatureKeyPair key, Uint8List message) → Future<Uint8List>
Signs one classical leg. P-256 and Ed25519 use the provider. P-384 and P-521 call the PointyCastle classes directly so a custom provider does not have to grow new methods.
verifyClassicalLeg(PqClassicalSignatureAlgorithm algorithm, Uint8List publicKey, Uint8List message, Uint8List signature) → Future<bool>
Verifies one classical leg.

Typedefs

PqClassicalSignatureVerifier = bool Function(Uint8List message, Uint8List signature)
PqKeyCustodyDelete = FutureOr<void> Function(String storageId)
PqKeyCustodyGet = FutureOr<Map<String, Object?>?> Function(String storageId)
PqKeyCustodyPut = FutureOr<void> Function(String storageId, Map<String, Object?> document)

Exceptions / Errors

PqForgeAuthTagException
Thrown when AEAD authentication-tag verification fails during decryption.
PqForgeException