Skip to content
프로젝트

thomas-vilte/mls-go has 33 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 03:19 UTC. Last push 2026-11-12.

이 수치를 측정하는 방법

측정된 스타 증가

in 24h
0
in 7 days
업데이트 지연
in 15 days
업데이트 지연
in 1 month
업데이트 지연

서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.

소개

MLS Protocol (RFC 9420) implementation in Go. Secure group key exchange with forward secrecy and post-compromise security for E2EE messaging.

보안

README.md

Original

mls-go mascot

mls-go

Pure Go implementation of Messaging Layer Security (MLS) per RFC 9420.

Go Reference CI Coverage RFC 9420 License: MIT

Performance

Benchmarked on Intel Core i3-9100F (4 cores), linux/amd64, Go toolchain used by this repo. UpdatePath path-secret encryption runs in parallel (one goroutine per filtered copath level).

Operation 2 members 10 members 50 members 100 members 500 members
Commit 468 us 1.15 ms 3.48 ms 6.80 ms 34.7 ms
JoinFromWelcome 693 us 1.92 ms 8.08 ms 15.8 ms 77.7 ms
SendMessage 50.4 us 49.3 us 52.1 us 49.8 us 51.3 us
ReceiveMessage 87.3 us 87.9 us 89.8 us 89.3 us 90.5 us

Commit and JoinFromWelcome scale with group size because they walk the ratchet tree. SendMessage/ReceiveMessage stay flat: each message only advances the sender's own secret tree ratchet, independent of how many other members are in the group.

Run with: go test ./group/... -run=^$ -bench=BenchmarkCommit -benchmem -count=5 and go test ./group/... -run=^$ -bench=BenchmarkJoinFromWelcome -benchmem -count=5 (swap in BenchmarkSendMessage / BenchmarkReceiveMessage for the messaging rows).

Current status: v1.3.0 — stable, interop-verified.

Why This Exists

I needed an RFC 9420-compliant MLS library in Go with no CGO dependency. The existing options either required C bindings or were incomplete. So I built this from scratch, testing interoperability against mlspp and OpenMLS to make sure the implementation is correct.

Use it if you need group key exchange in Go: encrypted messaging, E2EE group chats, audio/video call encryption (DAVE protocol), or any protocol that needs a standard group ratchet.

Overview

Main packages, organized around the RFC 9420 spec:

Package Purpose
mls (root) High-level thread-safe Client API
group Low-level group lifecycle, commits, proposals, Welcome
keypackages KeyPackage generation, validation, and lifetime options
credentials BasicCredential and X.509 credential support
ciphersuite AEAD, HPKE, HKDF, signatures, hash references
extensions Extension types (ExternalSenders, RequiredCapabilities, …)
framing MLSMessage, PublicMessage, PrivateMessage wire format
schedule Key schedule and MLS-Exporter (RFC 9420 §8)
secrettree Per-sender secret tree ratchets
treesync Ratchet tree and TreeKEM
storage Pluggable storage interfaces + file, memory, encrypted backends
testing/mlstest Testing helpers for MLS scenarios

What Works

Core RFC 9420 protocol:

  • Group lifecycle: create, join (Welcome + External Join), leave
  • Proposals: Add, Update, Remove, PSK, ReInit — with commit and Welcome
  • Message protection: PrivateMessage (encrypted) and PublicMessage (signed)
  • Post-compromise security: UpdatePath with parent-hash verification
  • External Senders (RFC §12.1.8.1)
  • Staged commits via CommitPendingProposalsStaged / ConfirmPendingCommit (RFC §14)
  • State serialization with nonce-safe SecretTree counters
  • Full LeafNode validation: lifetime, capabilities, extensions, credential types
  • Per-generation replay protection — duplicate generation numbers rejected
  • AEAD nonce counter limit enforced (2³²−1 per sender per epoch)
  • Welcome join validates ratchet_tree structure and PSK availability

All the boring validation stuff from the RFC is implemented too (varint encodings, required_capabilities checks, parent-hash chain verification, etc.). The interop tests verify correctness against mlspp and OpenMLS.

Interoperability

Tested against other MLS implementations via Docker:

Target Suites Result
mls-go self 1, 2, 3 21/21 PASS
mlspp cross 1, 2, 3 21/21 PASS
OpenMLS cross 1, 2, 3 12/12 PASS (subset; sequential mode required)

Scenarios: welcome_join, application, commit, external_join, external_proposals, reinit, branch.

OpenMLS Note

OpenMLS cross-interop is experimental and limited to a subset of configs (welcome_join, application, external_join, deep_random). The OpenMLS Docker image tracks upstream HEAD without a pinned revision, so results can drift after upstream changes. If the OpenMLS cross suite fails, check whether the error originates from the OpenMLS interop client (e.g. key-store lookup failures) before assuming a regression in mls-go.

See interop/README.md for details on the supported subset and known unimplemented OpenMLS handlers.

Quick Start

The recommended entry point is the mls.Client API.

package main

import (
    "context"
    "fmt"
    "log"

    mls "github.com/thomas-vilte/mls-go"
    "github.com/thomas-vilte/mls-go/ciphersuite"
)

func main() {
    ctx := context.Background()
    cs := ciphersuite.MLS128DHKEMP256

    alice, err := mls.NewClient([]byte("alice"), cs)
    if err != nil {
        log.Fatal(err)
    }
    bob, err := mls.NewClient([]byte("bob"), cs)
    if err != nil {
        log.Fatal(err)
    }

    bobKP, _ := bob.FreshKeyPackageBytes(ctx)
    groupID, _ := alice.CreateGroup(ctx)
    _, welcome, _ := alice.InviteMember(ctx, groupID, bobKP)
    bob.JoinGroup(ctx, welcome)

    ciphertext, _ := alice.SendMessage(ctx, groupID, []byte("hello"))
    msg, _ := bob.ReceiveMessage(ctx, groupID, ciphertext)
    fmt.Println(string(msg.Plaintext)) // hello
}

More runnable examples live under examples/: the low-level group package flow, a Delivery Service (HTTP + SSE) with a CLI client, and a WASM build.

Client API

// Identity
client.Epoch(ctx, groupID)          // current epoch number
client.OwnLeafIndex(ctx, groupID)   // my position in the ratchet tree
client.ListMembers(ctx, groupID)    // active members with identity + signing key

// Membership
client.CreateGroup(ctx)
client.InviteMember(ctx, groupID, memberKPBytes)        // → commit, welcome
client.JoinGroup(ctx, welcomeBytes)                     // → groupID
client.ExternalJoin(ctx, groupInfoBytes)                // → groupID, commit
client.RemoveMember(ctx, groupID, memberIdentity)       // → commit (not the caller's own identity)
client.LeaveGroup(ctx, groupID)                         // → signed Remove proposal; local state deleted - see note below

// Proposals (batch flow)
client.ProposeAddMember(ctx, groupID, memberKPBytes)    // → signed PublicMessage
client.ProposeRemoveMember(ctx, groupID, memberIdentity)
client.CommitPendingProposals(ctx, groupID)             // → commit, welcome (auto-merge)
client.CancelPendingProposals(ctx, groupID)             // discard without committing

// RFC §14 staged commit (DS conflict-safe)
handle, _  := client.CommitPendingProposalsStaged(ctx, groupID) // generate only, no state change
welcome, _ := client.ConfirmPendingCommit(ctx, handle)          // DS accepted → merge + welcome
_           = client.DiscardPendingCommit(ctx, handle)          // DS rejected → rollback

// Maintenance
client.SelfUpdate(ctx, groupID)                         // rotate leaf encryption key

// Messaging
client.SendMessage(ctx, groupID, plaintext)                         // → ciphertext
client.SendMessage(ctx, groupID, plaintext, mls.WithAAD(aad))       // with authenticated data
client.ReceiveMessage(ctx, groupID, ciphertext)                     // → ReceivedMessage

// Crypto material
client.Export(ctx, groupID, label, context, length)     // MLS-Exporter
client.EpochAuthenticator(ctx, groupID)
client.GroupInfo(ctx, groupID)                          // signed GroupInfo bytes

// Process incoming
client.ProcessCommit(ctx, groupID, commitBytes)

Note - LeaveGroup returns a Remove proposal, not a commit. It signs a Remove proposal for this client's own leaf, deletes this client's persisted state and returns the proposal. Deliver the proposal to the other members. One of them removes this client by committing it (for example ProcessPublicMessage followed by CommitPendingProposals), and the epoch advances with that commit. A member cannot remove itself with a commit (RFC 9420 §12.2), so RemoveMember refuses the caller's own identity.

Breaking change: earlier versions returned a commit from LeaveGroup. Code that broadcast that commit must now broadcast the returned proposal instead.

Options

mls.NewClient(identity, cs,
    mls.WithStorage(groupStorage, keyStore),       // durable storage
    mls.WithCredentialValidator(validator),         // allowlist / cert policy
    mls.WithX509Credential(certDER, privKey),       // X.509 instead of Basic
    mls.WithPaddingSize(32),                        // AEAD padding in bytes
    mls.WithCacheStrategy(mls.CacheAlways),         // keep state in memory
    mls.WithEventHandler(func(e mls.GroupEvent) {  // lifecycle callbacks
        // EventMemberJoined, EventMemberRemoved, EventEpochAdvanced,
        // EventMessageReceived, EventSelfUpdated
    }),
)

KeyPackage Options

// Default: now-1h / now+83d (interop-safe margin)
kp, priv, err := keypackages.Generate(credWithKey, cs)

// Custom window
kp, priv, err := keypackages.Generate(credWithKey, cs,
    keypackages.WithLifetime(notBefore, notAfter))

// No expiry (not_before=0, not_after=2^64-1)
kp, priv, err := keypackages.Generate(credWithKey, cs,
    keypackages.InfiniteLifetime())

Low-Level API

For advanced use cases (custom wire protocol, external commits, group inspection) use group.Group directly:

g, err := group.NewGroup(groupID, cs, kp, kpPriv, group.WithExtensions(extensions))
g.Export("My App v1", senderIDBytes, 16)         // derive sender key
g.EpochAuthenticator()                           // authentication tag
g.RevokeProposal(ref)                            // remove in-flight proposal
g.MarshalState() / group.UnmarshalGroupState()   // persist / restore

Storage

// In-memory (tests / demos - state is lost on restart)
store := memorystore.NewStore()

// File-backed (durable - see security note below)
store, err := filestore.NewStore("/var/lib/myapp/mls")

// Encrypted file-backed (required for production)
encStore, err := storage.NewEncryptedStore(store, encryptionKey) // 32-byte AES-256 key

client, err := mls.NewClient(identity, cs, mls.WithStorage(encStore, encStore))

Security - encrypt group state at rest. MarshalState serializes the complete MLS epoch state to JSON, including epoch secrets, leaf encryption keys, and the ratchet tree. If this data is stored unencrypted an attacker with file-system access can impersonate group members and decrypt past messages.

Always wrap the file store with storage.NewEncryptedStore (AES-256-GCM) in production. The in-memory store is safe for tests and ephemeral processes where state is never written to disk.

Build and Test

go build ./...
go test ./...
go test -race ./...
golangci-lint run ./...

Interop Tests

# Build the server image after local changes
docker compose -f docker/docker-compose.yml build mls-go

# Self-interop (all suites in parallel, ~8 min)
./docker/run-interop.sh self

# Cross-interop against mlspp
./docker/run-interop.sh cross

# Cross-interop against OpenMLS
CROSS_TARGET=openmls ./docker/run-interop.sh cross

# Single suite
SUITES="2" ./docker/run-interop.sh self

# Stress mode (includes deep_random, takes longer)
RUN_STRESS=1 ./docker/run-interop.sh self

Security

See SECURITY.md for deployment caveats, state encryption guidance, and known limitations.

Integration Guide

See INTEGRATION.md for storage patterns, delivery service architecture, and multi-device considerations.

Contributing

See CONTRIBUTING.md. All code, comments, errors, tests, and docs must be in English.

License

MIT. See LICENSE.