OpenSSL Studio / API Security & JWT Workshop
What you will do: Open seven sections: inspect a JWT, sign one with ML-DSA or SLH-DSA, build a composite ML-DSA-65+Ed25519 JWT, encrypt a payload as an HPKE JWE with ML-KEM-768 or the X25519 hybrid, compare token sizes, run the JOSE known-answer audit, and attack a JWT verifier in the Attack Lab.
Worked example: In PQC JWT Signing pick ML-DSA-65 on the @noble/post-quantum backend, Generate Keypair, sign the sample payload for Alice Engineer, then Verify (noble) reports Signature valid with the token's byte sizes.
Runtime and privacy: The cryptographic exercise runs in this browser. Review the site privacy terms before entering sensitive material; use synthetic inputs for learning and evaluation.
For your role
- Developer / Engineer
- Choose ML-DSA-44, 65 or 87 or an SLH-DSA set, pick the signing backend (@noble/post-quantum or SoftHSM3), Generate Keypair and Sign JWT: the editable payload and the resulting header show what your issuer and verifier will handle.
- Security Architect
- Step 3 offers two hybrid patterns, a Nested JWT and a Composite MLDSA65-Ed25519 signature: which verifiers accept each is the migration decision, and Step 4's ML-KEM-768 JWE shows encrypted tokens.
- Researcher / Academic
- Run the API Security JWT Known Answer Tests panel, then sign the same payload with each algorithm and backend to compare signature sizes and the composite encoding against the JOSE drafts.
Real PQC JWT Signing
Generate a real ML-DSA keypair, sign a JWT over the canonical signing input b64u(header).b64u(payload), and verify the compact JWS — all in your browser. Algorithm codes follow RFC 9964 (ML-DSA for JOSE and COSE, published May 2026). SLH-DSA codes follow draft-ietf-cose-sphincs-plus-10 and composite codes draft-ietf-jose-pq-composite-sigs-06 — both still Internet-Drafts.
Signing backend
Keypair Generation
Scope note: RFC 9964 §7.2 explicitly excludes HashML-DSA (FIPS 204 §5.4) from JOSE/COSE — this workshop only exposes the pure-mode variants accordingly.
JWT Payload (Editable)
Educational use only. The signing input is b64u(JOSE header).b64u(payload) per RFC 7515 §5.1. A token signed via noble or SoftHSM3 can be verified by the other implementation when it is given the matching public key and parameters, which shows that RFC 9964 interoperates across implementations. Signing the same input twice with the same key can produce different signatures (hedged ML-DSA signing uses fresh randomness) and each one verifies; byte-for-byte equality is reserved for known-answer tests with a fixed key, input and randomness, or for deterministic signing.
API Security JWT Known Answer Tests
RFC 9964 · FIPS 203 · FIPS 204
Loading failure exercise…
Click Run known-answer checks to run 4 use-case scenarios. Evidence in this set: NIST ACVP-Server reference sample — Expected values copied from the public NIST ACVP-Server repository with immutable source identity; Functional round-trip — Output produced by an implementation is consumed by the same or paired implementation.
Reference samples from the public NIST ACVP-Server repository · RFC 9964 · FIPS 203 · FIPS 204 · Generated keys are for educational use only.
Hybrid JWT Creation
During the PQC transition, a hybrid JWT combines a classical and a PQC signature, so forging a token requires breaking both algorithms, provided the verifier requires both signatures to be valid. Composite mode follows draft-ietf-jose-pq-composite-sigs-06 and verifies against that draft's published examples; it is a work-in-progress Internet-Draft, so treat this tab as experimental.
Signing backend
Nested JWT Creation Flow
Key insight: Neither approach lets an unmodified classical verifier accept the token on its own. Nested mode can serve one only if a gateway or protocol you define unwraps the inner JWT, and that path carries no PQC protection, so it must be retired on a schedule. Composite mode needs every verifier upgraded to draft-ietf-jose-pq-composite-sigs, but yields one token (3,309 B ML-DSA-65 + 64 B Ed25519 signature); forging it requires breaking both algorithms, because the verifier must check both. Either way, the verifier's algorithm allowlist is what stops a downgrade to the classical-only path.
JWE Encryption with HPKE experimental · draft-ietf-jose-hpke-pq-pqt-02
Post-quantum JWE runs through HPKE. draft-ietf-jose-hpke-encrypt (RFC Editor queue, editing in progress as of November 2026) defines how HPKE carries a JWE, and draft-ietf-jose-hpke-pq-pqt-02 registers the ML-KEM suites used here. This workshop checks its examples against revision -02 (25 October 2026). Compared with -01, that revision adds references for the KEM serialization and drops the sentence preferring hybrid suites; the HPKE-8, -9, -10, -12 and -13 parameters and the published examples are unchanged. All operations run real crypto in your browser, and the code is checked against the examples published in that draft. It is still a working-group draft (as of November 2026), so the algorithm names may change — not a format to deploy yet. An earlier direct-KEM design (draft-ietf-jose-pqc-kem) was dropped for JOSE in 2026.
HPKE suite ("alg")
Both use the SHAKE256 KDF and AES-256-GCM. The hybrid keeps a classical X25519 component, so a flaw found in ML-KEM alone would not expose the payload.
KEM backend
The browser path runs @noble/post-quantum (ML-KEM, X-Wing) and @noble/hashes (SHAKE256) inside the hpke package.
JWE Compact Serialization (5 parts)
JWE keeps its 5 parts. In HPKE Integrated Encryption the Encrypted Key carries the HPKE encapsulated secret (1,088 bytes for HPKE-12), and the IV and Tag stay empty because HPKE manages its own nonce and puts the GCM tag inside the ciphertext.
The recipient generates a ML-KEM-768 keypair and publishes the public key (1,184 bytes) as an "AKP" JWK with "alg": "HPKE-12". The private key is a 64-byte seed.
Encryption Pipeline
Check against the draft's published example
draft-ietf-jose-hpke-pq-pqt-02 Appendix A publishes, for each algorithm, a private key and a JWE made by the draft authors with a different ML-KEM implementation. Decrypting it here shows this code interoperates with theirs, not just with itself. With the SoftHSM3 backend the published private key is imported into the token and the example is opened there.
Key insight: moving JWE to post-quantum changes the key-establishment step, not the token format. HPKE packages "encapsulate a key, derive a symmetric key, encrypt" as one standard operation, so the same JWE layout works for classical ECDH suites (HPKE-0 to HPKE-7) and for ML-KEM. What does change is size: the 1,088-byte encapsulated secret makes every encrypted token roughly 1.5 KB larger than its plaintext.
Production Tool Capabilities & Verification Requirements
What this sample check establishes: Signs and verifies real JSON Web Tokens (JWS/JWT) and hybrid JWE payloads using `ML-DSA-44/65/87` and `ML-KEM-768` via OpenSSL 3.6 WASM.
Browser sandbox limitation (non-certification boundary): In-browser token signing and verification; it does not test production reverse-proxy HTTP header limits (e.g., NGINX `large_client_header_buffers`) or distributed JWKS caching.
What to require and test in your production tools:
- API gateway and ingress proxy buffer sizing validated for ~4.6 KB (`ML-DSA-65`) Base64URL-encoded `Authorization: Bearer` headers.
- Strict JWS algorithm allowlisting (`ML-DSA-65`, per the JOSE ML-DSA draft) in token verifiers.
- JWKS discovery endpoints serving post-quantum public keys with automated `kid` rollover.
Try it
- 1. Predict before you run it.
- 2. Run or change the tool above.
- 3. Explain what the result shows.
Create a Nested JWT in Step 3. Who validates what?
Next step
Turn it into a plan: Hybrid Transition PlannerThis tool practises the API Security & JWT module, phase 5 (Pilots & Migration); Hybrid Transition Planner produces a deliverable of that phase.
Related content
Next in OpenSSL Studio