Cryptography and E2EE Protocol
Relevant source files
The following files were used as context for generating this wiki page:The Sovereign Communications (SC) platform is built on a foundation of strong, modern cryptography to provide end-to-end encryption (E2EE), message authenticity, and forward secrecy for all communications over its decentralized mesh network. The cryptographic layer ensures that messages are secure and verifiable without reliance on any central servers, which is a core tenet of the project.
The protocol uses a combination of industry-standard, audited cryptographic libraries to handle identity management, digital signatures, key exchange, and symmetric encryption. This ensures that all data transmitted between peers is confidential, cannot be tampered with, and originates from a verified sender. The design prioritizes security and privacy, as detailed in the project's Security Model.
Sources: README.md, IMPLEMENTATION_SUMMARY.md, SECURITY.md
Cryptographic Stack
The core of the platform's security relies on a carefully selected stack of cryptographic primitives. These are implemented in the @sc/core library and are used consistently across all client platforms (Web, Android, iOS). The implementation exclusively uses audited libraries like @noble/curves and @noble/ciphers to avoid custom cryptographic implementations, a critical security best practice.
Sources: IMPLEMENTATION_SUMMARY.md, CONTRIBUTING.md, SECURITY.md
This diagram shows the high-level components of the cryptographic stack.
Sources: README.md, SECURITY.md
Core Primitives
The following table summarizes the main algorithms and their purpose within the SC protocol.
| Algorithm | Purpose | Details | Library |
|---|---|---|---|
| Ed25519 | Digital Signatures & Identity | Used for creating a user's identity keypair and for signing every message to ensure authenticity and integrity. | @noble/curves |
| X25519 | Key Exchange (ECDH) | Used to establish a shared secret between two peers, which is then used to derive symmetric encryption keys. | @noble/curves |
| XChaCha20-Poly1305 | Authenticated Encryption (AEAD) | The symmetric cipher used to encrypt message content. It provides confidentiality and integrity for the message payload. | @noble/ciphers |
| SHA-256 | Hashing | Used for generating key fingerprints for out-of-band verification and for creating message hashes for deduplication in the mesh network. | @noble/hashes |
Sources: IMPLEMENTATION_SUMMARY.md, README.md, core/package.json
Identity Management
A user's identity is a cryptographic keypair generated using the Ed25519 algorithm. This identity is fundamental to the system, as the public key serves as the user's permanent address or "Sender ID" within the mesh network.
generateIdentity(): A core function that creates a new Ed25519 keypair.- Public Key: A 32-byte value that uniquely identifies a user. It is included in the header of every message.
- Private Key: A secret key used to sign all outgoing messages.
The identity is intended to be persisted on the user's device in secure storage, such as IndexedDB on the web or the platform-specific Keystore on mobile.
Sources: IMPLEMENTATION_SUMMARY.md, V1_READINESS.md, tests/integration/crypto-protocol.integration.test.ts:8-12
Message Authentication Flow
To ensure message authenticity and integrity, every message sent across the network is digitally signed. The signature proves that the message was sent by the holder of the private key corresponding to the senderId in the message header and that the message content has not been altered in transit.
The signing process is unique: the signature is calculated over the entire encoded binary message, with the signature field in the header temporarily zeroed out. This ensures that all parts of the message, including header fields like ttl and timestamp, are protected from tampering.
Sources: tests/integration/crypto-protocol.integration.test.ts:27-33
Signing a Message
This sequence diagram illustrates the steps a sender's device takes to sign and encode a message.
Verifying a Message
A receiver performs the reverse process to verify a message's authenticity. Any modification to the message bytes during transit will cause the signature verification to fail.
This flowchart shows the verification logic.
The integration test crypto-protocol.integration.test.ts provides a clear implementation reference for this flow, including a test case that confirms tampered messages are correctly rejected.
Sources: tests/integration/crypto-protocol.integration.test.ts:70-103
End-to-End Encryption
In addition to authentication, the protocol provides confidentiality through end-to-end encryption. The payload of every message is encrypted using the XChaCha20-Poly1305 AEAD cipher.
Key aspects of the E2EE implementation include:
- Session Keys: Encryption uses ephemeral session keys, which are automatically rotated to provide Perfect Forward Secrecy (PFS). This ensures that if a long-term identity key is ever compromised, past conversations remain secure.
- Key Exchange: Session keys are established using the X25519 (ECDH) key exchange protocol.
- Double Ratchet: The system uses a Double Ratchet algorithm, similar to the Signal Protocol, for managing session keys. This provides both forward secrecy and future secrecy (break-in recovery).
The functions encryptMessage and decryptMessage are used to handle the symmetric encryption of the message payload.
Sources: README.md, SECURITY.md, IMPLEMENTATION_SUMMARY.md
Protocol Integration
The cryptographic functions are tightly integrated with the binary message protocol. The message header is a fixed 109-byte structure that includes all necessary cryptographic information.
| Header Field | Size (bytes) | Description |
|---|---|---|
version | 1 | Protocol version. |
type | 1 | The type of message (e.g., TEXT, FILE_CHUNK). |
ttl | 1 | Time-to-live for routing in the mesh. |
timestamp | 8 | Unix timestamp in milliseconds. |
senderId | 32 | The sender's 32-byte Ed25519 public key. |
signature | 65 | A 65-byte compact Ed25519 signature of the encoded message. |
The payload, which follows the header, contains the symmetrically encrypted content.
Sources: README.md, IMPLEMENTATION_SUMMARY.md, tests/integration/crypto-protocol.integration.test.ts:18-26
Summary
The cryptography and E2EE protocol in Sovereign Communications provides a robust, multi-layered security model for decentralized communication. By combining strong, audited cryptographic primitives for identity, authentication, and encryption, the system ensures that user messages are private and secure. The protocol's design, particularly the method of signing the entire encoded message and the use of a Double Ratchet for session key management, demonstrates a deep commitment to security and privacy as a foundational principle of the project.
Sources: SECURITY.md, README.md