Skip to content

Conversation

@bbug96-crkim
Copy link

@bbug96-crkim bbug96-crkim commented Dec 31, 2025

Description
This PR implements ML-DSA (Module Lattice Digital Signature Algorithm) post-quantum cryptographic signatures for model signing, providing quantum-resistant security standardized as NIST FIPS 204. Additionally, it includes documentation cleanup to fix broken links and remove redundant files.

Motivation
As quantum computing advances, traditional cryptographic signatures (like ECDSA) will become vulnerable to attacks. ML-DSA provides quantum-resistant security for long-term model integrity protection (10+ years). This implementation ensures that models signed today will remain verifiable even in a post-quantum era.

Problems Solved

  1. Quantum Vulnerability: Existing ECDSA signatures are vulnerable to quantum computer attacks
  2. Long-term Security: Models requiring extended verification periods need quantum-resistant signatures
  3. Standards Compliance: NIST FIPS 204 standardization provides industry-accepted post-quantum security
  4. Key Security: Password-protected private keys using AES-256-GCM encryption
  5. Documentation Issues: Fixed broken NIST FIPS 204 links and incorrect file paths

Changes Made
Core Features (Commit 4caedff)

  • ML-DSA Signing Implementation: Complete support for all three security levels (ML-DSA-44, ML-DSA-65, ML-DSA-87)
  • CLI Integration: New sign ml-dsa and verify ml-dsa commands with password protection
  • Key Encryption: AES-256-GCM encryption for private keys with PBKDF2 key derivation (100,000 iterations)
  • Key Management Tool: ml_dsa_key_tool.py for encrypting/decrypting/verifying keys
  • Python API: use_ml_dsa_signer() and use_ml_dsa_verifier() methods in Config classes
  • Comprehensive Testing:
    • 7 integration tests in api_test.py
    • 8 CLI tests in cli_ml_dsa_test.py
    • Shell test scripts for version compatibility
    • 100% test pass rate
  • Documentation:
  • Extensive examples in [ml_dsa_examples.md]
  • README updates with post-quantum cryptography section

Documentation Cleanup (Commit 0023a82)

  • Fixed broken NIST FIPS 204 URL (/publications/detail/ → /pubs/)
  • Fixed ML-DSA implementation documentation link in README
  • Fixed [ml_dsa_key_tool.py] source path resolution
  • Removed redundant documentation files ([ml_dsa_implementation.md, ml_dsa_testing.md)
  • Updated Quantum-Safe column in signature size comparison table
  • Fixed relative paths in documentation links

Breaking Changes
None - this is a purely additive feature. Existing ECDSA and Sigstore signing methods remain unchanged.

Performance Notes

  • Signature Size: ML-DSA signatures are ~50x larger than ECDSA (acceptable tradeoff for quantum resistance)
  • Signing Speed: Slightly slower than ECDSA but still sub-second
  • Verification Speed: Comparable to traditional methods
Checklist
  • [v] All commits are signed-off, using DCO
  • [v] All new code has docstrings and type annotations
  • [v] All new code is covered by tests. Aim for at least 90% coverage. CI is configured to highlight lines not covered by tests.
  • [v] Public facing changes are paired with documentation changes
  • [v] Release note has been added to CHANGELOG.md if needed

Added

  • ML-DSA Post-Quantum Signatures: Added support for NIST FIPS 204 ML-DSA (Module Lattice Digital Signature Algorithm) quantum-resistant signatures with three security levels (ML-DSA-44, ML-DSA-65, ML-DSA-87).
  • CLI Commands: Added model_signing sign ml-dsa and model_signing verify ml-dsa commands with password protection support.
  • Key Encryption: Added AES-256-GCM encryption for ML-DSA private keys with PBKDF2 key derivation (100,000 iterations).
  • Key Management Utility: Added scripts/ml_dsa_key_tool.py for encrypting, decrypting, and verifying ML-DSA keys.
  • Python API: Added use_ml_dsa_signer() and use_ml_dsa_verifier() methods to signing.Config and verifying.Config classes.
  • Dependencies: Added optional [pqc] extra for post-quantum cryptography support (dilithium-py).

Fixed

  • Fixed broken NIST FIPS 204 documentation links (updated from /publications/detail/ to /pubs/ URL structure).
  • Fixed ML-DSA implementation documentation link in README.md.
  • Fixed ml_dsa_key_tool.py source path resolution for correct module imports.
  • Updated Quantum-Safe column values in ML-DSA signature size comparison table.

Changed

  • Removed redundant documentation files (ml_dsa_implementation.md, ml_dsa_testing.md) to streamline documentation.

Documentation

  • Added comprehensive ML-DSA examples guide (docs/ml_dsa_examples.md) with 750+ lines covering all use cases.
  • Updated README.md with Post-Quantum Cryptography section including key generation, signing, verification, and password-protected keys.

Dependencies:

  • dilithium-py: ML-DSA implementation (install with pip install model-signing[pqc])
  • cryptography: Already in dependencies, used for AES-GCM encryption
  • Model signature changes (additions, deletions, updates)
  • API additions: new functions, new arguments, new supported signing methods, etc.
  • Anything noteworthy to an administrator using model-signing package (err on the side of over-communicating)
  • New features and improvements, including behavioural changes, UI changes and CLI changes
  • Bug fixes and fixes of previous known issues
  • Deprecation warnings, breaking changes, or compatibility notes

@bbug96-crkim bbug96-crkim requested review from a team as code owners December 31, 2025 18:42
Implement ML-DSA (FIPS 204) post-quantum cryptographic signatures
for model signing, providing quantum-resistant security. This adds
complete CLI integration, password-protected key encryption, and
comprehensive testing infrastructure.

ML-DSA (Module Lattice Digital Signature Algorithm) is a NIST-
standardized post-quantum signature scheme that provides security
against both classical and quantum computer attacks. This implementation
supports all three security levels (ML_DSA_44, ML_DSA_65, ML_DSA_87)
corresponding to NIST security levels 2, 3, and 5.

The implementation addresses the need for long-term security in model
signing as quantum computers become more capable. While ML-DSA
signatures are larger than traditional ECDSA signatures (~3-5KB vs
~70 bytes), this is an acceptable tradeoff for quantum resistance.

Core Implementation:
 - Add sign_ml_dsa.py module with Signer and Verifier classes
 - Implement AES-256-GCM encryption for private key protection
 - Add PBKDF2-HMAC-SHA256 key derivation (100,000 iterations)
 - Auto-detect encrypted vs raw private keys
 - Support all three ML-DSA security variants (44/65/87)

CLI Integration:
 - Add 'sign ml-dsa' command with --password and --variant options
 - Add 'verify ml-dsa' command with variant support
 - Integrate with existing ignore-paths and hashing config

Key Management:
 - Add ml_dsa_key_tool.py utility for key encryption/decryption
 - Support encrypted key format with 56-byte overhead
 - Provide key verification functionality

Testing:
 - Add 7 integration tests in api_test.py covering all scenarios
 - Add 8 CLI tests in cli_ml_dsa_test.py
 - Add shell test scripts for all variants and version compatibility
 - Generate test keys and pre-signed test data
 - Achieve 100% test pass rate across all test suites

Documentation:
 - Add ml_dsa_examples.md with 750+ line comprehensive guide
 - Add ml_dsa_implementation.md with technical details
 - Add ml_dsa_testing.md for test infrastructure
 - Update README.md with post-quantum cryptography section
 - Document password protection and security levels

Files Added:
 - src/model_signing/_signing/sign_ml_dsa.py (391 lines)
 - tests/cli_ml_dsa_test.py (427 lines, 8 tests)
 - tests/_signing/sign_ml_dsa_test.py
 - scripts/ml_dsa_key_tool.py (180 lines)
 - scripts/tests/test-sign-verify-ml-dsa.sh (176 lines)
 - scripts/tests/test-verify-v1.1.0-ml-dsa.sh
 - docs/ml_dsa_examples.md (750+ lines)
 - docs/ml_dsa_implementation.md
 - docs/ml_dsa_testing.md
 - scripts/tests/keys/ml-dsa/ (test keys)
 - scripts/tests/v1.1.0-ml-dsa/ (test data)

Files Modified:
 - src/model_signing/_cli.py (+161 lines)
 - src/model_signing/signing.py (add use_ml_dsa_signer)
 - src/model_signing/verifying.py (add use_ml_dsa_verifier)
 - tests/api_test.py (+270 lines, TestMLDSASigning class)
 - README.md (add post-quantum section)
 - scripts/tests/test-sign-verify-allversions.sh (add ML-DSA)

Dependencies:
 - dilithium-py: ML-DSA implementation
 - cryptography: AES-GCM encryption

Breaking Changes: None - purely additive changes

Performance Impact: ML-DSA signatures are larger (2-5KB) and slower
to generate/verify than ECDSA, but provide quantum resistance.

Security Notes:
 - Private keys can be encrypted with AES-256-GCM
 - Key derivation uses PBKDF2 with 100,000 iterations
 - Signature sizes: ML_DSA_44 (~2.4KB), ML_DSA_65 (~3.3KB),
   ML_DSA_87 (~4.6KB)

Signed-off-by: chungrae.kim <[email protected]>
Copy link
Author

@bbug96-crkim bbug96-crkim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed

@bbug96-crkim
Copy link
Author

@sigstore/model-transparency-codeowners
I'd like to request your review of this change. If I'm mishandling the review process, please let me know so I can correct it.

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