Pqc tls support for portals and apis #3296
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -4,9 +4,11 @@ | |
|
|
||
| Apply this rule whenever writing, refactoring, or reviewing JavaScript (`.js`) code in `portals/developer-portal` that performs key exchange, digital signatures, encryption, or any operation relying on the hardness of integer factorisation or discrete-logarithm problems (RSA, ECDH, ECDSA, `crypto.generateKeyPair` with classic algorithms). Cryptographic primitives must remain secure against an adversary with a cryptographically relevant quantum computer, per NIST FIPS 203 (ML-KEM), FIPS 204 (ML-DSA), and FIPS 205 (SLH-DSA). JS counterpart to `post-quantum-cryptography.md` (Go). | ||
|
|
||
| **PQC is optional-but-supported, not strictly mandated.** Backends this portal talks to (legacy gateway builds, third-party integrations, older IDPs) do not all negotiate PQC ciphers/curves yet. Configuration must make enabling PQC/hybrid easy — and default to it wherever the peer is known to support it — but code must not hard-fail or drop interoperability when talking to a peer that only speaks classical algorithms. Treat "PQC-capable" as a configurable posture, not an unconditional requirement in every code path. | ||
|
|
||
| ## Directives | ||
|
|
||
| 1. **Quantum-vulnerable algorithms are a configurable fallback, not a ban.** New key-exchange/signing code must offer ML-KEM/ML-DSA-based (hybrid) operation as the default when configuration enables PQC and the peer supports it. RSA, ECDH (any curve), ECDSA, Ed25519/Ed448, X448, or classic Diffie-Hellman — including `crypto.createECDH(...)`, `crypto.generateKeyPair('rsa', ...)`, and `crypto.sign` with `'RSA-SHA256'` — remain acceptable *only* as an explicit, configuration-gated fallback for legacy backends that don't yet support PQC, never as the silent, unconfigured default for new code, and never introduced or extended with a `// TODO(pqc): migrate`-style comment as the only nod to migration; a code comment is not a remediation plan. The one narrow exception for the PQC leg itself: X25519 may be used solely as the classical leg of the mandated X25519 + ML-KEM-768 hybrid construction in directive 3 — never standalone, never paired with any KEM other than ML-KEM-768/1024, and never as a substitute for it elsewhere. Existing classical-only uses that don't yet offer a PQC/hybrid configuration option must be filed as a tracked issue (not merely noted inline) with an owner and a migration deadline, and must gain that configuration option the next time that code is touched rather than being re-committed as classical-only. AES-256-GCM, ChaCha20-Poly1305, and SHA-3/BLAKE3 remain quantum-safe exceptions at 256-bit sizes; avoid AES-128/SHA-256 for new long-lived keys. | ||
| 2. **Approved algorithm selection:** | ||
|
|
||
| | Purpose | NIST Standard | Algorithm | npm Package | | ||
|
|
@@ -18,31 +20,38 @@ Apply this rule whenever writing, refactoring, or reviewing JavaScript (`.js`) c | |
| | Hashing | — | SHA3-256 / SHA3-512 | `node:crypto`, `@noble/hashes` | | ||
|
|
||
| Prefer `@noble/post-quantum` for pure-JS (no native bindings, audited); use `liboqs-node` when FIPS 140-3 or HSM integration is required. Use `-768`/`dilithium3` (NIST Level 3) as the minimum, escalating to `-1024`/`dilithium5` for long-lived or high-assurance keys. | ||
| 3. **Hybrid classical + PQC as the configured default, with a documented classical fallback.** When PQC is enabled in configuration, combine X25519 + ML-KEM-768 (IETF RFC 9180 pattern) so security degrades gracefully to whichever primitive remains unbroken — never deploy PQC standalone until the library has a stable 1.x release with a public audit. For TLS, Node.js 22+/OpenSSL 3.2+ supports `tls.createServer({ ecdhCurve: 'X25519MLKEM768:X25519' })` — list the hybrid curve first, keeping `X25519` (and other configured classical curves) after it so a handshake with a peer that doesn't yet support the hybrid curve still succeeds instead of failing closed. Surface the negotiated/effective curve (config, logs, or a status field) so operators can tell whether a connection actually ran PQC or fell back to classical. | ||
|
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win Resolve the standalone X25519 contradiction. Directive 1 prohibits standalone X25519. Directive 3 and the example return an X25519-only secret when PQC is disabled or Also applies to: 51-52 🤖 Prompt for AI Agents🔒 Security & Privacy | 🟠 Major | ⚡ Quick win 🧩 Analysis chain🌐 Web query:
💡 Result: As of August 24, 2026, the relevant standards and technical details for hybrid TLS key exchange using ML-KEM are as follows: RFC 10024, published in August 2026, defines post-quantum traditional (PQ/T) hybrid key agreement mechanisms for TLS 1.3 [1][2]. This standard introduces three new supported groups that combine the post-quantum algorithm ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism) with ephemeral Elliptic Curve Diffie-Hellman (ECDHE) [1][3]: - X25519MLKEM768 - SecP256r1MLKEM768 - SecP384r1MLKEM1024 These groups follow the construction principles defined in RFC 9954 [1][3]. RFC 9954, published in July 2026, provides an informational framework for constructing hybrid key exchanges in TLS 1.3 [4][5]. It utilizes a simple concatenation-based approach where the shared secrets and protocol messages from the component algorithms (e.g., ECDHE and ML-KEM) are concatenated to form a single key exchange mechanism, allowing them to be negotiated and transmitted using existing TLS 1.3 structures [4][6]. For the X25519MLKEM768 hybrid group, the shared secret is formed by concatenating the ML-KEM-768 shared secret and the X25519 shared secret [7][8]. While X25519 is not itself a FIPS-approved algorithm, the combination is generally considered compliant with FIPS 140-3 requirements because ML-KEM is FIPS-approved [7]. In practice, X25519MLKEM768 has become a standard approach for deploying post-quantum hybrid key exchange, supported by major TLS stacks including OpenSSL 3.5+, BoringSSL, and various Go-based implementations [9]. Citations:
🌐 Web query:
💡 Result: RFC 10024 and RFC 9954 are technical documents related to hybrid key exchange in the Transport Layer Security (TLS) protocol version 1.3 [1][2]. RFC 9954: Hybrid Key Exchange in TLS 1.3 This informational RFC, published in July 2026, defines a framework for combining traditional key exchange algorithms (such as ECDHE using Curve25519 or NIST curves) with next-generation algorithms (such as post-quantum KEMs) in TLS 1.3 [2][3]. The design employs a simple concatenation-based approach, where the key exchange messages from multiple algorithms are concatenated and transmitted as a single value to avoid modifying existing TLS 1.3 data structures [3][4]. RFC 10024: Post-Quantum Traditional (PQ/T) Hybrid Key Agreement Mechanisms for TLS 1.3 This document, published in August 2026, applies the framework established in RFC 9954 to specific post-quantum algorithms [1][5]. It introduces three hybrid key agreement mechanisms that combine the post-quantum ML-KEM (Module-Lattice-Based Key Encapsulation Mechanism) with ECDHE [1]: - X25519MLKEM768: Combines X25519 with ML-KEM-768 [1][6]. - SecP256r1MLKEM768: Combines SecP256r1 (NIST P-256) with ML-KEM-768 [1][6]. - SecP384r1MLKEM1024: Combines SecP384r1 (NIST P-384) with ML-KEM-1024 [1][6]. For X25519MLKEM768 specifically, the client key exchange value is the concatenation of the ML-KEM-768 encapsulation key and the X25519 ephemeral share, resulting in a total client share size of 1216 bytes [1][7]. The assigned identifier for X25519MLKEM768 is 4588 (0x11EC) [6][7]. Citations:
Reference the TLS hybrid specification.
🤖 Prompt for AI AgentsSource: MCP tools 🩺 Stability & Availability | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -eu
printf '%s\n' '--- runtime and dependency declarations ---'
rg -n -i --glob '!*node_modules*' \
'("engines"|"node"|openssl|X25519MLKEM768|ecdhCurve|createServer)' \
package.json '**/package.json' .nvmrc .node-version Dockerfile* .github 2>/dev/null || true
printf '%s\n' '--- TLS implementation references ---'
rg -n -C 4 'X25519MLKEM768|ecdhCurve|tls\.createServer|createSecureContext' .claude portals 2>/dev/null || true
printf '%s\n' '--- relevant tracked files ---'
git ls-files | rg '(^|/)(package\.json|\.nvmrc|\.node-version|Dockerfile[^/]*|.*openssl.*|.*tls.*)$' | head -200Repository: wso2/api-platform Length of output: 2917 🌐 Web query:
💡 Result: OpenSSL 3.5 introduced full support for the hybrid X25519MLKEM768 TLS group [1][2][3]. Key details regarding this support include: - Default Inclusion: Starting with OpenSSL 3.5, X25519MLKEM768 is included in the default TLS supported groups list and is preferred by default for TLS 1.3 keyshares [2][3][4][5]. - Functionality: It is a hybrid key exchange mechanism combining classical X25519 with the post-quantum ML-KEM-768 (as defined in FIPS 203) [3][6]. It is specifically documented as a post-quantum traditional (PQ/T) hybrid key agreement mechanism under RFC 10024 [6]. - Configuration: When configuring applications to use this group, users are advised to use SSL_set1_groups_list rather than SSL_set1_groups, as the latter may not accept it directly in all contexts [7]. - Compliance: Although X25519 is not itself a FIPS-approved algorithm, this hybrid combination is permitted in FIPS 140-3 contexts because the ML-KEM component is FIPS-approved [1]. In addition to X25519MLKEM768, OpenSSL 3.5 also introduced support for two other hybrid groups: SecP256r1MLKEM768 and SecP384r1MLKEM1024 [2][3]. Citations:
🌐 Web query:
💡 Result: Node.js 22 (codenamed Jod) bundles OpenSSL 3.5.x as part of its official release distributions [1][2]. While Node.js 22 initially launched with OpenSSL 3.0.x, the project updated the bundled OpenSSL version to 3.5.2 in Node.js v22.20.0 to ensure continued support for the release line, as the original OpenSSL 3.0.x reached its end-of-support in September 2026 [1][2]. As of August 24, 2026, Node.js 22.x releases have been further updated to include even newer versions, such as OpenSSL 3.5.7, to maintain security and stability [3]. These updates apply to official Node.js binaries and builds using the default configuration [1][2]. They do not affect third-party builds of Node.js that are dynamically linked against an external OpenSSL library [1][2]. Node.js 22 is scheduled for End-of-Life on April 30, 2027 [1][4][5]. Citations:
🏁 Script executed: #!/bin/bash
set -eu
for f in \
.claude/rules/js-post-quantum-cryptography.md \
portals/api-portal/src/config/tlsOptions.js \
portals/api-portal/.nvmrc \
portals/api-portal/package.json \
portals/api-control-plane/.nvmrc \
portals/api-control-plane/package.json \
portals/ai-workspace/package.json
do
if [ -f "$f" ]; then
printf '\n--- %s ---\n' "$f"
wc -l "$f"
case "$f" in
.claude/rules/js-post-quantum-cryptography.md) sed -n '1,90p' "$f" ;;
portals/api-portal/src/config/tlsOptions.js) cat -n "$f" ;;
*) cat -n "$f" | sed -n '1,100p' ;;
esac
fi
doneRepository: wso2/api-platform Length of output: 25472 🌐 Web query:
💡 Result: Node.js provides comprehensive support for OpenSSL 3.0.x. Official Node.js binaries, including Long Term Support (LTS) releases such as Node.js 22.x, currently incorporate OpenSSL 3.0.x (specifically, the quictls OpenSSL fork) [1]. OpenSSL 3.0.x is designated as a long-term support version, and Node.js maintains compatibility by tracking official OpenSSL release cycles [1]. As Node.js releases evolve, the project expects to transition to subsequent long-term supported versions of OpenSSL as they are announced by the upstream OpenSSL project [1]. Citations: 🌐 Web query:
💡 Result: X25519MLKEM768 is a hybrid post-quantum key exchange group introduced in OpenSSL 3.5 [1][2][3]. It combines the classical X25519 elliptic curve key exchange with the post-quantum ML-KEM-768 (Module-Lattice-Based Key-Encapsulation Mechanism) algorithm, as specified in FIPS 203 [4][3]. Key characteristics of X25519MLKEM768 include: - Hybrid Security: By deriving a session secret from both X25519 and ML-KEM-768, the key agreement remains secure as long as either of the underlying algorithms remains unbroken [4]. - FIPS Compliance: Although X25519 itself is not a FIPS-approved algorithm, the hybrid combination is permitted in FIPS 140-3 environments because ML-KEM is FIPS-approved [4]. - Default Usage: Starting with OpenSSL 3.5, X25519MLKEM768 is included in the default TLS group list and is often prioritized as a default keyshare [1][3]. - Implementation Details: The shared secret is formed by concatenating the 32-byte shared secret from ML-KEM-768 followed by the 32-byte shared secret from X25519 [4]. Public and private keys for this group consist of the ML-KEM component followed by the X25519 component [4]. - Performance: It offers CPU performance comparable to classical ECDH groups like X25519, though it requires significantly larger key exchange messages [1][3]. In OpenSSL 3.5 and later, a new configuration syntax for TLS 1.3 servers allows for the partitioning of groups into security-equivalent tuples to ensure optimal group negotiation, which helps prevent issues where clients might otherwise fail to negotiate this preferred quantum-resistant group [5]. Node.js versions utilizing OpenSSL 3.5.2 or later (such as Node.js 22.20.0) include support for these capabilities [6]. Citations:
Set the minimum TLS runtime to OpenSSL 3.5.
🤖 Prompt for AI AgentsSource: MCP tools |
||
| 4. **Key and ciphertext size awareness.** ML-KEM-768 public keys are 1184 bytes and ciphertexts 1088 bytes; ML-DSA-65 signatures are 3309 bytes. Never store these in Sequelize `STRING`/`VARCHAR(512)` columns sized for RSA — use `BLOB`/`BYTEA` or `TEXT` (base64). Avoid putting PQC signatures in `Authorization` headers where size limits apply — use the request body instead. Never truncate a PQC key or signature for storage convenience. | ||
| 5. **Randomness and nonce safety.** Key generation must use `crypto.randomBytes` — never `Math.random()`, `Date.now()`, or a non-CSPRNG. AES-256-GCM nonces (12 bytes) must be freshly generated per encryption via `crypto.randomBytes(12)` and never reused under the same key; rotate the key after 2³² encryptions. `@noble/post-quantum`'s `kyber768.encapsulate(...)` generates its own randomness internally — don't supply external randomness unless the API requires it. | ||
| 6. **No algorithm negotiation in sensitive paths.** Never accept the algorithm from a JWT header or request payload in auth/key-exchange flows — allowlist exact identifiers and reject deviation with a generic `401`. In `jose` JWS/JWT verification, always pass an explicit `algorithms: ['ML-DSA-65']` (or the IANA codepoint once standardised); never accept `'none'` or legacy `'RS256'`. | ||
|
|
||
| ## Example | ||
|
|
||
| ```js | ||
| // BAD: classical-only key exchange with no configuration option to enable PQC at | ||
| // all, and (separately) a standalone PQC KEM with no hybrid classical leg. | ||
| const ecdh = crypto.createECDH('prime256v1'); | ||
| const sharedSecret = ecdh.computeSecret(peerPublicKey); // quantum-vulnerable, not configurable — a TODO(pqc) comment would not excuse this | ||
| const { sharedSecret: pqcOnly } = ml_kem768.encapsulate(recipientPub); // no X25519 hybrid leg | ||
|
|
||
| // GOOD: hybrid X25519 + ML-KEM-768 (FIPS 203) when config.pqcEnabled and the | ||
| // recipient advertises PQC support — security holds if either leg is unbroken; | ||
| // all inputs bound into the combiner to prevent downgrade. When PQC isn't | ||
| // enabled or the recipient is a legacy peer (recipientPqcPub is undefined), | ||
| // falls back to the classical-only leg rather than failing closed. | ||
| const { x25519 } = require('@noble/curves/ed25519'); | ||
| const { ml_kem768 } = require('@noble/post-quantum/ml-kem'); | ||
| const { sha3_256 } = require('@noble/hashes/sha3'); | ||
|
|
||
| function encapsulate(config, recipientClassicalPub, recipientPqcPub) { | ||
| const ephemeralPriv = x25519.utils.randomPrivateKey(); // crypto.getRandomValues internally | ||
| const ephemeralPub = x25519.getPublicKey(ephemeralPriv); | ||
| const classicalShared = x25519.getSharedSecret(ephemeralPriv, recipientClassicalPub); | ||
|
|
||
| if (!config.pqcEnabled || !recipientPqcPub) { | ||
| return { ciphertext: { classical: ephemeralPub }, sharedSecret: classicalShared }; // documented, config-gated fallback | ||
|
Comment on lines
+51
to
+52
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | 🏗️ Heavy lift 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -e
printf '%s\n' '--- policy file ---'
cat -n .claude/rules/js-post-quantum-cryptography.md | sed -n '1,90p'
printf '%s\n' '--- relevant symbols ---'
rg -n -C 4 'recipientPqcPub|pqcEnabled|classicalShared|ephemeralPub|sharedSecret' . --glob '!node_modules' --glob '!dist' --glob '!build'
printf '%s\n' '--- changed-file summary ---'
git diff --stat -- .claude/rules/js-post-quantum-cryptography.md
git diff -- .claude/rules/js-post-quantum-cryptography.md | sed -n '1,180p'Repository: wso2/api-platform Length of output: 11921 🏁 Script executed: #!/bin/bash
set -e
python3 - <<'PY'
from itertools import product
def path(pqc_enabled, recipient_pqc_pub):
return "hybrid" if pqc_enabled and recipient_pqc_pub else "classical"
print("--- branch truth table ---")
for enabled, advertised in product((False, True), (False, True)):
print({
"config.pqcEnabled": enabled,
"recipientPqcPub_present": advertised,
"selected_path": path(enabled, advertised),
})
PY
printf '%s\n' '--- capability and authentication references in policy ---'
rg -n -i -C 3 'authentic|negot|advertis|capabil|downgrade|fallback|recipientPqcPub|peer' \
.claude/rules/js-post-quantum-cryptography.md
printf '%s\n' '--- JavaScript implementation references ---'
rg -n -i -C 3 'recipientPqcPub|pqcEnabled|X25519MLKEM768|ecdhCurve|encapsulate' \
portals --glob '*.js' --glob '*.mjs' --glob '*.cjs' --glob '*.ts' --glob '*.tsx' \
|| trueRepository: wso2/api-platform Length of output: 16729 Bind When 🤖 Prompt for AI Agents |
||
| } | ||
|
|
||
| const { cipherText: pqcCT, sharedSecret: pqcShared } = ml_kem768.encapsulate(recipientPqcPub); | ||
|
|
||
| const combined = sha3_256( | ||
|
|
@@ -53,9 +62,10 @@ function encapsulate(recipientClassicalPub, recipientPqcPub) { | |
| ``` | ||
|
|
||
| > **Verification Checklist before outputting code:** | ||
| > * Does any RSA/ECDH/ECDSA/Ed25519/Ed448/X448/classic-DH use have no configuration option to enable PQC/hybrid at all, or is X25519 used outside its role as the classical leg of the mandated X25519+ML-KEM-768 hybrid (directive 3) — e.g. standalone, or paired with a non-ML-KEM KEM — or is any of this "justified" by an inline `// TODO(pqc)`-style comment instead of a tracked issue and an actual configuration option? | ||
| > * When PQC is enabled and the peer supports it, is the PQC KEM used as hybrid X25519+ML-KEM-768 rather than standalone? | ||
| > * Does a classical-only code path exist with no way to enable PQC/hybrid, instead of a config-gated fallback for legacy peers? | ||
| > * Are ML-KEM/ML-DSA key/ciphertext/signature sizes accounted for in Sequelize columns (`BLOB`, never `STRING(512)`) and payload budgets? | ||
| > * Any nonce/key generation using `Math.random()`/`Date.now()` instead of `crypto.randomBytes`, or a reused GCM nonce? | ||
| > * Does TLS config list `X25519MLKEM768` first in `ecdhCurve`, keeping a classical curve after it for legacy peers, for Node.js 22+ services? | ||
| > * Does any `jose` JWT/JWS verification omit an explicit `algorithms: ['ML-DSA-65']`-style allowlist? (Enabling a classical fallback via config is fine; accepting an algorithm the peer/token itself claims is not.) | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
Repository: wso2/api-platform
Length of output: 16562
🏁 Script executed:
Repository: wso2/api-platform
Length of output: 50375
🏁 Script executed:
Repository: wso2/api-platform
Length of output: 3669
Extend the rule scope to cover
portals/api-portal.The current scope excludes the TLS listener in
portals/api-portal/src/server.js, which usessrc/config/tlsOptions.jsand supportsX25519MLKEM768. Include this service and any other affected Node.js TLS services, or add an equivalent rule.🤖 Prompt for AI Agents