PQC Suite Security API Documentation

⚠️ POST-QUANTUM CRYPTOGRAPHY SUITE ⚠️

THIS MODULE PROVIDES UNIFIED POST-QUANTUM CRYPTOGRAPHIC OPERATIONS

• Comprehensive PQC algorithm suite management
• Hybrid classical-quantum schemes
• Migration and compatibility tools
• Quantum resistance validation

1. Core PQC Suite Components

1.1 Algorithm Suite Management

create_pqc_suite(config: PqcConfig) -> Result<PqcSuite>

Security Contract:

• MUST validate all algorithm parameters
• MUST ensure quantum resistance levels
• MUST check NIST standardization status
• MUST enforce security level consistency

pub struct PqcConfig {
    pub kem: KemAlgorithm,           // Key Encapsulation
    pub signature: SigAlgorithm,      // Digital Signatures
    pub hybrid_mode: HybridMode,      // Classical fallback
    pub security_level: NistLevel,    // 1, 3, or 5
}

pub enum NistLevel {
    Level1 = 1,  // 128-bit quantum security
    Level3 = 3,  // 192-bit quantum security  
    Level5 = 5,  // 256-bit quantum security
}

validate_quantum_resistance(algorithm: &Algorithm) -> QuantumResistance

Security Contract:

• MUST assess against known quantum attacks
• MUST consider Grover’s algorithm impact
• MUST evaluate Shor’s algorithm vulnerability
• MUST track emerging quantum threats

1.2 Hybrid Schemes

create_hybrid_kem(classical: ClassicalKem, pqc: PqcKem) -> HybridKem

Security Contract:

• MUST combine both schemes securely
• MUST NOT reduce security below either component
• MUST handle key size differences
• MUST provide transitional security

Hybrid Modes:

pub enum HybridMode {
    Concatenate,      // Simple concatenation
    NestedMode,       // PQC(Classical(data))
    XorMode,          // XOR shared secrets
    KdfMode,          // KDF combination
}

hybrid_encapsulate(pk_classical: &PublicKey, pk_pqc: &PublicKey) -> (Ciphertext, SharedSecret)

Security Contract:

• MUST resist both classical and quantum attacks
• MUST maintain IND-CCA2 security
• MUST handle partial compromise
• MUST provide crypto-agility

1.3 Migration Tools

migrate_to_pqc(classical_key: &ClassicalKey) -> Result<PqcMigration>

Security Contract:

• MUST preserve security during transition
• MUST support rollback safely
• MUST handle hybrid period
• MUST maintain compatibility

pub struct PqcMigration {
    pub new_keys: PqcKeyPair,
    pub transition_cert: TransitionCertificate,
    pub hybrid_period: Duration,
    pub rollback_data: RollbackInfo,
}

2. Security Properties by Algorithm

2.1 NIST Standardized Algorithms

Algorithm	Type	NIST Level	Key Size	Quantum Security
ML-KEM-768	KEM	3	2400 bytes	192-bit
ML-DSA-65	Signature	3	1952 bytes	192-bit
SLH-DSA-256s	Signature	5	64 bytes	256-bit

2.2 Quantum Attack Resistance

class QuantumResistanceAnalyzer:
    @staticmethod
    def analyze_algorithm(algorithm: str) -> dict:
        """Analyze quantum resistance properties."""
        resistance = {
            'shor_vulnerable': False,
            'grover_impact': 'sqrt(N)',
            'quantum_security_bits': 0,
            'classical_security_bits': 0,
        }
        
        if algorithm == 'RSA':
            resistance['shor_vulnerable'] = True
            resistance['quantum_security_bits'] = 0
        elif algorithm == 'ML-KEM-768':
            resistance['shor_vulnerable'] = False
            resistance['quantum_security_bits'] = 192
            resistance['classical_security_bits'] = 256
        
        return resistance

3. Implementation Examples

3.1 Python PQC Suite

from typing import Tuple, Optional
import hashlib

class PqcSuite:
    def __init__(self, config: dict):
        self.kem_algorithm = config['kem']
        self.sig_algorithm = config['signature']
        self.hybrid_mode = config.get('hybrid_mode', 'concatenate')
        self.security_level = config['security_level']
        
        self._validate_config()
    
    def _validate_config(self):
        """Validate suite configuration."""
        # Check algorithm compatibility
        if self.security_level == 3:
            assert self.kem_algorithm in ['ML-KEM-768', 'Kyber768']
            assert self.sig_algorithm in ['ML-DSA-65', 'Dilithium3']
        
        # Verify quantum resistance
        for alg in [self.kem_algorithm, self.sig_algorithm]:
            if not self._is_quantum_resistant(alg):
                raise ValueError(f"{alg} is not quantum-resistant")
    
    def generate_keypair(self) -> Tuple[bytes, bytes]:
        """Generate PQC keypair with validation."""
        # Generate keys for both KEM and signature
        kem_pk, kem_sk = self._generate_kem_keypair()
        sig_pk, sig_sk = self._generate_sig_keypair()
        
        # Combine into suite keypair
        public_key = self._encode_public_key(kem_pk, sig_pk)
        secret_key = self._encode_secret_key(kem_sk, sig_sk)
        
        # Self-test
        if not self._self_test(public_key, secret_key):
            raise RuntimeError("Keypair self-test failed")
        
        return public_key, secret_key
    
    def hybrid_kem_encap(
        self, 
        pqc_pk: bytes, 
        classical_pk: Optional[bytes] = None
    ) -> Tuple[bytes, bytes]:
        """Hybrid KEM encapsulation."""
        # PQC encapsulation
        pqc_ct, pqc_ss = self._pqc_encapsulate(pqc_pk)
        
        if classical_pk is None:
            return pqc_ct, pqc_ss
        
        # Classical encapsulation
        classical_ct, classical_ss = self._classical_encapsulate(classical_pk)
        
        # Combine based on hybrid mode
        if self.hybrid_mode == 'concatenate':
            combined_ct = pqc_ct + classical_ct
            combined_ss = hashlib.sha3_256(pqc_ss + classical_ss).digest()
        elif self.hybrid_mode == 'xor':
            combined_ct = pqc_ct + classical_ct
            combined_ss = bytes(a ^ b for a, b in zip(pqc_ss, classical_ss))
        else:
            raise ValueError(f"Unknown hybrid mode: {self.hybrid_mode}")
        
        return combined_ct, combined_ss

3.2 Rust PQC Suite

use oqs::{kem::Kem, sig::Sig};
use zeroize::Zeroize;

pub struct PqcSuite {
    kem: Kem,
    sig: Sig,
    config: PqcConfig,
}

impl PqcSuite {
    pub fn new(config: PqcConfig) -> Result<Self, Error> {
        // Validate security levels match
        Self::validate_security_levels(&config)?;
        
        // Initialize algorithms
        let kem = Kem::new(&config.kem.to_string())?;
        let sig = Sig::new(&config.signature.to_string())?;
        
        // Verify quantum resistance
        Self::verify_quantum_resistance(&kem, &sig)?;
        
        Ok(Self { kem, sig, config })
    }
    
    fn validate_security_levels(config: &PqcConfig) -> Result<(), Error> {
        // Ensure consistent security levels
        let kem_level = Self::get_nist_level(&config.kem);
        let sig_level = Self::get_nist_level(&config.signature);
        
        if kem_level != sig_level {
            return Err(Error::InconsistentSecurityLevels);
        }
        
        if kem_level < config.security_level {
            return Err(Error::InsufficientSecurity);
        }
        
        Ok(())
    }
    
    pub fn hybrid_encapsulate(
        &self,
        pqc_pk: &[u8],
        classical_pk: Option<&[u8]>,
    ) -> Result<(Vec<u8>, Vec<u8>), Error> {
        // PQC encapsulation
        let (pqc_ct, mut pqc_ss) = self.kem.encapsulate(pqc_pk)?;
        
        let (combined_ct, combined_ss) = match classical_pk {
            Some(cpk) => {
                // Classical encapsulation
                let (classical_ct, mut classical_ss) = 
                    classical_encapsulate(cpk)?;
                
                // Combine based on mode
                let (ct, ss) = match self.config.hybrid_mode {
                    HybridMode::Concatenate => {
                        let ct = [&pqc_ct[..], &classical_ct[..]].concat();
                        let ss = Self::kdf_combine(&pqc_ss, &classical_ss)?;
                        (ct, ss)
                    },
                    HybridMode::NestedMode => {
                        // Encrypt classical with PQC
                        let nested_ct = self.nest_ciphertexts(
                            &pqc_ct, 
                            &classical_ct, 
                            &pqc_ss
                        )?;
                        let ss = Self::kdf_combine(&pqc_ss, &classical_ss)?;
                        (nested_ct, ss)
                    },
                    _ => return Err(Error::UnsupportedHybridMode),
                };
                
                // Clear intermediate secrets
                classical_ss.zeroize();
                
                (ct, ss)
            },
            None => (pqc_ct, pqc_ss.to_vec()),
        };
        
        // Clear PQC secret
        pqc_ss.zeroize();
        
        Ok((combined_ct, combined_ss))
    }
    
    fn kdf_combine(ss1: &[u8], ss2: &[u8]) -> Result<Vec<u8>, Error> {
        use hkdf::Hkdf;
        use sha3::Sha3_256;
        
        let mut combined = vec![0u8; 32];
        let hkdf = Hkdf::<Sha3_256>::new(None, &[ss1, ss2].concat());
        
        hkdf.expand(b"hybrid-kem-shared-secret", &mut combined)
            .map_err(|_| Error::KdfError)?;
        
        Ok(combined)
    }
}

// Migration support
pub struct PqcMigrator {
    source_type: CryptoSystem,
    target_suite: PqcSuite,
}

impl PqcMigrator {
    pub fn create_migration_plan(
        &self,
        current_keys: &[KeyMaterial],
    ) -> Result<MigrationPlan, Error> {
        let mut plan = MigrationPlan::new();
        
        for key in current_keys {
            // Assess current security
            let current_security = self.assess_security(key)?;
            
            // Determine target algorithm
            let target_alg = self.select_pqc_algorithm(current_security)?;
            
            // Create migration step
            let step = MigrationStep {
                source_key: key.id().clone(),
                target_algorithm: target_alg,
                hybrid_period: Duration::from_days(90),
                rollback_window: Duration::from_days(30),
            };
            
            plan.add_step(step);
        }
        
        plan.validate()?;
        Ok(plan)
    }
}

4. Attack Scenarios and Mitigations

Attack Type	Classical Impact	Quantum Impact	PQC Mitigation
Key Recovery	Exponential	Polynomial (Shor)	Lattice/Hash-based
Collision Finding	O(2^(n/2))	O(2^(n/3))	Larger parameters
Preimage Attack	O(2^n)	O(2^(n/2))	Quantum-resistant hash
Side Channel	High	Very High	Constant-time impl
Fault Injection	Medium	High	Redundancy checks

5. Security Validation

5.1 Quantum Resistance Testing

def validate_quantum_resistance(algorithm: str, params: dict) -> bool:
    """Validate algorithm against quantum attacks."""
    
    # Check against known quantum algorithms
    quantum_tests = {
        'shor_resistance': test_shor_resistance,
        'grover_resistance': test_grover_resistance,
        'brassard_resistance': test_brassard_resistance,
    }
    
    for test_name, test_func in quantum_tests.items():
        if not test_func(algorithm, params):
            print(f"Failed {test_name} for {algorithm}")
            return False
    
    # Check parameter sizes
    if not validate_parameter_sizes(algorithm, params):
        return False
    
    # Verify implementation security
    if not verify_constant_time_implementation(algorithm):
        return False
    
    return True

def test_shor_resistance(algorithm: str, params: dict) -> bool:
    """Test resistance to Shor's algorithm."""
    vulnerable_types = ['RSA', 'DSA', 'ECDSA', 'DH', 'ECDH']
    
    for vuln_type in vulnerable_types:
        if vuln_type.lower() in algorithm.lower():
            return False
    
    # Check mathematical foundation
    foundation = get_math_foundation(algorithm)
    return foundation in ['lattice', 'hash', 'code', 'multivariate']

5.2 Hybrid Security Analysis

pub fn analyze_hybrid_security(
    classical_alg: &Algorithm,
    pqc_alg: &Algorithm,
    mode: HybridMode,
) -> SecurityAnalysis {
    let mut analysis = SecurityAnalysis::new();
    
    // Individual algorithm security
    let classical_sec = analyze_algorithm(classical_alg);
    let pqc_sec = analyze_algorithm(pqc_alg);
    
    // Combined security based on mode
    match mode {
        HybridMode::Concatenate => {
            // Security is at least as strong as stronger component
            analysis.classical_bits = classical_sec.classical_bits.max(
                pqc_sec.classical_bits
            );
            analysis.quantum_bits = pqc_sec.quantum_bits;
        },
        HybridMode::NestedMode => {
            // Additive security (simplified model)
            analysis.classical_bits = classical_sec.classical_bits + 
                                    pqc_sec.classical_bits;
            analysis.quantum_bits = pqc_sec.quantum_bits;
        },
        _ => {}
    }
    
    // Check for security degradation
    analysis.validate_no_degradation(&classical_sec, &pqc_sec);
    
    analysis
}

6. Performance Considerations

Operation	Classical	PQC	Hybrid	Notes
Key Generation	<1ms	10-100ms	100-200ms	One-time cost
Encapsulation	<1ms	1-10ms	10-20ms	Per-session
Decapsulation	<1ms	1-10ms	10-20ms	Per-session
Signature	<1ms	10-100ms	N/A	Size vs speed trade-off
Verification	<1ms	1-10ms	N/A	Generally faster

7. Migration Checklist

• Current cryptographic inventory completed
• Quantum risk assessment performed
• Target PQC algorithms selected
• Hybrid mode strategy defined
• Performance impact evaluated
• Compatibility testing completed
• Rollback procedures established
• Timeline and phases planned
• Monitoring systems updated
• Emergency procedures documented

8. Common Pitfalls

8.1 Premature Migration

# WRONG - Migrating to non-standardized algorithm
def migrate_to_experimental_pqc():
    use_algorithm("ExperimentalPQC-2024")  # Not standardized!

# CORRECT - Use NIST standardized algorithms
def migrate_to_standard_pqc():
    use_algorithm("ML-KEM-768")  # NIST approved

8.2 Inadequate Hybrid Implementation

// WRONG - Weak hybrid combination
fn weak_hybrid(classical_ss: &[u8], pqc_ss: &[u8]) -> Vec<u8> {
    // Simple concatenation can be vulnerable
    [classical_ss, pqc_ss].concat()
}

// CORRECT - Secure hybrid combination
fn secure_hybrid(classical_ss: &[u8], pqc_ss: &[u8]) -> Vec<u8> {
    // Use KDF to combine secrets
    let mut okm = vec![0u8; 32];
    Hkdf::<Sha3_256>::new(None, &[classical_ss, pqc_ss].concat())
        .expand(b"hybrid-shared-secret", &mut okm)
        .unwrap();
    okm
}

9. Future Considerations

• Monitor NIST PQC standardization updates
• Track quantum computer development
• Prepare for algorithm agility
• Plan for larger key/signature sizes
• Consider network protocol impacts
• Evaluate storage requirements
• Update security policies
• Train development teams

10. References

• NIST PQC Standardization
• PQC Migration Playbook
• Hybrid PQC Schemes
• Quantum Computing Threat Timeline

Security Analysis

Threat Model: PQC Suite Threat Model

This component provides critical security infrastructure. For comprehensive security analysis including:

• Infrastructure security considerations
• Cross-algorithm implications
• Implementation best practices
• Deployment recommendations

See the dedicated threat model documentation for complete details.