From eace1ed3480b439f3178aedd7aa56cac1049fb8c Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Wed, 19 Nov 2025 09:46:17 -0500 Subject: [PATCH 01/22] Add core PQC rule with hybrid ML-KEM-768 guidance, ML-KEM selection/packet-size notes, ECDHE pairing examples, and TPM/mTLS guidance; regenerate Claude Code skills --- .../codeguard-1-post-quantum-cryptography.md | 98 +++++++++++++++++++ .../codeguard-1-post-quantum-cryptography.md | 96 ++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 skills/software-security/rules/codeguard-1-post-quantum-cryptography.md create mode 100644 sources/core/codeguard-1-post-quantum-cryptography.md diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md new file mode 100644 index 0000000..2b82d94 --- /dev/null +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -0,0 +1,98 @@ +--- +description: Post-Quantum Cryptography (PQC) guidance and migration best practices +alwaysApply: true +--- + +rule_id: codeguard-1-post-quantum-cryptography + +# Post-Quantum Cryptography (PQC) + +Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. + +## Goals +- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. +- Maintain algorithm agility (configurable algorithms, decoupled from business logic). +- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. +- Validate interoperability and performance before broad rollout. + +## Algorithm Selection (Key Establishment and Signatures) +- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. +- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. + - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. + +## ML-KEM Parameter Set Selection and Packet Size Considerations +- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. +- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. +- Packet/message size impacts: + - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. + - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. + - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. + - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). +- Operational guidance: + - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. + - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. + - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. + +## Recommendation for Multi-Tenant Ecosystems +- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. +- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. +- Implementation guidance: + - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. + - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. + - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. + +## Deprecations and Disallowed Predecessors +- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. +- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. + +## Protocol Guidance (e.g., TLS, SSH, HPKE) +- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. +- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. +- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. +- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. + +## Key Management and Operations +- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. +- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. +- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. +- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. +- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. + +## Authenticators and Credentials +- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. +- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. +- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. + +## Digital Signatures and Code/Artifact Signing +- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. +- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. +- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. +- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. + +## Adoptable Today (Open Source Projects) +- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. +- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. +- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. +- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. + +## Migration Plan +- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. +- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. +- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. +- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. + +## Implementation Checklist +- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. +- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. +- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. +- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. +- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. +- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. + +## Test Plan +- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. +- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. +- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. +- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md new file mode 100644 index 0000000..a99e200 --- /dev/null +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -0,0 +1,96 @@ +--- +description: Post-Quantum Cryptography (PQC) guidance and migration best practices +alwaysApply: true +--- + +# Post-Quantum Cryptography (PQC) + +Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. + +## Goals +- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. +- Maintain algorithm agility (configurable algorithms, decoupled from business logic). +- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. +- Validate interoperability and performance before broad rollout. + +## Algorithm Selection (Key Establishment and Signatures) +- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. +- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. + - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. + +## ML-KEM Parameter Set Selection and Packet Size Considerations +- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. +- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. +- Packet/message size impacts: + - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. + - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. + - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. + - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). +- Operational guidance: + - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. + - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. + - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. + +## Recommendation for Multi-Tenant Ecosystems +- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. +- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. +- Implementation guidance: + - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. + - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. + - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. + +## Deprecations and Disallowed Predecessors +- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. +- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. + +## Protocol Guidance (e.g., TLS, SSH, HPKE) +- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. +- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. +- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. +- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. + +## Key Management and Operations +- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. +- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. +- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. +- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. +- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. + +## Authenticators and Credentials +- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. +- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. +- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. + +## Digital Signatures and Code/Artifact Signing +- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. +- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. +- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. +- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. + +## Adoptable Today (Open Source Projects) +- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. +- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. +- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. +- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. + +## Migration Plan +- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. +- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. +- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. +- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. + +## Implementation Checklist +- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. +- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. +- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. +- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. +- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. +- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. + +## Test Plan +- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. +- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. +- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. +- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. From c69d9fb8b0c7a343390eb7a4548005afbcb7bcad Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Thu, 20 Nov 2025 21:36:03 -0500 Subject: [PATCH 02/22] docs(pqc): concise implementation/testing focus; prohibit draft Kyber; add ML-KEM-512 constrained-use guidance; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 114 +++++------------- .../codeguard-1-post-quantum-cryptography.md | 114 +++++------------- 2 files changed, 58 insertions(+), 170 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 2b82d94..b17a344 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -7,92 +7,36 @@ rule_id: codeguard-1-post-quantum-cryptography # Post-Quantum Cryptography (PQC) -Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. - -## Goals -- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. -- Maintain algorithm agility (configurable algorithms, decoupled from business logic). -- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. -- Validate interoperability and performance before broad rollout. - -## Algorithm Selection (Key Establishment and Signatures) -- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. -- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. - - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. - -## ML-KEM Parameter Set Selection and Packet Size Considerations -- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. -- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. -- Packet/message size impacts: - - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. - - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. - - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. - - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). -- Operational guidance: - - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. - - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. - - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. - -## Recommendation for Multi-Tenant Ecosystems -- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. -- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. -- Implementation guidance: - - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. - - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. - - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. - -## Deprecations and Disallowed Predecessors -- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. -- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. - -## Protocol Guidance (e.g., TLS, SSH, HPKE) -- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. -- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. -- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. -- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. - -## Key Management and Operations -- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. -- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. -- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. -- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. -- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. - -## Authenticators and Credentials -- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. -- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. -- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. - -## Digital Signatures and Code/Artifact Signing -- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. -- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. -- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. -- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. - -## Adoptable Today (Open Source Projects) -- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. -- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. -- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. -- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. - -## Migration Plan -- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. -- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. -- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. -- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. +Concise Code Guard focused on what to implement and how to test it. + +## Implementation (Do this) +- Enforce TLS 1.3 only (or later when available). +- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + +## Migration +- Inventory endpoints and crypto usage. +- Prioritize external/high‑value/long‑lived flows. +- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. ## Implementation Checklist -- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. -- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. -- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. -- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. -- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. -- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. +- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. +- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. +- Algorithm agility via configuration (not code); explicit fallback behavior. +- Keys via validated modules; separated by purpose; rotation policy in place. +- TLS version and group selections align with supported PQC options. +- Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan -- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. -- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. -- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. -- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. +- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. +- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. +- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index a99e200..9305ba2 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -5,92 +5,36 @@ alwaysApply: true # Post-Quantum Cryptography (PQC) -Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. - -## Goals -- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. -- Maintain algorithm agility (configurable algorithms, decoupled from business logic). -- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. -- Validate interoperability and performance before broad rollout. - -## Algorithm Selection (Key Establishment and Signatures) -- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. -- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. - - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. - -## ML-KEM Parameter Set Selection and Packet Size Considerations -- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. -- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. -- Packet/message size impacts: - - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. - - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. - - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. - - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). -- Operational guidance: - - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. - - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. - - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. - -## Recommendation for Multi-Tenant Ecosystems -- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. -- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. -- Implementation guidance: - - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. - - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. - - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. - -## Deprecations and Disallowed Predecessors -- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. -- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. - -## Protocol Guidance (e.g., TLS, SSH, HPKE) -- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. -- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. -- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. -- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. - -## Key Management and Operations -- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. -- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. -- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. -- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. -- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. - -## Authenticators and Credentials -- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. -- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. -- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. - -## Digital Signatures and Code/Artifact Signing -- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. -- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. -- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. -- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. - -## Adoptable Today (Open Source Projects) -- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. -- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. -- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. -- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. - -## Migration Plan -- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. -- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. -- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. -- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. +Concise Code Guard focused on what to implement and how to test it. + +## Implementation (Do this) +- Enforce TLS 1.3 only (or later when available). +- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + +## Migration +- Inventory endpoints and crypto usage. +- Prioritize external/high‑value/long‑lived flows. +- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. ## Implementation Checklist -- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. -- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. -- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. -- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. -- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. -- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. +- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. +- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. +- Algorithm agility via configuration (not code); explicit fallback behavior. +- Keys via validated modules; separated by purpose; rotation policy in place. +- TLS version and group selections align with supported PQC options. +- Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan -- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. -- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. -- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. -- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. +- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. +- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. +- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. From db831a39a88747a193c7d1199ea01cdb797b169c Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Mon, 24 Nov 2025 12:40:42 -0500 Subject: [PATCH 03/22] docs(pqc): clarify AES unaffected by Shor; recommend AES-256; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 26 ++++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 26 ++++++++++--------- 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index b17a344..bb4e54b 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -12,14 +12,16 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. + - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. + - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. + - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. + - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. + - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. + - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. + - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. + - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. @@ -30,13 +32,13 @@ Concise Code Guard focused on what to implement and how to test it. - Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. - No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. -- Algorithm agility via configuration (not code); explicit fallback behavior. -- Keys via validated modules; separated by purpose; rotation policy in place. -- TLS version and group selections align with supported PQC options. -- Monitoring in place for handshake success/latency/errors and negotiated groups. + - Algorithm agility via configuration (not code); explicit fallback behavior. + - Keys via validated modules; separated by purpose; rotation policy in place. + - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. + - TLS version and group selections align with supported PQC options. + - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. -- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 9305ba2..4280e07 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -10,14 +10,16 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. + - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. + - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. + - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. + - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. + - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. + - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. + - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. + - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. @@ -28,13 +30,13 @@ Concise Code Guard focused on what to implement and how to test it. - Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. - No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. -- Algorithm agility via configuration (not code); explicit fallback behavior. -- Keys via validated modules; separated by purpose; rotation policy in place. -- TLS version and group selections align with supported PQC options. -- Monitoring in place for handshake success/latency/errors and negotiated groups. + - Algorithm agility via configuration (not code); explicit fallback behavior. + - Keys via validated modules; separated by purpose; rotation policy in place. + - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. + - TLS version and group selections align with supported PQC options. + - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. -- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. From d20a8b7ea3cf0c213d383a0ccaf65ae1c9a1d3cd Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Tue, 25 Nov 2025 11:24:36 -0500 Subject: [PATCH 04/22] docs(pqc): add IPsec guidance; reference IKEv2 PQC RFCs 9242/9370; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 20 ++++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 20 ++++++++++--------- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index bb4e54b..8d2fa19 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -11,17 +11,19 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. - - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. - - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. - - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. +- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 4280e07..8c4c573 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -9,17 +9,19 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. - - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. - - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. - - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. +- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. From 46ea915cf4be7b6abdb6327c81319b44a928860d Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Tue, 25 Nov 2025 12:21:08 -0500 Subject: [PATCH 05/22] docs(pqc): clarify DTLS; enforce (D)TLS 1.3 only; regenerate skills --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- sources/core/codeguard-1-post-quantum-cryptography.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 8d2fa19..de29183 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -10,7 +10,7 @@ rule_id: codeguard-1-post-quantum-cryptography Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) -- Enforce TLS 1.3 only (or later when available). +- Enforce (D)TLS 1.3 only (or later when available). - IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); - IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 8c4c573..0b137cc 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -8,7 +8,7 @@ alwaysApply: true Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) -- Enforce TLS 1.3 only (or later when available). +- Enforce (D)TLS 1.3 only (or later when available). - IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); - IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. From 7a0972a5cc2ff3bf9bf58b1199dc7400b453441b Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Thu, 4 Dec 2025 14:13:52 -0500 Subject: [PATCH 06/22] docs(pqc): (D)TLS PQC groups + IKEv2/IPsec re-key; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 23 +++++++++++++++---- .../codeguard-1-post-quantum-cryptography.md | 23 +++++++++++++++---- 2 files changed, 36 insertions(+), 10 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index de29183..3674a4f 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -11,10 +11,18 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce (D)TLS 1.3 only (or later when available). -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- (D)TLS PQC key exchange (when supported by your stack): + - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: + - X25519MLKEM768 (X25519 + ML‑KEM‑768) + - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) + - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments + - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: + - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance + - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. @@ -22,8 +30,9 @@ Concise Code Guard focused on what to implement and how to test it. - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. @@ -37,10 +46,14 @@ Concise Code Guard focused on what to implement and how to test it. - Algorithm agility via configuration (not code); explicit fallback behavior. - Keys via validated modules; separated by purpose; rotation policy in place. - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - TLS version and group selections align with supported PQC options. + - (D)TLS version and group selections align with supported PQC options. + - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. +- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 0b137cc..4263372 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -9,10 +9,18 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce (D)TLS 1.3 only (or later when available). -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- (D)TLS PQC key exchange (when supported by your stack): + - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: + - X25519MLKEM768 (X25519 + ML‑KEM‑768) + - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) + - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments + - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: + - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance + - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. @@ -20,8 +28,9 @@ Concise Code Guard focused on what to implement and how to test it. - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. @@ -35,10 +44,14 @@ Concise Code Guard focused on what to implement and how to test it. - Algorithm agility via configuration (not code); explicit fallback behavior. - Keys via validated modules; separated by purpose; rotation policy in place. - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - TLS version and group selections align with supported PQC options. + - (D)TLS version and group selections align with supported PQC options. + - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. +- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From 12eb989b14aed1af829e5b33edbf1230ab8952ff Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:12:52 -0500 Subject: [PATCH 07/22] Update skills/software-security/rules/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 3674a4f..1f01b2f 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -54,6 +54,6 @@ Concise Code Guard focused on what to implement and how to test it. - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. - Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SAs maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From 8ec9f5e9a04f3c8509b0c83eb1e43c345d72d176 Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:13:30 -0500 Subject: [PATCH 08/22] Update skills/software-security/rules/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 1f01b2f..41913c6 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -32,7 +32,7 @@ Concise Code Guard focused on what to implement and how to test it. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. +- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. From 08b5a34b59e60098fc93da08ac51463ac1515d63 Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:13:38 -0500 Subject: [PATCH 09/22] Update sources/core/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- sources/core/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 4263372..c2c6919 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -30,7 +30,7 @@ Concise Code Guard focused on what to implement and how to test it. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. +- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. From bfe9ba0b0e1e306b5a295bf6edafbb712c535648 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Wed, 10 Dec 2025 11:25:34 -0500 Subject: [PATCH 10/22] Cryptographic Security Guidelines: add PQC readiness; consolidate into core rule; remove standalone PQC; regenerate skills --- .../rules/codeguard-1-crypto-algorithms.md | 189 +++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 59 ------ sources/core/codeguard-1-crypto-algorithms.md | 189 +++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 57 ------ 4 files changed, 192 insertions(+), 302 deletions(-) delete mode 100644 skills/software-security/rules/codeguard-1-post-quantum-cryptography.md delete mode 100644 sources/core/codeguard-1-post-quantum-cryptography.md 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/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md deleted file mode 100644 index 41913c6..0000000 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Post-Quantum Cryptography (PQC) guidance and migration best practices -alwaysApply: true ---- - -rule_id: codeguard-1-post-quantum-cryptography - -# Post-Quantum Cryptography (PQC) - -Concise Code Guard focused on what to implement and how to test it. - -## Implementation (Do this) -- Enforce (D)TLS 1.3 only (or later when available). -- (D)TLS PQC key exchange (when supported by your stack): - - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: - - X25519MLKEM768 (X25519 + ML‑KEM‑768) - - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) - - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments - - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: - - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance - - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. -- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. -- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. - -## Migration -- Inventory endpoints and crypto usage. -- Prioritize external/high‑value/long‑lived flows. -- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. - -## Implementation Checklist -- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. -- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. - - Algorithm agility via configuration (not code); explicit fallback behavior. - - Keys via validated modules; separated by purpose; rotation policy in place. - - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - (D)TLS version and group selections align with supported PQC options. - - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - - Monitoring in place for handshake success/latency/errors and negotiated groups. - -## Test Plan -- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. -- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. -- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SAs maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. -- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. -- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. 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 diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md deleted file mode 100644 index c2c6919..0000000 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: Post-Quantum Cryptography (PQC) guidance and migration best practices -alwaysApply: true ---- - -# Post-Quantum Cryptography (PQC) - -Concise Code Guard focused on what to implement and how to test it. - -## Implementation (Do this) -- Enforce (D)TLS 1.3 only (or later when available). -- (D)TLS PQC key exchange (when supported by your stack): - - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: - - X25519MLKEM768 (X25519 + ML‑KEM‑768) - - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) - - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments - - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: - - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance - - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. -- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. -- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. - -## Migration -- Inventory endpoints and crypto usage. -- Prioritize external/high‑value/long‑lived flows. -- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. - -## Implementation Checklist -- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. -- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. - - Algorithm agility via configuration (not code); explicit fallback behavior. - - Keys via validated modules; separated by purpose; rotation policy in place. - - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - (D)TLS version and group selections align with supported PQC options. - - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - - Monitoring in place for handshake success/latency/errors and negotiated groups. - -## Test Plan -- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. -- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. -- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. -- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. -- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From 704d9f276a1e8daade86711853e2b4391edcea25 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Wed, 19 Nov 2025 09:46:17 -0500 Subject: [PATCH 11/22] Add core PQC rule with hybrid ML-KEM-768 guidance, ML-KEM selection/packet-size notes, ECDHE pairing examples, and TPM/mTLS guidance; regenerate Claude Code skills --- .../codeguard-1-post-quantum-cryptography.md | 98 +++++++++++++++++++ .../codeguard-1-post-quantum-cryptography.md | 96 ++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 skills/software-security/rules/codeguard-1-post-quantum-cryptography.md create mode 100644 sources/core/codeguard-1-post-quantum-cryptography.md diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md new file mode 100644 index 0000000..2b82d94 --- /dev/null +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -0,0 +1,98 @@ +--- +description: Post-Quantum Cryptography (PQC) guidance and migration best practices +alwaysApply: true +--- + +rule_id: codeguard-1-post-quantum-cryptography + +# Post-Quantum Cryptography (PQC) + +Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. + +## Goals +- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. +- Maintain algorithm agility (configurable algorithms, decoupled from business logic). +- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. +- Validate interoperability and performance before broad rollout. + +## Algorithm Selection (Key Establishment and Signatures) +- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. +- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. + - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. + +## ML-KEM Parameter Set Selection and Packet Size Considerations +- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. +- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. +- Packet/message size impacts: + - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. + - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. + - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. + - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). +- Operational guidance: + - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. + - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. + - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. + +## Recommendation for Multi-Tenant Ecosystems +- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. +- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. +- Implementation guidance: + - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. + - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. + - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. + +## Deprecations and Disallowed Predecessors +- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. +- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. + +## Protocol Guidance (e.g., TLS, SSH, HPKE) +- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. +- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. +- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. +- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. + +## Key Management and Operations +- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. +- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. +- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. +- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. +- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. + +## Authenticators and Credentials +- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. +- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. +- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. + +## Digital Signatures and Code/Artifact Signing +- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. +- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. +- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. +- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. + +## Adoptable Today (Open Source Projects) +- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. +- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. +- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. +- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. + +## Migration Plan +- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. +- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. +- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. +- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. + +## Implementation Checklist +- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. +- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. +- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. +- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. +- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. +- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. + +## Test Plan +- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. +- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. +- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. +- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md new file mode 100644 index 0000000..a99e200 --- /dev/null +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -0,0 +1,96 @@ +--- +description: Post-Quantum Cryptography (PQC) guidance and migration best practices +alwaysApply: true +--- + +# Post-Quantum Cryptography (PQC) + +Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. + +## Goals +- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. +- Maintain algorithm agility (configurable algorithms, decoupled from business logic). +- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. +- Validate interoperability and performance before broad rollout. + +## Algorithm Selection (Key Establishment and Signatures) +- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. +- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. + - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. + +## ML-KEM Parameter Set Selection and Packet Size Considerations +- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. +- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. +- Packet/message size impacts: + - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. + - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. + - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. + - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). +- Operational guidance: + - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. + - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. + - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. + +## Recommendation for Multi-Tenant Ecosystems +- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. +- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. +- Implementation guidance: + - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. + - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. + - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. + +## Deprecations and Disallowed Predecessors +- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. +- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. + +## Protocol Guidance (e.g., TLS, SSH, HPKE) +- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. +- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. +- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. +- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. + +## Key Management and Operations +- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. +- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. +- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. +- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. +- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. + +## Authenticators and Credentials +- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. +- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. +- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. +- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. + +## Digital Signatures and Code/Artifact Signing +- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. +- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. +- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. +- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. + +## Adoptable Today (Open Source Projects) +- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. +- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. +- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. +- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. + +## Migration Plan +- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. +- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. +- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. +- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. + +## Implementation Checklist +- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. +- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. +- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. +- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. +- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. +- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. + +## Test Plan +- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. +- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. +- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. +- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. From ef560cdf919f1dd7f5df8357fbf05b460bdad9ae Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Thu, 20 Nov 2025 21:36:03 -0500 Subject: [PATCH 12/22] docs(pqc): concise implementation/testing focus; prohibit draft Kyber; add ML-KEM-512 constrained-use guidance; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 114 +++++------------- .../codeguard-1-post-quantum-cryptography.md | 114 +++++------------- 2 files changed, 58 insertions(+), 170 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 2b82d94..b17a344 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -7,92 +7,36 @@ rule_id: codeguard-1-post-quantum-cryptography # Post-Quantum Cryptography (PQC) -Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. - -## Goals -- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. -- Maintain algorithm agility (configurable algorithms, decoupled from business logic). -- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. -- Validate interoperability and performance before broad rollout. - -## Algorithm Selection (Key Establishment and Signatures) -- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. -- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. - - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. - -## ML-KEM Parameter Set Selection and Packet Size Considerations -- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. -- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. -- Packet/message size impacts: - - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. - - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. - - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. - - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). -- Operational guidance: - - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. - - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. - - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. - -## Recommendation for Multi-Tenant Ecosystems -- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. -- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. -- Implementation guidance: - - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. - - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. - - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. - -## Deprecations and Disallowed Predecessors -- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. -- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. - -## Protocol Guidance (e.g., TLS, SSH, HPKE) -- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. -- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. -- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. -- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. - -## Key Management and Operations -- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. -- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. -- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. -- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. -- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. - -## Authenticators and Credentials -- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. -- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. -- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. - -## Digital Signatures and Code/Artifact Signing -- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. -- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. -- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. -- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. - -## Adoptable Today (Open Source Projects) -- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. -- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. -- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. -- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. - -## Migration Plan -- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. -- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. -- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. -- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. +Concise Code Guard focused on what to implement and how to test it. + +## Implementation (Do this) +- Enforce TLS 1.3 only (or later when available). +- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + +## Migration +- Inventory endpoints and crypto usage. +- Prioritize external/high‑value/long‑lived flows. +- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. ## Implementation Checklist -- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. -- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. -- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. -- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. -- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. -- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. +- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. +- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. +- Algorithm agility via configuration (not code); explicit fallback behavior. +- Keys via validated modules; separated by purpose; rotation policy in place. +- TLS version and group selections align with supported PQC options. +- Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan -- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. -- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. -- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. -- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. +- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. +- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. +- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index a99e200..9305ba2 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -5,92 +5,36 @@ alwaysApply: true # Post-Quantum Cryptography (PQC) -Post-quantum cryptography protects long-lived secrets and future-proof communications against adversaries with quantum capabilities. Adopt PQC via supported libraries and protocols, favoring algorithm agility and incremental, interoperable rollout. - -## Goals -- Prefer standardized primitives and vendor-supported APIs; never implement custom crypto. -- Maintain algorithm agility (configurable algorithms, decoupled from business logic). -- Use hybrid key establishment during transition to preserve interoperability and defense-in-depth. -- Validate interoperability and performance before broad rollout. - -## Algorithm Selection (Key Establishment and Signatures) -- Key establishment (KEM): Use NIST-standardized ML-KEM (FIPS 203). Select parameter sets per risk and performance. -- Digital signatures: Use standardized ML-DSA (FIPS 204) where supported. Consider SLH-DSA (FIPS 205) where required by policy; account for larger signatures. - - Continue to rely on vendor-provided, audited implementations. Do not hardcode experimental group names or OIDs; use library-provided options. - -## ML-KEM Parameter Set Selection and Packet Size Considerations -- Minimum baseline: ML-KEM-768 should be the minimum consideration for general-purpose and multi-tenant deployments. Avoid ML-KEM-512 for broad use; only consider in highly constrained environments after explicit risk acceptance and compensating controls. -- High-assurance option: ML-KEM-1024 for regulated or high-assurance segments where added overhead is acceptable; validate capacity and latency budgets. -- Packet/message size impacts: - - ML-KEM public keys and ciphertexts increase handshake sizes; expect larger ClientHello/ServerHello and key exchange messages. - - Plan for path MTU and fragmentation: tune TLS record sizing as supported; validate middlebox tolerance to larger handshakes; monitor for handshake failures/timeouts. - - Assess QUIC vs TCP/TLS behavior in your environment; verify congestion and packetization with your vendor’s stack. - - Measure peak and P95 handshake size and latency before/after enabling hybrids; adjust proxy/load balancer limits as needed (e.g., header/body/initial settings). -- Operational guidance: - - Prefer vendor-documented hybrid groups or ciphersuites that include ML-KEM-768; avoid experimental or draft identifiers. - - Document fallback behavior and client capability detection; surface algorithm choices in configuration, not code. - - Ensure telemetry captures negotiated groups and retry causes to support safe rollouts and rollbacks. - -## Recommendation for Multi-Tenant Ecosystems -- Use a hybrid key establishment that combines a classical ECDHE group with ML-KEM-768. -- Rationale: ML-KEM-768 provides a widely recommended balance of security and performance suitable for shared, multi-tenant environments where diverse client capabilities and high request volume demand efficient handshakes. -- Implementation guidance: - - Enable the library’s supported hybrid mode pairing ML-KEM-768 with a classical group such as X25519 or secp256r1, as documented by the vendor. - - For example, use X25519 + ML-KEM-768 as the default hybrid pairing; use secp256r1 + ML-KEM-768 when X25519 is unavailable due to policy or platform constraints. - - Avoid bespoke or ad-hoc hybrids. Do not assemble hybrid handshakes manually; use stable, supported configuration flags or cipher/group selections provided by the stack. - -## Deprecations and Disallowed Predecessors -- Discontinue pre-standard, draft, or experiment-only Kyber-based hybrid groups and ciphers (often labeled generically as “Hybrid-Kyber” or with draft names like X25519Kyber…/P256_Kyber/CECPQ2). These predecessors must be replaced with a hybrid ML-KEM alternative provided by the vendor. -- Do not introduce new dependencies on legacy Kyber draft identifiers or OIDs. Migrate configuration and policy to ML-KEM-based hybrids in accordance with FIPS 203 and vendor guidance. - -## Protocol Guidance (e.g., TLS, SSH, HPKE) -- Prefer TLS 1.3 where hybrid KEMs are supported by your stack. New solutions should mandate using TLS 1.3 only and avoid TLS 1.2 and earlier versions where possible. -- Use vendor-documented hybrid groups that include ML-KEM-768 during transition. Avoid TLS 1.2 and earlier versions where possible. -- Only enable pure-PQC key establishment when interoperability with required clients is verified. Otherwise, deploy hybrid modes to preserve compatibility while adding PQC assurances. -- For signatures, adopt ML-DSA when supported by the protocol and vendor stack; validate message sizes, handshake overhead, and client support. - -## Key Management and Operations -- Generate keys via FIPS-validated or vendor-audited modules (KMS/HSM where available). Use a CSPRNG suitable for the platform. -- Maintain separate keys by purpose (encryption, signatures). Rotate per policy, compromise, or cryptoperiod changes. -- Store keys in KMS/HSM or secure vaults. Never hardcode keys or parameters; avoid plain environment variables for long-lived secrets. Prefer HW-based key protections over Software-only solutions. -- Ensure algorithm identifiers, parameters, and certificates reflect ML-KEM/ML-DSA selections from supported libraries; avoid stale Kyber-era identifiers. -- TPM-backed keys typically do not support ML-DSA today; for mTLS client/server authentication, continue to use EC algorithms supported by your TPM (e.g., ECDSA with secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- You can deploy hybrid ML-KEM key establishment while continuing to authenticate with ECDSA mTLS certificates; plan migration to ML-DSA-signed certificates when vendor hardware and ecosystem support becomes available. - -## Authenticators and Credentials -- FIDO2/WebAuthn: Platform and roaming authenticators today primarily use ECC (e.g., ECDSA/EdDSA). PQC attestation is not broadly deployed; continue using supported authenticators and track vendor roadmaps for PQC or hybrid attestation. -- TPM-backed mTLS: Current TPMs typically do not support ML-DSA. For client/server mTLS certificates, continue to use ECDSA (e.g., secp256r1) until suitable ML-DSA TPM implementations are available in hardware. -- Tokens and credentials: Hybrid ML-KEM key establishment protects transport but does not change token formats. Keep token signing on widely supported algorithms today and design for algorithm agility to adopt ML-DSA when ecosystems support it. -- Policy and configurability: Surface algorithm choices in configuration/policy (not code), define safe defaults and explicit fallback behavior, and capture telemetry for negotiated groups and failures. - -## Digital Signatures and Code/Artifact Signing -- Current practice: Use vetted, widely supported signatures (e.g., ECDSA P-256 or Ed25519) for code, container, and SBOM signing while PQC HSM/TPM support is nascent. -- Migration path: Plan for algorithm agility and adopt ML-DSA (FIPS 204) when your toolchain, HSMs/TPMs, and verifiers support it. Expect larger signatures and potential format/verification updates. -- Avoid drafts: Do not adopt draft/proprietary PQC signatures. Prefer standardized ML-DSA when available from audited libraries and hardware. -- Operational checks: Verify verifier support across CI/CD, registries, update servers, and clients; measure artifact size impact; ensure revocation and audit logs remain effective. - -## Adoptable Today (Open Source Projects) -- TLS 1.3 hybrid KEM with ML-KEM-768 is available using OpenSSL 3 with the oqs-provider (Open Quantum Safe) or OQS-OpenSSL builds. Use in controlled environments where you manage both client and server. Keep classical fallback enabled; note these builds are not yet FIPS-validated. -- SSH: OpenSSH supports a hybrid key exchange (sntrup761x25519). While not ML-KEM, it provides a PQC KEX option. Adopt per your policy until ML-KEM hybrids are supported in your SSH stack. -- HPKE and libraries: Open Quantum Safe libraries (liboqs) can be used to develop ML-KEM-based HPKE and related constructs. -- FIDO/WebAuthn (production today): Continue to use platform/hardware authenticators with classical algorithms (COSE ES256/ECDSA P-256; allow EdDSA where supported). Keep accepted COSE algorithms configurable on the RP/server, log negotiated algorithms, and maintain attestation/trust metadata. PQC authenticators/attestations are not broadly available today; track standards and vendor roadmaps. - -## Migration Plan -- Inventory cryptography usage and endpoints. Identify where key establishment and signature algorithms are configured or negotiated. -- Prioritize externally facing, high-value, and long-lived data flows for hybrid deployment first. -- Roll out hybrid ML-KEM-768 in stages with monitoring, fallbacks, and explicit client compat testing. -- Decommission predecessor “Hybrid-Kyber” configurations and remove any policy allowances or feature flags that enable them. +Concise Code Guard focused on what to implement and how to test it. + +## Implementation (Do this) +- Enforce TLS 1.3 only (or later when available). +- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + +## Migration +- Inventory endpoints and crypto usage. +- Prioritize external/high‑value/long‑lived flows. +- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. ## Implementation Checklist -- Hybrid key establishment enabled with ML-KEM-768 alongside a classical ECDHE group. -- No usage of predecessor draft Kyber hybrids; configurations updated to ML-KEM hybrids. -- Algorithms are configurable (algorithm agility) and surfaced in policy/config, not compiled into business logic. -- Keys generated with a CSPRNG in validated modules; stored in KMS/HSM; separated by purpose; rotation documented. -- Protocol versions and cipher/group selections align with vendor-documented, supported PQC options. -- Monitoring in place for handshake success rates, latency, and error codes after enabling hybrids. +- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. +- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. +- Algorithm agility via configuration (not code); explicit fallback behavior. +- Keys via validated modules; separated by purpose; rotation policy in place. +- TLS version and group selections align with supported PQC options. +- Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan -- Interoperability tests across representative clients/agents for hybrid ML-KEM-768 handshakes; verify negotiation and fallback behavior. -- Negative tests: reject configurations attempting legacy Hybrid-Kyber or draft-only group names. -- Performance/regression tests: measure handshake latency and server CPU for peak and P95 after enabling hybrids. -- Configuration validation: confirm algorithm identifiers and parameters map to ML-KEM/ML-DSA in logs and diagnostics; ensure no stale Kyber draft identifiers remain. +- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. +- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. +- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. From a10c995814d6029269c26b73c22d3d5cfa51a689 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Mon, 24 Nov 2025 12:40:42 -0500 Subject: [PATCH 13/22] docs(pqc): clarify AES unaffected by Shor; recommend AES-256; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 26 ++++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 26 ++++++++++--------- 2 files changed, 28 insertions(+), 24 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index b17a344..bb4e54b 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -12,14 +12,16 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. + - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. + - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. + - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. + - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. + - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. + - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. + - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. + - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. @@ -30,13 +32,13 @@ Concise Code Guard focused on what to implement and how to test it. - Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. - No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. -- Algorithm agility via configuration (not code); explicit fallback behavior. -- Keys via validated modules; separated by purpose; rotation policy in place. -- TLS version and group selections align with supported PQC options. -- Monitoring in place for handshake success/latency/errors and negotiated groups. + - Algorithm agility via configuration (not code); explicit fallback behavior. + - Keys via validated modules; separated by purpose; rotation policy in place. + - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. + - TLS version and group selections align with supported PQC options. + - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. -- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 9305ba2..4280e07 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -10,14 +10,16 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. + - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. + - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until ML‑DSA is supported by your stack; plan migration to ML‑DSA. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. + - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. + - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. + - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. + - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. + - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. + - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. + - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. @@ -28,13 +30,13 @@ Concise Code Guard focused on what to implement and how to test it. - Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. - No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. -- Algorithm agility via configuration (not code); explicit fallback behavior. -- Keys via validated modules; separated by purpose; rotation policy in place. -- TLS version and group selections align with supported PQC options. -- Monitoring in place for handshake success/latency/errors and negotiated groups. + - Algorithm agility via configuration (not code); explicit fallback behavior. + - Keys via validated modules; separated by purpose; rotation policy in place. + - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. + - TLS version and group selections align with supported PQC options. + - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. -- Configuration validation: confirm groups/algorithm identifiers in logs and diagnostics; ensure no stale Kyber‑era identifiers remain. From 4f41e61c324b3a5cfb9e2077f42546bc41edfa67 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Tue, 25 Nov 2025 11:24:36 -0500 Subject: [PATCH 14/22] docs(pqc): add IPsec guidance; reference IKEv2 PQC RFCs 9242/9370; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 20 ++++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 20 ++++++++++--------- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index bb4e54b..8d2fa19 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -11,17 +11,19 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. - - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. - - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. - - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. +- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 4280e07..8c4c573 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -9,17 +9,19 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce TLS 1.3 only (or later when available). +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. - - Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. - - Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. - - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. +- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. +- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. +- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. +- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. ## Migration - Inventory endpoints and crypto usage. From 93b70d33bef2f3932a46b07278dc16e0658b67d9 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Tue, 25 Nov 2025 12:21:08 -0500 Subject: [PATCH 15/22] docs(pqc): clarify DTLS; enforce (D)TLS 1.3 only; regenerate skills --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- sources/core/codeguard-1-post-quantum-cryptography.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 8d2fa19..de29183 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -10,7 +10,7 @@ rule_id: codeguard-1-post-quantum-cryptography Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) -- Enforce TLS 1.3 only (or later when available). +- Enforce (D)TLS 1.3 only (or later when available). - IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); - IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 8c4c573..0b137cc 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -8,7 +8,7 @@ alwaysApply: true Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) -- Enforce TLS 1.3 only (or later when available). +- Enforce (D)TLS 1.3 only (or later when available). - IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); - IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. From e76bd551a1ea7ade0b0d98597e12fdf8e50be28d Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Thu, 4 Dec 2025 14:13:52 -0500 Subject: [PATCH 16/22] docs(pqc): (D)TLS PQC groups + IKEv2/IPsec re-key; regenerate skills --- .../codeguard-1-post-quantum-cryptography.md | 23 +++++++++++++++---- .../codeguard-1-post-quantum-cryptography.md | 23 +++++++++++++++---- 2 files changed, 36 insertions(+), 10 deletions(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index de29183..3674a4f 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -11,10 +11,18 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce (D)TLS 1.3 only (or later when available). -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- (D)TLS PQC key exchange (when supported by your stack): + - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: + - X25519MLKEM768 (X25519 + ML‑KEM‑768) + - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) + - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments + - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: + - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance + - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. @@ -22,8 +30,9 @@ Concise Code Guard focused on what to implement and how to test it. - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. @@ -37,10 +46,14 @@ Concise Code Guard focused on what to implement and how to test it. - Algorithm agility via configuration (not code); explicit fallback behavior. - Keys via validated modules; separated by purpose; rotation policy in place. - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - TLS version and group selections align with supported PQC options. + - (D)TLS version and group selections align with supported PQC options. + - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. +- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 0b137cc..4263372 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -9,10 +9,18 @@ Concise Code Guard focused on what to implement and how to test it. ## Implementation (Do this) - Enforce (D)TLS 1.3 only (or later when available). -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC); -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. +- (D)TLS PQC key exchange (when supported by your stack): + - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: + - X25519MLKEM768 (X25519 + ML‑KEM‑768) + - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) + - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments + - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: + - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance + - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases +- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). +- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. - Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is strongly recommended. +- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. - Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. - Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. - Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. @@ -20,8 +28,9 @@ Concise Code Guard focused on what to implement and how to test it. - Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. - Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. +- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. +- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. @@ -35,10 +44,14 @@ Concise Code Guard focused on what to implement and how to test it. - Algorithm agility via configuration (not code); explicit fallback behavior. - Keys via validated modules; separated by purpose; rotation policy in place. - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - TLS version and group selections align with supported PQC options. + - (D)TLS version and group selections align with supported PQC options. + - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - Monitoring in place for handshake success/latency/errors and negotiated groups. ## Test Plan - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. +- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. +- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From d2ad730e6ecfc14396c553a0ad29475f7ebeb8b9 Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:12:52 -0500 Subject: [PATCH 17/22] Update skills/software-security/rules/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 3674a4f..1f01b2f 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -54,6 +54,6 @@ Concise Code Guard focused on what to implement and how to test it. - Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. - Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. - Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. +- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SAs maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. - Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. - Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From 6e5523db9ec5cffbfe896c8a9d8482e123d358fe Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:13:30 -0500 Subject: [PATCH 18/22] Update skills/software-security/rules/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../rules/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md index 1f01b2f..41913c6 100644 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md @@ -32,7 +32,7 @@ Concise Code Guard focused on what to implement and how to test it. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. +- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. From 1bbc963ca328171c8b75336cb203cc9deb07895b Mon Sep 17 00:00:00 2001 From: Omar Santos Date: Tue, 9 Dec 2025 22:13:38 -0500 Subject: [PATCH 19/22] Update sources/core/codeguard-1-post-quantum-cryptography.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- sources/core/codeguard-1-post-quantum-cryptography.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md index 4263372..c2c6919 100644 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ b/sources/core/codeguard-1-post-quantum-cryptography.md @@ -30,7 +30,7 @@ Concise Code Guard focused on what to implement and how to test it. - Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. - Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. - SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re-key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. +- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. ## Migration - Inventory endpoints and crypto usage. From 3307342dd84b4a64c15a6512ad2cc9f8a0812cd5 Mon Sep 17 00:00:00 2001 From: Vinny Parla Date: Wed, 10 Dec 2025 11:25:34 -0500 Subject: [PATCH 20/22] Cryptographic Security Guidelines: add PQC readiness; consolidate into core rule; remove standalone PQC; regenerate skills --- .../rules/codeguard-1-crypto-algorithms.md | 189 +++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 59 ------ sources/core/codeguard-1-crypto-algorithms.md | 189 +++++++++--------- .../codeguard-1-post-quantum-cryptography.md | 57 ------ 4 files changed, 192 insertions(+), 302 deletions(-) delete mode 100644 skills/software-security/rules/codeguard-1-post-quantum-cryptography.md delete mode 100644 sources/core/codeguard-1-post-quantum-cryptography.md 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/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md b/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md deleted file mode 100644 index 41913c6..0000000 --- a/skills/software-security/rules/codeguard-1-post-quantum-cryptography.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -description: Post-Quantum Cryptography (PQC) guidance and migration best practices -alwaysApply: true ---- - -rule_id: codeguard-1-post-quantum-cryptography - -# Post-Quantum Cryptography (PQC) - -Concise Code Guard focused on what to implement and how to test it. - -## Implementation (Do this) -- Enforce (D)TLS 1.3 only (or later when available). -- (D)TLS PQC key exchange (when supported by your stack): - - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: - - X25519MLKEM768 (X25519 + ML‑KEM‑768) - - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) - - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments - - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: - - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance - - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. -- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. -- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. - -## Migration -- Inventory endpoints and crypto usage. -- Prioritize external/high‑value/long‑lived flows. -- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. - -## Implementation Checklist -- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. -- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. - - Algorithm agility via configuration (not code); explicit fallback behavior. - - Keys via validated modules; separated by purpose; rotation policy in place. - - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - (D)TLS version and group selections align with supported PQC options. - - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - - Monitoring in place for handshake success/latency/errors and negotiated groups. - -## Test Plan -- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. -- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. -- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SAs maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. -- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. -- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. 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 diff --git a/sources/core/codeguard-1-post-quantum-cryptography.md b/sources/core/codeguard-1-post-quantum-cryptography.md deleted file mode 100644 index c2c6919..0000000 --- a/sources/core/codeguard-1-post-quantum-cryptography.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -description: Post-Quantum Cryptography (PQC) guidance and migration best practices -alwaysApply: true ---- - -# Post-Quantum Cryptography (PQC) - -Concise Code Guard focused on what to implement and how to test it. - -## Implementation (Do this) -- Enforce (D)TLS 1.3 only (or later when available). -- (D)TLS PQC key exchange (when supported by your stack): - - Prefer hybrid named groups per I-D.ietf-tls-ecdhe-mlkem: - - X25519MLKEM768 (X25519 + ML‑KEM‑768) - - SecP256r1MLKEM768 (P‑256 + ML‑KEM‑768) - - SecP384r1MLKEM1024 (P‑384 + ML‑KEM‑1024) for high‑assurance segments - - Pure PQC (only after interop validation) per I-D.ietf-tls-mlkem-key-agreement: - - ML‑KEM‑768 baseline; ML‑KEM‑1024 where required; avoid ML‑KEM‑512 except in constrained environments with explicit risk acceptance - - Use vendor‑documented, supported identifiers; avoid legacy “Hybrid‑Kyber” names and draft‑only aliases -- IPsec: Enforce IKEv2 only; use ESP with AEAD (e.g. AES‑256‑GCM or stronger); require PFS via ECDHE (X25519 or secp256r1); use SHA‑256+ for IKE PRF/auth; configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; disable IKEv1 and legacy suites (3DES, DES, MD5, SHA‑1, AES‑CBC). -- IKEv2 PQC support: implement RFC 9242 (IKEv2 Intermediate Exchange) and RFC 9370 (Multiple Key Exchanges in IKEv2) to enable hybrid PQC + ECDHE and handle larger exchanges. Apply to both initial exchanges and re‑key (CREATE_CHILD_SA) so hybrids persist across re‑keys. Select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Use vendor‑supported crypto APIs only; never implement custom crypto. Do not hand‑roll hybrids or hardcode experimental group names/OIDs. -- Symmetric encryption: Shor's algorithm and quantum computers do not affect symmetric algorithms like AES; using AES‑256 keys (or stronger) is highly recommended. -- Hybrid KEM: enable vendor‑documented hybrids that include ML‑KEM‑768 with a classical ECDHE group (X25519 or secp256r1). Use ML‑KEM‑1024 for high‑assurance segments after validating overhead. -- Multi-tenant systems that share crypto resources across tenants should select Hybrid KEM with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. X25519 is recommended for ECDHE. -- Avoid predecessors: remove legacy/draft “Hybrid‑Kyber” groups (e.g., CECPQ2; X25519Kyber…, P256_Kyber) and draft OIDs. -- Configuration, not code: expose algorithm choices in config/policy; document fallback behavior; keep a classical‑only fallback for incompatible clients if you don't control both client and server. -- Key management: use KMS/HSM; generate keys with a CSPRNG; separate encryption vs signatures; rotate per policy; never hardcode keys/parameters; avoid plain env vars for long‑lived secrets; require hardware‑backed keys (HSM/TPM) for private key storage. -- Certificates/signatures: continue ECDSA (P‑256) for mTLS and code signing until hardware‑backed ML‑DSA is available in your stack (e.g., HSM or TPM); plan migration to ML‑DSA once supported. -- Hardware requirement for ML‑DSA: do not enable PQC ML‑DSA signatures using software‑only keys. Require HSM/TPM‑backed key storage and signing paths before migrating. -- Telemetry and limits: capture negotiated groups, handshake sizes, and retry/failure causes. Tune (D)TLS record sizes and proxy/LB/concentrator limits to avoid fragmentation and timeouts. -- SSH/HPKE: enable only vendor‑supported PQC/hybrid KEX (e.g., sntrup761x25519 in OpenSSH if allowed). For HPKE, rely on native language runtime/vendor/audited libraries that support ML‑KEM. -- IPsec re‑key: configure time/byte‑based lifetimes to re‑key IKE_SA and CHILD_SAs; ensure re‑key maintains the same algorithms used during IKEv2 exchanges. - -## Migration -- Inventory endpoints and crypto usage. -- Prioritize external/high‑value/long‑lived flows. -- Roll out hybrids in stages with metrics and rollback; remove predecessor configs after success criteria are met. - -## Implementation Checklist -- Hybrid key establishment with ML‑KEM‑768 + ECDHE; ML‑KEM‑1024 where required. -- Avoid ML‑KEM‑512 except in explicitly risk‑accepted, highly constrained device or network environments, with compensating controls and tight scope. -- No draft Kyber groups; only vendor‑documented ML‑KEM hybrids. - - Algorithm agility via configuration (not code); explicit fallback behavior. - - Keys via validated modules; separated by purpose; rotation policy in place. - - Hardware‑backed key storage (HSM/TPM) required before enabling ML‑DSA signatures; continue ECDSA (P‑256) for mTLS/signing until hardware support exists. - - (D)TLS version and group selections align with supported PQC options. - - IPsec re‑key configured (time/byte lifetimes) with PFS; hybrid ML‑KEM + ECDHE persists across re‑key. - - Monitoring in place for handshake success/latency/errors and negotiated groups. - -## Test Plan -- Interoperability: verify hybrid ML‑KEM‑768 and ML‑KEM‑1024 handshakes across representative clients; validate negotiated groups and fallback paths. -- Interoperability ((D)TLS): verify negotiation of X25519MLKEM768 / SecP256r1MLKEM768 hybrids and fallback to classical ECDHE; validate pure ML‑KEM groups only in staged tests. -- Interoperability (IKEv2/IPsec): verify hybrid ML‑KEM‑768 + ECDHE (X25519 or P‑256) via RFC 9242/9370 multi‑KE; confirm fallback to classical ECDHE; evaluate ML‑KEM‑1024 where required. Use vendor‑documented identifiers; -- Re‑key (IKEv2/IPsec): validate re‑key of IKE_SA and CHILD_SA maintains hybrid ML‑KEM + ECDHE; confirm no fallback to classical‑only on re‑key; measure re‑key overhead. -- Negative: reject legacy/draft Hybrid‑Kyber identifiers and misconfigured groups. -- Performance: measure handshake size and latency (peak and P95) and server CPU after enabling hybrids; tune record sizes and limits as needed. From e0cde0ddbcef7fde7767192722df92acd1930b84 Mon Sep 17 00:00:00 2001 From: Ramraj Bishnoie Date: Fri, 16 Jan 2026 16:20:03 -0500 Subject: [PATCH 21/22] chore: converting claude code to agent skills --- README.md | 4 +- src/convert_to_ide_formats.py | 132 ++++++++++-------- src/formats/__init__.py | 10 +- src/formats/{claudecode.py => agentskills.py} | 61 ++++---- 4 files changed, 116 insertions(+), 91 deletions(-) rename src/formats/{claudecode.py => agentskills.py} (52%) diff --git a/README.md b/README.md index ceb5d6f..e30bc60 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ Get started in minutes: ## How It Works 1. **Security rules** are written in unified markdown format (`sources/` directory) -2. **Conversion tools** translate rules to IDE-specific formats (Cursor, Windsurf, Copilot, Claude Code, Antigravity) +2. **Conversion tools** translate rules to IDE-specific formats (Cursor, Windsurf, Copilot, Agent Skills, Antigravity) 3. **Release automation** packages rules into downloadable ZIP files 4. **AI assistants** reference these rules when generating or reviewing code 5. **Secure code** is produced automatically without developer intervention @@ -63,7 +63,7 @@ Get started in minutes: ``` sources/ # Source rules -skills/ # Claude Code plugin (generated, committed) +skills/ # Agent Skills format (generated, committed) src/ # Conversion and validation tools dist/ # Other IDE bundles (generated, not committed) ``` diff --git a/src/convert_to_ide_formats.py b/src/convert_to_ide_formats.py index 1657366..0a1e2d0 100644 --- a/src/convert_to_ide_formats.py +++ b/src/convert_to_ide_formats.py @@ -6,8 +6,8 @@ Convert Unified Rules to IDE Formats Transforms the unified markdown sources into IDE-specific bundles (Cursor, -Windsurf, Copilot, Claude Code). This script is the main entry point for producing -distributable rule packs from the sources/ directory. +Windsurf, Copilot, Agent Skills, Antigravity). This script is the main entry point +for producing distributable rule packs from the sources/ directory. """ import re @@ -16,7 +16,13 @@ from collections import defaultdict from converter import RuleConverter -from formats import CursorFormat, WindsurfFormat, CopilotFormat, ClaudeCodeFormat, AntigravityFormat +from formats import ( + CursorFormat, + WindsurfFormat, + CopilotFormat, + AgentSkillsFormat, + AntigravityFormat, +) from utils import get_version_from_pyproject from validate_versions import set_plugin_version, set_marketplace_version @@ -26,7 +32,7 @@ def sync_plugin_metadata(version: str) -> None: """ - Sync version from pyproject.toml to Claude Code plugin metadata files. + Sync version from pyproject.toml to Agent Skills metadata files. Args: version: Version string from pyproject.toml @@ -39,17 +45,17 @@ def sync_plugin_metadata(version: str) -> None: def matches_tag_filter(rule_tags: list[str], filter_tags: list[str]) -> bool: """ Check if rule has all required tags (AND logic). - + Args: rule_tags: List of tags from the rule (already normalized to lowercase) filter_tags: List of tags to filter by (already normalized to lowercase) - + Returns: True if rule has all filter tags (or no filter), False otherwise """ if not filter_tags: return True # No filter means all pass - + return all(tag in rule_tags for tag in filter_tags) @@ -98,14 +104,20 @@ def update_skill_md(language_to_rules: dict[str, list[str]], skill_path: str) -> print(f"Updated SKILL.md with language mappings") -def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: bool = True, version: str = None, filter_tags: list[str] = None) -> dict[str, list[str]]: +def convert_rules( + input_path: str, + output_dir: str = "dist", + include_agentskills: bool = True, + version: str = None, + filter_tags: list[str] = None, +) -> dict[str, list[str]]: """ Convert rule file(s) to all supported IDE formats using RuleConverter. Args: input_path: Path to a single .md file or folder containing .md files output_dir: Output directory (default: 'dist/') - include_claudecode: Whether to generate Claude Code plugin (default: True, only for core rules) + include_agentskills: Whether to generate Agent Skills format (default: True, only for core rules) version: Version string to use (default: read from pyproject.toml) filter_tags: Optional list of tags to filter by (AND logic, case-insensitive) @@ -117,7 +129,7 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: } Example: - results = convert_rules("sources/core", "dist", include_claudecode=True) + results = convert_rules("sources/core", "dist", include_agentskills=True) print(f"Converted {len(results['success'])} rules") """ if version is None: @@ -130,10 +142,10 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: CopilotFormat(version), AntigravityFormat(version), ] - - # Only include Claude Code for core rules (committed plugin) - if include_claudecode: - all_formats.append(ClaudeCodeFormat(version)) + + # Only include Agent Skills format for core rules (committed as skills) + if include_agentskills: + all_formats.append(AgentSkillsFormat(version)) converter = RuleConverter(formats=all_formats) path = Path(input_path) @@ -151,7 +163,7 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: md_files = sorted(list(path.rglob("*.md"))) if not md_files: raise ValueError(f"No .md files found in {input_path}") - + print(f"Converting {len(md_files)} files from: {path}") # Setup output directory @@ -165,7 +177,7 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: try: # Convert the file (raises exceptions on error) result = converter.convert(md_file) - + # Apply tag filter if specified if filter_tags and not matches_tag_filter(result.tags, filter_tags): results["skipped"].append(result.filename) @@ -175,17 +187,15 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: output_files = [] for format_name, output in result.outputs.items(): # Construct output path - # Claude Code goes to project root ./skills/ + # Agent Skills goes to project root ./skills/ # Other formats go to dist/ (or specified output_dir) - if format_name == "claudecode": + if format_name == "agentskills": base_dir = PROJECT_ROOT else: base_dir = output_base - + output_file = ( - base_dir - / output.subpath - / f"{result.basename}{output.extension}" + base_dir / output.subpath / f"{result.basename}{output.extension}" ) # Create directory if it doesn't exist and write file @@ -225,30 +235,32 @@ def convert_rules(input_path: str, output_dir: str = "dist", include_claudecode: f"\nResults: {len(results['success'])} success, {len(results['errors'])} errors" ) - # Generate SKILL.md with language mappings (only if Claude Code is included) - if include_claudecode and language_to_rules: - template_path = PROJECT_ROOT / "sources" / "core" / "codeguard-SKILLS.md.template" - + # Generate SKILL.md with language mappings (only if Agent Skills is included) + if include_agentskills and language_to_rules: + template_path = ( + PROJECT_ROOT / "sources" / "core" / "codeguard-SKILLS.md.template" + ) + if not template_path.exists(): raise FileNotFoundError( f"SKILL.md template not found at {template_path}. " - "This file is required for Claude Code plugin generation." + "This file is required for Agent Skills generation." ) - + output_skill_dir = PROJECT_ROOT / "skills" / "software-security" output_skill_dir.mkdir(parents=True, exist_ok=True) output_skill_path = output_skill_dir / "SKILL.md" - + # Read template and inject current version from pyproject.toml template_content = template_path.read_text(encoding="utf-8") # Replace the hardcoded version with actual version template_content = re.sub( r'codeguard-version:\s*"[^"]*"', f'codeguard-version: "{version}"', - template_content + template_content, ) output_skill_path.write_text(template_content, encoding="utf-8") - + update_skill_md(language_to_rules, str(output_skill_path)) return results @@ -262,7 +274,7 @@ def _resolve_source_paths(args) -> list[Path]: # If --source flags provided, resolve under sources/ if args.source: return [Path("sources") / src for src in args.source] - + # Default: core rules only return [Path("sources/core")] @@ -270,7 +282,7 @@ def _resolve_source_paths(args) -> list[Path]: if __name__ == "__main__": import sys from argparse import ArgumentParser - + parser = ArgumentParser( description="Convert unified rule markdown into IDE-specific bundles." ) @@ -291,7 +303,7 @@ def _resolve_source_paths(args) -> list[Path]: dest="tags", help="Filter rules by tags (comma-separated, case-insensitive, AND logic). Example: --tag api,web-security", ) - + cli_args = parser.parse_args() source_paths = _resolve_source_paths(cli_args) @@ -307,27 +319,31 @@ def _resolve_source_paths(args) -> list[Path]: for source_path in source_paths: for md_file in source_path.rglob("*.md"): filename_to_sources[md_file.name].append(source_path.name) - - duplicates = {name: srcs for name, srcs in filename_to_sources.items() if len(srcs) > 1} + + duplicates = { + name: srcs for name, srcs in filename_to_sources.items() if len(srcs) > 1 + } if duplicates: print(f"❌ Found {len(duplicates)} duplicate filename(s) across sources:") for filename, sources in duplicates.items(): print(f" - {filename} in: {', '.join(sources)}") print("\nPlease rename files to have unique names across all sources.") sys.exit(1) - + # Get version once and sync to metadata files version = get_version_from_pyproject() sync_plugin_metadata(version) - # Check if core is in the sources for Claude Code plugin generation + # Check if core is in the sources for Agent Skills generation has_core = Path("sources/core") in source_paths if has_core: # Validate template exists early - template_path = PROJECT_ROOT / "sources" / "core" / "codeguard-SKILLS.md.template" + template_path = ( + PROJECT_ROOT / "sources" / "core" / "codeguard-SKILLS.md.template" + ) if not template_path.exists(): print(f"❌ SKILL.md template not found at {template_path}") - print("This file is required for Claude Code plugin generation.") + print("This file is required for Agent Skills generation.") sys.exit(1) # Clean output directories once before processing @@ -341,46 +357,50 @@ def _resolve_source_paths(args) -> list[Path]: if skills_rules_dir.exists(): shutil.rmtree(skills_rules_dir) print(f"✅ Cleaned skills/ directory") - + # Print processing summary if len(source_paths) > 1: - sources_list = ', '.join(p.name for p in source_paths) + sources_list = ", ".join(p.name for p in source_paths) print(f"\nConverting {len(source_paths)} sources: {sources_list}") if has_core: - print("(Claude Code plugin will include only core rules)") + print("(Agent Skills will include only core rules)") print() - + # Convert all sources aggregated = {"success": [], "errors": [], "skipped": []} # Parse comma-separated tags and normalize to lowercase filter_tags = None if cli_args.tags: - filter_tags = [tag.strip().lower() for tag in cli_args.tags.split(",") if tag.strip()] - + filter_tags = [ + tag.strip().lower() for tag in cli_args.tags.split(",") if tag.strip() + ] + # Print tag filter info if active if filter_tags: - print(f"Tag filter active: {', '.join(filter_tags)} (AND logic - rules must have all tags)\n") - + print( + f"Tag filter active: {', '.join(filter_tags)} (AND logic - rules must have all tags)\n" + ) + for source_path in source_paths: is_core = source_path == Path("sources/core") - + print(f"Processing: {source_path}") results = convert_rules( - str(source_path), - cli_args.output_dir, - include_claudecode=is_core, + str(source_path), + cli_args.output_dir, + include_agentskills=is_core, version=version, - filter_tags=filter_tags + filter_tags=filter_tags, ) - + aggregated["success"].extend(results["success"]) aggregated["errors"].extend(results["errors"]) if "skipped" in results: aggregated["skipped"].extend(results["skipped"]) print("") - + if aggregated["errors"]: print("❌ Some conversions failed") sys.exit(1) - + print("✅ All conversions successful") diff --git a/src/formats/__init__.py b/src/formats/__init__.py index 55cc0d0..e1a48a3 100644 --- a/src/formats/__init__.py +++ b/src/formats/__init__.py @@ -11,7 +11,8 @@ - CursorFormat: Generates .mdc files for Cursor IDE - WindsurfFormat: Generates .md files for Windsurf IDE - CopilotFormat: Generates .instructions.md files for GitHub Copilot -- ClaudeCodeFormat: Generates .md files for Claude Code plugins +- AgentSkillsFormat: Generates .md files for Agent Skills (OpenAI Codex, Claude Code, other AI coding tools) +- AntigravityFormat: Generates .md files for Google Antigravity Usage: from formats import BaseFormat, ProcessedRule, CursorFormat, WindsurfFormat, CopilotFormat, ClaudeCodeFormat @@ -21,7 +22,8 @@ CursorFormat(version), WindsurfFormat(version), CopilotFormat(version), - ClaudeCodeFormat(version), + AgentSkillsFormat(version), + AntigravityFormat(version), ] """ @@ -29,7 +31,7 @@ from formats.cursor import CursorFormat from formats.windsurf import WindsurfFormat from formats.copilot import CopilotFormat -from formats.claudecode import ClaudeCodeFormat +from formats.agentskills import AgentSkillsFormat from formats.antigravity import AntigravityFormat __all__ = [ @@ -38,6 +40,6 @@ "CursorFormat", "WindsurfFormat", "CopilotFormat", - "ClaudeCodeFormat", + "AgentSkillsFormat", "AntigravityFormat", ] diff --git a/src/formats/claudecode.py b/src/formats/agentskills.py similarity index 52% rename from src/formats/claudecode.py rename to src/formats/agentskills.py index 4c3b152..798b2db 100644 --- a/src/formats/claudecode.py +++ b/src/formats/agentskills.py @@ -3,72 +3,75 @@ # SPDX-License-Identifier: Apache-2.0 """ -Claude Code Format Implementation +Agent Skills Format Implementation -Generates .md files for Claude Code Skills/Plugins. +Generates .md files for the Agent Skills standard (agentskills.io). +This format is used by OpenAI Codex, Claude Code, and other AI coding tools. """ from formats.base import BaseFormat, ProcessedRule -class ClaudeCodeFormat(BaseFormat): +class AgentSkillsFormat(BaseFormat): """ - Claude Code plugin format implementation (.md files). - - Claude Code Skills use standard markdown files without - special frontmatter. The original rule content is preserved - and placed in the skills/software-security/rules/ directory - for plugin distribution. - - Unlike other IDE formats, Claude Code doesn't require special - frontmatter transformations - it uses the rules as-is for - plugin-based Skills. + Agent Skills format implementation (.md files). + + Agent Skills (https://agentskills.io/) is an open standard for extending + AI coding agents with task-specific capabilities. It uses standard markdown + files with YAML frontmatter to define rules and instructions. + + This format is adopted by: + - OpenAI Codex (skills) + - Claude Code (plugins) + - Other AI coding tools + + The original rule content is preserved and placed in the + skills/software-security/rules/ directory for distribution. """ def get_format_name(self) -> str: - """Return Claude Code format identifier.""" - return "claudecode" + """Return Agent Skills format identifier.""" + return "agentskills" def get_file_extension(self) -> str: - """Return Claude Code format file extension.""" + """Return Agent Skills format file extension.""" return ".md" def get_output_subpath(self) -> str: - """Return Claude Code output subdirectory.""" + """Return Agent Skills output subdirectory.""" return "skills/software-security/rules" def generate(self, rule: ProcessedRule, globs: str) -> str: """ - Generate Claude Code .md format. - - Claude Code Skills should preserve the original YAML frontmatter + Generate Agent Skills .md format. + + Agent Skills should preserve the original YAML frontmatter (description, languages, alwaysApply) so the rules remain complete - and can be referenced properly. - + and can be referenced properly by AI coding agents. + Args: rule: The processed rule to format - globs: Glob patterns (not used for Claude Code format) - + globs: Glob patterns (not used for Agent Skills format) + Returns: Complete markdown with original YAML frontmatter preserved """ # Build YAML frontmatter yaml_lines = [] - + # Add description desc = self._format_yaml_field("description", rule.description) if desc: yaml_lines.append(desc) - + # Add languages if present if rule.languages: # Format as YAML list yaml_lines.append("languages:") for lang in rule.languages: yaml_lines.append(f"- {lang}") - + # Add alwaysApply yaml_lines.append(f"alwaysApply: {str(rule.always_apply).lower()}") - - return self._build_yaml_frontmatter(yaml_lines, rule.content) + return self._build_yaml_frontmatter(yaml_lines, rule.content) From 3259fd7f8d0d3dc0dc1dd7f14aa885e9f5d966a3 Mon Sep 17 00:00:00 2001 From: Ramraj Bishnoie Date: Fri, 16 Jan 2026 20:01:32 -0500 Subject: [PATCH 22/22] chore: remove ClaudeCodeFormat from docstring --- src/formats/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/formats/__init__.py b/src/formats/__init__.py index e1a48a3..2e80ed5 100644 --- a/src/formats/__init__.py +++ b/src/formats/__init__.py @@ -15,7 +15,7 @@ - AntigravityFormat: Generates .md files for Google Antigravity Usage: - from formats import BaseFormat, ProcessedRule, CursorFormat, WindsurfFormat, CopilotFormat, ClaudeCodeFormat + from formats import BaseFormat, ProcessedRule, CursorFormat, WindsurfFormat, CopilotFormat, AgentSkillsFormat, AntigravityFormat version = "1.0.0" formats = [