pqsum: a coreutils-style file signing CLI on liboqs — would value review of two design choices

[iA7maz]

Hi all,

I've built pqsum, a small Rust CLI that uses liboqs (via liboqs-rust) to give sha256sum-style ergonomics for post-quantum file signatures:

$ pqsum --keygen --algo ML-DSA-65 --out keys/
$ pqsum --sign release.tar.gz --key keys/private.key
$ pqsum --verify release.tar.gz --pub keys/public.key
release.tar.gz: OK

It exposes ML-DSA 44/65/87, all twelve SLH-DSA parameter sets and Falcon 512/1024, plus a signed-manifest mode that covers file names as well as contents. Files are streamed through a digest so a 2 GiB image signs in about 3.5 MiB of RAM.

To be clear about scope: there is no new cryptography here. liboqs does all key generation, signing and verification. pqsum is framing, file formats and CLI behaviour — which is precisely why I'd like a second opinion on the two places where I made a construction choice rather than following a standard.

Repo: https://github.com/iA7maz/pqsum · Release: https://github.com/iA7maz/pqsum/releases/tag/v0.1.0

1. I rolled my own domain separation instead of using the context string

Rather than signing file bytes, pqsum signs a canonical, length-prefixed encoding, through the plain OQS_SIG_sign:

"pqsum/v1/detached\x00"
  || u16 len | signature algorithm name
  || u16 len | digest algorithm name
  || u16 len | digest

The intent is that a signature can't be relabelled as covering a different digest algorithm, or replayed into a different context (manifests and key fingerprints use distinct prefixes).

Since writing that I noticed OQS_SIG_sign_with_ctx_str and FIPS 204's ctx parameter, which is the standard's own mechanism for exactly this.

Question: should a downstream tool prefer the context string over an in-message prefix? My hesitation is that context support isn't uniform across schemes, so using it would make pqsum's behaviour algorithm-dependent, and I'd need a fallback for algorithms without it — which reintroduces the bespoke encoding for some subset. Is there a recommended way to handle that heterogeneity, or a pattern other OQS-adjacent tools have settled on?

2. Bespoke pre-hash rather than HashML-DSA

pqsum streams the file through SHA3-512 and signs the digest with pure ML-DSA. FIPS 204 standardises HashML-DSA for the pre-hashed case, with a defined encoding of the digest OID and value.

Question: is a bespoke digest-then-pure-sign construction a mistake when a standardised pre-hash variant exists? I chose it for uniformity — the same code path drives ML-DSA, SLH-DSA and Falcon, and the digest algorithm is recorded in the signature file so verification is self-describing. But it does mean pqsum signatures aren't interoperable with anything that implements HashML-DSA properly, and I'd rather understand the cost now than after people depend on the format.

3. Secret key memory

Secret keys are held in zeroizing buffers on the Rust side and are never rendered in Debug output. Is there anything liboqs-specific I should be doing beyond that — does liboqs zero its own internal buffers on free, and is there a recommended practice around how oqs-sys hands back secret key material?

4. Are algorithm identifier strings safe to persist?

Signature files record the algorithm as the liboqs name (ML-DSA-65, SPHINCS+-SHA2-128f-simple) so that adding schemes needs no format change. A test asserts the internal table matches Algorithm::name() so a rename is caught at build time rather than by writing files nobody can read back.

Question: are those names intended as stable identifiers across liboqs releases, or is persisting them on disk relying on something I shouldn't?

On maturity

pqsum is 0.1.0 and unaudited, and its SECURITY.md says so plainly, along with what it does not do: no key distribution, no revocation or expiry, and private keys unencrypted at rest. It also carries liboqs's own note that the library is research-quality and that its algorithm implementations have not all had the review that, say, OpenSSL's have — I'd rather that reach users through my docs than surprise them later.

Happy to go into detail on any of the above, and grateful for the work that made this possible in the first place.

[Kxrma47]

For a v1 format, I would keep your canonical framing as the mandatory cross-algorithm contract rather than make verification semantics depend on optional context-string support. For ML-DSA interoperability, however, sign(SHA3-512(file)) with pure ML-DSA should be treated as a pqsum-specific scheme, not HashML-DSA: FIPS 204 defines separate domain separation and pre-hash identification for HashML-DSA. Supporting that standardized path explicitly would avoid two constructions sharing an ambiguous label.

I would also persist pqsum-owned numeric identifiers and map them to liboqs names, instead of making implementation strings part of the permanent file format. Zeroizing the Rust-owned key buffer is good, but document that guarantee only for memory pqsum controls; avoid promising that every temporary allocation below the FFI boundary is wiped. References: FIPS 204 and the liboqs signature API.

[iA7maz]

Thank you — that is exactly the kind of answer I was hoping for, and it changed
the plan in three places.

Canonical framing stays. I had drafted a change to move domain separation
onto the ctx parameter and have dropped it. Your reasoning is the same

hesitation that made me ask: making verification semantics depend on optional,
per-algorithm context support is worse for a v1 format than one mandatory
cross-algorithm contract. The length-prefixed encoding stays as the required
path for every scheme.

Agreed on not sharing a label with HashML-DSA. To be explicit: pqsum has
never claimed HashML-DSA anywhere in its docs or code, but “not claiming it”
is weaker than saying what it is, so FORMAT.md will now state plainly that
sign(SHA3-512(file)) over pure ML-DSA is a pqsum-specific scheme, distinct
from FIPS 204’s pre-hash variant and its separate domain separation and PH
identification.

I would like to support the standardized path too, as a separately identified
scheme rather than a reinterpretation of the existing one. That looks blocked
for now: liboqs 0.13 exposes only pure ML-DSA-{44,65,87}, and M′ for
HashML-DSA begins 0x01 where the pure ctx path prepends 0x00, so there is
no way to compose it without reaching ML-DSA.Sign_internal. If HashML-DSA
support is something liboqs is considering exposing, I would rather wait for
that than build a parallel implementation underneath it — is that on the
roadmap, or should downstream tools plan around its absence?
Adopting pqsum-owned numeric identifiers. This one I had wrong, and the
reasoning is worth stating because I had actively defended the opposite. I
chose liboqs name strings so the format would be self-describing and need no
registry, and even added a test asserting our table matches
Algorithm::name() exactly — which, put plainly, made an upstream naming
decision part of a permanent on-disk format and wrote a test to enforce that
coupling. A registry is cheap to maintain; a format migration is not.

Format v2 will store a numeric id owned by pqsum and map it to the backend
internally, so an upstream rename touches one table rather than every
signature ever written. The text manifest keeps human-readable names since it
is meant to be read, but those become pqsum’s canonical names resolved through
the same registry rather than inherited from the backend. v1 files stay
readable, and that test inverts to assert the mapping resolves rather than that
the strings match.
Zeroization wording scoped. Fair, and the current phrasing does overreach —
the README says private keys are “wiped from memory on drop” with no
qualification. That will be scoped to memory pqsum owns, with an explicit note
that temporary allocations below the FFI boundary are not something a wrapper
can promise about.
All of this is now written down at
https://github.com/iA7maz/pqsum/blob/main/docs/ROADMAP.md, with the items your
answer settled marked as decided, so the reasoning does not just live in this
thread.

Much appreciated — this was worth asking before anyone depends on the format.