A Hybrid Post-Quantum Secure, Decentralized Messaging Protocol for High-Threat Environments
- Executive Summary
- The Problem We Solve
- Who Should Use LMP
- Core Capabilities
- Technical Architecture
- Cryptographic Foundation
- Security Mechanisms
- How It Works
- Threat Model
- Trade-offs & Design Decisions
- Getting Started
- Documentation
- Project Status
- Contributing
- License
- Acknowledgments
Lattice Mesh Protocol (LMP) is a next-generation secure messaging protocol engineered to withstand the most sophisticated threats imaginable—including future quantum computers. Unlike traditional encrypted messengers that rely on centralized servers and algorithms vulnerable to quantum attacks, LMP combines:
-
Hybrid Post-Quantum Cryptography — Dual classical (X25519, Ed25519) and post-quantum (Kyber768, Dilithium3) algorithms working in tandem. If either is compromised, the other continues protecting you.
-
Decentralized Mesh Architecture — No central servers to compromise, seize, or subpoena. Messages route through a distributed network of peer nodes.
-
Metadata Resistance — Not just message content is encrypted, but the patterns of who communicates with whom, when, and how often are obscured through onion routing, cover traffic, and fixed-size cells.
-
Perfect Forward Secrecy — Every message uses a unique key. Compromise of current keys cannot decrypt past messages. The Double Ratchet mechanism with hybrid key exchange ensures cryptographic keys are constantly evolving.
The result: A messaging system designed for journalists, activists, whistleblowers, and privacy-conscious individuals operating in environments where adversaries have nation-state-level surveillance capabilities.
Current encryption standards (RSA, Elliptic Curve Cryptography) will be broken by sufficiently powerful quantum computers. Security researchers estimate:
| Timeline | Threat Level |
|---|---|
| Today | Classical cryptography secure against current computers |
| 2030-2035 | Large-scale quantum computers expected to emerge |
| Post-2035 | RSA-2048 and ECC-256 potentially broken in hours, not millennia |
"Harvest Now, Decrypt Later" Attacks: Adversaries are already recording encrypted communications today, storing them until quantum computers can break the encryption. If you're protecting information that must remain secret for decades, classical encryption alone is insufficient.
LMP's Solution: Hybrid cryptography using NIST-standardized post-quantum algorithms (Kyber, Dilithium) ensures your messages remain secure even when quantum computers become powerful enough to break classical encryption.
Even with perfect content encryption, traditional messengers leak catastrophic amounts of metadata:
| What They See | What It Reveals |
|---|---|
| IP addresses | Your physical location |
| Timestamps | When you're active and patterns of activity |
| Contact lists | Your complete social graph |
| Message sizes | Types of content (text vs. files) |
| Frequency of contact | Relationship strength and nature |
| Online status indicators | Real-time movements and habits |
Intelligence agencies have stated that "We kill people based on metadata." Social graph analysis can identify journalists' sources, activists' collaborators, and organizational structures—all without reading a single message.
LMP's Solution:
- Onion Routing: Messages traverse 3-5 random mesh nodes; each node only knows its immediate predecessor and successor
- Fixed-Size Cells: All network traffic consists of identical 16KB packets, making message size analysis impossible
- Cover Traffic: Continuous fake traffic mixed with real messages makes traffic analysis impractical
- No Central Servers: No single point stores your contact list or communication patterns
In traditional systems, compromise of long-term keys can decrypt:
- All past messages (if stored)
- All future messages (until key changes)
- Your entire communication history
LMP's Solution: The Double Ratchet algorithm ensures:
- Forward Secrecy: Compromise of today's keys cannot decrypt yesterday's messages (keys are deleted immediately after use)
- Post-Compromise Recovery: Even if an adversary gains temporary access to your device, security is restored within 50 messages or 24 hours
LMP is specifically designed for individuals and organizations operating in high-threat environments where adversaries have significant resources:
| User Type | Threat Scenario |
|---|---|
| Journalists | Protecting sources from government surveillance; investigating organized crime or corruption |
| Human Rights Activists | Operating in authoritarian regimes with state surveillance apparatus |
| Whistleblowers | Communicating evidence of wrongdoing without exposing identity |
| Lawyers | Maintaining attorney-client privilege against sophisticated adversaries |
| Researchers | Communicating sensitive findings before publication |
| High-Value Targets | Executives, diplomats, or others at risk of targeted surveillance |
- ISP and backbone-level surveillance (NSA, GCHQ-style monitoring)
- Nation-state actors with substantial computational resources
- "Harvest now, decrypt later" quantum computing threats
- Compromised infrastructure and malicious relay nodes
- Temporary device seizure (border crossings, brief arrests)
- Advanced traffic analysis and metadata correlation
- Casual messaging — The security comes with latency and bandwidth trade-offs
- Permanently compromised devices — If malware has root access, no software can protect you
- Users who share their passwords — Social engineering defeats all technical measures
- Guaranteed availability — Security may occasionally require accepting message delays
Every key establishment uses both classical and post-quantum algorithms in parallel:
| Purpose | Classical Algorithm | Post-Quantum Algorithm |
|---|---|---|
| Key Agreement | X25519 (ECDH) | Kyber768 (ML-KEM) |
| Digital Signatures | Ed25519 | Dilithium3 (ML-DSA) |
The final shared secret is derived by combining both shared secrets through HKDF-SHA3-256. Both cryptographic families must be broken to compromise the key establishment—if quantum computers break ECDH, Kyber protects you; if a flaw is found in Kyber, ECDH protects you.
Derived from the Signal Protocol's Double Ratchet, LMP extends it with hybrid cryptography:
- Symmetric Ratchet: Every message derives a new encryption key from the previous chain key. After use, keys are immediately deleted.
- Asymmetric Ratchet: Every 50 messages or 24 hours (whichever comes first), a new Diffie-Hellman and Kyber key exchange generates entirely new root keys.
Result: Compromise of any single key reveals only a tiny window of messages, and security automatically recovers.
No central servers, no single point of failure:
- Peer-to-Peer Architecture: Your device connects to 8-20 mesh peers
- Onion Routing: Messages are encrypted in layers, with each hop decrypting only enough to know the next destination
- Path Diversity: Different messages take different random paths (3-5 hops)
- Mailbox Nodes: For offline recipients, encrypted blobs are stored temporarily on distributed nodes
Comprehensive protection against traffic analysis:
| Technique | Purpose |
|---|---|
| Fixed 16KB Cells | All packets identical in size; prevents inferring message content type |
| Cover Traffic | Continuous fake traffic (Poisson distribution, ~1 cell/5 min baseline) |
| Batching | Messages are held briefly and transmitted in randomized bursts |
| Relay Shuffling | Each relay randomly delays and reorders packets |
| No Online Indicators | No presence status, typing indicators, or read receipts |
Multiple layers prevent message replay attacks:
- Message Number Tracking: Each (conversation, device, message number) tuple is recorded in a local database
- Timestamp Validation: Messages must be within ±5 minutes of receiver's clock
- Ratchet State Validation: Messages from old ratchet iterations are rejected
- Automatic Pruning: Tracking data older than 7 days is automatically cleaned
Sensitive cryptographic material is protected in memory:
- Memory Locking: Key material is pinned in RAM (mlock) to prevent swapping to disk
- Secure Zeroing: Keys are explicitly overwritten with zeros when no longer needed
- Zeroize on Drop: Rust's Drop trait ensures automatic secure cleanup
LMP is structured as a modular Rust library with clear separation of concerns:
┌─────────────────────────────────────────────────────────────────────┐
│ APPLICATION │
│ (Messaging Client / SDK User) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ DEVICE │ │ PROTOCOL │ │ NETWORK │ │
│ │ │ │ │ │ │ │
│ │ • Identity Mgmt │ │ • Handshake │ │ • Mesh Routing │ │
│ │ • LTIK / MTSK │ │ • Double Ratchet│ │ • Cell Creation │ │
│ │ • Intro Tokens │ │ • Session State │ │ • Cover Traffic │ │
│ │ • Multi-Device │ │ • Message Enc │ │ • Mailbox Nodes │ │
│ │ • Fingerprints │ │ • Replay Protect│ │ • Padding │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────┐ │
│ │ STORAGE │ │
│ │ │ │
│ │ • Protected Memory (mlock, zeroize) │ │
│ │ • Encrypted Keychain (OS integration) │ │
│ │ • Replay Protection Database (SQLite) │ │
│ │ • Conversation State Persistence │ │
│ └───────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────┤
│ CRYPTOGRAPHIC LAYER │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────┐ │
│ │ X25519 │ │Kyber768 │ │ Ed25519 │ │Dilithium3│ │ChaCha20- │ │
│ │ (ECDH) │ │ (KEM) │ │ (Sigs) │ │ (Sigs) │ │Poly1305 │ │
│ └─────────┘ └─────────┘ └─────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ HKDF-SHA3-256 │ │
│ │ (Key Derivation) │ │
│ └─────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
| Module | Responsibility |
|---|---|
| crypto/ | All cryptographic primitives: hybrid key exchange, hybrid signatures, AEAD encryption, key derivation, secure random generation |
| protocol/ | Protocol logic: handshake orchestration, Double Ratchet state machine, session management, nonce derivation, replay detection |
| network/ | Mesh networking: 16KB cell construction, multi-hop routing, cover traffic generation, message padding, mailbox integration |
| storage/ | Data persistence: protected memory regions, encrypted keychain integration, SQLite-backed replay database |
| device/ | Identity management: long-term key generation, introduction token creation/parsing, device fingerprints |
| Layer | Algorithm | Configuration | Security Level |
|---|---|---|---|
| Symmetric Encryption | ChaCha20-Poly1305 | 256-bit key, 96-bit nonce | 256-bit |
| Classical Key Exchange | X25519 | Curve25519 ECDH | ~128-bit classical |
| Post-Quantum Key Exchange | Kyber768 | ML-KEM NIST Level 3 | ~192-bit quantum |
| Classical Signatures | Ed25519 | RFC 8032 | ~128-bit classical |
| Post-Quantum Signatures | Dilithium3 | ML-DSA NIST Level 3 | ~192-bit quantum |
| Key Derivation | HKDF-SHA3-256 | Extract-then-expand | 256-bit |
LMP uses a hierarchical key structure with different lifetimes optimized for security and usability:
┌───────────────────────────────────────────────────────────────────────────────┐
│ LONG-TERM IDENTITY KEY (LTIK) │
│ │
│ Purpose: Root of trust, signs all other keys │
│ Algorithms: Ed25519 + Dilithium3 (dual classical/PQ signatures) │
│ Lifetime: 90 days (10-day overlap during rotation) │
│ Storage: Secure Enclave (iOS) / Keystore (Android) / Encrypted file │
│ Rotation: New LTIK signed by old LTIK, broadcast to all contacts │
├───────────────────────────────────────────────────────────────────────────────┤
│ MEDIUM-TERM SIGNING KEY (MTSK) │
│ │
│ Purpose: Day-to-day signing operations │
│ Algorithm: Ed25519 only (PQ not needed for ephemeral operations) │
│ Lifetime: 14 days (2-day overlap during rotation) │
│ Chain: Signed by current LTIK to prove authorization │
│ Rotation: Automatic, transparent to user │
├───────────────────────────────────────────────────────────────────────────────┤
│ SESSION KEYS │
│ │
│ Purpose: Per-conversation encrypted channel │
│ Algorithms: Derived from X25519 + Kyber768 handshake │
│ Lifetime: Until conversation ends or offline >7 days │
│ Derivation: HKDF(X25519_DH || Kyber_SS_AB || Kyber_SS_BA, context) │
├───────────────────────────────────────────────────────────────────────────────┤
│ RATCHET KEYS │
│ │
│ Purpose: Forward secrecy within conversations │
│ Algorithms: X25519 + Kyber768 ephemeral per ratchet step │
│ Lifetime: 50 messages OR 24 hours (whichever first) │
│ Derivation: DH ratchet advances root key, derives new chain keys │
├───────────────────────────────────────────────────────────────────────────────┤
│ MESSAGE KEYS │
│ │
│ Purpose: Encrypt exactly one message │
│ Algorithm: ChaCha20-Poly1305 AEAD │
│ Lifetime: Single use — NEVER stored, deleted immediately after use │
│ Derivation: Symmetric ratchet from chain key │
└───────────────────────────────────────────────────────────────────────────────┘
| Key Type | Size | Notes |
|---|---|---|
| X25519 Public Key | 32 bytes | Compact ECDH |
| X25519 Secret Key | 32 bytes | |
| Kyber768 Public Key | 1,184 bytes | Post-quantum necessitates larger keys |
| Kyber768 Secret Key | 2,400 bytes | |
| Kyber768 Ciphertext | 1,088 bytes | |
| Ed25519 Public Key | 32 bytes | |
| Ed25519 Signature | 64 bytes | |
| Dilithium3 Public Key | 1,952 bytes | |
| Dilithium3 Signature | 3,293 bytes | Larger than classical, but one-time per handshake |
The initial handshake establishes a shared secret through multiple independent paths:
- X25519 Diffie-Hellman: Classical ephemeral key agreement
- Kyber KEM (Alice → Bob): Post-quantum encapsulation from Alice's ephemeral public to Bob's prekey
- Kyber KEM (Bob → Alice): Post-quantum encapsulation from Bob's ephemeral public to Alice's
The combined shared secret: HKDF-SHA3-256(SS_x25519 || SS_kyber_AB || SS_kyber_BA, "LMP-v1-session-init")
Authentication: Both parties sign their handshake messages with BOTH Ed25519 AND Dilithium3. A message is rejected if EITHER signature fails.
Sending a message:
- Check if DH ratchet needed (50 messages or 24 hours since last)
- If yes: generate new ephemeral keys, perform DH, update root key
- Derive message key from chain key:
(CK_new, MK) = HKDF(CK_old, "message-key") - Construct nonce: 4-byte device-specific prefix + 8-byte message counter
- Encrypt with ChaCha20-Poly1305, including header as associated data
- Immediately delete message key (never stored)
- Increment message counter
Receiving a message:
- Check if message contains new ephemeral public keys (DH ratchet step)
- If yes: perform corresponding DH ratchet on receiving side
- Derive message key from receiving chain key
- Verify message not in replay database
- Validate timestamp within ±5 minutes
- Decrypt and verify AEAD tag
- Immediately delete message key
- Record message number in replay database
The 96-bit nonce is constructed deterministically to prevent reuse:
┌──────────────────────────────────────────────────────────────┐
│ NONCE (96 bits) │
├─────────────────────────────┬────────────────────────────────┤
│ Prefix (32 bits) │ Counter (64 bits) │
│ │ │
│ HKDF(conversation_id || │ Little-endian message │
│ device_id, │ number within ratchet │
│ "LMP-nonce-prefix") │ │
└─────────────────────────────┴────────────────────────────────┘
Why device-specific prefix? In multi-device scenarios, different devices might share the same conversation ID. The device-specific prefix guarantees that even if two devices in the same conversation send message #7, their nonces are different.
| Layer | Mechanism | Catches |
|---|---|---|
| Message Number Database | SQLite table: (conv_id, device_id, msg_num) | Exact duplicates |
| Timestamp Validation | Message timestamp within ±5 minutes of receiver's clock | Old replayed messages |
| Ratchet State Validation | prev_chain_length must match expected value | Cross-ratchet replays |
| Database Pruning | Entries older than 7 days deleted | Storage exhaustion |
Before two users can communicate, they must exchange introduction tokens through an out-of-band channel (QR code, NFC, secure email, in-person meeting):
┌────────────────────────────────────────────────────────────────┐
│ INTRODUCTION TOKEN │
├────────────────────────────────────────────────────────────────┤
│ • Ed25519 Identity Public Key (32 bytes) │
│ • Dilithium3 Identity Public Key (1,952 bytes) │
│ • MTSK Signing Public Key (32 bytes) │
│ • Prekey X25519 Public Key (32 bytes) │
│ • Prekey Kyber768 Public Key (1,184 bytes) │
│ • Temporary DHT Address (for initial contact) │
│ • Expiration Timestamp (7 days from creation) │
│ • Signature over all above (Ed25519 + Dilithium3) │
├────────────────────────────────────────────────────────────────┤
│ Encoded as Base64 for QR codes (~4.5 KB) │
└────────────────────────────────────────────────────────────────┘
ALICE BOB
│ │
│ 1. ClientHello │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Protocol version ││
│ │ • Alice's LTIK (Ed25519 + Dilithium3) ││
│ │ • Alice's MTSK (Ed25519) ││
│ │ • Alice's ephemeral X25519 public key ││
│ │ • Alice's Kyber768 public key ││
│ │ • Kyber ciphertext encapsulated to Bob's prekey ││
│ │ • Supported ciphers ││
│ │ • Timestamp (nanoseconds) ││
│ │ • Ed25519 signature + Dilithium3 signature ││
│ └─────────────────────────────────────────────────────────┘│
│─────────────────────────────────────────────────────────────▶│
│ [Encrypted with Bob's prekeys, routed via mesh] │
│ │
│ 2. Verify ClientHello │
│ • Check all signatures │
│ • Validate timestamp │
│ │
│ 3. Compute partial SS: │
│ • X25519 DH │
│ • Decapsulate Kyber │
│ │
│ ServerHello │
│◀─────────────────────────────────────────────────────────────│
│ ┌─────────────────────────────────────────────────────────┐│
│ │ • Bob's ephemeral X25519 public key ││
│ │ • Kyber ciphertext encapsulated to Alice's key ││
│ │ • Selected cipher (ChaCha20-Poly1305) ││
│ │ • Timestamp + signatures ││
│ └─────────────────────────────────────────────────────────┘│
│ │
│ 4. Verify ServerHello │
│ 5. Compute final shared secret: │
│ SS = HKDF(X25519_DH || Kyber_AB || Kyber_BA) │
│ │
│ 6. Initialize Double Ratchet: │
│ RK_0 = HKDF(SS, "root-key") │
│ CK_alice = HKDF(RK_0, "alice-send") │
│ CK_bob = HKDF(RK_0, "bob-send") │
│ │
│ 7. Exchange confirmation messages │
│◀─────────────────────────────────────────────────────────────│
│─────────────────────────────────────────────────────────────▶│
│ │
│ ═══════ SESSION ESTABLISHED ═══════ │
│ │
SENDER RECEIVER
│ │
│ 1. Plaintext: "Hello, world!" │
│ │
│ 2. Check ratchet: 50 msgs or 24h? │
│ [If yes: generate new ephemeral keys, │
│ perform DH ratchet] │
│ │
│ 3. Derive message key: │
│ (CK_new, MK) = HKDF(CK_old, "message-key") │
│ │
│ 4. Build nonce: │
│ prefix = HKDF(conv_id || device_id) │
│ nonce = prefix || message_counter │
│ │
│ 5. Encrypt (AEAD): │
│ ciphertext = ChaCha20-Poly1305(MK, nonce, │
│ plaintext, header_as_AAD) │
│ │
│ 6. Delete MK immediately │
│ │
│ 7. Build message cell: │
│ ┌───────────────────────────────────────────────────┐ │
│ │ Header: conv_id, device_id, msg_num, timestamp │ │
│ │ Ciphertext + Tag │ │
│ │ Padding (random bytes to fill 16 KB) │ │
│ └───────────────────────────────────────────────────┘ │
│ │
│ 8. Route through mesh (3-5 hops): │
│ ┌────┐ ┌────┐ ┌────┐ ┌────┐ │
│ │Node│────▶│Node│────▶│Node│────▶│Node│ │
│ │ A │ │ B │ │ C │ │ D │ │
│ └────┘ └────┘ └────┘ └────┘ │
│ │ │ │ │ │
│ Each node sees only previous and next hop │
│ │
│─────────────────────────────────────────────────────────────▶│
│ │
│ 9. Receive 16 KB cell │
│ 10. Check replay database │
│ 11. Validate timestamp │
│ 12. Derive message key │
│ 13. Decrypt and verify MAC │
│ 14. Delete MK immediately │
│ 15. Store (conv_id, dev_id, │
│ msg_num) in replay DB │
│ │
│ 16. Plaintext: "Hello, world!" │
│ │
Every network transmission uses identical 16,384-byte cells:
┌────────────────────────────────────────────────────────────────────────┐
│ NETWORK CELL (16,384 bytes) │
├────────────────────────────────────────────────────────────────────────┤
│ │
│ UNENCRYPTED HEADER (per-hop visible): │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ • Protocol version: 1 byte │ │
│ │ • Hop count remaining: 1 byte (decremented each hop) │ │
│ │ • Cell type: 1 byte (MESSAGE / COVER / CONTROL) │ │
│ │ • Routing token: 32 bytes (determines next hop) │ │
│ │ • Cell ID: 16 bytes (unique identifier) │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
│ ENCRYPTED PAYLOAD: │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ • Actual message length: 2 bytes │ │
│ │ • Message content: variable │ │
│ │ • Random padding: fills to 16 KB total │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────┘
Cell Types:
• MESSAGE — Contains actual user message
• COVER — Fake traffic, indistinguishable from real
• CONTROL — Mesh network maintenance
The cover traffic system makes traffic analysis impractical:
| Mode | Behavior | Data Rate |
|---|---|---|
| Idle | Poisson-distributed cover cells, mean 1 cell per 5 minutes | ~4.6 MB/day |
| Active | Cover rate increases to match ±20% of real traffic | Variable |
| Burst Mimicking | Random fake message bursts simulate user typing sessions | Variable |
Cover traffic is cryptographically indistinguishable from real messages—same encryption, same cell size, same routing.
| Adversary Type | Capability | LMP Defense |
|---|---|---|
| Passive Network Observers | ISP/backbone surveillance, recording all traffic | Encryption + mesh routing + cover traffic |
| Active Network Adversaries | MITM, packet injection/modification | Mutual authentication via hybrid signatures |
| Replay Attackers | Re-sending captured messages | Message number tracking + timestamp validation |
| Compromised Relay Nodes | Up to 30% of mesh nodes controlled by adversary | Multi-hop routing, path diversity |
| Mailbox Node Seizure | Adversary captures temporary storage nodes | Encrypted blobs, anonymous recipient tokens |
| Temporary Device Compromise | Physical access for <48 hours | Ratchet refreshes within 50 msgs or 24h |
| Future Quantum Computers | Breaking ECDH/RSA encryption | Hybrid post-quantum cryptography |
| Traffic Analysis | Correlating timing/size patterns | Fixed cells, cover traffic, batching |
| Threat | Why It's Out of Scope |
|---|---|
| Permanently compromised endpoints | If OS/firmware has backdoors, no application-layer protocol can help |
| Hardware keyloggers | Requires physical security, not cryptography |
| Global passive adversary with unlimited compute | Theoretical limit; we make this expensive, not impossible |
| Social engineering | Users voluntarily revealing keys/passwords |
| Rubber-hose cryptanalysis | Physical coercion is outside technical scope |
| Zero-day exploits in the client app | Mitigated by audits and secure coding, not eliminated |
| Denial of service | We aim for resilience, not guaranteed availability |
LMP explicitly prioritizes security over convenience. These are intentional trade-offs:
| Aspect | LMP Choice | Traditional Messengers | Rationale |
|---|---|---|---|
| Latency | 2-8 seconds typically | <1 second | Mesh routing adds hops; security worth the wait |
| Bandwidth | Higher (cover traffic, padding) | Lower | Metadata protection requires traffic obfuscation |
| Battery | Higher | Lower | Cover traffic runs continuously |
| Multi-device | Manual device-as-peer sync | Automatic cloud sync | No server can store your message history |
| Key sizes | Larger (PQ keys ~3KB) | Smaller (~32 bytes) | Post-quantum algorithms require larger keys |
| Handshake complexity | 4+ round trips | 1-2 round trips | Hybrid crypto + mutual authentication |
| User experience | Requires understanding | "Just works" | Target users accept complexity for security |
| Offline delivery | 7 days max (mailbox nodes) | Unlimited (server storage) | No central storage reduces attack surface |
Traditional messengers store your message history on servers, enabling seamless multi-device sync. This creates:
- A single point for legal demands (subpoenas)
- A high-value target for attackers
- Potential for insider abuse
LMP's device-as-peer model means:
- Each device has its own session keys
- Devices sync directly (encrypted, when both online)
- No server ever sees your messages
- Trade-off: offline devices miss messages beyond mailbox duration
- Rust 1.75 or later — Installation instructions
- C compiler — Required for building post-quantum cryptography libraries
- Linux:
gcc(installed via package manager) - macOS: Xcode Command Line Tools (
xcode-select --install) - Windows: Visual Studio Build Tools
- Linux:
# Clone the repository
git clone https://github.com/AaryanBansal-Dev/LMP_Lattice-Mesh-Protocol.git
cd LMP_Lattice-Mesh-Protocol
# Navigate to the core library
cd lmp-core
# Build in release mode (optimized)
cargo build --release
# Run all tests (103 tests)
cargo test
# Run tests with output
cargo test -- --nocapture| Directory | Contents |
|---|---|
lmp-core/ |
Core Rust library implementing the full protocol |
MAIN.md |
Complete protocol specification (normative) |
SECURITY.md |
Security hardening extensions |
GUIDE.md |
Developer guide with usage examples |
CONTEXT.md |
AI-friendly implementation context |
docs/ |
Additional documentation (glossary, examples, overview) |
| Document | Purpose | Audience |
|---|---|---|
| GUIDE.md | Developer-focused guide with architecture overview, usage examples, and quick reference | Developers integrating LMP |
| MAIN.md | Complete normative protocol specification | Protocol implementers, auditors |
| SECURITY.md | Security enhancements, hardening techniques, and responsible disclosure policy | Security researchers, auditors |
| CONTEXT.md | Implementation context for AI assistants and new developers | AI tools, onboarding developers |
| lmp-core/README.md | Library-specific documentation | Rust developers |
| docs/OVERVIEW.md | Getting started primer | New users |
| docs/GLOSSARY.md | Term definitions | Everyone |
| docs/EXAMPLES.md | Worked examples | Developers |
| Component | Status | Tests |
|---|---|---|
| Cryptographic Primitives | ✅ Complete | Unit tested |
| Hybrid Key Exchange (X25519 + Kyber768) | ✅ Complete | ✅ |
| Hybrid Signatures (Ed25519 + Dilithium3) | ✅ Complete | ✅ |
| ChaCha20-Poly1305 AEAD | ✅ Complete | ✅ |
| HKDF-SHA3-256 Key Derivation | ✅ Complete | ✅ |
| Protocol Logic | ✅ Complete | Unit + Integration |
| Handshake Protocol | ✅ Complete | ✅ |
| Double Ratchet | ✅ Complete | ✅ |
| Session Management | ✅ Complete | ✅ |
| Nonce Derivation | ✅ Complete | ✅ |
| Replay Protection | ✅ Complete | ✅ |
| Network Layer | ✅ Complete | Unit tested |
| Fixed 16KB Cells | ✅ Complete | ✅ |
| Message Padding | ✅ Complete | ✅ |
| Multi-hop Routing (structural) | ✅ Complete | ✅ |
| Cover Traffic Generator | ✅ Complete | ✅ |
| Mailbox Node Protocol | ✅ Complete | ✅ |
| Storage | ✅ Complete | Unit tested |
| Protected Memory (mlock, zeroize) | ✅ Complete | ✅ |
| Replay Database (SQLite) | ✅ Complete | ✅ |
| Device/Identity | ✅ Complete | Unit tested |
| Identity Generation | ✅ Complete | ✅ |
| Introduction Tokens | ✅ Complete | ✅ |
| Fingerprints | ✅ Complete | ✅ |
Current Test Status: 103 tests passing ✅
| Feature | Priority | Status |
|---|---|---|
| Full async networking (libp2p/Tokio) | High | 🚧 Planned |
| PAKE for introduction tokens (SPAKE2+) | Medium | 🚧 Planned |
| iOS bindings (Swift FFI) | Medium | 🚧 Planned |
| Android bindings (Kotlin JNI) | Medium | 🚧 Planned |
| WebAssembly (WASM) support | Medium | 🚧 Planned |
| GUI application | Low | 🚧 Planned |
| Formal security audit | Critical | 🚧 Before production |
This implementation is a proof of concept demonstrating the LMP protocol architecture. Before production deployment:
- ✅ Conduct a formal security audit by qualified cryptographers
- ✅ Perform extensive fuzzing of all parsing code
- ✅ Review all cryptographic implementations against known attacks
- ✅ Test in your specific threat model and operational environment
- ✅ Address the known limitations documented in GUIDE.md
- ✅ Implement full async networking for production mesh operations
For responsible disclosure: See SECURITY.md for our security policy.
We welcome contributions from the community! Please follow these guidelines:
-
Read the documentation:
- GUIDE.md — Understand the architecture
- MAIN.md — Understand the protocol specification
- SECURITY.md — Understand security requirements
- CONTRIBUTING.md — Contribution guidelines
-
Check existing issues — Your idea may already be discussed
-
Run the test suite — All 103 tests must pass before submitting
| Area | What's Needed |
|---|---|
| Security Review | Identify vulnerabilities, suggest hardening |
| Testing | Add edge cases, fuzzing, stress tests |
| Documentation | Improve clarity, add examples |
| Platform Support | iOS/Android/WASM bindings |
| Performance | Optimize hot paths, reduce allocations |
| Protocol Extensions | Group messaging, file transfer (maintain security properties!) |
- Follow Rust best practices and idioms
- All public APIs must have documentation
- All cryptographic operations must use constant-time comparisons
- All key material must be securely zeroed after use
- Maintain ≥90% test coverage for new code
Lattice Mesh Protocol is dual-licensed under your choice of:
- MIT License — Permissive, allows commercial use
- Apache License 2.0 — Permissive with patent grant
See LICENSE for full details.
LMP builds upon decades of cryptographic research and the work of many brilliant minds:
| Contribution | Credit |
|---|---|
| Double Ratchet Algorithm | Signal Foundation |
| CRYSTALS-Kyber (ML-KEM) | NIST Post-Quantum Cryptography Standardization |
| CRYSTALS-Dilithium (ML-DSA) | NIST Post-Quantum Cryptography Standardization |
| X25519 / Ed25519 | Daniel J. Bernstein et al. |
| ChaCha20-Poly1305 | Daniel J. Bernstein |
| HKDF | RFC 5869 |
| Rust Cryptography Ecosystem | RustCrypto contributors |
Built with 🦀 Rust for a more private future
When they break the math we use today, we'll still be secure.
📚 Developer Guide • 📋 Specification • 🔒 Security • 🤝 Contributing