bash-pqc-keygen 🐚

Shell utilities and a Go cryptographic helper tool to generate and manage NIST-compliant Post-Quantum Cryptography (PQC) keys and local Certificate Authorities (CA) locally.

Features

• NIST Post-Quantum Cryptography Support:
  • ML-DSA-65 (FIPS 204 Module-Lattice-Based Digital Signature Algorithm, formerly Dilithium3) for signatures.
  • ML-KEM-768 (FIPS 203 Module-Lattice-Based Key-Encapsulation Mechanism, formerly Kyber768) for key exchange.
• Local Certificate Authority (CA) Simulation:
  • Initialize a Root CA (generating keys and self-signed certificates).
  • Issue and sign developer certificates (e.g., signing a server's ML-KEM key using the CA's ML-DSA signing key).
  • Validate certificate signature chains and dates.
• Cryptographic File Signing:
  • Create detached signatures for arbitrary files.
  • Validate signatures using public keys.
• Standard PEM Formats:
  • Keys are wrapped in clean, developer-friendly PEM delimiters:
    • -----BEGIN ML-DSA PRIVATE KEY----- / -----BEGIN ML-DSA PUBLIC KEY-----
    • -----BEGIN ML-KEM PRIVATE KEY----- / -----BEGIN ML-KEM PUBLIC KEY-----
    • -----BEGIN PQC CERTIFICATE----- (custom Base64-JSON encoded metadata)

Directory Structure

• cmd/pqc-tool/: Go helper source code containing the cryptographic logic.
  • main.go: Key generators, Ed25519-like lattice signers, and certificate managers.
• pqc-keygen.sh: Shell wrapper for generating keys.
• pqc-sign.sh: Shell wrapper for file signing and signature validation.
• pqc-ca.sh: Shell CA manager for root CA setup, certificate signing, and validation.
• Makefile: Script automation and integration test suite.

Getting Started

Prerequisites

Ensure you have Go installed (version 1.25+ recommended for native crypto/mlkem support).

Compile and Run Test Suite

To compile the pqc-tool helper binary, configure execute permissions for the shell scripts, and execute the integration test suite:

make test

Shell Script Usage Reference

1. Key Generation (pqc-keygen.sh)

Generate an ML-DSA-65 keypair (default):

./pqc-keygen.sh --type mldsa65 --out my_sig_key

Generate an ML-KEM-768 keypair:

./pqc-keygen.sh --type mlkem768 --out my_kem_key

2. File Signing & Verification (pqc-sign.sh)

Sign a target file:

./pqc-sign.sh sign --key client.key --file data.txt --out data.txt.sig

Verify a signature:

./pqc-sign.sh verify --key client.pub --file data.txt --sig data.txt.sig

3. Local Certificate Authority (pqc-ca.sh)

Initialize a Root CA (generates ca.key, ca.pub, and the self-signed ca.crt):

./pqc-ca.sh init-ca --out ca --subject "PQC Root CA"

Sign a client or server public key (using the Root CA key to issue server.crt):

./pqc-ca.sh sign --pub server.pub --ca-cert ca.crt --ca-key ca.key --out server.crt --subject "PQC Server Node"

Verify a signed certificate:

./pqc-ca.sh verify --cert server.crt --ca-cert ca.crt

Certificate Structure

To support lightweight local execution without dynamic X.509 library dependencies, certificates are represented as signed JSON payloads base64-encoded inside standard PEM delimiters:

{
  "subject": "PQC Server Node",
  "issuer": "PQC Root CA",
  "not_before": "2026-06-06T01:54:30Z",
  "not_after": "2027-06-06T01:54:30Z",
  "pub_key_algo": "mlkem768",
  "pub_key_hex": "616263...",
  "signature": "6661696c..."
}

License

MIT License.