diff --git a/skills/software-security/rules/codeguard-1-crypto-algorithms.md b/skills/software-security/rules/codeguard-1-crypto-algorithms.md index 7f0b820..18fcd78 100644 --- a/skills/software-security/rules/codeguard-1-crypto-algorithms.md +++ b/skills/software-security/rules/codeguard-1-crypto-algorithms.md @@ -1,115 +1,126 @@ --- -description: Cryptographic Security Guidelines +description: Cryptographic Security Guidelines & Post-Quantum Readiness alwaysApply: true --- rule_id: codeguard-1-crypto-algorithms -# Cryptographic Security Guidelines +# Cryptographic Security Guidelines & Post-Quantum Readiness -## Banned (Insecure) Algorithms +## 1. Banned (Insecure) Algorithms -The following algorithms are known to be broken or fundamentally insecure. **NEVER** generate or use code with these algorithms. -Examples: +The following algorithms are known to be broken or fundamentally insecure. NEVER generate or use code with these algorithms. -* Hash: `MD2`, `MD4`, `MD5`, `SHA-0` -* Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES` -* Key Exchange: Static RSA, Anonymous Diffie-Hellman -* Classical: `Vigenère` +* Hash: `MD2`, `MD4`, `MD5`, `SHA-0` +* Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES` +* Key Exchange: Static RSA, Anonymous Diffie-Hellman +* Classical: `Vigenère` -## Deprecated (Legacy/Weak) Algorithms +Reason: These are cryptographically broken and vulnerable to collision or man-in-the-middle attacks. -The following algorithms are not outright broken, but have known weaknesses, or are considered obsolete. **NEVER** generate or use code with these algorithms. -Examples: +## 2. Deprecated (Legacy/Weak) Algorithms -* Hash: `SHA-1` -* Symmetric: `AES-CBC`, `AES-ECB` -* Signature: RSA with `PKCS#1 v1.5` padding -* Key Exchange: DHE with weak/common primes +The following algorithms have known weaknesses or are considered obsolete. Avoid in new designs and prioritize migration. +* Hash: `SHA-1` +* Symmetric: `AES-CBC`, `AES-ECB` +* Signature: RSA with `PKCS#1 v1.5` padding +* Key Exchange: DHE with weak/common primes -## Deprecated SSL/Crypto APIs - FORBIDDEN -NEVER use these deprecated functions. Use the replacement APIs listed below: +## 3. Recommended & Post-Quantum Ready Algorithms -### Symmetric Encryption (AES) +Implement these modern, secure algorithms to ensure resistance against both classical and quantum threats. + +### Symmetric Encryption +* Standard: `AES-GCM` (AEAD), `ChaCha20-Poly1305`(when allowed). +* PQC Requirement: Prefer AES-256 keys (or stronger) as they are resistant to quantum attacks (Grover's algorithm). +* Avoid: Custom crypto or unauthenticated modes. + +### Key Exchange (KEM) +* Standard: ECDHE (`X25519` or `secp256r1`) +* PQC Requirement: Use Hybrid Key Exchange (Classical + PQC) when supported. + * Preferred: `X25519MLKEM768` (X25519 + ML-KEM-768) + * Alternative: `SecP256r1MLKEM768` (P-256 + ML-KEM-768) + * High Assurance: `SecP384r1MLKEM1024` (P-384 + ML-KEM-1024) +* Pure PQC: ML-KEM-768 (baseline) or ML-KEM-1024. Avoid ML-KEM-512 unless explicitly risk-accepted. +* Constraints: + * Use vendor-documented identifiers (RFC 9242/9370). + * Remove legacy/draft "Hybrid-Kyber" groups (e.g., `X25519Kyber`) and draft or hardcoded OIDs. + +### Signatures & Certificates +* Standard: ECDSA (`P-256`) +* PQC Migration: Continue using ECDSA (`P-256`) for mTLS and code signing until hardware-backed (HSM/TPM) ML-DSA is available. +* Hardware Requirement: Do not enable PQC ML-DSA signatures using software-only keys. Require HSM/TPM storage. + +### Protocol Versions +* (D)TLS: Enforce (D)TLS 1.3 only (or later). +* IPsec: Enforce IKEv2 only. + * Use ESP with AEAD (AES-256-GCM). + * Require PFS via ECDHE. + * Implement RFC 9242 and RFC 9370 for Hybrid PQC (ML-KEM + ECDHE). + * Ensure re-keys (CREATE_CHILD_SA) maintain hybrid algorithms. +* SSH: Enable only vendor-supported PQC/hybrid KEX (e.g., `sntrup761x25519`). + +## 4. Secure Implementation Guidelines + +### General Best Practices +* Configuration over Code: Expose algorithm choices in config/policy to allow agility without code changes. +* Key Management: + * Use KMS/HSM for key storage. + * Generate keys with a CSPRNG. + * Separate encryption keys from signature keys. + * Rotate keys per policy. + * NEVER hardcode keys, secrets, or experimental OIDs. +* Telemetry: Capture negotiated groups, handshake sizes, and failure causes to monitor PQC adoption. + +### Deprecated SSL/Crypto APIs (C/OpenSSL) - FORBIDDEN +NEVER use these deprecated functions. Use the replacement EVP high-level APIs. + +#### Symmetric Encryption (AES) - Deprecated: `AES_encrypt()`, `AES_decrypt()` -- Replacement: Use EVP high-level APIs: - ```c - EVP_EncryptInit_ex() +- Replacement: + + EVP_EncryptInit_ex() // Use EVP_aes_256_gcm() for PQC readiness EVP_EncryptUpdate() EVP_EncryptFinal_ex() - EVP_DecryptInit_ex() - EVP_DecryptUpdate() - EVP_DecryptFinal_ex() - ``` - -### RSA Operations -- Deprecated: `RSA_new()`, `RSA_up_ref()`, `RSA_free()`, `RSA_set0_crt_params()`, `RSA_get0_n()` -- Replacement: Use EVP key management APIs: - ```c + + +#### RSA/PKEY Operations +- Deprecated: `RSA_new()`, `RSA_free()`, `RSA_get0_n()` +- Replacement: + EVP_PKEY_new() EVP_PKEY_up_ref() EVP_PKEY_free() - ``` - -### Hash Functions -- Deprecated: `SHA1_Init()`, `SHA1_Update()`, `SHA1_Final()` -- Replacement: Use EVP digest APIs: - ```c - EVP_DigestInit_ex() - EVP_DigestUpdate() - EVP_DigestFinal_ex() - EVP_Q_digest() // For simple one-shot hashing - ``` - -### MAC Operations -- Deprecated: `CMAC_Init()`, `HMAC()` (especially with SHA1) -- Replacement: Use EVP MAC APIs: - ```c - EVP_Q_MAC() // For simple MAC operations - ``` - -### Key Wrapping -- Deprecated: `AES_wrap_key()`, `AES_unwrap_key()` -- Replacement: Use EVP key wrapping APIs or implement using EVP encryption - -### Other Deprecated Functions -- Deprecated: `DSA_sign()`, `DH_check()` -- Replacement: Use corresponding EVP APIs for DSA and DH operations - -## Banned Insecure Algorithms - STRICTLY FORBIDDEN -These algorithms MUST NOT be used in any form: - -### Hash Algorithms (Banned) -- MD2, MD4, MD5, SHA-0 -- Reason: Cryptographically broken, vulnerable to collision attacks -- Use Instead: SHA-256, SHA-384, SHA-512 - -### Symmetric Ciphers (Banned) -- RC2, RC4, Blowfish, DES, 3DES -- Reason: Weak key sizes, known vulnerabilities -- Use Instead: AES-128, AES-256, ChaCha20 - -### Key Exchange (Banned) -- Static RSA key exchange -- Anonymous Diffie-Hellman -- Reason: No forward secrecy, vulnerable to man-in-the-middle attacks -- Use Instead: ECDHE, DHE with proper validation - -## Broccoli Project Specific Requirements -- HMAC() with SHA1: Deprecated per Broccoli project requirements + + +#### Hash & MAC Functions +- Deprecated: `SHA1_Init()`, `HMAC()` (especially with SHA1) +- Replacement: + + EVP_DigestInit_ex() // Use SHA-256 or stronger + EVP_Q_MAC() // For one-shot MAC + + +## 5. Broccoli Project Specific Requirements +- HMAC() with SHA1: Deprecated. - Replacement: Use HMAC with SHA-256 or stronger: - ```c - // Instead of HMAC() with SHA1 - EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len); - ``` -## Secure Crypto Implementation Pattern + +// Example: Secure replacement for HMAC-SHA1 +```c +EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len); +``` + +## 6. Secure Crypto Implementation Pattern + + +// Example: Secure AES-256-GCM encryption (PQC-Ready Symmetric Strength) ```c -// Example: Secure AES encryption EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new(); if (!ctx) handle_error(); +// Use AES-256-GCM if (EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv) != 1) handle_error(); @@ -124,11 +135,3 @@ ciphertext_len += len; EVP_CIPHER_CTX_free(ctx); ``` - -## Code Review Checklist -- [ ] No deprecated SSL/crypto APIs used -- [ ] No banned algorithms (MD5, DES, RC4, etc.) -- [ ] HMAC uses SHA-256 or stronger (not SHA1) -- [ ] All crypto operations use EVP high-level APIs -- [ ] Proper error handling for all crypto operations -- [ ] Key material properly zeroed after use diff --git a/sources/core/codeguard-1-crypto-algorithms.md b/sources/core/codeguard-1-crypto-algorithms.md index e748452..edbf65d 100644 --- a/sources/core/codeguard-1-crypto-algorithms.md +++ b/sources/core/codeguard-1-crypto-algorithms.md @@ -1,114 +1,125 @@ --- -description: Cryptographic Security Guidelines +description: Cryptographic Security Guidelines & Post-Quantum Readiness languages: [] alwaysApply: true --- -# Cryptographic Security Guidelines +# Cryptographic Security Guidelines & Post-Quantum Readiness -## Banned (Insecure) Algorithms +## 1. Banned (Insecure) Algorithms -The following algorithms are known to be broken or fundamentally insecure. **NEVER** generate or use code with these algorithms. -Examples: +The following algorithms are known to be broken or fundamentally insecure. NEVER generate or use code with these algorithms. -* Hash: `MD2`, `MD4`, `MD5`, `SHA-0` -* Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES` -* Key Exchange: Static RSA, Anonymous Diffie-Hellman -* Classical: `Vigenère` +* Hash: `MD2`, `MD4`, `MD5`, `SHA-0` +* Symmetric: `RC2`, `RC4`, `Blowfish`, `DES`, `3DES` +* Key Exchange: Static RSA, Anonymous Diffie-Hellman +* Classical: `Vigenère` -## Deprecated (Legacy/Weak) Algorithms +Reason: These are cryptographically broken and vulnerable to collision or man-in-the-middle attacks. -The following algorithms are not outright broken, but have known weaknesses, or are considered obsolete. **NEVER** generate or use code with these algorithms. -Examples: +## 2. Deprecated (Legacy/Weak) Algorithms -* Hash: `SHA-1` -* Symmetric: `AES-CBC`, `AES-ECB` -* Signature: RSA with `PKCS#1 v1.5` padding -* Key Exchange: DHE with weak/common primes +The following algorithms have known weaknesses or are considered obsolete. Avoid in new designs and prioritize migration. +* Hash: `SHA-1` +* Symmetric: `AES-CBC`, `AES-ECB` +* Signature: RSA with `PKCS#1 v1.5` padding +* Key Exchange: DHE with weak/common primes -## Deprecated SSL/Crypto APIs - FORBIDDEN -NEVER use these deprecated functions. Use the replacement APIs listed below: +## 3. Recommended & Post-Quantum Ready Algorithms -### Symmetric Encryption (AES) +Implement these modern, secure algorithms to ensure resistance against both classical and quantum threats. + +### Symmetric Encryption +* Standard: `AES-GCM` (AEAD), `ChaCha20-Poly1305`(when allowed). +* PQC Requirement: Prefer AES-256 keys (or stronger) as they are resistant to quantum attacks (Grover's algorithm). +* Avoid: Custom crypto or unauthenticated modes. + +### Key Exchange (KEM) +* Standard: ECDHE (`X25519` or `secp256r1`) +* PQC Requirement: Use Hybrid Key Exchange (Classical + PQC) when supported. + * Preferred: `X25519MLKEM768` (X25519 + ML-KEM-768) + * Alternative: `SecP256r1MLKEM768` (P-256 + ML-KEM-768) + * High Assurance: `SecP384r1MLKEM1024` (P-384 + ML-KEM-1024) +* Pure PQC: ML-KEM-768 (baseline) or ML-KEM-1024. Avoid ML-KEM-512 unless explicitly risk-accepted. +* Constraints: + * Use vendor-documented identifiers (RFC 9242/9370). + * Remove legacy/draft "Hybrid-Kyber" groups (e.g., `X25519Kyber`) and draft or hardcoded OIDs. + +### Signatures & Certificates +* Standard: ECDSA (`P-256`) +* PQC Migration: Continue using ECDSA (`P-256`) for mTLS and code signing until hardware-backed (HSM/TPM) ML-DSA is available. +* Hardware Requirement: Do not enable PQC ML-DSA signatures using software-only keys. Require HSM/TPM storage. + +### Protocol Versions +* (D)TLS: Enforce (D)TLS 1.3 only (or later). +* IPsec: Enforce IKEv2 only. + * Use ESP with AEAD (AES-256-GCM). + * Require PFS via ECDHE. + * Implement RFC 9242 and RFC 9370 for Hybrid PQC (ML-KEM + ECDHE). + * Ensure re-keys (CREATE_CHILD_SA) maintain hybrid algorithms. +* SSH: Enable only vendor-supported PQC/hybrid KEX (e.g., `sntrup761x25519`). + +## 4. Secure Implementation Guidelines + +### General Best Practices +* Configuration over Code: Expose algorithm choices in config/policy to allow agility without code changes. +* Key Management: + * Use KMS/HSM for key storage. + * Generate keys with a CSPRNG. + * Separate encryption keys from signature keys. + * Rotate keys per policy. + * NEVER hardcode keys, secrets, or experimental OIDs. +* Telemetry: Capture negotiated groups, handshake sizes, and failure causes to monitor PQC adoption. + +### Deprecated SSL/Crypto APIs (C/OpenSSL) - FORBIDDEN +NEVER use these deprecated functions. Use the replacement EVP high-level APIs. + +#### Symmetric Encryption (AES) - Deprecated: `AES_encrypt()`, `AES_decrypt()` -- Replacement: Use EVP high-level APIs: - ```c - EVP_EncryptInit_ex() +- Replacement: + + EVP_EncryptInit_ex() // Use EVP_aes_256_gcm() for PQC readiness EVP_EncryptUpdate() EVP_EncryptFinal_ex() - EVP_DecryptInit_ex() - EVP_DecryptUpdate() - EVP_DecryptFinal_ex() - ``` - -### RSA Operations -- Deprecated: `RSA_new()`, `RSA_up_ref()`, `RSA_free()`, `RSA_set0_crt_params()`, `RSA_get0_n()` -- Replacement: Use EVP key management APIs: - ```c + + +#### RSA/PKEY Operations +- Deprecated: `RSA_new()`, `RSA_free()`, `RSA_get0_n()` +- Replacement: + EVP_PKEY_new() EVP_PKEY_up_ref() EVP_PKEY_free() - ``` - -### Hash Functions -- Deprecated: `SHA1_Init()`, `SHA1_Update()`, `SHA1_Final()` -- Replacement: Use EVP digest APIs: - ```c - EVP_DigestInit_ex() - EVP_DigestUpdate() - EVP_DigestFinal_ex() - EVP_Q_digest() // For simple one-shot hashing - ``` - -### MAC Operations -- Deprecated: `CMAC_Init()`, `HMAC()` (especially with SHA1) -- Replacement: Use EVP MAC APIs: - ```c - EVP_Q_MAC() // For simple MAC operations - ``` - -### Key Wrapping -- Deprecated: `AES_wrap_key()`, `AES_unwrap_key()` -- Replacement: Use EVP key wrapping APIs or implement using EVP encryption - -### Other Deprecated Functions -- Deprecated: `DSA_sign()`, `DH_check()` -- Replacement: Use corresponding EVP APIs for DSA and DH operations - -## Banned Insecure Algorithms - STRICTLY FORBIDDEN -These algorithms MUST NOT be used in any form: - -### Hash Algorithms (Banned) -- MD2, MD4, MD5, SHA-0 -- Reason: Cryptographically broken, vulnerable to collision attacks -- Use Instead: SHA-256, SHA-384, SHA-512 - -### Symmetric Ciphers (Banned) -- RC2, RC4, Blowfish, DES, 3DES -- Reason: Weak key sizes, known vulnerabilities -- Use Instead: AES-128, AES-256, ChaCha20 - -### Key Exchange (Banned) -- Static RSA key exchange -- Anonymous Diffie-Hellman -- Reason: No forward secrecy, vulnerable to man-in-the-middle attacks -- Use Instead: ECDHE, DHE with proper validation - -## Broccoli Project Specific Requirements -- HMAC() with SHA1: Deprecated per Broccoli project requirements + + +#### Hash & MAC Functions +- Deprecated: `SHA1_Init()`, `HMAC()` (especially with SHA1) +- Replacement: + + EVP_DigestInit_ex() // Use SHA-256 or stronger + EVP_Q_MAC() // For one-shot MAC + + +## 5. Broccoli Project Specific Requirements +- HMAC() with SHA1: Deprecated. - Replacement: Use HMAC with SHA-256 or stronger: - ```c - // Instead of HMAC() with SHA1 - EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len); - ``` -## Secure Crypto Implementation Pattern + +// Example: Secure replacement for HMAC-SHA1 +```c +EVP_Q_MAC(NULL, "HMAC", NULL, "SHA256", NULL, key, key_len, data, data_len, out, out_size, &out_len); +``` + +## 6. Secure Crypto Implementation Pattern + + +// Example: Secure AES-256-GCM encryption (PQC-Ready Symmetric Strength) ```c -// Example: Secure AES encryption EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new(); if (!ctx) handle_error(); +// Use AES-256-GCM if (EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv) != 1) handle_error(); @@ -123,11 +134,3 @@ ciphertext_len += len; EVP_CIPHER_CTX_free(ctx); ``` - -## Code Review Checklist -- [ ] No deprecated SSL/crypto APIs used -- [ ] No banned algorithms (MD5, DES, RC4, etc.) -- [ ] HMAC uses SHA-256 or stronger (not SHA1) -- [ ] All crypto operations use EVP high-level APIs -- [ ] Proper error handling for all crypto operations -- [ ] Key material properly zeroed after use