pqc

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 29, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

README

pqc

Post-quantum migration is not just an algorithm swap. Systems need to generate new key material, keep private keys out of application code, rotate versions, measure TLS and certificate readiness, preserve audit history, and experiment with draft certificate formats without letting draft churn contaminate the core key manager.

pqc is a Go post-quantum key-management sandbox for that transition. It provides a core library, CLI, local file stores, an optional HTTP API daemon, TLS/PQC readiness inspection, tamper-evident audit and transparency checkpoints, and isolated artifact profiles for PQ certificate/signature approaches.

The first supported primitives are:

  • ML-KEM-768 for envelope encryption.
  • ML-DSA-65 for signatures.
  • ML-DSA-87 for signatures.

The implementation uses Cloudflare CIRCL for PQC primitives and the Go standard library for HKDF and AES-GCM.

The project is designed for teams that need to prototype crypto-agility and PQC migration workflows before committing to a production KMS, HSM, Vault, cloud secret manager, or PKI platform.

Quick Start

Fastest path from install to useful output:

go install github.com/helsingin/pqc/cmd/pqc@latest
pqc tls readiness cloudflare.com:443
pqc readiness scan --target cloudflare.com:443

Example output from pqc tls readiness cloudflare.com:443 on June 29, 2026:

target: cloudflare.com:443
policy: public-web-2029
ready_for_47_day_certs: false
certificate_validity_days: 91
days_until_expiry: 41
renewal_window_risk: low
recommended_renewal_cadence_days: 30
recommended_renewal_lead_time_days: 17
san_count: 5
san_dcv_reuse_risk: low
certificate_chain_bytes: 2591
certificate_count: 3
leaf_signature_algorithm: ECDSA-SHA256
leaf_public_key_algorithm: ECDSA
hybrid_pqc_key_exchange: true
verified: true
verification_mode: system
warning: certificate_validity: leaf certificate validity exceeds the public-web-2029 target

The companion pqc readiness scan --target cloudflare.com:443 command emits a JSON readiness report. For the same scan it produced:

{
  "score": 75,
  "level": "watch",
  "summary": "watch readiness with risks: automation-risk"
}

Live endpoint results will change as certificates rotate and TLS deployments change.

Build the CLI and daemon:

make build

The binaries are written to:

bin/pqc
bin/pqcd

Create a KEM key and a signing key:

bin/pqc keys create --type ml-kem-768 --id service-a
bin/pqc keys create --type ml-dsa-65 --id signer-a

Encrypt, decrypt, sign, and verify:

bin/pqc encrypt --key service-a < message.json > message.pqc
bin/pqc decrypt < message.pqc > message.out

bin/pqc sign --key signer-a artifact.tar > artifact.sig
bin/pqc verify --key signer-a artifact.tar artifact.sig

Run the Go test suite:

make test

Install from the local checkout:

go install ./cmd/pqc
go install ./cmd/pqcd

Documentation

The README is the publishing overview. Detailed usage lives in docs/:

  • CLI Reference: local and remote key operations, age store, audit checkpoints, transparency bundles, TLS readiness, readiness scoring, MTC log/proof modeling, and treehead cache commands.
  • Artifact Profiles: mtc, x509-ml-dsa, composite-x509, and fndsa profile versions, inputs, issue/verify flows, estimates, and smoke tests.
  • Daemon, HTTP API, And Transport: pqcd, HTTP endpoints, bearer auth, HTTPS, mTLS, authorization policy, environment variables, and hybrid PQ TLS transport boundaries.

What It Does

pqc handles common post-quantum key-management and migration workflows:

  • Generates versioned ML-KEM-768, ML-DSA-65, and ML-DSA-87 keys.
  • Encrypts and decrypts envelopes using ML-KEM, HKDF-SHA-256, and AES-256-GCM.
  • Signs and verifies payloads with ML-DSA.
  • Rotates keys while preserving old decrypt and verify versions.
  • Stores key metadata and public fingerprints for inventory and transparency.
  • Supports a plain local file store and a passphrase-encrypted age file store.
  • Runs as a local CLI or as a remote CLI talking to pqcd.
  • Serves an optional HTTP API for centralized key operations.
  • Supports bearer-token auth, HTTPS, mTLS, and mTLS identity authorization policy for the daemon.
  • Prefers TLS 1.3 hybrid PQ key exchange groups for remote CLI transport.
  • Emits metadata-only JSONL audit events.
  • Builds signed Merkle checkpoints for audit logs.
  • Builds signed transparency bundles over key inventory, TLS endpoint facts, and optional revocation manifests.
  • Maintains experimental MTC log, checkpoint, proof, revocation, and treehead cache utilities.
  • Scans TLS endpoints for PQ/hybrid key exchange, certificate chain facts, and public-web 2029 lifecycle readiness.
  • Produces an opinionated readiness score across local keys and TLS targets.
  • Isolates PQ certificate/signature approaches behind artifact profiles: mtc, x509-ml-dsa, composite-x509, and fndsa.

Post-Quantum Context

The project currently focuses on three practical migration tracks:

  • Operational key management: generate, rotate, store, encrypt, decrypt, sign, verify, and audit PQ key usage.
  • TLS and certificate readiness: inspect current TLS endpoints, detect hybrid PQ key exchange, measure chain size, and model CA/B Forum 47-day certificate lifecycle pressure.
  • Certificate/signature experiments: keep MTC, ML-DSA in X.509, Composite X.509, and FN-DSA logic behind artifact profile boundaries so draft updates stay localized.

It intentionally separates hybrid PQ transport from PQ-signed certificate authentication. pqcd can negotiate hybrid PQ TLS key exchange, but its server and client certificates are normal X.509 certificates.

Typical Pattern

local CLI
   |
   | local store mode
   v
 file or age key store

remote CLI
   |
   | HTTP or HTTPS JSON API
   v
 pqcd daemon
   |
   +-- file or age key store
   +-- audit JSONL
   +-- optional mTLS identity policy

For migration and readiness work:

pqc inventory/readiness scan
   |
   +-- local or remote key inventory
   +-- TLS endpoint inspection
   +-- public-web-2029 lifecycle policy
   +-- signed transparency checkpoint
   +-- optional revocation manifest

For certificate/signature experiments:

pqc profiles
   |
   +-- mtc
   +-- x509-ml-dsa
   +-- composite-x509
   +-- fndsa

Each profile owns its draft-specific inputs, metadata, estimates, and verification behavior.

Status

This is an early open source scaffold. The default local file store writes private key material to JSON files with 0600 permissions under $PQC_STORE_DIR or ~/.pqc/keys. The age-backed file store encrypts key files with passphrase-based age encryption. Production deployments should still prefer careful secret management, Vault-backed stores, HSM-backed stores, cloud secret stores, or platform secret managers.

CLI

The CLI command groups are:

  • keys: create, rotate, list, show, and export public keys.
  • encrypt / decrypt: ML-KEM envelope encryption.
  • sign / verify: ML-DSA signatures.
  • audit: tamper-evident Merkle checkpoints for JSONL audit logs.
  • transparency: signed inventory checkpoints and revocation manifests.
  • inventory: crypto-agility inventory reports for stores and TLS endpoints.
  • tls: TLS/PQC readiness inspection.
  • readiness: opinionated readiness scoring over stores and TLS targets.
  • mtc: experimental Merkle Tree Certificate log/proof simulator.
  • profiles: PQ certificate/signature artifact profile discovery, inspection, and sizing.
  • issue / verify-artifact: issue and verify signed artifact profile documents.

Key-manager commands can operate locally against a store or remotely through pqcd. In remote mode only the daemon opens the key store. Commands that read keys accept manager access flags like --store, --remote, --token, and remote TLS options.

Create keys:

pqc keys create --type ml-kem-768 --id service-a
pqc keys create --type ml-dsa-65 --id signer-a

Run with a remote daemon:

pqc keys list --remote http://127.0.0.1:8080 --token change-me
pqc encrypt --remote http://127.0.0.1:8080 --token change-me --key service-a < message.json > message.pqc

Inspect TLS readiness and generate a combined readiness score:

pqc tls readiness --json example.com:443
pqc readiness scan --store ./dev-keys --target example.com:443 > readiness.json

Run the experimental MTC log/proof flow:

pqc mtc log init --log mtc-log.json
pqc mtc issue --log mtc-log.json --subject example.com --public-key org-root.public.json
pqc mtc checkpoint --store ./mtc-keys --log mtc-log.json --sign-key org-root > mtc-checkpoint.json
pqc mtc prove --log mtc-log.json --leaf 0 > mtc-proof.json
pqc mtc verify --store ./mtc-keys --proof mtc-proof.json --checkpoint mtc-checkpoint.json

Detailed command flows are in CLI Reference. Artifact profile versions and issue/verify smoke tests are in Artifact Profiles.

What You Can Build With It

PQC Key-Management Prototype

Use the core library or CLI to generate ML-KEM and ML-DSA keys, rotate versions, encrypt/decrypt envelopes, sign artifacts, and verify old versions while a service migration is underway.

Crypto-Agility Inventory Job

Run pqc inventory scan and pqc readiness scan against local key stores and TLS endpoints to produce repeatable reports for migration planning, public-web certificate lifecycle readiness, and chain-size risk.

Signed Transparency Bundle

Build signed transparency checkpoints over key inventory, TLS target state, and optional revocation manifests. This gives teams a portable record of what keys and public fingerprints existed at a point in time.

MTC Experiment Harness

Use the experimental MTC log, checkpoint, proof, revocation, and treehead cache commands to model Merkle Tree Certificate workflows without depending on browser PKI infrastructure.

PQ Certificate Profile Lab

Use artifact profiles to issue and verify signed JSON artifacts for MTC, ML-DSA-in-X.509, Composite X.509, and FN-DSA experiments. The profile boundary keeps draft-specific behavior isolated.

Remote Key Service

Run pqcd as a local or private-network daemon so CLI users do not open the key store directly. Add bearer-token auth, HTTPS, mTLS, and mTLS authorization policy as needed for the test environment.

What an Integration Needs

An integration normally chooses:

  • Store mode: local file, local age, or remote pqcd.
  • Key IDs and rotation policy for KEM and signing keys.
  • Audit location if operation metadata should be checkpointed later.
  • TLS trust configuration for remote pqcd access.
  • Whether private operations are local-only or sent to a daemon.
  • Whether inventory and readiness reports are target-only, store-only, or both.
  • Which artifact profiles are allowed in the project, especially for draft formats.
  • Where transparency bundles, revocation manifests, and MTC treehead caches are stored.

For production-facing work, treat this repository as a migration and integration toolkit rather than a replacement for a hardened KMS or HSM deployment.

What It Is Not

pqc is not:

  • A production HSM, Vault, or cloud KMS replacement.
  • A browser-trusted WebPKI CA.
  • A full ACME CA or certificate issuance authority.
  • A PQC-signed X.509 implementation for the public WebPKI.
  • An implementation of browser MTC validation.
  • An OpenSSL trust store generator.
  • A guarantee that observed TLS endpoints are quantum-safe.
  • A substitute for private-key custody, access-control, and incident-response design.

The project does implement useful pieces for experimentation: key operations, hybrid-PQ transport preference, signed artifacts, transparency checkpoints, revocation manifests, MTC log/proof modeling, treehead cache utilities, TLS readiness facts, and opinionated readiness scoring.

Library

store, err := file.New("./keys")
if err != nil {
    panic(err)
}
manager := pqc.NewManager(store)

_, err = manager.Generate(context.Background(), pqc.GenerateRequest{
    ID:        "service-a",
    Algorithm: pqc.AlgorithmMLKEM768,
})
if err != nil {
    panic(err)
}

env, err := manager.Encrypt(context.Background(), "service-a", []byte("hello"), pqc.EncryptOptions{})
if err != nil {
    panic(err)
}

plaintext, err := manager.Decrypt(context.Background(), env, pqc.EncryptOptions{})
if err != nil {
    panic(err)
}
_ = plaintext

HTTP API And Remote Mode

Start the optional daemon:

pqcd --addr 127.0.0.1:8080

Use it from the CLI:

pqc keys list --remote http://127.0.0.1:8080 --token "$PQC_API_TOKEN"

The daemon supports bearer-token auth, HTTPS, mTLS client certificates, and mTLS identity authorization policy. Its HTTP API exposes key inventory, create/rotate, encrypt/decrypt, and sign/verify operations.

Full daemon setup, endpoint list, TLS flags, authorization policy format, environment variables, and transport boundaries are documented in Daemon, HTTP API, And Transport.

Audit And Transparency

CLI operation audit is opt-in through --audit-log FILE or PQC_AUDIT_LOG. Daemon audit is opt-in through pqcd --audit FILE or PQC_AUDIT_LOG. Events are JSONL records with operation metadata only:

{
  "time": "2026-06-28T20:00:00Z",
  "operation": "key.generate",
  "key_id": "service-a",
  "algorithm": "ML-KEM-768",
  "key_version": 1,
  "success": true
}

Audit records intentionally exclude private keys, public key bytes, plaintext, ciphertext, signatures, shared secrets, and request bodies.

When using --remote, audit belongs on pqcd; remote CLI commands reject --audit-log.

Audit checkpoints make a JSONL audit file tamper-evident. The checkpoint stores the SHA-256 Merkle root, line count, audit digest, and an ML-DSA signature from the configured signing key:

pqc audit checkpoint --audit ./audit.jsonl --sign-key audit-signer > audit-checkpoint.json
pqc audit verify --audit ./audit.jsonl --checkpoint audit-checkpoint.json

Transparency bundles checkpoint the current key inventory and optional TLS targets. The bundle contains the normalized inventory and a signed Merkle root:

pqc transparency checkpoint --sign-key org-root --target example.com:443 > transparency.json
pqc transparency verify transparency.json

Revocation events are recorded in a JSON revocation manifest and can be folded into the transparency bundle:

pqc transparency revoke --key service-a --reason key-compromise --revocations ./revocations.json
pqc transparency checkpoint \
  --sign-key org-root \
  --target example.com:443 \
  --include-revocations \
  --revocations ./revocations.json \
  > transparency.json
pqc transparency verify transparency.json

The checkpoint commits to revocation_count, revocation_root, and revocation_digest. Verification recomputes those fields from the embedded manifest, so removing or editing a revocation event breaks the signed bundle.

Store Encryption

Two local stores are available:

  • file: plain JSON keysets protected only by filesystem permissions.
  • age: binary .age keysets encrypted with passphrase-based age encryption.

age is a small modern file-encryption tool and Go library. This project uses its scrypt passphrase mode for the first encrypted local backend, which avoids inventing a custom password-based encryption format.

Age store filenames are derived from SHA-256 of the key ID, so directory listings do not directly reveal key names.

Prefer PQC_AGE_PASSPHRASE or --age-passphrase-file over --age-passphrase, because command-line arguments can be visible in shell history and process listings.

Envelope Design

ML-KEM-768 is used as a KEM, not as direct encryption:

  1. Encapsulate with the recipient public key.
  2. Derive a 256-bit AEAD key with HKDF-SHA256.
  3. Encrypt the payload with AES-256-GCM.
  4. Store metadata, key version, salt, KEM ciphertext, nonce, and AEAD ciphertext in a JSON envelope.

Main Files

  • manager.go: core key generation, rotation, encryption, decryption, signing, verification, and public-key export.
  • envelope.go: ML-KEM/HKDF/AES-GCM envelope structure.
  • algorithm.go: supported algorithm names and aliases.
  • checkpoint.go: audit checkpoints, inventory reports, transparency bundles, and Merkle helpers.
  • revocation.go: revocation manifest model and validation.
  • readiness.go: opinionated readiness scoring over inventory and TLS facts.
  • tlsinspect.go: TLS endpoint inspection and hybrid PQ key exchange detection.
  • tlsreadiness.go: public-web 2029 certificate lifecycle readiness policy.
  • mtclog.go: experimental MTC log, checkpoint, proof, and verification model.
  • mtctreeheads.go: experimental MTC treehead cache parsing, verification, and export model.
  • profile/: stable artifact profile plugin interfaces and shared artifact signing helpers.
  • profiles/: built-in artifact profiles for MTC, ML-DSA in X.509, Composite X.509, and FN-DSA.
  • store/file/: plain local JSON key store.
  • store/agefile/: passphrase-encrypted age local key store.
  • cmd/pqc/: CLI commands.
  • cmd/pqcd/: optional HTTP API daemon.

Verification

make test
make build

Build outputs:

bin/pqc
bin/pqcd

Additional useful checks before publishing changes:

gofmt -w .
git diff --check
go test ./...
make build

Tested Environments

The codebase is currently developed and tested with the Go toolchain available in this repository's local environment. The project uses Go's standard TLS stack for hybrid PQ key exchange groups and Cloudflare CIRCL for ML-KEM and ML-DSA primitives.

Remote TLS behavior depends on the Go version used to build the binaries, because hybrid PQ TLS group support is provided by the Go standard library.

Security

This is an early open source scaffold and should be treated as a migration and integration toolkit.

Important boundaries:

  • The plain file store writes private key material to local JSON files with filesystem permissions only.
  • The age store encrypts local key files with a passphrase, but passphrase handling still matters.
  • Remote decrypt and sign send operation inputs to pqcd; this is by design because the daemon owns the private keys.
  • TLS transport can negotiate hybrid PQ key exchange, but the X.509 certificates used for TLS authentication are classical certificates.
  • Artifact profile documents are application-level signed JSON artifacts, not browser-trusted certificates.
  • Audit logs intentionally exclude private keys, public key bytes, plaintext, ciphertext, signatures, shared secrets, and request bodies.
  • MTC commands model log/checkpoint/proof mechanics for development and testing; they do not create browser-trusted WebPKI certificates.
  • Readiness scores are operational guidance based on observed facts, not a cryptographic proof that an endpoint or organization is quantum-safe.

License

Apache-2.0. See LICENSE.

Summary

pqc is a practical post-quantum key-management and migration sandbox. It combines ML-KEM and ML-DSA key operations, local and remote key-store modes, audit and transparency checkpoints, TLS lifecycle readiness, MTC modeling, and isolated PQ certificate/signature artifact profiles. The goal is to make PQC migration workflows concrete and testable while keeping experimental certificate formats behind clear boundaries.

Documentation

Index

Constants

View Source 
const (
	MerkleHashSHA256             = "SHA-256"
	AuditCheckpointSchema        = "pqc.audit-checkpoint.v1"
	InventoryReportSchema        = "pqc.inventory.v1"
	TransparencyCheckpointSchema = "pqc.transparency-checkpoint.v1"
	TransparencyBundleSchema     = "pqc.transparency-bundle.v1"
)
View Source 
const (
	EnvelopeSchema  = "pqc.envelope.v1"
	SignatureSchema = "pqc.signature.v1"

	KDFHKDFSHA256 = "HKDF-SHA256"
	AEADAES256GCM = "AES-256-GCM"
)
View Source 
const (
	MTCLogSchema        = "pqc.mtc-log.v1"
	MTCCheckpointSchema = "pqc.mtc-checkpoint.v1"
	MTCProofSchema      = "pqc.mtc-proof.v1"
)
View Source 
const (
	TLSVerificationSystem  = "system"
	TLSVerificationCustom  = "custom"
	TLSVerificationSkipped = "skipped"
)
View Source 
const (
	MTCTreeheadCacheSchema = "pqc.mtc-treehead-cache.v1"
)
View Source 
const (
	ReadinessScanSchema = "pqc.readiness-scan.v1"
)
View Source 
const (
	RevocationManifestSchema = "pqc.revocation-manifest.v1"
)
View Source 
const (
	TLSReadinessPolicyPublicWeb2029 = "public-web-2029"
)

Variables

View Source 
var (
	ErrKeyNotFound      = errors.New("key not found")
	ErrKeyExists        = errors.New("key already exists")
	ErrInvalidEnvelope  = errors.New("invalid envelope")
	ErrInvalidSignature = errors.New("invalid signature")
)

Functions

func ApplyTLSReadinessPolicy 

func ApplyTLSReadinessPolicy(report *InventoryReport, policyID string, now time.Time) error

func DefaultMTCTreeheadLogID 

func DefaultMTCTreeheadLogID(source string) string

func MTCLeafHash 

func MTCLeafHash(entry MTCLogEntry) (string, error)

func MTCTreeheadEntryID 

func MTCTreeheadEntryID(entry MTCTreeheadEntry) (string, error)

func MerkleRootHex 

func MerkleRootHex(leaves [][]byte) string

func ParseRevocationSubject 

func ParseRevocationSubject(subjectType, subject string) (string, string, error)

func PublicKeyFingerprint 

func PublicKeyFingerprint(publicKey []byte) string

func RevocationEventID 

func RevocationEventID(event RevocationEvent) (string, error)

func RevocationManifestDigest 

func RevocationManifestDigest(manifest RevocationManifest) (string, error)

func RevocationManifestRoot 

func RevocationManifestRoot(manifest RevocationManifest) (string, error)

func SignAuditCheckpoint 

func SignAuditCheckpoint(ctx context.Context, manager interface {
	Sign(context.Context, string, []byte, SignOptions) (*SignatureEnvelope, error)
}, checkpoint *AuditCheckpoint, signKey string) error

func SignMTCCheckpoint 

func SignMTCCheckpoint(ctx context.Context, manager interface {
	Sign(context.Context, string, []byte, SignOptions) (*SignatureEnvelope, error)
}, checkpoint *MTCCheckpoint, signKey string) error

func SignTransparencyCheckpoint 

func SignTransparencyCheckpoint(ctx context.Context, manager interface {
	Sign(context.Context, string, []byte, SignOptions) (*SignatureEnvelope, error)
}, checkpoint *TransparencyCheckpoint, signKey string) error

func ValidateRevocationManifest 

func ValidateRevocationManifest(manifest RevocationManifest) error

func VerifyAuditCheckpoint 

func VerifyAuditCheckpoint(r io.Reader, checkpoint *AuditCheckpoint, publicKey *PublicKey) error

func VerifyMTCProof 

func VerifyMTCProof(proof *MTCProof, checkpoint *MTCCheckpoint, publicKey *PublicKey) error

func VerifyTransparencyBundle 

func VerifyTransparencyBundle(bundle TransparencyBundle, publicKey *PublicKey) error

func VerifyTransparencyCheckpoint 

func VerifyTransparencyCheckpoint(report InventoryReport, checkpoint *TransparencyCheckpoint, publicKey *PublicKey) error

func VerifyTransparencyCheckpointWithRevocations 

func VerifyTransparencyCheckpointWithRevocations(report InventoryReport, revocations *RevocationManifest, checkpoint *TransparencyCheckpoint, publicKey *PublicKey) error

func VerifyWithPublicKey 

func VerifyWithPublicKey(publicKey PublicKey, message []byte, sig *SignatureEnvelope) error

VerifyWithPublicKey verifies a signature envelope against an exported public key without opening a private key store.

func WriteRevocationManifest 

func WriteRevocationManifest(w io.Writer, manifest RevocationManifest) error

Types

type Algorithm 

type Algorithm string

Algorithm identifies a supported post-quantum primitive. 

const (
	AlgorithmMLKEM768 Algorithm = "ML-KEM-768"
	AlgorithmMLDSA65  Algorithm = "ML-DSA-65"
	AlgorithmMLDSA87  Algorithm = "ML-DSA-87"
)

func ParseAlgorithm 

func ParseAlgorithm(value string) (Algorithm, error)

ParseAlgorithm accepts canonical names and common aliases used by earlier PQC drafts and libraries.

func (Algorithm) Use 

func (a Algorithm) Use() (KeyUse, error)

func (Algorithm) Validate 

func (a Algorithm) Validate() error

type AuditCheckpoint 

type AuditCheckpoint struct {
	Schema      string             `json:"schema"`
	Hash        string             `json:"hash"`
	LeafCount   int                `json:"leaf_count"`
	MerkleRoot  string             `json:"merkle_root"`
	AuditDigest string             `json:"audit_digest"`
	CreatedAt   time.Time          `json:"created_at"`
	Signature   *SignatureEnvelope `json:"signature,omitempty"`
}

func BuildAuditCheckpoint 

func BuildAuditCheckpoint(r io.Reader, now time.Time) (*AuditCheckpoint, error)

type AuditEvent 

type AuditEvent struct {
	Time       time.Time `json:"time"`
	Operation  string    `json:"operation"`
	KeyID      string    `json:"key_id,omitempty"`
	Algorithm  Algorithm `json:"algorithm,omitempty"`
	KeyVersion int       `json:"key_version,omitempty"`
	Success    bool      `json:"success"`
	Error      string    `json:"error,omitempty"`
}

AuditEvent is a metadata-only record for key manager operations. It must not contain key material, plaintext, ciphertext, signatures, or shared secrets.

type Auditor 

type Auditor interface {
	Record(context.Context, AuditEvent) error
}

Auditor records metadata-only key manager events.

type AuditorFunc 

type AuditorFunc func(context.Context, AuditEvent) error

AuditorFunc adapts a function to Auditor.

func (AuditorFunc) Record 

func (f AuditorFunc) Record(ctx context.Context, event AuditEvent) error

type EncryptOptions 

type EncryptOptions struct {
	AAD []byte
}

type Envelope 

type Envelope struct {
	Schema          string    `json:"schema"`
	KeyID           string    `json:"key_id"`
	KeyVersion      int       `json:"key_version"`
	KEM             Algorithm `json:"kem"`
	KDF             string    `json:"kdf"`
	AEAD            string    `json:"aead"`
	Salt            []byte    `json:"salt"`
	EncapsulatedKey []byte    `json:"encapsulated_key"`
	Nonce           []byte    `json:"nonce"`
	Ciphertext      []byte    `json:"ciphertext"`
	CreatedAt       time.Time `json:"created_at"`
}

Envelope contains an ML-KEM encapsulated content-encryption key and an AEAD ciphertext. Byte slices are base64 encoded when marshaled as JSON.

type FileAuditor 

type FileAuditor struct {
	// contains filtered or unexported fields
}

FileAuditor appends one JSON audit event per line.

func NewFileAuditor 

func NewFileAuditor(path string) (*FileAuditor, error)

func (*FileAuditor) Record 

func (a *FileAuditor) Record(ctx context.Context, event AuditEvent) error

type GenerateRequest 

type GenerateRequest struct {
	ID        string
	Algorithm Algorithm
}

type InventoryEntry 

type InventoryEntry struct {
	ID                   string    `json:"id"`
	Algorithm            Algorithm `json:"algorithm"`
	Use                  KeyUse    `json:"use"`
	Version              int       `json:"version"`
	CreatedAt            time.Time `json:"created_at"`
	PublicKeyFingerprint string    `json:"public_key_fingerprint"`
	RotationAgeHours     int       `json:"rotation_age_hours"`
}

type InventoryReport 

type InventoryReport struct {
	Schema          string           `json:"schema"`
	CreatedAt       time.Time        `json:"created_at"`
	Policy          string           `json:"policy,omitempty"`
	KeyStoreScanned bool             `json:"key_store_scanned,omitempty"`
	Keys            []InventoryEntry `json:"keys,omitempty"`
	Targets         []TLSReport      `json:"targets,omitempty"`
	Warnings        []string         `json:"warnings,omitempty"`
}

func BuildInventoryReport 

func BuildInventoryReport(keys []KeyMetadata, targets []TLSReport, now time.Time) InventoryReport

type KeyMetadata 

type KeyMetadata struct {
	ID        string    `json:"id"`
	Algorithm Algorithm `json:"algorithm"`
	Use       KeyUse    `json:"use"`
	Version   int       `json:"version"`
	PublicKey []byte    `json:"public_key,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

type KeyRecord 

type KeyRecord struct {
	ID         string    `json:"id"`
	Algorithm  Algorithm `json:"algorithm"`
	Use        KeyUse    `json:"use"`
	Version    int       `json:"version"`
	PublicKey  []byte    `json:"public_key"`
	PrivateKey []byte    `json:"private_key"`
	CreatedAt  time.Time `json:"created_at"`
}

type KeyUse 

type KeyUse string

KeyUse describes what an algorithm can be used for. 

const (
	KeyUseKEM       KeyUse = "kem"
	KeyUseSignature KeyUse = "signature"
)

type MTCCheckpoint 

type MTCCheckpoint struct {
	Schema      string             `json:"schema"`
	Hash        string             `json:"hash"`
	TreeSize    int                `json:"tree_size"`
	MerkleRoot  string             `json:"merkle_root"`
	GeneratedAt time.Time          `json:"generated_at"`
	Signature   *SignatureEnvelope `json:"signature,omitempty"`
}

func BuildMTCCheckpoint 

func BuildMTCCheckpoint(log MTCLog, now time.Time) (*MTCCheckpoint, error)

type MTCLog 

type MTCLog struct {
	Schema    string        `json:"schema"`
	Hash      string        `json:"hash"`
	CreatedAt time.Time     `json:"created_at"`
	Entries   []MTCLogEntry `json:"entries,omitempty"`
}

func NewMTCLog 

func NewMTCLog(now time.Time) MTCLog

func (*MTCLog) Add 

func (l *MTCLog) Add(subject, publicKeyFingerprint string, metadata map[string]any, now time.Time) (MTCLogEntry, error)

type MTCLogEntry 

type MTCLogEntry struct {
	Index                int            `json:"index"`
	Subject              string         `json:"subject"`
	PublicKeyFingerprint string         `json:"public_key_fingerprint"`
	IssuedAt             time.Time      `json:"issued_at"`
	Metadata             map[string]any `json:"metadata,omitempty"`
	LeafHash             string         `json:"leaf_hash"`
}

type MTCProof 

type MTCProof struct {
	Schema      string         `json:"schema"`
	Hash        string         `json:"hash"`
	LeafIndex   int            `json:"leaf_index"`
	TreeSize    int            `json:"tree_size"`
	Leaf        MTCLogEntry    `json:"leaf"`
	Siblings    []MTCProofNode `json:"siblings,omitempty"`
	MerkleRoot  string         `json:"merkle_root"`
	GeneratedAt time.Time      `json:"generated_at"`
}

func BuildMTCProof 

func BuildMTCProof(log MTCLog, leafIndex int, now time.Time) (*MTCProof, error)

type MTCProofNode 

type MTCProofNode struct {
	Position string `json:"position"`
	Hash     string `json:"hash"`
}

type MTCTreeheadCache 

type MTCTreeheadCache struct {
	Schema    string             `json:"schema"`
	Source    string             `json:"source,omitempty"`
	FetchedAt time.Time          `json:"fetched_at"`
	Treeheads []MTCTreeheadEntry `json:"treeheads"`
}

func NewMTCTreeheadCache 

func NewMTCTreeheadCache(source string, entries []MTCTreeheadEntry, now time.Time) MTCTreeheadCache

func ParseMTCTreeheadSource 

func ParseMTCTreeheadSource(data []byte, source string, publicKey *PublicKey, logID string, now time.Time) (MTCTreeheadCache, error)

type MTCTreeheadEntry 

type MTCTreeheadEntry struct {
	ID         string        `json:"id"`
	LogID      string        `json:"log_id"`
	Source     string        `json:"source,omitempty"`
	Checkpoint MTCCheckpoint `json:"checkpoint"`
	PublicKey  PublicKey     `json:"public_key"`
	ReceivedAt time.Time     `json:"received_at"`
}

func NewMTCTreeheadEntry 

func NewMTCTreeheadEntry(source, logID string, checkpoint MTCCheckpoint, publicKey PublicKey, now time.Time) (MTCTreeheadEntry, error)

type MTCTreeheadFinding 

type MTCTreeheadFinding struct {
	Severity string         `json:"severity"`
	Subject  string         `json:"subject"`
	Message  string         `json:"message"`
	Evidence map[string]any `json:"evidence,omitempty"`
}

type MTCTreeheadVerifyResult 

type MTCTreeheadVerifyResult struct {
	OK       bool                 `json:"ok"`
	Verified int                  `json:"verified"`
	Findings []MTCTreeheadFinding `json:"findings,omitempty"`
}

func VerifyMTCTreeheadCache 

func VerifyMTCTreeheadCache(cache MTCTreeheadCache) (*MTCTreeheadVerifyResult, error)

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

func NewManager 

func NewManager(store Store, opts ...Option) *Manager

func (*Manager) Decrypt 

func (m *Manager) Decrypt(ctx context.Context, envelope *Envelope, opts EncryptOptions) (plaintext []byte, err error)

func (*Manager) Encrypt 

func (m *Manager) Encrypt(ctx context.Context, keyID string, plaintext []byte, opts EncryptOptions) (envelope *Envelope, err error)

func (*Manager) ExportPublic 

func (m *Manager) ExportPublic(ctx context.Context, id string) (publicKey *PublicKey, err error)

func (*Manager) Generate 

func (m *Manager) Generate(ctx context.Context, req GenerateRequest) (meta *KeyMetadata, err error)

func (*Manager) Get 

func (m *Manager) Get(ctx context.Context, id string) (meta *KeyMetadata, err error)

func (*Manager) List 

func (m *Manager) List(ctx context.Context) (keys []KeyMetadata, err error)

func (*Manager) Rotate 

func (m *Manager) Rotate(ctx context.Context, id string) (meta *KeyMetadata, err error)

func (*Manager) Sign 

func (m *Manager) Sign(ctx context.Context, keyID string, message []byte, opts SignOptions) (signature *SignatureEnvelope, err error)

func (*Manager) Verify 

func (m *Manager) Verify(ctx context.Context, message []byte, sig *SignatureEnvelope) (err error)

type Option 

type Option func(*Manager)

func WithAuditor 

func WithAuditor(auditor Auditor) Option

func WithClock 

func WithClock(now func() time.Time) Option

func WithRand 

func WithRand(randReader io.Reader) Option

type PublicKey 

type PublicKey struct {
	ID        string    `json:"id"`
	Algorithm Algorithm `json:"algorithm"`
	Use       KeyUse    `json:"use"`
	Version   int       `json:"version"`
	PublicKey []byte    `json:"public_key"`
	CreatedAt time.Time `json:"created_at"`
}

type ReadinessCategory 

type ReadinessCategory struct {
	ID          string         `json:"id"`
	Status      string         `json:"status"`
	Applies     bool           `json:"applies"`
	ScoreImpact int            `json:"score_impact"`
	Summary     string         `json:"summary"`
	Evidence    map[string]any `json:"evidence,omitempty"`
}

type ReadinessCoverage 

type ReadinessCoverage struct {
	Confidence                       string `json:"confidence"`
	ScoreImpact                      int    `json:"score_impact"`
	KeyStoreScanned                  bool   `json:"key_store_scanned"`
	KeyCount                         int    `json:"key_count"`
	TLSTargetsScanned                bool   `json:"tls_targets_scanned"`
	TLSTargetCount                   int    `json:"tls_target_count"`
	TLSLifecycleReadinessTargetCount int    `json:"tls_lifecycle_readiness_target_count"`
	SystemVerifiedTargetCount        int    `json:"system_verified_target_count"`
	CustomVerifiedTargetCount        int    `json:"custom_verified_target_count"`
	UnverifiedTargetCount            int    `json:"unverified_target_count"`
}

type ReadinessFinding 

type ReadinessFinding struct {
	Severity string         `json:"severity"`
	Subject  string         `json:"subject"`
	Message  string         `json:"message"`
	Evidence map[string]any `json:"evidence,omitempty"`
}

type ReadinessScan 

type ReadinessScan struct {
	Schema     string              `json:"schema"`
	CreatedAt  time.Time           `json:"created_at"`
	Policy     string              `json:"policy,omitempty"`
	Score      int                 `json:"score"`
	Level      string              `json:"level"`
	Coverage   ReadinessCoverage   `json:"coverage"`
	Summary    string              `json:"summary"`
	Categories []ReadinessCategory `json:"categories"`
	Findings   []ReadinessFinding  `json:"findings,omitempty"`
	Inventory  InventoryReport     `json:"inventory"`
}

func BuildReadinessScan 

func BuildReadinessScan(report InventoryReport, now time.Time) ReadinessScan

type RevocationEvent 

type RevocationEvent struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`
	Subject   string         `json:"subject"`
	Reason    string         `json:"reason"`
	RevokedAt time.Time      `json:"revoked_at"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type RevocationManifest 

type RevocationManifest struct {
	Schema    string            `json:"schema"`
	Hash      string            `json:"hash"`
	CreatedAt time.Time         `json:"created_at"`
	Events    []RevocationEvent `json:"events,omitempty"`
}

func NewRevocationManifest 

func NewRevocationManifest(now time.Time) RevocationManifest

func ReadRevocationManifest 

func ReadRevocationManifest(r io.Reader) (RevocationManifest, error)

func (*RevocationManifest) Add 

func (m *RevocationManifest) Add(subjectType, subject, reason string, metadata map[string]any, now time.Time) (RevocationEvent, error)

type SignOptions 

type SignOptions struct {
	Context    []byte
	Randomized bool
}

type SignatureEnvelope 

type SignatureEnvelope struct {
	Schema     string    `json:"schema"`
	KeyID      string    `json:"key_id"`
	KeyVersion int       `json:"key_version"`
	Algorithm  Algorithm `json:"algorithm"`
	Context    []byte    `json:"context,omitempty"`
	Signature  []byte    `json:"signature"`
	CreatedAt  time.Time `json:"created_at"`
}

SignatureEnvelope carries an ML-DSA signature plus enough metadata to verify it later using the manager's key store.

type Store 

type Store interface {
	Put(ctx context.Context, record KeyRecord) error
	Get(ctx context.Context, id string) (KeyRecord, error)
	GetVersion(ctx context.Context, id string, version int) (KeyRecord, error)
	List(ctx context.Context) ([]KeyMetadata, error)
}

Store persists versioned key material. Implementations are responsible for protecting private keys at rest.

type TLSCertificate 

type TLSCertificate struct {
	Subject            string    `json:"subject"`
	Issuer             string    `json:"issuer"`
	DNSNames           []string  `json:"dns_names,omitempty"`
	NotBefore          time.Time `json:"not_before"`
	NotAfter           time.Time `json:"not_after"`
	SignatureAlgorithm string    `json:"signature_algorithm"`
	PublicKeyAlgorithm string    `json:"public_key_algorithm"`
	FingerprintSHA256  string    `json:"fingerprint_sha256"`
	RawBytes           int       `json:"raw_bytes"`
}

type TLSInspectOptions 

type TLSInspectOptions struct {
	ServerName         string
	Timeout            time.Duration
	InsecureSkipVerify bool
	PQC                bool
	RootCAs            *x509.CertPool
}

type TLSReadiness 

type TLSReadiness struct {
	Policy                         TLSReadinessPolicy `json:"policy"`
	Target                         string             `json:"target"`
	ReadyFor47DayCerts             bool               `json:"ready_for_47_day_certs"`
	CertificateValidityDays        int                `json:"certificate_validity_days"`
	DaysUntilExpiry                int                `json:"days_until_expiry"`
	RenewalWindowRisk              string             `json:"renewal_window_risk"`
	RecommendedRenewalCadenceDays  int                `json:"recommended_renewal_cadence_days"`
	RecommendedRenewalLeadTimeDays int                `json:"recommended_renewal_lead_time_days"`
	SANCount                       int                `json:"san_count"`
	SANDCVReuseRisk                string             `json:"san_dcv_reuse_risk"`
	SANDCVReuseRiskReason          string             `json:"san_dcv_reuse_risk_reason"`
	ChainSizeBytes                 int                `json:"chain_size_bytes"`
	CertificateCount               int                `json:"certificate_count"`
	LeafSignatureAlgorithm         string             `json:"leaf_signature_algorithm,omitempty"`
	LeafPublicKeyAlgorithm         string             `json:"leaf_public_key_algorithm,omitempty"`
	ChainSignatureAlgorithms       []string           `json:"chain_signature_algorithms,omitempty"`
	ChainPublicKeyAlgorithms       []string           `json:"chain_public_key_algorithms,omitempty"`
	HybridPQCKeyExchange           bool               `json:"hybrid_pqc_key_exchange"`
	Verified                       bool               `json:"verified"`
	Findings                       []ReadinessFinding `json:"findings,omitempty"`
}

func EvaluateTLSReadiness 

func EvaluateTLSReadiness(report TLSReport, policy TLSReadinessPolicy, now time.Time) TLSReadiness

type TLSReadinessPolicy 

type TLSReadinessPolicy struct {
	ID                             string    `json:"id"`
	Name                           string    `json:"name"`
	EffectiveDate                  time.Time `json:"effective_date"`
	MaxValidityDays                int       `json:"max_validity_days"`
	MaxDomainValidationReuseDays   int       `json:"max_domain_validation_reuse_days"`
	RecommendedRenewalCadenceDays  int       `json:"recommended_renewal_cadence_days"`
	RecommendedRenewalLeadTimeDays int       `json:"recommended_renewal_lead_time_days"`
	Source                         string    `json:"source"`
}

func PublicWeb2029TLSReadinessPolicy 

func PublicWeb2029TLSReadinessPolicy() TLSReadinessPolicy

func ResolveTLSReadinessPolicy 

func ResolveTLSReadinessPolicy(id string) (TLSReadinessPolicy, error)

type TLSReport 

type TLSReport struct {
	Target                  string           `json:"target"`
	ServerName              string           `json:"server_name,omitempty"`
	TLSVersion              string           `json:"tls_version,omitempty"`
	CipherSuite             string           `json:"cipher_suite,omitempty"`
	KeyExchange             string           `json:"key_exchange,omitempty"`
	HybridPQCKeyExchange    bool             `json:"hybrid_pqc_key_exchange"`
	CertificateChainBytes   int              `json:"certificate_chain_bytes"`
	CertificateCount        int              `json:"certificate_count"`
	Verified                bool             `json:"verified"`
	VerificationMode        string           `json:"verification_mode,omitempty"`
	VerificationError       string           `json:"verification_error,omitempty"`
	Leaf                    *TLSCertificate  `json:"leaf,omitempty"`
	Certificates            []TLSCertificate `json:"certificates,omitempty"`
	SignedCertificateStamps int              `json:"signed_certificate_timestamps"`
	OCSPStapled             bool             `json:"ocsp_stapled"`
	ECHAccepted             bool             `json:"ech_accepted"`
	InspectedAt             time.Time        `json:"inspected_at"`
	Readiness               *TLSReadiness    `json:"readiness,omitempty"`
	Warnings                []string         `json:"warnings,omitempty"`
}

func InspectTLS 

func InspectTLS(ctx context.Context, target string, opts TLSInspectOptions) (TLSReport, error)

type TransparencyBundle 

type TransparencyBundle struct {
	Schema      string                 `json:"schema"`
	Inventory   InventoryReport        `json:"inventory"`
	Revocations *RevocationManifest    `json:"revocations,omitempty"`
	Checkpoint  TransparencyCheckpoint `json:"checkpoint"`
}

func BuildTransparencyBundle 

func BuildTransparencyBundle(report InventoryReport, checkpoint *TransparencyCheckpoint) (TransparencyBundle, error)

func BuildTransparencyBundleWithRevocations 

func BuildTransparencyBundleWithRevocations(report InventoryReport, revocations *RevocationManifest, checkpoint *TransparencyCheckpoint) (TransparencyBundle, error)

type TransparencyCheckpoint 

type TransparencyCheckpoint struct {
	Schema           string             `json:"schema"`
	Hash             string             `json:"hash"`
	GeneratedAt      time.Time          `json:"generated_at"`
	KeyCount         int                `json:"key_count"`
	TargetCount      int                `json:"target_count"`
	RevocationCount  int                `json:"revocation_count"`
	MerkleRoot       string             `json:"merkle_root"`
	InventoryRoot    string             `json:"inventory_root"`
	RevocationRoot   string             `json:"revocation_root,omitempty"`
	RevocationDigest string             `json:"revocation_digest,omitempty"`
	Signature        *SignatureEnvelope `json:"signature,omitempty"`
}

func BuildTransparencyCheckpoint 

func BuildTransparencyCheckpoint(report InventoryReport, now time.Time) (*TransparencyCheckpoint, error)

func BuildTransparencyCheckpointWithRevocations 

func BuildTransparencyCheckpointWithRevocations(report InventoryReport, revocations *RevocationManifest, now time.Time) (*TransparencyCheckpoint, error)

Source Files

View all Source files

Directories

Path Synopsis
cmd
pqc command
pqcd command
Package profile defines artifact profile plugins for PQC certificate, signature, and TLS authentication artifact families.
 Package profile defines artifact profile plugins for PQC certificate, signature, and TLS authentication artifact families.
profiles
all
compositex509
fndsa
mtc
x509mldsa
store
agefile
file

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.