docs: prepare PQF for external cryptographic review#29
Merged
Conversation
Adds the artifacts a reviewer needs to engage quickly, makes the spec honest about what has and hasn't been reviewed, and fixes a handful of pre-X-Wing stale references that survived the 0.6 cutover. New documents ------------- - spec/PQF-OVERVIEW.md (3 pages) — goals, threat model, primitives, wire format, the five decisions worth a reviewer's focus. The "read this first" entry point for someone landing cold on the repo. - spec/SECURITY-CONSIDERATIONS.md — IETF-style consolidated argument: assumed primitive properties → claimed file-level guarantees → per-construction analysis (KEM combiner, AAD-binding glue, per-chunk AEAD, hybrid signature composition, footer integrity) → known unanalyzed compositions → out-of-scope adversary capabilities → operational obligations. Cite-able from the IETF draft. - spec/external-review/REVIEW-STATUS.md — transparent layer-by-layer table of what's been reviewed (X-Wing combiner inherits IND-CCA ROM/QROM from Barbosa et al. 2024), what's been LLM-assisted only, what hasn't been touched. Names the gaps. - spec/external-review/cfrg-mailing-list-post.md — ready-to-send draft for cfrg@irtf.org plus sending etiquette notes (plain text, list moderation, follow-up cadence). - spec/external-review/researcher-outreach-template.md — per-recipient template with one personalized paragraph the author fills in. Lists five candidate researcher *types* (not specific names) so targeting reasoning is in the doc. - spec/external-review/workshop-abstract.md — ~450-word abstract targetable at Real World Crypto or RWPQC; venue notes inline. - spec/external-review/POLISH-NOTES.md — punch list from a spec read-through, separating items already fixed inline from recommendations the author can take, leave, or modify. - test-vectors/QUICKSTART.md — two-command path from `git clone` to watching the independent Rust reader accept every .NET-written vector. Plus a path for regenerating from seed and a path for replaying the X-Wing draft KAT against published IETF vectors. Spec fixes inline (PQF-SPEC-v1.md, all §10.3-class editorial — no wire-format change) --------------------------------------------------------------------- - §6.5 cost-of-trial: said "ML-KEM-1024 decapsulation, one HKDF derivation"; corrected to ML-KEM-768 and SHA3-256 (the X-Wing combiner). Pre-X-Wing leftover from 0.5 / earlier. - §11.1 Properties-PQF-provides table: two rows said "in salt" (file_id and recipient_index). X-Wing has no salt slot; corrected to "in AEAD AAD" and added the pk_X-binding note for the cross-recipient row. - §12.1: extended the negative-vector list with TV-NEG-023..033 (the header-schema refusal classes that actually ship), each with its RefusalReason. - §12.2: rewrote the test-vector file format section to describe the actual shipped schema (single manifest.json + cases/ dir, with Identities[] and Vectors[] arrays) and pointed at manifest.schema.json as authoritative. The previous example was a pre-implementation sketch that the project outgrew. README ------ - Fixed the "Cryptographic review wanted" section: it pointed at the dropped HkdfCombiner.cs and described the old in-house construction. Now points at XWingKem.cs and the standardized X-Wing combiner. - Added pointers to PQF-OVERVIEW.md, REVIEW-STATUS.md, and test-vectors/QUICKSTART.md as the recommended reviewer entry points. - Restructured the feedback section into Issue / Discussion / refusal-vector PR / private security channels. Nothing in this PR is a wire-format change. v1.0.x freeze is unaffected.
github-actions
Bot
added
spec
systemslibrarian
added a commit
that referenced
this pull request
Jun 11, 2026
…able Post-merge polish for the external-review pass (PR #29): - spec/SECURITY-CONSIDERATIONS.md §5.3: heading was line-wrapped across two source lines; strict CommonMark renderers can break on this. Join into a single heading line. - spec/PQF-SPEC-v1.md: drop the trailing "Document history" table. It only covered 0.1.0–0.3.1, missing 0.5.0 and 0.6.0, while the top-of-document "Change log" is the authoritative running record. Per POLISH-NOTES.md P-4, the cleaner option is to leave one source of truth instead of syncing two. POLISH-NOTES.md P-3 (Barbosa author list: spec §14.2 vs. the new OVERVIEW/SECURITY-CONSIDERATIONS citations) is intentionally NOT touched here — it needs a citation lookup against the X-Wing draft authorship vs. the IND-CCA proof paper authorship before it's edited in either direction. Resolve before sending the CFRG post. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the artifacts a reviewer needs to engage quickly, makes the spec honest about what has and hasn't been reviewed, and fixes a handful of pre-X-Wing stale references that survived the 0.6 cutover.
Nothing here changes the wire format. v1.0.x freeze is unaffected (everything is §10.3-class editorial).
What's new
What's edited
Verification
This is documentation + spec-editorial; no code touched. Sanity checks worth running before merging:
If anything reads wrong, edit in this branch before merging.
🤖 Generated with Claude Code