Skip to main content

End-to-End Encryption

Better Messages supports end-to-end encryption (E2EE) for private conversations, ensuring that only the participants can read the messages. The server never has access to message content — all encryption and decryption happens directly in the users' browsers.

Requirements​

  • WebSocket version — E2E encryption is only available with the WebSocket real-time mechanism (not available in AJAX mode)
  • HTTPS/SSL — the site must have SSL enabled, since the Web Crypto API requires a secure context
  • Modern browser — any browser with Web Crypto API support (all modern browsers including Chrome, Firefox, Safari, Edge)

How it works​

When end-to-end encryption is enabled, each user generates a personal encryption key pair. When a conversation is created, a unique conversation key is generated and securely shared with each participant. Messages are encrypted before leaving the sender's browser and can only be decrypted by the intended recipients.

The server stores only encrypted data — it relays messages between participants but cannot read their content. Even site administrators cannot access the plaintext of encrypted messages.

Key capabilities​

  • Messages encrypted in the browser before transmission — server never sees plaintext
  • AES-256-GCM encryption for message content and file attachments
  • ECDH P-256 key exchange for secure key distribution between participants
  • Password-protected key backup for multi-device access
  • Key recovery if the user forgets their encryption password
  • Automatic key distribution for new conversation participants
  • Key rotation when participants are removed from a conversation
  • Crypto operations offloaded to Web Workers for better performance
  • Mobile app support (iOS and Android)

Setting up encryption​

First-time setup​

When a user first joins an encrypted conversation, they are prompted to create an encryption password. This password is used to protect their private key so it can be recovered on other devices or browsers.

  1. User opens an encrypted conversation
  2. A setup dialog appears asking them to create an encryption password
  3. The system generates a personal key pair and securely backs up the private key (encrypted with the password) on the server
  4. The user can now send and receive encrypted messages

Multi-device access​

When accessing encrypted conversations from a new device or browser:

  1. The user is prompted to enter their encryption password
  2. The encrypted private key backup is downloaded from the server
  3. The private key is decrypted locally using the password
  4. The user can now read and send encrypted messages on the new device

This works the same way on the mobile app — enter the encryption password to restore keys and access encrypted conversations.

Password recovery​

If a user forgets their encryption password:

  1. Click "Forgot password?" in the key restore dialog
  2. Confirm the intent to reset — this generates new encryption keys
  3. Enter a new encryption password
  4. Other participants will automatically re-wrap the conversation key for the user's new identity key when they come online
  5. Once re-wrapped, the user regains access to the conversation and can read previous messages

How encryption works​

Identity keys​

Each user has a personal ECDH P-256 key pair:

  • Public key — shared with other users so they can establish secure key exchanges
  • Private key — never leaves the user's device in unencrypted form; backed up on the server encrypted with the user's password (PBKDF2 with 600,000 iterations)

Conversation keys​

Each encrypted conversation has its own AES-256 symmetric key:

  • A random 256-bit key is generated when the conversation is created
  • This key is wrapped (encrypted) individually for each participant using ECDH shared secrets
  • Each participant unwraps the conversation key using their own private key
  • The conversation key is used to encrypt and decrypt all messages in that conversation

File attachments​

File attachments in encrypted conversations are also encrypted:

  • A unique encryption key is generated for each file
  • The file is encrypted with AES-256-GCM before upload
  • The file key is wrapped with the conversation key (not directly with participant keys)
  • Each participant unwraps the file key using the conversation key, then decrypts the file
  • Decrypted files are cached locally in the browser for performance
  • File metadata (size, type) is visible to the server, but file content is encrypted

Performance​

  • All cryptographic operations (encryption, decryption, key wrapping) are offloaded to a SharedWorker or Web Worker so they don't block the UI
  • Conversation keys are cached in memory after first unwrap for fast encrypt/decrypt

Group conversations​

End-to-end encryption works with group conversations:

  • All participants share the same conversation key
  • When a new participant is added, they are marked as "pending" until they receive the wrapped conversation key
  • Pending users see a notice that they need to set up encryption — they cannot send or read messages until setup is complete
  • Other participants can continue messaging normally while some users are pending
  • Key distribution happens automatically when both the pending user and a participant who holds the key are online
  • When a participant is removed, their wrapped key is deleted and they lose access to future messages

Restrictions​

  • Messages in encrypted conversations cannot be forwarded to other conversations
  • Encrypted conversations bypass the moderation queue — the server cannot read ciphertext, so content moderation is not possible for E2E messages
  • The server rejects unencrypted messages sent to encrypted conversations — all messages must be valid E2E ciphertext
  • AI chat bots are always excluded from encrypted conversations

Security properties​

What is encrypted end-to-end​

  • Message text content
  • File attachment content

What is NOT encrypted end-to-end​

  • Message metadata (sender, timestamp, read status)
  • Conversation participant list
  • User presence and typing indicators
  • Conversation settings
  • File metadata (size, type)

Server limitations​

  • The server relays encrypted messages but cannot decrypt them
  • The server stores encrypted private key backups but cannot access them without the user's password
  • Site administrators can see conversation metadata but not message content

Admin experience​

  • The moderation queue shows "Encrypted message" as a placeholder for E2E message content
  • Admins can see conversation metadata (participants, timestamps, message count) but not the actual content
  • File attachment metadata (count and size) is visible in the admin panel, but file content is encrypted

Mobile app support​

End-to-end encryption is fully supported on the iOS and Android mobile apps:

  • Uses native cryptographic operations
  • Keys are backed up and recoverable across devices using the same password-based recovery as the web version
  • The same encryption password works on both web and mobile

How to enable​

End-to-end encryption settings are located in WP Admin → Better Messages → Settings.

General tab​

  • Enable End-to-End Encryption — main toggle to activate the E2E encryption feature. Requires HTTPS to be enabled on your site.

Messaging tab​

These options appear under the E2E Encryption section and are only available when E2E encryption is enabled in the General tab:

  • Enabled by default — the encryption toggle will be pre-checked when users create new conversations. Users can still uncheck it to create unencrypted conversations.
  • Force for all conversations — all new private conversations will be end-to-end encrypted. Users cannot disable encryption. This option requires "Enabled by default" to be checked.
  • Allow guest users — allow guest chat users to participate in end-to-end encrypted conversations. AI chat bots are always excluded regardless of this setting.