Security Overview

A detailed look at how Freedom Messenger protects your data — from passphrase hashing to message encryption, rate limiting to key rotation.

Authentication

Passphrase Hashing

User passphrases are hashed using Argon2id, the winner of the Password Hashing Competition and the current best practice for password storage. Even if an attacker gains access to the database, the passphrases cannot be reversed.

Two-Factor Authentication

All users must enable TOTP-based two-factor authentication. This uses the same standard as Google Authenticator, Authy, and similar apps. A 6-digit code that changes every 30 seconds is required to log in.

When setting up 2FA, users receive 16-character hex recovery codes. These can be used once each to bypass 2FA if the authenticator app is lost.

Session Management

Sessions use JWT tokens with a 30-day expiration. The JWT signing key is derived from the master secret using HKDF (HMAC-based Key Derivation Function) with a dedicated "jwt" context. This means the signing key is never stored directly — it is derived on each server start.

Encryption

At-Rest Encryption

Message content is encrypted at rest using AES-256-GCM. Each message's unique ID is used as Additional Authenticated Data (AAD), binding the ciphertext to the specific message and preventing message swapping attacks.

The encryption key is derived from the master secret using HKDF with a dedicated "encryption" context.

In-Transit Encryption

All connections use TLS encryption. In HTTPS mode, the server obtains certificates from Let's Encrypt. In Cloudflare mode, Cloudflare provides the TLS termination. In VLESS mode, the REALITY protocol provides TLS that is indistinguishable from legitimate connections.

Key Rotation

The master secret can be rotated without losing access to old messages:

  1. Generate a new secret
  2. Move the old secret to previous_secrets in config.toml
  3. New messages are encrypted with the new key
  4. Old messages are decrypted using the previous key

All derived keys (JWT, encryption, TURN) are automatically regenerated from the new secret.

Privacy

EXIF Stripping

When users upload images, Freedom Messenger automatically strips EXIF metadata — including GPS coordinates, camera model, timestamps, and other identifying information. The image content is preserved, but the metadata is removed.

SSRF Protection

The link preview feature fetches URLs to generate previews. The fetcher includes SSRF (Server-Side Request Forgery) protection to prevent it from accessing internal network resources.

Rate Limiting

Built-in rate limiting protects against brute-force attacks and abuse:

  • Login attempts: 20 per 15 minutes per IP
  • Registration: 10 per 15 minutes per IP
  • TOTP verification: 10 per 5 minutes per IP
  • File uploads: 20 per hour per user
  • Messages: 60 per minute per user
  • Global: 120 requests per minute per IP

Account Lockout

After repeated failed login attempts, the account is temporarily locked. This prevents brute-force password guessing even for accounts with shorter passphrases.

Infrastructure Security

Config File Protection

The server enforces that config.toml has 0600 file permissions (owner read/write only). A warning is issued if the file is more permissive.

Systemd Hardening

On Linux, the systemd service includes security hardening:

  • Memory limit: 512 MB
  • OOM protection
  • Restart throttling: 5 restarts per 5 minutes

What Is Not Included Yet

End-to-end encryption (E2E) is planned for v2.0 using the Signal Protocol. Currently, the server can read messages at rest (they are encrypted with the server's key, not with user keys). If your threat model requires E2E, this is an important limitation to be aware of.

See Transparency for an honest discussion of current limitations.