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
- PqAeadSuite
- The AEAD-suite container marker (R3).
- PqArtifactSignature
- PqBytes
- PqCallbackKeyCustodyStore
- 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.
- 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.
- PqForgeStreamCipher
-
Encrypts and decrypts files in bounded memory using the
.pqfsstreaming envelope. Construct once and reuse; the engine is the hardware-acceleration lever. - 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. - PqOffloadRequest
- PqOffloadResponse
- PqPackEntry
- One file to pack: its archive-relative path and its on-disk source path.
- PqPassphraseKeyCustody
- 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
- 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
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.
- 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.
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