PQ pqforge

A product of Yardenah PQ

Encrypt files, folders, text, media, webhooks, tokens, and server sessions.

pqforge turns the pqcrypto ML-KEM (FIPS 203), ML-DSA (FIPS 204), and SLH-DSA (FIPS 205) primitives into application-ready cryptography: KEM-DEM envelopes, RFC 9180 HPKE, X-Wing (draft-connolly-cfrg-xwing-kem-11, not a .pqf algorithm), AES-256-GCM and ChaCha20-Poly1305 AEAD, an RFC 8439 ChaCha20 keystream, X25519/X448/Ed25519/Ed448/ECDSA-P256/ECDSA-P384/ECDSA-P521/RSA hybrids and signatures, P-256/P-384 ECDH for TLS hybrid groups and P-521 ECDH for HPKE, X.509 certificates and PKCS#10 requests that OpenSSL req reads, bounded-memory gigabyte streaming, multi-recipient envelopes, Argon2id-wrapped key custody, named recipes, and a universal CLI. SLH-DSA is composed into keygen, custody, and detached sign/verify; envelopes and hybrid-sign remain ML-DSA-only. compose-sign is an opt-in 2-leg or 3-leg signature. PqEcdsaP521 is not the P-521 HPKE share and not a TLS group. The core is pure Dart and web-safe — no dart:ffi.

  • Pure Dart, no FFI
  • Web-safe core
  • FIPS 203/204-aligned via pqcrypto
  • MIT licensed
pqforge recipe pipeline from payloads to post-quantum envelopes
3ML-KEM profiles
3ML-DSA profiles
15named recipes
1universal CLI

Recipe catalog

Build with named operations, not ad hoc crypto glue.

CLI: keygen, encrypt, decrypt

Local File Vault

developer machines, backup jobs, admin laptops, server batch jobs

encryptFileBytes, decryptFileBytes, encryptAsync, PqEnvelope
CLI: encrypt-folder, decrypt-folder

Folder Archive

case files, release bundles, evidence folders, internal archives

encryptFolderEntry, decryptFolderEntry
CLI: pack, unpack

Folder Pack Archive

many small files, site exports, evidence bundles, dataset shards

PqForgePackService (package:pqforge/pqforge_io.dart)
CLI: encrypt / encrypt-media (auto .pqfs at 8 MiB)

Large Files And Media Streaming

gigabyte media, datasets, disk images, backups, VM snapshots

PqForgeStreamCipher.encryptFile, decryptStream (package:pqforge/pqforge_io.dart)
CLI: repeatable --recipient-public on encrypt commands

Multi-Recipient Envelopes

shared vaults, team archives, escrow, break-glass recipients

encryptAsync, PqMultiRecipient, PqRecipientSpec
CLI: encrypt-text, decrypt-text, sign --kind text

Text Snippets

notes, secrets, prompts, policy snippets, short messages

sealText, openText, signText, verifyText
CLI: encrypt-media, decrypt-media, sign --kind media

Media Assets

photos, audio, video, PDFs, campaign media, identity images

sealMedia, openMedia, signMedia, verifyMedia
CLI: sign, verify

Document Signing

contracts, reports, certificates, approvals, policy documents

signDocument, verifyDocument
CLI: hybrid-sign, hybrid-verify, compose-sign, compose-verify, ecdsa-sign, ecdsa-verify, cert req, cert issue, cert sign

Hybrid And Classical Signatures

release artifacts, firmware, long-lived approvals, dual-trust signing

PqForgeHybridSigner, PqForgeSignatureComposer, PqEcdsaP256, PqEcdsaP384, PqEcdsaP521, PqEd25519, PqEd448, PqRsa, PqX509, dualSign, dualVerify
CLI: sign --kind webhook, verify

Webhook Integrity

payment callbacks, audit delivery, server-to-server events

signWebhook, verifyWebhook
library

Signed Tokens

API capabilities, admin actions, short-lived grants

issueToken, verifyToken
library

Private Email Payloads

encrypted mail bodies, secure notifications, outbound archive mail

sealEmail, openEmail
library

Government And Medical Records

public-sector records, patient records, registry payloads

encryptRecord, appendSignedLogEntry
CLI/library

Software Artifacts

release bundles, firmware, packages, configuration rollouts

signArtifact, verifyArtifact
core import (package:pqforge/pqforge.dart)

Hybrid Server Sessions

Serverpod, API services, local agents, backend handshakes

PqForgeHybridKeyAgreement, PqForgeSecureSession

Universal CLI

Local files and server jobs get the same envelope model.

Generate reusable public keys and wrapped secret keys, then encrypt or sign files, folders, text, and media without writing application code.

export PQFORGE_PASSPHRASE='from-your-secret-manager'
dart run pqforge keygen --profile maximum --key-id vault --out-dir keys --passphrase-env PQFORGE_PASSPHRASE
dart run pqforge encrypt-folder --recipient-public keys/vault.kem.public.json --in-dir ./records --out-dir ./records.pqf
dart run pqforge decrypt-folder --recipient-secret keys/vault.kem.secret.wrapped.json --passphrase-env PQFORGE_PASSPHRASE --in-dir ./records.pqf --out-dir ./records.open
dart run pqforge sign --kind media --signer-secret keys/vault.sign.secret.wrapped.json --passphrase-env PQFORGE_PASSPHRASE --in cover.png --mime-type image/png --out cover.sig.json
dart run pqforge compose-sign --ml-dsa-secret keys/vault.sign.secret.wrapped.json --classical-secret keys/vault.ecdsa-p256.secret.wrapped.json --passphrase-env PQFORGE_PASSPHRASE --in cover.png --out cover.composite.json

Use cases

From local vaults to server sessions.

Local File Vault

developer machines, backup jobs, admin laptops, server batch jobs

Folder Archive

case files, release bundles, evidence folders, internal archives

Folder Pack Archive

many small files, site exports, evidence bundles, dataset shards

Large Files And Media Streaming

gigabyte media, datasets, disk images, backups, VM snapshots

Multi-Recipient Envelopes

shared vaults, team archives, escrow, break-glass recipients

Text Snippets

notes, secrets, prompts, policy snippets, short messages

Media Assets

photos, audio, video, PDFs, campaign media, identity images

Document Signing

contracts, reports, certificates, approvals, policy documents

Hybrid And Classical Signatures

release artifacts, firmware, long-lived approvals, dual-trust signing

Webhook Integrity

payment callbacks, audit delivery, server-to-server events

Signed Tokens

API capabilities, admin actions, short-lived grants

Private Email Payloads

encrypted mail bodies, secure notifications, outbound archive mail

Government And Medical Records

public-sector records, patient records, registry payloads

Software Artifacts

release bundles, firmware, packages, configuration rollouts

Hybrid Server Sessions

Serverpod, API services, local agents, backend handshakes

Profiles

Pick a security margin that matches the lifetime.

compact

ML-KEM-512 + ML-DSA-44

smaller demos, constrained payloads, and low-bandwidth signatures

balanced

ML-KEM-768 + ML-DSA-65

default application and server profile

maximum

ML-KEM-1024 + ML-DSA-87

long-lived records, archives, media, and high-value artifacts

Documentation

Everything users and agents need to stay inside the boundary.

On this site

The recipe homepage stays. The guides sit next to it.

Claim boundary

Composition, not certification.

pqforge is the application layer built on pqcrypto ML-KEM/ML-DSA. It does not claim CMVP/FIPS 140 validation, hard constant-time Dart behavior, or hard memory erasure. RC4 is rejected.

FAQ

Answers before integration.

What is pqforge?

pqforge is a pure-Dart post-quantum application toolkit. It turns the ML-KEM, ML-DSA, and SLH-DSA primitives from pqcrypto into encrypted files, folders, text, media, email payloads, records, signed documents, signed webhooks, signed tokens, release artifacts, tamper-evident logs, identity bindings, hybrid sessions, wrapped key custody, and a universal CLI. SLH-DSA (FIPS 205) is composed into keygen, custody, and detached sign/verify; envelopes and hybrid-sign remain ML-DSA-only. compose-sign can take one SLH-DSA leg when that key is passed.

How is pqforge different from pqcrypto?

pqcrypto is the primitives layer: FIPS 203 ML-KEM, FIPS 204 ML-DSA, FIPS 205 SLH-DSA (all 12 parameter sets), SHA-2, and SHA-3/SHAKE with zero runtime dependencies. pqforge is the application layer built on top of it: KEM-DEM envelopes, AES-256-GCM and ChaCha20-Poly1305 AEAD, RFC 9180 HPKE (X25519, X448, P-256, P-384, P-521), X25519/Ed25519/ECDSA-P256 hybrids plus opt-in ECDSA-P384 and ECDSA-P521, P-256/P-384 ECDH for TLS hybrid groups and P-521 ECDH for HPKE, key custody, streaming, multi-recipient envelopes, named recipes, compose-sign, and a CLI. SLH-DSA is composed into keygen and detached sign/verify, and is not used for envelopes or hybrid-sign. PqEcdsaP521 is not the P-521 HPKE share and not a TLS group. Use pqcrypto for raw algorithms; use pqforge to ship a feature.

Does pqforge compose SLH-DSA?

Yes, for key generation, custody, and detached signatures. pqcrypto 0.4.4 ships all 12 FIPS 205 SLH-DSA parameter sets. pqforge exposes them as PqSlhDsaAlgorithm / PqSlhDsaPrimitives, emits a profile-matched SHAKE-f key from keygen (compact 128f, balanced 192f, maximum 256f), and accepts those keys on sign/verify (document, text, media, artifact, webhook) and on issueToken, appendSignedLogEntry, and createIdentityBinding via slhDsa:. Envelope headers, streaming signatures, and hybrid-sign remain ML-DSA-only because SLH-DSA signatures are 8-50 KiB and the s sets are slow. compose-sign can take one SLH-DSA leg when you pass that key. That does not put SLH-DSA on an envelope or on hybrid-sign.

Is pqforge post-quantum / quantum-safe?

Yes. It uses NIST FIPS 203 ML-KEM for key establishment and FIPS 204 ML-DSA for signatures through pqcrypto, so confidentiality and signatures resist quantum attacks. Hybrid modes add X25519, Ed25519, or ECDSA-P256 so security also holds if a classical break ever lands on the post-quantum scheme.

Does pqforge work on Flutter and the web?

Yes. The core import, package:pqforge/pqforge.dart, is pure Dart and web-safe with no dart:ffi, so the same code runs on the Dart VM, Flutter, and the web. Gigabyte-scale dart:io file streaming lives behind package:pqforge/pqforge_io.dart. On Flutter, FlutterCryptography.enable() adds hardware-backed AEAD.

Can pqforge encrypt gigabyte files without running out of memory?

Yes. Inputs at or above 8 MiB automatically use the .pqfs streaming container: a signed master header followed by independently authenticated frames, with a working set of roughly two frames regardless of total size. Per-frame sequence and final-flag binding prevent truncation, reordering, duplication, and splicing.

Can one ciphertext target multiple recipients?

Yes. Repeat --recipient-public on the encrypt commands (or use PqMultiRecipient in the library). The payload is sealed exactly once and the DEM key is wrapped to each additional recipient as a metadata entry, costing about 1.6 KB and 2 ms per extra recipient instead of a full re-encryption. Entries can individually be hybrid, and it works for both one-shot envelopes and .pqfs streams.

Which ciphers does pqforge support, and which is fastest?

AES-256-GCM (default) and ChaCha20-Poly1305, on a pure-Dart PointyCastle engine or the native package:cryptography engine. Where hardware AES is not dispatched, ChaCha20-Poly1305 measures about 30.4 MiB/s versus 11.5 MiB/s for AES-256-GCM (about 2.6x); with hardware AEAD both exceed 1 GB/s. RC4 is rejected.

What is the difference between the cryptography and pure-dart engines?

--engine cryptography (the default) uses package:cryptography and is roughly 10x faster than the PointyCastle reference even in pure Dart, and hardware-backed on Flutter. --engine pure-dart uses PointyCastle only. The wire formats are engine-independent, so an envelope sealed by one engine opens on the other.

Is pqforge FIPS validated?

No. pqforge composes FIPS 203/204/205-aligned primitives from pqcrypto, but is not a CMVP or FIPS 140 validated cryptographic module. A PqFipsMode deployment layer restricts suites to AES-256-GCM and PBKDF2-HMAC-SHA256 key wrapping (SP 800-132) and allows a swappable DRBG for validated-module deployments.

Can pqforge sign and verify documents and releases?

Yes. It provides ML-DSA detached signatures, recipe-bound signatures for documents, text, media, artifacts, tokens, and webhooks, SLH-DSA (FIPS 205) detached signatures via keygen and sign/verify, hybrid ML-DSA + Ed25519/ECDSA-P256 signatures, and standalone ECDSA-P256 (RFC 6979 deterministic nonces, canonical low-S). AES never signs.

Can I sign a gigabyte artifact without reading it all into memory?

Yes. hybrid-sign --digest and ecdsa-sign --digest sign the streamed SHA-256 of the input under a domain-separation label, recorded in the signature JSON so the verify commands re-hash automatically. Envelope signatures are likewise computed over a header-plus-payload hash, so signing cost does not scale with payload size.

Can pqforge bundle a whole folder into one file?

Yes. pqforge pack collapses a whole folder into one encrypted streaming archive with a single KEM encapsulation and signature for the tree, roughly 100x less ciphertext overhead than per-file envelopes for a thousand small files. pqforge unpack restores it path-traversal-safe, and a failed unpack removes everything it created.

What does hybrid mean in pqforge?

Two independent hard problems guard the same secret. Hybrid encryption combines the ML-KEM shared secret with an ephemeral X25519 exchange using the IETF concatenate-then-KDF construction, so confidentiality holds while either Module-LWE or Curve25519 stands. Hybrid signatures pair an ML-DSA signature with an Ed25519 or ECDSA-P256 signature over the same message. That hybrid command also accepts opt-in ECDSA-P384 and ECDSA-P521. compose-sign is separate: 2 or 3 legs you name, among ML-DSA, SLH-DSA, Ed25519, and those ECDSA curves. ECDSA-P384 and ECDSA-P521 are keygen --classical opt-ins, not the default set. PqEcdsaP521 is not a TLS group and not the HPKE share. Library-only NIST P-256/P-384 ECDH (uncompressed SEC1, x-coordinate secret) is exported for TLS hybrid groups; it is not the X25519 initiate/accept handshake and does not overload PqEcdsaP256. PqEcdsaP384 is the P-384 signature, not that shared secret. PqX509 parses, mints, and checks an X.509 certificate, and it writes the PKCS#10 request openssl req verifies. cert req, cert issue, and cert sign are that CLI. It is not a trust store and not TLS.

Where does the CLI store keys?

In the directory passed to keygen --out-dir. Public keys are raw JSON. Secret keys are wrapped JSON when a passphrase source is supplied. keygen emits the full hybrid keyset by default: ML-KEM and ML-DSA, a profile-matched SLH-DSA SHAKE-f key, plus X25519, Ed25519, and ECDSA-P256. --no-slh-dsa skips hash-based keys; --slh-dsa selects specific FIPS 205 sets; --slh-dsa-only emits only SLH-DSA.

Are CLI keys password protected?

Yes when keygen is run with --passphrase-env, --passphrase-file, or --passphrase. Wrapped secrets use Argon2id for passphrase-to-key derivation and AES-256-GCM for authenticated encryption of the key bytes, with AAD binding the key kind, algorithm, and key id.

Can I inspect an encrypted file without decrypting it?

Yes. pqforge inspect describes any .pqf, .pqfs, key, or signature file: format, profile, suite (for example ML-KEM-1024 + X25519 then HKDF-SHA-512 then AES-256-GCM), engine, signature, recipients, and metadata, without needing a secret key.

Does pqforge provide identity, trust, or replay protection?

No. pqforge composes cryptographic building blocks. Public-key trust, identity vetting, replay windows, authorization policy, session storage, and TLS remain the application's responsibility. A self-provided public key is not an identity.

Is the published package pure Dart? Does it use FFI?

Yes, it is pure Dart with no dart:ffi, so it runs everywhere Dart runs, including the web. The OpenSSL interop harness used in CI to prove byte-compatibility with the system libcrypto is a separate publish_to: none dev package and is never shipped.

What HPKE does pqforge implement?

RFC 9180 Hybrid Public Key Encryption as PqHpke. Modes are base, PSK, auth, and authPSK. KEMs are DHKEM(X25519, HKDF-SHA256), DHKEM(X448, HKDF-SHA512), DHKEM(P-256, HKDF-SHA256), DHKEM(P-384, HKDF-SHA384), and DHKEM(P-521, HKDF-SHA512). X-Wing is an additional KEM, HpkeKem.xWing, id 0x647A, from draft-connolly-cfrg-xwing-kem-11. It is not a DHKEM. Base and PSK work. Auth and authPSK throw. It is not a FIPS construction. FIPS mode rejects it at PqHpke and PqForgeHybridKeyAgreement. There is no BoringSSL or OpenSSL evidence for 0x647A. pqforge hpke writes magic XW01, not PQF1. The custom hybrid is unchanged. Key-schedule KDFs are HKDF-SHA256, HKDF-SHA384, and HKDF-SHA512. AEADs are AES-128-GCM, AES-256-GCM, ChaCha20-Poly1305, and export-only. A sender seals, a recipient opens, and export does not use the sequence number. X448 is RFC 7748 on Dart integers and is not a constant-time claim. BoringSSL 0.20261020.0 is checked for base and auth, both directions, on X25519 and P-256, with HKDF-SHA256 and HKDF-SHA384 and the three AEADs. That API has no PSK and no X448 or P-521. OpenSSL 3.5.9 OSSL_HPKE is checked for all four modes, both directions, on X448 and P-521, with HKDF-SHA256 and HKDF-SHA512 and the three AEADs. That is not an OpenSSL claim for X25519, P-256, or P-384. This is not TLS and not a FIPS module. .pqf and .pqfs are unchanged.

What is the ChaCha20 keystream for?

PqSymmetricPrimitives.chacha20 is RFC 8439 ChaCha20. It takes a 32-byte key, a 12-byte nonce, a caller-supplied 32-bit block counter, and returns 1 to 4096 keystream bytes. QUIC header protection uses the first 5 bytes. It is the same Dart engine as chacha20Poly1305Encrypt, so it runs on dart2js. It is not an AEAD: the AEAD forces counter 1 and appends a Poly1305 tag.

Does pqforge read and mint X.509 certificates?

Yes. PqX509 parses, mints, checks one signature, and checks a path against caller-supplied anchors. now is an argument. It writes the PKCS#10 request openssl req verifies. cert req, cert issue, cert sign, cert inspect, and cert verify are the CLI. Signature algorithms on that path include ECDSA P-256 and P-384, Ed25519, RSA PKCS#1 and RSASSA-PSS, and ML-DSA. It is not a trust store and it does not fetch AIA, OCSP, or CT.

Does pqforge support RC4?

No. RC4 is not post-quantum, not authenticated encryption, not in pqcrypto, and not safe for new systems. pqforge offers AES-256-GCM and ChaCha20-Poly1305 instead.

Can AES sign documents?

No. AES encrypts; ML-DSA, hybrid signatures, or ECDSA-P256 sign and verify. Encryption and signing are distinct operations with distinct keys.

Can encrypt/decrypt/pack/unpack report progress, and what does --quiet do?

encrypt, decrypt, encrypt-text, decrypt-text (when --out is set), encrypt-media, decrypt-media, encrypt-folder, decrypt-folder, pack, unpack, sign, verify, hybrid-sign, hybrid-verify, ecdsa-sign, and ecdsa-verify print a live, throttled progress line. Folder jobs forward streaming byte progress from background isolates over a SendPort so concurrent files keep separate live totals; pack/unpack add per-file SUCCESS or FAILED with in-entry byte progress. hybrid-sign/ecdsa-sign --digest reports hashing progress. keygen reports per-key wrapping progress when a passphrase is used. --quiet / -q mutes those per-file lines, skip warnings, and keygen created-file listings; the completion summary still prints. keygen --quiet still warns if raw secret-key JSON was written. A folder job that fails any file exits non-zero. Pack/unpack failures before the first entry report a job-level failure. Listing skips sockets, FIFOs, broken symlinks, and unreadable files instead of failing the whole tree. decrypt-text without --out writes plaintext to stdout and does not attach a progress line.

Which apps can use pqforge?

Local file vaults, folder and pack archives, server export jobs, gigabyte media and dataset pipelines, multi-recipient shared vaults, webhook systems, token issuers, document workflows, email payload protection, government and medical record systems, signed release and firmware pipelines, tamper-evident logs, and hybrid Serverpod/API server sessions.