Docs / Explanation

The Security Model

What protects your files, what the servers can see, and what is not claimed.

The threat model assumes the relay is untrusted and attackers may control the network, but not your devices. The design document with the full protocol is Security.md in the repository; this page is the same model in plain words.

What protects your files in transit

The two peers agree on session keys with a hybrid key exchange: ML-KEM-1024, a post-quantum algorithm at NIST's highest security category, combined with X25519, the well-studied classical one. Both must be broken to recover the keys. The idea of the hybrid is simple: even if a future quantum computer breaks the classical half, or a flaw appears in the newer post-quantum half, the other half still stands.

File data then travels under authenticated encryption: AES-256-GCM when both machines have hardware AES support, ChaCha20-Poly1305 otherwise. Authenticated means tampering is detected, not just hidden.

The handshake keys are your identity keys, and the fingerprint you exchange out-of-band is their hash. The handshake proves to each side that the other really owns the registered fingerprint. There is no separate word-list or emoji comparison step: sending the fingerprint over a channel you trust is the verification.

Key rotation during a session

Two mechanisms limit what any single key ever protects:

• A symmetric ratchet rotates the transfer keys continuously: at the latest after 1 GB, about a million messages, or 60 seconds of writing in a direction.
• Right after connecting, and again after every reconnect, the peers run an ephemeral hybrid exchange (fresh ML-KEM-1024 plus X25519) and fold the result into the session keys. This is the construction Apple's iMessage PQ3 and Signal use. After the fold, a later theft of the long-term identity keys does not expose the recorded session.

What the relay can see

The relay stores an encrypted blob under an opaque lookup key. It cannot decrypt the blob, cannot recover the fingerprint from the key, and cannot learn the address a peer advertises for direct connection. The bridge, when used, forwards ciphertext.

What the relay does observe, because it is an HTTP endpoint: the source IP of each request, its size, and its timing. Two addresses using the same lookup key inside a short window let it infer that those two addresses are talking to each other. It cannot name who they are, but the connection graph is visible at that moment.

Protecting identity at rest

Your identity and contacts are stored encrypted (identity.enc, contacts.enc, ChaCha20-Poly1305) under a per-install master key. The key lives in the OS keychain where one exists (macOS Keychain, Windows Credential Manager, Linux Secret Service), in a file with owner-only permissions on headless systems, or, if you enable passphrase_protect, it is derived from your passphrase with Argon2id and never stored.

Incognito mode uses ephemeral keys and writes nothing to disk. The tradeoff: after a disconnect, interrupted downloads cannot resume, because the identity they were tied to is gone. KeibiDrop never regenerates persistent identity files on its own, because that would silently discard your saved contacts.

What we do not claim

Security text that only lists strengths is advertising. The current honest edges:

• The handshake alone is not forward-secret, because it uses the long-term identity keys. Forward secrecy comes from the ratchet and the fold on top of it, which cover the session from the first fold onward.
• The fold runs once per connection, not periodically. If a device is compromised mid-session, key rotation alone does not heal that session.
• Anonymity from the relay operator is not provided, as described above.
• An independent security audit has not been performed yet.

Related reading: What KeibiDrop is not for product-level boundaries, and Files and folders for what is stored where.