Protocol Simulations / MLS Group Messaging

What you will do: Run the MLS primitives with real keys — ML-DSA-65 credential signing, ML-KEM-768 TreeKEM updates, AES-128-GCM messages — and watch the ratchet tree change as members join.

Worked example: Alice and Bob start the group; add a third member and see which nodes on the direct path have to re-key.

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.

Browse all Crypto Lab tools · Learn with MLS — Group Messaging

For your role

Developer / Engineer
Run the three live primitives, the ML-DSA-65 credential signing, the ML-KEM-768 HPKE TreeKEM update and the AES-128-GCM message encryption, then Add a member to the ratchet tree: the nodes on the direct path that must re-key are the ones your client would update.
Security Architect
Use Add, Remove and Update on the TreeKEM ratchet tree to see how group size changes the number of re-keyed nodes; the How openmls_pqctoday_crypto wires OpenMLS to the HSM section shows where signature keys can be kept in custody.
Researcher / Academic
Enable HSM mode so the three primitives route through softhsmv3 (C_SignMessage, C_EncapsulateKey, C_EncryptInit) and compare the key material with the software path; the Authoritative references list the RFCs the invariants come from.

Live MLS crypto primitives

Three in-browser operations that underpin every MLS session. Run each step to see real key material and verify the cryptographic invariants. Enable HSM mode below to route all steps through softhsmv3 (PKCS#11 v3.2) — C_SignMessage, C_EncapsulateKey, and C_EncryptInit. All crypto executes client-side — no server contact.

Live HSM Mode Active

SoftHSM3 · PKCS#11 v3.2 · Rust · session open

1

Credential signing key — ML-DSA-65

Each MLS leaf node carries an identity credential. The leaf_node is signed with ML-DSA-65 before being committed to the tree.

2

TreeKEM node update — ML-KEM-768 HPKE

When a member commits, it sends an UpdatePath with encrypted path secrets for the nodes in the filtered direct path of its leaf. ML-KEM decapsulation with a wrong key returns an implicit-rejection value (FIPS 203).

3

Application message encryption — AES-128-GCM

Choose the receiver context and run AES-GCM. In MLS, the content key and nonce come from the sender’s ratchet. This exercise uses a fresh demo key and a readable encoding of the authenticated group, epoch and content type.

Receiver context:

Check a proposed group reinitialization

Compare the target suite with the MLS 1.0 KeyPackages available for both existing members. This preflight uses fictional metadata and assumes package signatures and credentials are valid.

Hold reinitialization

Matching KeyPackages still needed for Bob.

This draft suite uses Ed25519. Its post-quantum confidentiality claim covers passive attacks.

RFC 9420 reinitialization · Draft cipher suite security considerations

TreeKEM ratchet tree

Watch which nodes get re-keyed on every Commit. Highlighted nodes are the committer's direct path — the only nodes touched by an O(log N) update.

Epoch: 0
Members: 2
Last op: initial state — 2-member group
rootAliBob
Re-keyed this Commit
Existing node
Blank / unoccupied

How openmls_pqctoday_crypto wires OpenMLS to the HSM

OpenMLS expects a single OpenMlsProvider trait combining crypto, randomness, and storage. Our provider routes each crypto trait method through PKCS#11 v3.2 against softhsmv3. The table below reflects the v0.2 implementation (Phase 1 + Phase 2 of the provider roadmap).

What this table describes: the real openmls_pqctoday_crypto Rust crate, which runs server-side. The workshop in this module is a JavaScript reimplementation of the same PKCS#11 calls against the same softhsmv3 software token — the crypto runs in that same token either way, but the steps you run here are not literally this crate executing.

OpenMLS operationPKCS#11 mechanismHSM-residentNotes
hashCKM_SHA256 / SHA384 / SHA512 yesC_DigestInit + C_Digest
hmacCKM_SHA256_HMAC yesSession-only generic-secret key, destroyed after each MAC
hkdf_extract / hkdf_expandCKM_*_HMAC (RFC 5869 over HSM HMAC) yesEvery HMAC round executes in the token
aead_encrypt / aead_decryptCKM_AES_GCM yesSession-only AES key for each operation
signature_key_genCKM_EC_EDWARDS_KEY_PAIR_GEN / CKM_EC_KEY_PAIR_GEN yesToken object with CKA_SENSITIVE=TRUE, CKA_EXTRACTABLE=FALSE
sign / verify_signatureCKM_EDDSA / CKM_ECDSA_SHA* yesProvider returns an opaque HsmKeyHandle, not key material
HPKE (DhKem25519 + SHA-256 + AES-128-GCM)CKM_ECDH1_DERIVE + CKM_SHA256_HMAC + CKM_AES_GCM yesRFC 9180 reimplementation over PKCS#11 primitives
HPKE (other suites)hpke-rs-rust-crypto (fallback) Phase 2.1Phase 2.1 — generalise PKCS#11 path to P-256/P-384/P-521/ChaCha20

Signature key custody

When OpenMLS calls signature_key_gen(), our provider runs C_GenerateKeyPair with CKA_SENSITIVE=TRUE and CKA_EXTRACTABLE=FALSE. What we return to OpenMLS as the "private key" is an opaque, versioned handle blob.

HsmKeyHandle wire format
┌────────┬─────────┬──────────┬──────────────┬────────────┐
│ "PQTH" │ ver (1) │ sig sch. │ cka_id_len   │  cka_id    │
│  4 B   │   1 B   │   2 B    │     2 B      │   N bytes  │
└────────┴─────────┴──────────┴──────────────┴────────────┘

On every sign() call, the provider decodes the handle, looks up the token object via C_FindObjects{ CKA_CLASS=PRIVATE_KEY, CKA_ID=… }, and runs C_SignInit + C_Sign inside the token. The provider never receives the raw private-key bytes: with CKA_SENSITIVE=TRUE and CKA_EXTRACTABLE=FALSE the PKCS#11 interface does not reveal them outside the token. In this sample the token is a software module (softhsmv3) loaded as a library into the same process, so the key bytes still exist in that process's memory and the attributes only limit what the interface returns. A production HSM has to demonstrate separately its tamper resistance, isolation of key material from the host and assurance evidence for the module and its configuration.

Authoritative references

The library entries that anchor this module's claims:

  • • RFC 9420
  • • RFC 9180
  • • draft-ietf-mls-pq-ciphersuites-07
  • • draft-ietf-mls-combiner-02
  • • draft-ietf-mls-extensions-11
Production Tool Capabilities & Verification Requirements

What this sample check establishes: Demonstrates RFC 9420 Messaging Layer Security (MLS) TreeKEM group key establishment and epoch ratcheting, plus draft post-quantum ciphersuites (draft-ietf-mls-pq-ciphersuites).

Browser sandbox limitation (non-certification boundary): Runs in a single browser session; it does not test distributed Delivery Service message ordering or multi-device offline queue synchronization.

What to require and test in your production tools:

  • MLS (RFC 9420) implementation that also supports the draft PQ ciphersuites (draft-ietf-mls-pq-ciphersuites) with a hybrid ML-KEM KEM and `ML-DSA` signatures.
  • Strict epoch-authenticity and TreeKEM parent-hash verification to detect malicious Delivery Service tree tampering.
  • Automated PCS (Post-Compromise Security) self-update cadence policies for long-lived messaging groups.

Try it

  1. 1. Predict before you run it.
  2. 2. Run or change the tool above.
  3. 3. Explain what the result shows.

Add a third member to the group. Which nodes re-key?

Next step

Turn it into a plan: Hybrid Transition Planner

This tool practises the MLS — Group Messaging module, phase 5 (Pilots & Migration); Hybrid Transition Planner produces a deliverable of that phase.

Next in Protocol Simulations