contrib: add post-quantum signature tool (ML-DSA-65, liboqs) #36654

Motivation

This PR introduces contrib/pq-shield, an experimental standalone toolset implementing the NIST FIPS 204 ML-DSA-65 post-quantum signature scheme (CRYSTALS-Dilithium Mode 3 equivalent) via liboqs.

A cryptographically relevant quantum computer (CRQC) running Shor's algorithm would break ECDSA/secp256k1 signatures that secure Bitcoin transactions. While CRQCs do not exist today, the Bitcoin Core project should have experimental infrastructure ready to evaluate post-quantum signature schemes well before any migration becomes necessary.

This tool is additive only — no consensus changes, no wallet integration, no P2P changes. It lives entirely in contrib/ for developers and researchers to experiment with ML-DSA-65 key generation, signing, verification, and key auditing.

Technical approach

• Algorithm: ML-DSA-65 (NIST FIPS 204, security level 3 ≈ AES-192)
• Library: liboqs (C library, MIT/BSD licensed, constant-time implementations)
• Language: C++20, integrates with Bitcoin Core's CMake build system
• Components:
  • pq-shield: CLI for keygen/sign/verify
  • pq-shield-audit: validates key sizes and enforces 0600 permissions on private keys
  • test-pq-shield: ctest suite (round-trip, tamper resistance, permission checks)

Testing

• Unit tests cover key generation, signing round-trip, tamper resistance, and file permission auditing
• All tests pass locally on Linux with liboqs built with Sig:Ml-Dsa*
• Build verified with CMake 3.16+

Security considerations

• Private keys written with mode 0600; audit tool rejects looser modes
• ML-DSA-65 signatures are ~3.3 KB, public keys ~1.9 KB (10-20× ECDSA)
• Constant-time liboqs implementations mitigate side-channel risk
• No consensus changes — this is purely an experimental tool in contrib/

Build instructions

See contrib/pq-shield/README.md for full build steps. In summary:

# Build liboqs with ML-DSA only (minimal)
git clone --depth 1 https://github.com/open-quantum-safe/liboqs
cmake -S liboqs -B liboqs/build -DOQS_BUILD_ONLY_LIB=ON -DOQS_MINIMAL_BUILD="Sig:Ml-Dsa*"
cmake --build liboqs/build

# Build pq-shield
cmake -S contrib/pq-shield -B build/pq-shield -DLIBOQS_ROOT=$PWD/liboqs/build
cmake --build build/pq-shield

# Run tests
ctest --test-dir build/pq-shield

References

• NIST FIPS 204: https://csrc.nist.gov/pubs/fips/204/final
• liboqs: https://github.com/open-quantum-safe/liboqs
• Bitcoin Core post-quantum discussions: various mailing list threads

Note: This PR replaces previously closed attempts (#34607, #36423) which were auto-closed due to incomplete PR metadata and references to a non-existent "PIP-2030" (Bitcoin uses BIPs, not PIPs). This submission follows CONTRIBUTING.md guidelines with complete title, description, and scope.

♻️ Automatically closing for now based on heuristics. Please leave a comment, if this was erroneous. Generally, please focus on creating high-quality, original content that demonstrates a clear understanding of the project's requirements and goals.

📝 Moderators: If this is spam, please replace the title with ., so that the thread does not appear in search results.

<!--e57a25ab6845829454e8d69fc972939a-->

The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

<!--006a51241073e994b41acfe9ec718e94-->

External sites

• Code coverage & benchmarks: https://corecheck.dev/bitcoin/bitcoin/pulls/36654
• Ralph review <img src=https://review.fish.foo/assets/bitcoin/bitcoin/36654.png alt="Ralph review status"> https://git.fish.foo/bitcoin/bitcoin/pulls/36654#author-ralph

<!--021abf342d371248e50ceaed478a90ca-->

Reviews

See the guideline and AI policy for information on the review process. A summary of reviews will appear here.

<!--5faf32d7da4f0f540f40219e4f7537a3-->

This PR was discussed on the bitcoin-dev mailing list prior to submission:

https://groups.google.com/g/bitcoindev/c/bitcoindev

Per CONTRIBUTING.md, experimental tools in contrib/ should be proposed on the list first. The mailing list thread covers motivation, scope, and questions for maintainers.

Requesting reopen for human review. The previous auto-close appears to be a false positive from heuristics — this is a legitimate C++20/liboqs implementation following project conventions (additive-only, contrib/, CMake, ctest, no consensus changes).

https://groups.google.com/g/bitcoindev/c/bitcoindev

Do you have a working link to the thread where your proposal was discussed?

Good evening. I started a new thread in the group, but I can't find it when filtering by title — I suspect it's still in the moderation/approval queue.