Cryptographic Security Guidelines: add PQC readiness; consolidate into core rule

[vparla]

Summary

• Merge PQC guidance into the core cryptographic guidelines; remove standalone PQC rule.

Key updates

• Recommended & PQC-ready:
  • Symmetric: AES-GCM (AEAD), ChaCha20-Poly1305 where allowed; prefer AES-256.
  • (D)TLS: enforce 1.3 only; hybrids per I-D.ietf-tls-ecdhe-mlkem (X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024); pure ML-KEM (768 baseline; 1024 where required).
  • IPsec/IKEv2: IKEv2-only; AEAD ESP; PFS via ECDHE; RFC 9242/9370 hybrids; ensure re-keys (CREATE_CHILD_SA) maintain hybrids.
  • Signatures: continue ECDSA P-256 until HSM/TPM ML-DSA is available; no software-only ML-DSA.
• General: configuration over code; KMS/HSM; telemetry of negotiated groups/handshake sizes; remove legacy "Hybrid-Kyber" and draft OIDs.
• Deprecated SSL/Crypto APIs: use EVP high-level APIs; avoid SHA-1 and HMAC(SHA1).

Files

• Updated: sources/core/codeguard-1-crypto-algorithms.md
• Removed: sources/core/codeguard-1-post-quantum-cryptography.md; skills/software-security/rules/codeguard-1-post-quantum-cryptography.md
• Regenerated: skills/software-security/rules/codeguard-1-crypto-algorithms.md

Validation

• Validator: 108/108 passed
• Converter: all conversions successful
• Frontmatter: description + alwaysApply: true

[Copilot]

Pull request overview

This PR introduces comprehensive Post-Quantum Cryptography (PQC) guidance covering both (D)TLS and IKEv2/IPsec transports. The guidance specifies hybrid and pure ML-KEM key exchange mechanisms, following emerging IETF standards for quantum-resistant cryptography.

Key changes:

• Added (D)TLS 1.3 PQC named groups (X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024) per I-D.ietf-tls-ecdhe-mlkem
• Introduced IKEv2/IPsec hybrid PQC support via RFC 9242/9370 with comprehensive re-keying guidance
• Established migration strategy, implementation checklist, and test plan for PQC adoption

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
sources/core/codeguard-1-post-quantum-cryptography.md	New PQC guidance source document defining implementation requirements, migration strategy, and testing approach across TLS and IPsec transports
skills/software-security/rules/codeguard-1-post-quantum-cryptography.md	Regenerated skill file from source with added rule_id, otherwise identical content

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[santosomar]

The original codeguard-1-crypto-algorithms.md and the new "Post-Quantum Cryptography (PQC)" rules can be combined because PQC is not a separate discipline; it is the modern standard for cryptographic security. Treating them as separate rules risks creating a "split-brain" situation where a coding agent might follow standard guidelines but miss critical forward-looking requirements.

Here is why combining them into a single, unified source of truth is the correct architectural decision:

1. Thematic Overlap

Both rules fundamentally govern the same three primitives of secure communication. PQC doesn't replace these categories; it simply updates the acceptable parameters for them.

Category	Original Rule Focus	PQC Rule Focus	Why Combine?
Symmetric Encryption	Banned legacy algorithms (DES, RC4) and modes (CBC).	Recommends AES-256 for quantum resistance (Grover's algorithm).	A single rule now defines "Safe Symmetric Encryption" as: Authenticated (GCM) + Strong Keys (256-bit).
Key Exchange	Banned static RSA and weak DHE.	mandated Hybrid Exchange (Classical ECDHE + ML-KEM).	Separating them would be confusing: one rule says "Use ECDHE," the other says "Use Hybrid." The combined rule clarifies that Hybrid is the new standard for ECDHE.
Protocols	Implied modern standards.	Explicitly enforces TLS 1.3 and IKEv2.	PQC relies heavily on protocol versions (like TLS 1.3) to support the large keys required for post-quantum algorithms.

2. Preventing Contradictions

If kept separate, the rules could offer conflicting advice or "partial truths":

• The "Safe" Falsehood: The original rule might flag AES-128-GCM as "Safe" because it's not broken classically. However, PQC guidance specifically prefers AES-256 for long-term data protection. A unified rule captures this nuance: "Safe, but prefer AES-256 for future-proofing."
• Key Exchange Confusion: The original rule warns against weak Diffie-Hellman. The PQC rule introduces "Hybrid" groups. A developer reading only the first rule might implement standard X25519 and think they are done, missing the critical requirement to layer ML-KEM on top for quantum resistance.

3. Simplified Compliance (One Source of Truth)

For a developer or auditor, having a single "Cryptographic Security & Readiness" checklist is far more efficient than checking two separate lists:

1. Inventory: You only need to inventory crypto usage once.
2. Migration: The "Banned" list (MD5, SHA1) seamlessly flows into the "Migration" plan (Adopt ML-KEM). It presents a clear maturity path: Stop doing the bad things -> Do the standard things -> Start doing the post-quantum things.

By merging them, we transformed the document from a static "Don't do this" list into a proactive "Here is how to secure your application for the next decade" guide.

---

We can combine them as follows:

---
description: Cryptographic Security Guidelines & Post-Quantum Readiness
languages: []
alwaysApply: true
---

# Cryptographic Security Guidelines & Post-Quantum Readiness

## 1. Banned (Insecure) Algorithms

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`

Reason: These are cryptographically broken and vulnerable to collision or man-in-the-middle attacks.

## 2. Deprecated (Legacy/Weak) Algorithms

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

## 3. Recommended & Post-Quantum Ready Algorithms

Implement these modern, secure algorithms to ensure resistance against both classical and quantum threats.

### Symmetric Encryption
*   Standard: `AES-GCM` (AEAD), `ChaCha20-Poly1305`
*   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 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:

  EVP_EncryptInit_ex()   // Use EVP_aes_256_gcm() for PQC readiness
  EVP_EncryptUpdate()
  EVP_EncryptFinal_ex()


#### RSA/PKEY Operations
- Deprecated: `RSA_new()`, `RSA_free()`, `RSA_get0_n()`
- Replacement:

  EVP_PKEY_new()
  EVP_PKEY_up_ref()
  EVP_PKEY_free()
 

#### 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:


  // Secure replacement for HMAC-SHA1
  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)
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);

[vparla]

Great comments @santosomar. I will review the proposed combined file and submit an updated revision.

[vparla]

Hi @santosomar — addressed your feedback by consolidating PQC guidance into the core cryptographic rule and removing the standalone PQC file.

Highlights:

• (D)TLS 1.3 only; TLS NamedGroups for hybrids (X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024) and pure ML‑KEM (768 baseline; 1024 where required); removed legacy “Hybrid‑Kyber”.
• IPsec/IKEv2: IKEv2-only; AEAD ESP; PFS via ECDHE; RFC 9242/9370 hybrids; explicit re‑key (CREATE_CHILD_SA) guidance.
• Symmetric/signatures: AES‑GCM/ChaCha20‑Poly1305 (where allowed); prefer AES‑256; continue ECDSA P‑256 until HSM/TPM ML‑DSA is available.
• General: configuration over code; KMS/HSM; telemetry updates; EVP APIs; avoid SHA‑1/HMAC(SHA1).

Validation/conversion rerun; skills regenerated. Please re-review when convenient — thank you!

[santosomar]

Thank you so much!

[ramraaj25]

Rule LGTM, Thank You!