performing-post-quantum-cryptography-migration

What this skill does

# Performing Post-Quantum Cryptography Migration

## When to Use

- When assessing organizational readiness for the NIST post-quantum cryptography transition
- When building a cryptographic inventory to identify quantum-vulnerable algorithms across infrastructure
- When evaluating hybrid TLS 1.3 configurations using X25519MLKEM768 key exchange
- When testing CRYSTALS-Kyber (ML-KEM) and CRYSTALS-Dilithium (ML-DSA) algorithm support
- When implementing crypto-agility to support both classical and post-quantum algorithms
- When preparing migration roadmaps aligned with NIST IR 8547 deprecation timelines
- When configuring oqs-provider with OpenSSL 3.x for post-quantum algorithm support

## Prerequisites

- Python 3.8+ with `cryptography`, `requests`, `pyOpenSSL` libraries
- OpenSSL 3.0+ (3.5+ recommended for native ML-KEM/ML-DSA support)
- oqs-provider for OpenSSL (for hybrid TLS testing with older OpenSSL)
- Network access to target servers for TLS assessment
- Administrative access for infrastructure scanning
- Familiarity with PKI, TLS, and cryptographic protocols

## Core Concepts

### NIST Post-Quantum Cryptography Standards

NIST published three finalized PQC standards on August 13, 2024:

| Standard | Algorithm | Renamed To | Purpose | Based On |
|----------|-----------|------------|---------|----------|
| FIPS 203 | CRYSTALS-Kyber | ML-KEM | Key Encapsulation Mechanism | Module lattice |
| FIPS 204 | CRYSTALS-Dilithium | ML-DSA | Digital Signatures | Module lattice |
| FIPS 205 | SPHINCS+ | SLH-DSA | Digital Signatures (backup) | Stateless hash |

**ML-KEM (FIPS 203)** -- Primary standard for key exchange and encryption. Replaces
RSA and ECDH for key establishment. Three security levels: ML-KEM-512, ML-KEM-768,
ML-KEM-1024.

**ML-DSA (FIPS 204)** -- Primary standard for digital signatures. Replaces RSA and
ECDSA for signing. Three security levels: ML-DSA-44, ML-DSA-65, ML-DSA-87.

**SLH-DSA (FIPS 205)** -- Backup signature standard using hash-based approach. Intended
as fallback if lattice-based ML-DSA is found vulnerable. Larger signatures but
conservative security assumptions.

### Quantum-Vulnerable Algorithms

These classical algorithms are vulnerable to quantum attack via Shor's algorithm:

| Algorithm | Usage | Quantum Threat | Migration Priority |
|-----------|-------|---------------|-------------------|
| RSA-2048/4096 | Key exchange, signatures, encryption | Shor's algorithm breaks factoring | Critical |
| ECDH (P-256, P-384) | TLS key exchange | Shor's algorithm breaks ECDLP | Critical |
| ECDSA | Code signing, TLS certificates | Shor's algorithm breaks ECDLP | Critical |
| DSA | Legacy signatures | Shor's algorithm breaks DLP | Critical |
| DH (Diffie-Hellman) | Key exchange | Shor's algorithm breaks DLP | Critical |
| AES-128 | Symmetric encryption | Grover's halves key strength | Medium (upgrade to AES-256) |
| SHA-256 | Hashing | Grover's reduces to 128-bit | Low (still adequate) |

### NIST Migration Timeline (IR 8547)

- **2024**: Standards published, migration planning should begin
- **2030**: Deprecation of quantum-vulnerable algorithms for most federal systems
- **2035**: Complete removal of quantum-vulnerable algorithms from NIST standards
- **Now**: "Harvest now, decrypt later" attacks make early migration essential for
  long-lived secrets and data requiring long-term confidentiality

### Hybrid TLS Key Exchange

During the transition period, hybrid key exchange combines a classical algorithm with
a post-quantum algorithm. If either algorithm is secure, the connection remains protected.

```
Hybrid Key Exchange: X25519MLKEM768
  = X25519 (classical ECDH) + ML-KEM-768 (post-quantum)

Client Hello:
  supported_groups: X25519MLKEM768, X25519, secp256r1
  key_share: X25519MLKEM768

Server Hello:
  selected_group: X25519MLKEM768
  key_share: X25519MLKEM768

Shared Secret = KDF(X25519_shared || MLKEM768_shared)
```

## Instructions

### Phase 1: Cryptographic Inventory Scanning

The first step in PQC migration is discovering all cryptographic algorithm usage
across the enterprise. This includes TLS configurations, certificates, code libraries,
key stores, and protocol configurations.

```python
# Scan TLS endpoints for quantum-vulnerable algorithms
python scripts/agent.py --action scan_tls \
    --targets targets.txt \
    --output tls_inventory.json
```

The scanner identifies:
- TLS protocol versions in use
- Key exchange algorithms (RSA, ECDH, DH -- all quantum-vulnerable)
- Certificate signature algorithms (RSA, ECDSA)
- Cipher suite configurations
- Certificate key sizes and expiration dates

### Phase 2: Crypto-Agility Assessment

Evaluate the organization's ability to swap cryptographic algorithms without
major infrastructure changes:

```python
# Assess crypto-agility readiness
python scripts/agent.py --action assess_agility \
    --scan-results tls_inventory.json \
    --output agility_report.json
```

Key assessment areas:
1. **Protocol flexibility**: Can TLS configurations be updated without downtime?
2. **Library versions**: Do deployed crypto libraries support PQC algorithms?
3. **Certificate infrastructure**: Can CA issue PQC certificates?
4. **Key management**: Can KMS handle larger PQC key sizes?
5. **Hardware constraints**: Can HSMs support PQC operations?

### Phase 3: Hybrid TLS Readiness Testing

Test whether infrastructure supports hybrid key exchange with X25519MLKEM768:

```python
# Test hybrid TLS support on target servers
python scripts/agent.py --action test_hybrid_tls \
    --target server.example.com:443 \
    --output hybrid_tls_report.json
```

**OpenSSL 3.5+ (native ML-KEM support):**
```bash
# Test with native PQC support
openssl s_client -connect server.example.com:443 \
    -groups X25519MLKEM768
```

**OpenSSL 3.0-3.4 with oqs-provider:**
```bash
# Configure oqs-provider
# /etc/ssl/openssl-oqs.cnf
[openssl_init]
providers = provider_sect

[provider_sect]
default = default_sect
oqsprovider = oqsprovider_sect

[default_sect]
activate = 1

[oqsprovider_sect]
activate = 1
module = /usr/lib/oqs-provider/oqsprovider.so

# Test hybrid TLS
OPENSSL_CONF=/etc/ssl/openssl-oqs.cnf \
openssl s_client -connect server.example.com:443 \
    -groups x25519_mlkem768
```

**Web Server Configuration for Hybrid TLS:**

Apache httpd:
```apache
SSLEngine on
SSLCertificateFile /etc/ssl/certs/server.crt
SSLCertificateKeyFile /etc/ssl/private/server.key
SSLOpenSSLConfCmd Curves X25519MLKEM768:X25519:prime256v1
SSLProtocol -all +TLSv1.2 +TLSv1.3
```

NGINX:
```nginx
ssl_ecdh_curve X25519MLKEM768:X25519:prime256v1;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;
```

### Phase 4: ML-KEM Key Encapsulation Validation

Validate that ML-KEM (CRYSTALS-Kyber) key encapsulation works correctly in your
environment:

```python
# Test ML-KEM key encapsulation at all security levels
python scripts/agent.py --action test_mlkem \
    --output mlkem_validation.json
```

ML-KEM parameter comparison:

| Parameter | ML-KEM-512 | ML-KEM-768 | ML-KEM-1024 |
|-----------|-----------|-----------|------------|
| Security Level | NIST Level 1 | NIST Level 3 | NIST Level 5 |
| Public Key Size | 800 bytes | 1,184 bytes | 1,568 bytes |
| Ciphertext Size | 768 bytes | 1,088 bytes | 1,568 bytes |
| Shared Secret | 32 bytes | 32 bytes | 32 bytes |
| Comparable To | AES-128 | AES-192 | AES-256 |

### Phase 5: ML-DSA Digital Signature Validation

Validate ML-DSA (CRYSTALS-Dilithium) signature operations:

```python
# Test ML-DSA digital signatures
python scripts/agent.py --action test_mldsa \
    --output mldsa_validation.json
```

ML-DSA parameter comparison:

| Parameter | ML-DSA-44 | ML-DSA-65 | ML-DSA-87 |
|-----------|----------|----------|----------|
| Security Level | NIST Level 2 | NIST Level 3 | NIST Level 5 |
| Public Key Size | 1,312 bytes | 1,952 bytes | 2,592 bytes |
| Signature Size | 2,420 bytes | 3,293 bytes | 4,595 bytes |
| Secret Key Size | 2,560 bytes | 4,032 bytes | 4,896 bytes |

### Phase 6: Migration Roadmap Gener