v1.0.0 to v1.5.0
89 added, 86 removed. Audit A to A.
---
- description: Cryptographic Security Guidelines
+ description: Cryptographic Security Guidelines & Post-Quantum Readiness
globs: **/*
- version: 1.0.0
+ version: 1.5.0
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
- ```
+ #### Hash & MAC Functions
+ - Deprecated: `SHA1_Init()`, `HMAC()` (especially with SHA1)
+ - Replacement:
- ### Key Wrapping
- - Deprecated: `AES_wrap_key()`, `AES_unwrap_key()`
- - Replacement: Use EVP key wrapping APIs or implement using EVP encryption
+ EVP_DigestInit_ex() // Use SHA-256 or stronger
+ EVP_Q_MAC() // For one-shot MAC
- ### 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:
+ ## 5. Broccoli Project Specific Requirements
+ - HMAC() with SHA1: Deprecated.
+ - Replacement: Use HMAC with SHA-256 or stronger:
- ### 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
+ // 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);
+ ```
- ### 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
+ ## 6. Secure Crypto Implementation Pattern
- ## Broccoli Project Specific Requirements
- - HMAC() with SHA1: Deprecated per Broccoli project requirements
- - 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 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();
int len, ciphertext_len;
if (EVP_EncryptUpdate(ctx, ciphertext, &len, plaintext, plaintext_len) != 1)
handle_error();
ciphertext_len = len;
if (EVP_EncryptFinal_ex(ctx, ciphertext + len, &len) != 1)
handle_error();
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