Skip to main content
LibXMTP implements the Messaging Layer Security (MLS) protocol using OpenMLS to provide secure, authenticated messaging with strong security guarantees.

​
Security Properties

The security of XMTP rests on the MLS protocol. The chosen configuration provides:

​
Privacy and Authenticity

  • End-to-end encryption: All messages are encrypted using the MLS secret tree and AEAD
  • Message authenticity: Every message is authenticated through the MLS signature chain
  • Metadata protection: XMTP uses private messages exclusively, providing the highest metadata hiding properties possible in MLS

​
Forward Secrecy

Forward secrecy ensures that past messages remain secure even if current keys are compromised. XMTP provides forward secrecy through:
  • Automatic key rotation: Path encryption secrets are updated periodically
  • Ephemeral keys: HPKE keys are rotated with each key package update
  • Limited key retention: Maximum of 3 past epochs retained (lower than OpenMLS default of 5)
The maximum_past_epochs parameter of 3 is a trade-off between functionality and forward secrecy. This lower value (compared to OpenMLS default of 5) increases security by limiting the key material retained for past epochs.

​
Post-Compromise Security (PCS)

Post-compromise security allows the system to heal from key compromise through subsequent key updates. Path updates occur:
  1. Before sending the first message to a group
  2. Before sending a message if 3 months have elapsed since the last path update
Signature keys are not rotated, as their public key forms a persistent identity for the installation. Only path encryption secrets are rotated.

​
Harvest Now, Decrypt Later (HNDL) Protection

With PR #1851, libxmtp provides HNDL forward security using post-quantum cryptography. Key features:
  • XWing-06 encryption: Welcome messages use post-quantum secure HPKE with XWing-06 key pairs
  • HNDL-FS guarantee: Even an attacker with a quantum computer in the future cannot decrypt messages encrypted before key deletion
  • Limitation: HNDL Post-Remove Security (HNDL-PRS) is not provided - removed clients break the HNDL chain
See the HNDL security analysis for technical details.

​
Cryptographic Parameters

LibXMTP uses the following MLS configuration: 
// Ciphersuite
MLS_128_DHKEMX25519_CHACHA20POLY1305_SHA256_Ed25519

// Parameters
maximum_past_epochs: 3
maximum_forward_ratchets: 1000
Cryptographic primitives:
  • Key exchange: X25519
  • AEAD: ChaCha20Poly1305
  • Hash: SHA-256
  • Signatures: Ed25519

​
Storage Security

​
Database Encryption

The XMTP SQLite database supports optional encryption using SQLCipher.
App developers are strongly encouraged to use an encryption key for the database and store that key securely. However, key derivation, storage, and encryption are the app’s responsibility and considered out of scope for the protocol.
The database stores:
  • MLS group state
  • Decrypted messages
  • Installation private keys
  • Identity information

​
Endpoint Security

In the XMTP messaging app, private key material is stored in the secure key storage of mobile operating systems. XMTP encourages SDK users to do the same.

​
Transport Security

XMTP uses gRPC with TLS (via Rustls) to protect metadata during transmission. While the secure transport protects MLS and XMTP metadata, it is not necessary for end-to-end security - MLS provides that independently.

​
Threat Model

​
In Scope

  • Message privacy and authenticity
  • Forward secrecy
  • Post-compromise security
  • HNDL forward security
  • Credential validation
  • DoS and spam protection (IP-based rate limiting)

​
Out of Scope

The following are explicitly not covered by XMTP’s threat model:
  • Physical attacks on endpoints
  • Network privacy (IP addresses)
  • Deniability of messages
  • Membership privacy (inherited from MLS)
  • Ciphertext size attacks (XMTP does not use extra padding)
  • Quantum adversary attacks on signatures (no standardized post-quantum signature suites yet)
  • Push token privacy (for FCM notifications)

​
Additional Security Mechanisms

XMTP allows blocking group invites from unwanted senders, providing spam protection at the application layer.

​
Signature Uniqueness

The system protects against signature re-use:
  • Between inboxes: Inbox ID is included in all signature challenge text
  • Within inbox: Raw signatures are stored and checked for reuse

​
Trust Assumptions

The backend maintains a directory mapping wallet addresses to Inbox IDs and may return incorrect information. Backends can hide revocations of bindings. This is an inherent trust assumption in the current architecture.

​
Key Package Security

LibXMTP uses last resort key packages only, meaning key packages may be reused. Mitigation strategy:
  • Key packages are rotated immediately after receiving a Welcome message that used the published key package
  • Clients batch rotations when receiving multiple Welcomes simultaneously
  • Maximum of 2 HPKE keypairs retained (current + previous)
While Section 16.8 of RFC 9420 states key packages SHOULD NOT be reused, XMTP’s decentralized nature makes ephemeral key packages impractical. The rotation protocol minimizes the reuse window.

Build docs developers (and LLMs) love

Get started for freeTalk to us