Skip to content

feat: add export and post-quantum signing#11

Open
akeemjenkins wants to merge 1 commit into
mainfrom
feat/export-pq-sign
Open

feat: add export and post-quantum signing#11
akeemjenkins wants to merge 1 commit into
mainfrom
feat/export-pq-sign

Conversation

@akeemjenkins

Copy link
Copy Markdown
Contributor

Summary

  • okf export — Export an entire OKF bundle as a deterministic .okf tar.gz archive. The archive is byte-reproducible (sorted paths, zeroed timestamps) so the same bundle always produces the same bytes. Output includes a manifest with per-file SHA-256 hashes, file count, total bytes, and archive hash.

  • okf sign — Post-quantum authentication for exported archives using ML-KEM-768 (FIPS 203, formerly Kyber) via HPKE (RFC 9180). Uses only the Go standard library (crypto/hpke + crypto/mlkem) — no external dependencies.

    • keygen — generate an ML-KEM-768 key pair
    • sign — seal the archive hash with HPKE using the public key
    • verify — open the HPKE ciphertext with the private key and confirm the archive hash matches (detects tampering)

Both commands are registered in the schema (okf schema) for agentic-first discovery.

How it works

ML-KEM is a key-encapsulation mechanism (KEM), not a digital signature scheme. This feature uses HPKE to achieve authenticated encryption of the archive hash:

  1. Sign: hpke.Seal(pubkey, hash) produces a ciphertext containing the encapsulated key + sealed archive hash
  2. Verify: hpke.Open(privkey, ciphertext) recovers the archive hash; if it doesn't match the actual archive hash, the archive has been tampered with

Only the holder of the corresponding private key can open the ciphertext, proving the archive was sealed for that key and has not been modified.

Test plan

  • 5 export tests: archive creation, determinism, hidden dir skipping, non-directory error, manifest file hashes
  • 4 sign tests: key generation, sign+verify happy path, tampered archive detection, wrong key rejection
  • Full test suite passes (44 tests, race-enabled)
  • go vet clean
  • End-to-end: export → keygen → sign → verify cycle verified
okf export ./testdata/valid -o bundle.okf
okf sign bundle.okf keygen
okf sign bundle.okf sign --pub <pubkey> -o sig.json
okf sign bundle.okf verify --priv <privkey> --sig sig.json
# { "verified": true }

- export: deterministic tar.gz archive of entire bundle with per-file
  SHA-256 manifest and archive hash
- sign: post-quantum authentication via ML-KEM-768 (FIPS 203) and HPKE
  (RFC 9180) using only the Go standard library (crypto/hpke +
  crypto/mlkem) — no external dependencies
- sign keygen: generate ML-KEM-768 key pair
- sign sign: seal archive hash with HPKE using public key
- sign verify: open HPKE ciphertext with private key, confirm archive
  hash matches (detects tampering)
- Schema entries for both commands (agentic-first discovery)
- 9 new tests (5 export, 4 sign) covering happy path, determinism,
  tampered archive, wrong key, hidden dir skipping
- Updated README with export + sign documentation

End-to-end verified: export → keygen → sign → verify cycle works.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant