Lab-10: Crypto-Agility
Lab-10: Crypto-Agility
Section titled “Lab-10: Crypto-Agility”CA Rotation and Trust Bundle Migration
Section titled “CA Rotation and Trust Bundle Migration”Key Message: Crypto-agility = your PKI can switch algorithms without downtime. This requires versioning, not just configuration.
The Scenario
Section titled “The Scenario”“We have 10,000 ECDSA certificates in production. We need to migrate to ML-DSA. But we can’t break everything at once.”
CURRENT SITUATION─────────────────
┌─────────────────────────────────────────────────────────────┐ │ │ │ Production │ │ ────────── │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ Server │ │ Server │ │ Server │ ... x 500 │ │ │ ECDSA │ │ ECDSA │ │ ECDSA │ │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ Client │ │ Client │ │ Client │ ... x 9500 │ │ │ Legacy │ │ Legacy │ │ Modern │ │ │ │ (ECDSA) │ │ (ECDSA) │ │ (PQC OK) │ │ │ └───────────┘ └───────────┘ └───────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘
How to migrate without cutting service?The Problem
Section titled “The Problem”┌──────────────────────────────────────────────────────────────────┐│ ││ "BIG BANG" MIGRATION: Risk of massive outage ││ ││ ││ Day D: Migration to ML-DSA ││ ││ ┌─────────┐ ┌─────────┐ ││ │ Server │ ❌───► │ Client │ Doesn't understand ML-DSA││ │ ML-DSA │ │ Legacy │ ││ └─────────┘ └─────────┘ ││ ││ Result: ││ - 80% of clients can't connect anymore ││ - Massive outage ││ - Rollback required ││ - Migration delayed 6 months ││ │└──────────────────────────────────────────────────────────────────┘The Solution: CA Rotation with Trust Bundles
Section titled “The Solution: CA Rotation with Trust Bundles”┌──────────────────────────────────────────────────────────────────┐│ ││ CA VERSIONING ││ ───────────── ││ ││ Migration CA ││ ├── v1 (ECDSA) ──► archived ││ ├── v2 (Hybrid) ──► archived ││ └── v3 (ML-DSA) ──► active ││ ││ Key Insight: ││ - ONE logical CA with MULTIPLE cryptographic versions ││ - Old certificates remain valid after rotation ││ - Trust bundles allow gradual client migration ││ ││ PKI reality: Each version has its own key. "Versioning" is ││ an operational abstraction over distinct trust anchors. ││ │└──────────────────────────────────────────────────────────────────┘Trust Store Strategy
Section titled “Trust Store Strategy”┌──────────────────────────────────────────────────────────────────┐│ ││ TRUST STORE DEPLOYMENT ││ ││ Clients Legacy ── trust-legacy.pem ──► CA v1 ──► Cert v1 ││ Clients Modern ── trust-modern.pem ──► CA v3 ──► Cert v3 ││ ││ Transition : ││ Clients ── trust-transition.pem ──► CA v1 / v2 / v3 ││ ││ During migration: ││ - Publish trust-transition.pem (contains ALL CA versions) ││ - ALL certificates validate correctly ││ - Clients upgrade at their own pace ││ │└──────────────────────────────────────────────────────────────────┘Important: The trust bundle is a temporary migration artifact. It should be removed once all clients have migrated to PQC.
What is Crypto-Agility?
Section titled “What is Crypto-Agility?”┌─────────────────────────────────────────────────────────────────┐│ ││ CRYPTO-AGILITY ││ ────────────── ││ ││ The ability of a system to: ││ ││ 1. CHANGE algorithm ││ → Without redesigning the architecture ││ ││ 2. SUPPORT multiple algorithms ││ → During transition ││ ││ 3. ROLLBACK quickly ││ → If a problem occurs ││ ││ It's an ARCHITECTURAL PROPERTY, not a tool. ││ │└─────────────────────────────────────────────────────────────────┘What We’ll Do
Section titled “What We’ll Do”- Create Migration CA (ECDSA) 1b. Issue ECDSA server certificate (v1)
- Rotate to hybrid (ECDSA + ML-DSA) 2b. Issue hybrid server certificate (v2) (optional)
- Rotate to full PQC (ML-DSA) 3b. Issue PQC server certificate (v3)
- Create trust stores
- Verify certificates against trust stores
- Simulate rollback
Run the Demo
Section titled “Run the Demo”./journey/10-crypto-agility/demo.shThe Commands
Section titled “The Commands”Step 1: Create Migration CA (ECDSA)
Section titled “Step 1: Create Migration CA (ECDSA)”# Create a Migration CA starting with ECDSAqpki ca init --profile profiles/classic-ca.yaml \ --var cn="Migration CA" \ --ca-dir output/caStep 1b: Issue ECDSA Server Certificate (v1)
Section titled “Step 1b: Issue ECDSA Server Certificate (v1)”# Issue ECDSA server certificateqpki credential enroll --ca-dir output/ca \ --cred-dir output/credentials \ --profile profiles/classic-tls-server.yaml \ --var cn=server.example.com
qpki credential export <credential-id> \ --ca-dir output/ca \ --cred-dir output/credentials \ --out output/server-v1.pemStep 2: Rotate to Hybrid CA
Section titled “Step 2: Rotate to Hybrid CA”# Rotate to hybrid mode (ECDSA + ML-DSA)qpki ca rotate --ca-dir output/ca \ --profile profiles/hybrid-ca.yaml
qpki ca activate --ca-dir output/ca --version v2
qpki ca versions --ca-dir output/ca# v1 archived ecdsa-p256# v2 active ecdsa-p256+ml-dsa-65Step 2b: Issue Hybrid Server Certificate (v2)
Section titled “Step 2b: Issue Hybrid Server Certificate (v2)”# Issue hybrid server certificate (optional but useful for testing)qpki credential enroll --ca-dir output/ca \ --cred-dir output/credentials \ --profile profiles/hybrid-tls-server.yaml \ --var cn=server.example.com
qpki credential export <credential-id> \ --ca-dir output/ca \ --cred-dir output/credentials \ --out output/server-v2.pemStep 3: Rotate to Full PQC CA
Section titled “Step 3: Rotate to Full PQC CA”# Rotate to full post-quantumqpki ca rotate --ca-dir output/ca \ --profile profiles/pqc-ca.yaml
qpki ca activate --ca-dir output/ca --version v3
qpki ca versions --ca-dir output/ca# v1 archived ecdsa-p256# v2 archived ecdsa-p256+ml-dsa-65# v3 active ml-dsa-65Step 3b: Issue PQC Server Certificate (v3)
Section titled “Step 3b: Issue PQC Server Certificate (v3)”# Issue PQC server certificateqpki credential enroll --ca-dir output/ca \ --cred-dir output/credentials \ --profile profiles/pqc-tls-server.yaml \ --var cn=server.example.com
qpki credential export <credential-id> \ --ca-dir output/ca \ --cred-dir output/credentials \ --out output/server-v3.pemStep 4: Create Trust Stores
Section titled “Step 4: Create Trust Stores”# Trust store for legacy clients (v1 only)qpki ca export --ca-dir output/ca --version v1 --out output/trust-legacy.pem
# Trust store for modern PQC-capable clients (v3 only)qpki ca export --ca-dir output/ca --version v3 --out output/trust-modern.pem
# Trust store for transition period (all versions - enables gradual migration)qpki ca export --ca-dir output/ca --all --out output/trust-transition.pemStep 5: Verify Certificates Against Trust Stores
Section titled “Step 5: Verify Certificates Against Trust Stores”# Legacy cert validates with legacy trust store (legacy clients scenario)qpki cert verify output/server-v1.pem --ca output/trust-legacy.pem
# PQC cert validates with modern trust store (modern clients scenario)qpki cert verify output/server-v3.pem --ca output/trust-modern.pem
# Transition trust store accepts BOTH old and new certificates# This is the key to gradual migration - all certs work during transitionqpki cert verify output/server-v1.pem --ca output/trust-transition.pemqpki cert verify output/server-v3.pem --ca output/trust-transition.pemINTEROPERABILITY MATRIX─────────────────────────────────────────── Certificate │ Trust Store │ Result─────────────────┼─────────────────────┼───────── v1 (ECDSA) │ trust-legacy.pem │ ✓ OK v3 (ML-DSA) │ trust-modern.pem │ ✓ OK v1 (ECDSA) │ trust-transition │ ✓ OK v3 (ML-DSA) │ trust-transition │ ✓ OK───────────────────────────────────────────
Key insight: The transition bundle supports ALL certificate versions,enabling gradual client migration without breaking existing services.Step 6: Simulate Rollback
Section titled “Step 6: Simulate Rollback”# Scenario: A compatibility issue is detected on legacy appliances.# Solution: Rollback to Hybrid CA (v2) - the "best of both worlds"## Why v2 (Hybrid) is ideal for rollback:# - Legacy clients can still verify using ECDSA# - Modern clients benefit from PQC protection# - No certificates are invalidated
qpki ca activate --ca-dir output/ca --version v2
qpki ca versions --ca-dir output/ca# v1 archived ecdsa-p256# v2 active ecdsa-p256+ml-dsa-65 <-- rolled back here# v3 archived ml-dsa-65Crypto-Agility Checklist
Section titled “Crypto-Agility Checklist”| Question | Crypto-Agile | Not Crypto-Agile |
|---|---|---|
| Are algorithms configured or hardcoded? | Configured | Hardcoded |
| Can you change algo without rebuild? | Yes | No |
| Do certs support multiple algos? | Yes (hybrid) | No |
| Can you rollback in < 1h? | Yes | No |
| Is crypto inventory automated? | Yes | Manual |
Size Comparison
Section titled “Size Comparison”| Phase | Algorithm | CA Cert | Server Cert | Notes |
|---|---|---|---|---|
| Phase 1 | ECDSA P-256 | ~600 B | ~800 B | Compact |
| Phase 2 | ECDSA + ML-DSA | ~5 KB | ~6 KB | Hybrid |
| Phase 3 | ML-DSA-65 | ~4 KB | ~5 KB | Full PQC |
Size increase is usually negligible compared to TLS records, HTTP payloads, or firmware images.
What You Learned
Section titled “What You Learned”- Crypto-agility is the ability to change algorithms without breaking your system
- CA rotation allows evolving cryptographic algorithms over time
- Trust bundles enable gradual client migration
- Old certificates remain valid after CA rotation
- Rollback is always possible - reactivate older versions
- Never do “big bang” migration - it’s too risky
- You’re ready: You now have the knowledge to plan and execute a PQC migration.