MetaMUI Post-Quantum Cryptography Migration Guide

Side-channel claim limit. Nothing on this page claims constant-time behaviour or side-channel resistance for any target: the side-channel harness covers nothing (finding A48) and no measurement exists. The Rust and C cores are designed for constant time and unmeasured; managed runtimes (JIT, GC, bounds checks) make no timing claim. Where this page names constant-time or side-channel techniques, in prose or in code, they are design intent or recommendations, not measured properties.

Executive Summary

This guide provides comprehensive instructions for migrating from classical cryptographic algorithms to post-quantum alternatives in the MetaMUI ecosystem. With 43 PQC algorithm variants now available, organizations can ensure quantum-resistant security while maintaining performance and compatibility.

Table of Contents

  1. Migration Overview
  2. Algorithm Selection Guide
  3. Platform-Specific Migration
  4. Hybrid Approaches
  5. Testing Strategy
  6. Production Deployment
  7. Rollback Procedures

Migration Overview

Why Migrate to PQC?

Migration Timeline

Phase 1 (Immediate): Inventory and Assessment
Phase 2 (Q1 2025): Development and Testing
Phase 3 (Q2 2025): Pilot Deployment
Phase 4 (Q3 2025): Production Migration
Phase 5 (Q4 2025): Full Transition

Algorithm Selection Guide

Choosing the Right Algorithm

For Key Exchange (Replacing ECDH/RSA)

Current Algorithm Recommended PQC Alternative Options Notes
ECDH P-256 ML-KEM-768 Kyber768, NTRU-HRSS NIST Level 3
ECDH P-384 ML-KEM-1024 Kyber1024 NIST Level 5
RSA-2048 ML-KEM-512 Kyber512, FrodoKEM-640 NIST Level 1
RSA-3072 ML-KEM-768 Classic McEliece Balance size/speed
RSA-4096 ML-KEM-1024 FrodoKEM-1344 Maximum security

For Digital Signatures (Replacing ECDSA/RSA)

Current Algorithm Recommended PQC Alternative Options Notes
ECDSA P-256 ML-DSA-65 Dilithium3, Falcon-512 General purpose
ECDSA P-384 ML-DSA-87 Dilithium5, Falcon-1024 High security
RSA-2048 PSS ML-DSA-44 Dilithium2 NIST Level 2
RSA-3072 PSS ML-DSA-65 SLH-DSA-128f Fast verification
Ed25519 ML-DSA-44 Falcon-512 Compact signatures

Special Use Cases

Use Case Recommended Algorithm Rationale
IoT/Embedded Falcon-512 Small signatures, fast verification
Long-term archives SLH-DSA-256s Hash-based, quantum-secure
High-volume signing LMS/XMSS Stateful but efficient
Bandwidth-constrained Falcon-512 Smallest signatures
Memory-constrained ML-DSA-44 Balanced performance

Security Level Mapping

Classical Security -> PQC Security Level
AES-128 -> NIST Level 1 (ML-KEM-512, ML-DSA-44)
SHA-256 -> NIST Level 2 (intermediate)
AES-192 -> NIST Level 3 (ML-KEM-768, ML-DSA-65)
SHA-384 -> NIST Level 4 (intermediate)
AES-256 -> NIST Level 5 (ML-KEM-1024, ML-DSA-87)

Platform-Specific Migration

TypeScript/JavaScript

// Before: Classical ECDH
import { ECDH } from 'crypto';
const ecdh = crypto.createECDH('prime256v1');
const publicKey = ecdh.generateKeys();

// After: Post-Quantum KEM
import { PQCFactory } from '@metamui/crypto';
const kem = await PQCFactory.createKEM('ML-KEM-768');
const { publicKey, secretKey } = await kem.generateKeypair();

Python

# Before: Classical signatures
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import rsa, padding

private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
signature = private_key.sign(message, padding.PSS(...), hashes.SHA256())

# After: Post-Quantum signatures
from metamui_crypto.pqc import PqcSignature, Algorithm

sig = PqcSignature(Algorithm.ML_DSA_65)
keypair = sig.generate_keypair()
signature = sig.sign(message, keypair.private_key)

Rust

// Before: Classical crypto
use ring::signature::{self, KeyPair};
let rng = rand::SystemRandom::new();
let pkcs8 = signature::Ed25519KeyPair::generate_pkcs8(&rng)?;

// After: Post-Quantum crypto
use metamui_mldsa::MLDSASignature;
let mut rng = rand::thread_rng();
let (pk, sk) = MLDSASignature::keypair(&mut rng);
let signature = MLDSASignature::sign(&message, &sk);

Swift

// Before: Classical crypto
import CryptoKit
let privateKey = P256.Signing.PrivateKey()
let signature = try privateKey.signature(for: data)

// After: Post-Quantum crypto
import MetaMUIPQC
let mldsa = try PQCFactory.createSignature("ML-DSA-65")
let keypair = try mldsa.generateKeypair()
let signature = try mldsa.sign(message: data, secretKey: keypair.secretKey)

Kotlin/Java

// Before: Classical crypto
val keyGen = KeyPairGenerator.getInstance("RSA")
keyGen.initialize(2048)
val keyPair = keyGen.generateKeyPair()

// After: Post-Quantum crypto
import id.metamui.crypto.pqc.MetaMUIPQC
val mldsa = MetaMUIPQC.createSignature("ML-DSA-65")
val keypair = mldsa.generateKeypair()
val signature = mldsa.sign(message, keypair.secretKey)

Hybrid Approaches

Implementing Hybrid Cryptography

Combine classical and post-quantum algorithms for defense in depth:

// Hybrid KEM Example
class HybridKEM {
  async encapsulate(classicalPubKey: Buffer, pqcPubKey: Buffer) {
    // Classical ECDH
    const classicalSecret = await performECDH(classicalPubKey);
    
    // Post-Quantum KEM
    const pqc = await PQCFactory.createKEM('ML-KEM-768');
    const { ciphertext, sharedSecret } = await pqc.encapsulate(pqcPubKey);
    
    // Combine secrets using KDF
    const hybridSecret = await kdf(
      Buffer.concat([classicalSecret, sharedSecret])
    );
    
    return { ciphertext, hybridSecret };
  }
}

Hybrid Signature Schemes

def hybrid_sign(message, classical_key, pqc_key):
    # Classical signature
    classical_sig = classical_key.sign(message)
    
    # PQC signature
    pqc = PqcSignature(Algorithm.ML_DSA_65)
    pqc_sig = pqc.sign(message, pqc_key)
    
    # Combine signatures
    return {
        'classical': classical_sig,
        'pqc': pqc_sig,
        'algorithm': 'ECDSA-P256+ML-DSA-65'
    }

Testing Strategy

1. Unit Testing

describe('PQC Migration Tests', () => {
  it('should maintain functionality with ML-KEM', async () => {
    const kem = await PQCFactory.createKEM('ML-KEM-768');
    const keypair = await kem.generateKeypair();
    
    const { ciphertext, sharedSecret } = await kem.encapsulate(keypair.publicKey);
    const decapsulated = await kem.decapsulate(ciphertext, keypair.secretKey);
    
    expect(sharedSecret).toEqual(decapsulated);
  });
});

2. Integration Testing

def test_cross_platform_compatibility():
    # Generate keys in Python
    py_kem = PqcKem(Algorithm.ML_KEM_768)
    py_keypair = py_kem.generate_keypair()
    
    # Test with TypeScript implementation
    result = subprocess.run([
        'node', 'test_kem.js',
        base64.b64encode(py_keypair.public_key).decode()
    ], capture_output=True)
    
    assert result.returncode == 0

3. Performance Testing

#[bench]
fn bench_pqc_vs_classical(b: &mut Bencher) {
    b.iter(|| {
        // Measure PQC performance
        let (pk, sk) = MLKEMKeyPair::generate();
        let (ct, ss) = pk.encapsulate();
        let _ = sk.decapsulate(&ct);
    });
}

4. Compatibility Testing

Test interoperability matrix:

Platform Rust Python TypeScript Swift Kotlin
Rust ✅ ✅ ✅ ✅ ✅
Python ✅ ✅ ✅ ✅ ✅
TypeScript ✅ ✅ ✅ ✅ ✅
Swift ✅ ✅ ✅ ✅ ✅
Kotlin ✅ ✅ ✅ ✅ ✅

Production Deployment

Pre-Deployment Checklist

Deployment Strategies

1. Canary Deployment

# Deploy to 5% of infrastructure first
deployment:
  strategy: canary
  stages:
    - percentage: 5
      duration: 24h
      metrics:
        - error_rate < 0.1%
        - latency_p99 < 100ms
    - percentage: 25
      duration: 48h
    - percentage: 100

2. Blue-Green Deployment

class PQCDeployment {
  async switchToGreen() {
    // New PQC implementation
    const greenEnv = new PQCEnvironment();
    await greenEnv.initialize();
    
    // Test green environment
    if (await greenEnv.healthCheck()) {
      // Switch traffic
      await loadBalancer.switchTo('green');
      
      // Keep blue as fallback
      await blueEnv.standby();
    }
  }
}

3. Feature Flags

def get_crypto_implementation():
    if feature_flag('use_pqc_crypto'):
        return PqcImplementation()
    else:
        return ClassicalImplementation()

Monitoring and Alerting

alerts:
  - name: pqc_performance_degradation
    condition: pqc_operation_time > classical_operation_time * 2
    severity: warning
    
  - name: pqc_verification_failures
    condition: verification_failure_rate > 0.01
    severity: critical
    
  - name: stateful_signature_exhaustion
    condition: remaining_signatures < 1000
    severity: warning

Rollback Procedures

Emergency Rollback Plan

#!/bin/bash
# Emergency rollback script

# 1. Stop new PQC operations
kubectl set env deployment/crypto-service USE_PQC=false

# 2. Drain PQC traffic
kubectl patch service crypto-service -p '{"spec":{"selector":{"version":"classical"}}}'

# 3. Verify classical crypto working
curl -X POST https://api.example.com/health/crypto

# 4. Archive PQC keys for investigation
aws s3 cp /var/keys/pqc/ s3://backup/pqc-keys-$(date +%Y%m%d)/ --recursive

# 5. Notify team
slack-notify "PQC rollback completed at $(date)"

Gradual Rollback

class GradualRollback {
  async execute() {
    // Phase 1: Stop new PQC adoptions
    await featureFlag.set('allow_new_pqc', false);
    
    // Phase 2: Migrate active sessions
    for (const session of activeSessions) {
      if (session.usesPQC) {
        await session.migrateToClassical();
      }
    }
    
    // Phase 3: Disable PQC completely
    await config.set('pqc_enabled', false);
  }
}

Migration Examples

Example 1: TLS Certificate Migration

// Configure hybrid TLS with PQC
const tlsConfig = {
  // Classical for compatibility
  classical: {
    key: fs.readFileSync('classical-key.pem'),
    cert: fs.readFileSync('classical-cert.pem')
  },
  
  // PQC for quantum resistance
  pqc: {
    algorithm: 'ML-DSA-65',
    key: await loadPQCKey('pqc-key.der'),
    cert: await loadPQCCert('pqc-cert.der')
  },
  
  // Negotiation preference
  preference: 'prefer-pqc-with-fallback'
};

Example 2: Database Encryption Migration

class DatabaseMigration:
    def migrate_to_pqc(self):
        # Read with old key
        data = self.decrypt_with_classical(encrypted_data)
        
        # Re-encrypt with PQC
        pqc_kem = PqcKem(Algorithm.ML_KEM_768)
        new_key = pqc_kem.generate_keypair()
        
        # Store encrypted with new algorithm
        new_encrypted = self.encrypt_with_pqc(data, new_key.public_key)
        
        # Atomic swap
        with transaction():
            self.store(new_encrypted)
            self.update_key_metadata(new_key)

Example 3: API Authentication Migration

class APIAuthMigration {
    fun migrateToHybridAuth() {
        // Support both authentication methods
        val authHandlers = listOf(
            ClassicalJWTHandler(),
            PQCSignatureHandler("ML-DSA-65"),
            HybridAuthHandler()
        )
        
        // Try PQC first, fallback to classical
        fun authenticate(request: Request): Boolean {
            return authHandlers.any { handler ->
                handler.canHandle(request) && handler.verify(request)
            }
        }
    }
}

Best Practices

1. Crypto-Agility

Design systems to easily switch algorithms:

interface CryptoProvider {
  generateKeypair(): Promise<KeyPair>;
  sign(message: Buffer, key: Buffer): Promise<Buffer>;
  verify(message: Buffer, signature: Buffer, key: Buffer): Promise<boolean>;
}

class CryptoFactory {
  static create(algorithm: string): CryptoProvider {
    switch(algorithm) {
      case 'ML-DSA-65': return new MLDSA65Provider();
      case 'Falcon-512': return new Falcon512Provider();
      case 'ECDSA-P256': return new ECDSA256Provider();
      default: throw new Error(`Unknown algorithm: ${algorithm}`);
    }
  }
}

2. Key Management

class PQCKeyManager:
    def rotate_keys(self):
        # Generate new PQC keypair
        new_keypair = self.generate_pqc_keypair()
        
        # Distribute new public key
        self.distribute_public_key(new_keypair.public)
        
        # Archive old keys
        self.archive_keys(self.current_keypair)
        
        # Atomic switch
        self.current_keypair = new_keypair
        
        # Log rotation
        audit_log.record('key_rotation', {
            'algorithm': 'ML-KEM-768',
            'timestamp': datetime.now(),
            'key_id': new_keypair.id
        })

3. Performance Optimization

// Cache expensive operations
lazy_static! {
    static ref KEM_CACHE: Cache<Vec<u8>, SharedSecret> = Cache::new(1000);
}

fn cached_encapsulate(public_key: &[u8]) -> (Vec<u8>, SharedSecret) {
    if let Some(cached) = KEM_CACHE.get(public_key) {
        return cached.clone();
    }
    
    let result = perform_encapsulation(public_key);
    KEM_CACHE.insert(public_key.to_vec(), result.clone());
    result
}

Troubleshooting Guide

Common Issues and Solutions

Issue Symptoms Solution
Performance degradation High latency, timeouts Use faster algorithms (Falcon), implement caching
Memory exhaustion OOM errors with Classic McEliece Use streaming APIs, implement key pagination
Signature verification failures Invalid signature errors Check key encoding, verify algorithm parameters
Stateful signature exhaustion “Key exhausted” errors Implement key rotation, increase tree height
Cross-platform incompatibility Different results across platforms Verify byte order, check serialization format

Debug Commands

# Check algorithm support
metamui-crypto list-algorithms

# Verify key compatibility
metamui-crypto verify-key --algorithm ML-KEM-768 --key public.key

# Test interoperability
metamui-crypto test-interop --from python --to rust --algorithm ML-DSA-65

# Benchmark performance
metamui-crypto benchmark --algorithm all --iterations 1000

Compliance and Regulations

Regulatory Timeline

Compliance Checklist

Resources and Support

Documentation

Support Channels

Conclusion

Migrating to post-quantum cryptography is essential for long-term security. This guide provides the framework for a successful transition. Start with hybrid approaches, test thoroughly, and deploy gradually. The MetaMUI PQC suite provides all necessary tools for a smooth migration.

Version: 1.0.0
Last Updated: 2025-08-22
Next Review: Q1 2025