A Messaging Layer Security (RFC 9420) engine in
pure Kotlin Multiplatform: TLS presentation-language codec, HPKE, the
ratchet tree, the key schedule, the secret tree, message framing, proposals, commits,
Welcome, and the app_data_dictionary component carrier from
draft-ietf-mls-extensions-10.
It implements ciphersuite 0x0001
(MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519) and runs on JVM, Android, iOS
(arm64 and simulator), macOS (arm64) and Linux (x64).
It is the engine under Amethyst's two MLS bindings, each its own library: marmot-kmp (MLS over Nostr) and cordn-kmp (MLS over an MCP coordinator). It knows nothing about either, nor about Nostr, and must stay that way. The library depends on no Nostr code, so a binding cannot leak into it.
dependencies {
implementation("com.vitorpamplona.mls:mls:1.4.1")
}Releases are on Maven Central (1.3.1 and 1.4.0 are on Nostr only; they are built on a crypto-kmp that Central doesn't have).
Releases also go to Nostr + Blossom through Magpie. To
take them from there (signed by the key vitorpamplona.com/.well-known/nostr.json names as
releases), add Magpie's settings plugin in settings.gradle.kts and commit the
gradle/magpie.lock it writes; Gradle has to run on Java 21 or newer:
plugins {
id("com.vitorpamplona.magpie") version "0.2.3"
}
magpie {
group("com.vitorpamplona.mls")
group("com.vitorpamplona.crypto")
}From 1.3.1 on, its dependency crypto-kmp is released on
Nostr + Blossom only, so a build needs the com.vitorpamplona.crypto group above wherever it
takes this library from, Maven Central included.
The guide walks through everything below in order, from the first KeyPackage to fork recovery, and covers what the library validates and what your application must. Its examples are compiled and run as tests. This section is the short version.
val group = MlsGroup.create(identity) // a plain RFC 9420 group
val group = MlsGroup.create(identity, policy = myPolicy) // a binding's profileThe default group requires nothing beyond RFC 9420: no required_capabilities,
no leaf capabilities (§7.2 forbids advertising DEFAULT types), no commit
exporter, and no limit on who may commit what.
// Any MLSMessage for the group: application data, a proposal or a commit,
// as a PublicMessage or a PrivateMessage.
when (val result = group.processMessage(bytes)) {
is ProcessedMessage.Application -> show(result.message.content)
is ProcessedMessage.StagedProposal -> {} // waits in the pending pool
is ProcessedMessage.AppliedCommit -> {} // the group moved to result.epoch
}
// Send a proposal by reference for any member to commit.
val update = group.proposalMessage(group.proposeSigningKeyRotation())
// Commit everything pending. stageCommit() builds the commit without moving
// the group; merge it once the delivery service accepts it, or clear it if
// another commit won the epoch (receiving our own commit back also merges it).
val staged = group.stageCommit(wireFormat = WireFormat.PRIVATE_MESSAGE)
group.mergePendingCommit() // or group.clearPendingCommit()commit() is stageCommit() + mergePendingCommit(). Whichever is used, a
commit is all-or-nothing: if building or applying one fails, the group is left
exactly as it was.
Standalone proposals are accepted from members, from the group's
external_senders and from a new member proposing its own Add, after the
RFC 9420 §12.1 checks. Everything accepted waits in the pending pool and goes
into this member's next commit(), so a binding that must keep, say, a
non-admin's Add out of an admin's commit restricts it in
MlsGroupPolicy.authorizeProposal.
MlsGroup.processWelcome(welcome, bundle,
ratchetTree = treeBytes, // when the GroupInfo carries no ratchet_tree
psks = { id -> lookUp(id) }) // PSKs the Welcome names
MlsGroup.externalJoin(groupInfo, identity,
ratchetTree = treeBytes, // likewise
resyncLeafIndex = myOldLeaf) // a resync replaces our old leafgroupInfoMessage() publishes the GroupInfo as an MLSMessage for external
joiners; commit(includeRatchetTreeInWelcome = false) leaves the tree out of
Welcomes for applications that deliver it separately. stageWelcome does
everything processWelcome does but lets you inspect the group before
join().
MlsGroupPolicy.wireFormatPolicysends handshakes as PublicMessages or PrivateMessages and refuses the other kind (guide).PublicGroupfollows a group from a server, from its GroupInfo and PublicMessages, without being a member (guide).recoverForkByReaddingandrebootrepair a forked group (guide).
group.proposeReInit(newGroupId = id, newExtensions = exts); group.commit()
val next = group.reinit(otherMembersKeyPackages) // RFC 9420 §11.2
val sub = group.branch(someMembersKeyPackages) // RFC 9420 §11.3
MlsGroup.joinSuccessor(next.commit.welcomeBytes!!, myNewBundle, predecessor = group)The successor's first commit carries the predecessor's resumption PSK, and
joinSuccessor checks that the new group is what the ReInit asked for (or,
for a branch, only holds members of the predecessor).
Every LeafNode, KeyPackage, proposal list, UpdatePath and joined tree is held
to RFC 9420 §7.3, §10.1, §12.2, §12.4.2 and §12.4.3.1, by the committer
before sending and by every receiver before applying. The credential itself
is the application's to judge (the Authentication Service): implement
MlsGroupPolicy.validateCredential.
RFC 9420 says who may send a proposal and never who may commit one. Real deployments need more — Marmot's MIP-03 names admin accounts and allows everyone else only a self-Update or a SelfRemove — so the engine asks a policy wherever the spec defers to the application:
| Hook | Called from | Marmot uses it for |
|---|---|---|
authorizeCommit |
commit() and both inbound commit paths |
MIP-03 proposal-set rules + admin depletion |
authorizeSelfRemove |
proposeSelfRemove, buildSelfRemoveProposalMessage |
admin must self-demote first |
authorizeProposal |
every standalone proposal received | — |
authorizeExternalCommit |
every inbound external commit | — |
validateCredential |
every LeafNode validated | — |
validateCredentialSuccession |
every replaced leaf (Update, UpdatePath, resync) | — (default: same type and Basic identity) |
validateJoin |
processWelcome, stageWelcome |
required_member_roles on the agent-text-stream component |
defaultLeafCapabilities |
every leaf the engine builds | 0xF2EE + self_remove |
defaultRequiredCapabilities |
create(), epoch 0 |
the MIP-era interop set |
knownExtensionTypes |
GroupContextExtensions validation | 0xF2EE |
commitExporter |
CommitResult.preCommitExporterSecret |
MLS-Exporter("marmot", "group-event", 32) |
wireFormatPolicy |
the default wire format of commits and proposals; every member's inbound handshake | — (default: send public, accept both) |
Three things to know before you add a binding:
-
One argument selects a whole profile.
policysupplies the rules and the capability defaults and the exporter binding, socapabilitiesandrequiredCapabilitiesdefault from it. Adopting a profile is one argument, not five. -
A policy is behaviour, not state. It is deliberately absent from
MlsGroupState, so whatever restores a group must pass the same policy it was created with. A restore that forgets it gets a group that silently skips the binding's rules. -
A policy gets a
GroupView, not theMlsGroup. A policy holding the group could commit or rotate keys from inside the check meant to gate exactly that.
The default is permissive rather than closed. Closed would make the engine unusable without a policy and would push callers into writing an allow-everything one anyway; open puts each restriction in the binding that documents it. The cost is item 2 above.
A handful of engine internals (the lifetime clock, the staged-proposal pool, the
PSK secret, the required_capabilities checks, the join-time parent-hash
verifier) are public only so the bindings' own test suites can reach them. They
require @OptIn(InternalMlsApi::class) and are not a stable API.
See docs/guide/upgrading.md: what changed on the wire since 1.2, and the APIs added since.
Every primitive comes from crypto-kmp
(com.vitorpamplona.crypto:crypto): SHA-256, HMAC-SHA256 and HKDF, AES-128-GCM,
X25519, Ed25519 and the secure random source. It is an api dependency because
MlsGroup takes its Ed25519KeyPair. crypto-kmp uses JCA on the JVM and Android,
CommonCrypto on Apple where it has the primitive, and constant-time pure Kotlin
elsewhere, and depends on nothing but the Kotlin stdlib. So does this library,
apart from crypto-kmp.
JS and Wasm are not targets yet. The engine is synchronous and WebCrypto's ciphers are async-only, but crypto-kmp 2.1 brings synchronous, constant-time Kotlin primitives to both, so nothing in the crypto layer stands in the way any more.
mls/src/commonTest runs on every target; mls/src/jvmAndroidTest holds the
JVM/Android-only suites. interop/ replays the RFC 9420 test vectors from
mls-implementations — the
passive-client vectors end to end through MlsGroup (joining, every commit
shape, a 200-epoch random run), plus TreeKEM, message protection, tree
validation, PSK secrets and the rest.
The other direction is covered too: MlsKmpAuthoredVectors has mls-kmp
members run a group through every epoch change — commits of every shape,
proposals by reference, external joins and resyncs, PSKs, ReInit and branch
successors — and records it as passive-client vectors, which ts-mls
(tools/tsmls-vector-gen/verify-passive-client.mjs), OpenMLS
(tools/openmls-verifier/run.sh) and mls-rs (tools/mlsrs-verifier/run.sh)
must follow epoch by epoch. CI runs all three, and also has mls-kmp join
ts-mls groups by external commit from ts-mls GroupInfos
(tools/tsmls-vector-gen/external-join.mjs), with ts-mls then following
mls-kmp's commits and messages.
Live interop goes through the mlswg test-runner: interop-client/ is the gRPC
client it drives, and the nightly runs it alone and against OpenMLS's
(interop-client/README.md). CI also has mls-rs
write fresh passive-client vectors and mls-kmp replay them
(ForeignPassiveClientVectorsTest).
MdkWelcomeInteropTest and TsMlsWelcomeInteropTest join groups created by
OpenMLS (via MDK) and ts-mls, and TsMlsExternalJoinInteropTest joins
ts-mls groups by external commit. group/MlsGroupPolicySeamTest pins the policy seam
itself with a recording policy.
./gradlew jvmTest # JVM
./gradlew testAndroidHostTest # Android, on the host JVM
./gradlew linuxX64Test # Linux native
./gradlew iosSimulatorArm64Test # iOS (macOS host)Vector generators: tools/tsmls-vector-gen (ts-mls) here; the OpenMLS one is
marmot-kmp's marmot/tools/mdk-vector-gen, because it shares an MDK pin with
Marmot's vectors.
marmot-kmp, cordn-kmp and Amethyst consume the published artifact. To build one against a local checkout instead, point it at this directory:
./gradlew -PmlsKmpDir=../mls-kmp :marmot:jvmTest # in marmot-kmp
./gradlew -PmlsKmpDir=../mls-kmp :cordn:jvmTest # in cordn-kmpAGENTS.md has the project rules, for people and coding agents alike.
The library is built in explicit-API mode, and its public ABI is dumped to
mls/api/. CI's checkKotlinAbi fails when the API changes without the dump
changing too, so every API change shows up as a diff in review: run
./gradlew updateKotlinAbi and commit the result.
Saved group states (MlsGroupState, v1 to v10) and KeyPackage bundles
(KeyPackageBundleCodec v1) are frozen in
mls/src/commonTest/resources/mls/persisted-formats.json.
PersistedFormatsTest restores every one of them and keeps using it. A new
layout version adds an entry (PersistedFormatFixtureWriter); the old entries
never change.
Push a v* tag. .github/workflows/create-release.yml runs the tests and
publishes to Maven Central and to Nostr + Blossom, with the version taken from the tag, then
opens the GitHub release.
publishToMavenLocal works without signing keys for local testing.
MIT. See LICENSE.