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.
- 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:cryptographyand 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 || 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.
- PqForgeSignatureComposer
- Signs and verifies an explicit set of signature legs.
- PqForgeStreamCipher
-
Encrypts and decrypts files in bounded memory using the
.pqfsstreaming 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: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.
- 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
.pqfsstreaming envelope. - PqStreamingHeader
-
The fixed, canonical, signed part of a
.pqfsstreaming-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
-addextline, or several. This is the subsetopenssl requses for a name, a key usage, an extended key usage, and basic constraints. - PqX509Certificate
- PqX509DirectoryName
-
directoryName, the DERName. - 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.
Enums
- 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.
- 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
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. -
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
metadataalready 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< 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