Skip to content

README.md

Latest commit

 

History

History
47 lines (38 loc) · 2.01 KB

README.md

File metadata and controls

47 lines (38 loc) · 2.01 KB

pqf CLI

pqf is the command-line wrapper over the PostQuantum.FileFormat library.

What this is. pqf is a demonstration / dogfooding CLI for the PostQuantum.FileFormat library and the broader PostQuantum.* ecosystem. It exists so you can try the PQF container format, generate the right pair of identities, encrypt and decrypt real files, and cross-check against the reference test vectors and the Rust implementation. It is also useful as a readable reference for how to drive the library's public API.

What this is NOT. It is not intended as a production library dependency. Other projects should depend on PostQuantum.FileFormat directly — the pqf tool's API surface (its commands, exit codes, output shape) is not a stability contract and may change between previews.

EXPERIMENTAL preview; not externally audited; do not use to protect irreplaceable data.

Commands

  • pqf keygen --type encrypt --public-out recipient.pub.pem --private-out recipient.identity.json
  • pqf keygen --type sign --public-out signer.pub.pem --private-out signer.identity.json
  • pqf encrypt --in plain.bin --out file.pqf --recipient recipient.pub.pem [--recipient recipient2.pub.pem] [--signing-key signer.identity.json] [--chunk-size 65536]
  • pqf decrypt --in file.pqf --out plain.out.bin --identity recipient.identity.json [--mode authenticated|streaming]
  • pqf inspect --in file.pqf [--json]
  • pqf fingerprint --public-key recipient.pub.pem

Key file formats

  • Public keys are armored PEM files using labels from spec §7:
    • PQF PUBLIC KEY
    • PQF SIGNING PUBLIC KEY
  • Private identities are JSON files written by pqf keygen and consumed by pqf encrypt / pqf decrypt.

Exit codes

  • 0: success
  • 2: usage error
  • 3: I/O or permissions error
  • 4: key parse/format error
  • 5: cryptographic refusal (PqfRefusalReason)
  • 10: internal error

In streaming mode, post-hoc signature/footer failures return exit code 5 and are reported on stderr with post-hoc-auth=true.