FerryKey

FerryKey protocol

How FerryKey keeps bookmarks and passwords in sync without our server being able to read them. It’s detailed enough to check our claims, or to write your own client.

Protocol version 2 · Published 17 October 2026 · The endpoint reference and test vectors are on a second page: API reference and test vectors.

Contents

  1. Overview and trust model
  2. Versions and support
  3. Keys
  4. Encrypted blobs (the envelope)
  5. Signatures
  6. Membership log
  7. Syncing a collection
  8. Data formats
  9. Live updates (MQTT)
  10. Writing your own client
  11. Changes

1. Overview and trust model

Actors

Collections

An account’s data is split into collections. Each collection has its own key and its own history. The current collections are:

A collection name is 1 to 32 characters of a-z, 0-9 and -, starting with a letter. The name log is reserved (live updates use it for the membership log). An account has at most 16 collections.

Trust model

We assume the server may be malicious. Clients must verify everything they receive. If they do, the server can’t:

The server can still:

Anyone with your 24 words, or an unlocked device of yours, can read your data. A locked-out device keeps whatever it already downloaded.

What the server sees

SeesNever sees
Account ID (a hash of the root public key)The 24 words or anything derived from them except public keys
Public keys of the root, recovery key and every devicePrivate keys of any device
Device IDs, which collections each device may use, and when devices were added or removedDevice names (encrypted in meta)
Collection names, commit numbers, times, and blob sizes rounded up to 1 KiBBookmarks, URLs, titles, folders, passwords, notes or any other content
When each device last made a request (to the hour), and the network address of each connectionCollection keys (only wrapped copies it can’t open)

The API keeps no IP addresses. For the signup limit it stores a keyed hash of the network (IPv4 /24 or IPv6 /64) and the day.

2. Versions and support

The current protocol version is 2. Every API request names the version it speaks in the X-Fk-Protocol header. The /v1/ in API paths is the path prefix, not the protocol version: protocol 2 uses /v1/ paths. Signed objects also carry their own version (heads have "Version": 2).

Support policy

How you’ll know

Frozen values

Every label string on this page (they all start with ferrykey v1 or ferrykey v2) is frozen. Changing one would change every user’s keys or invalidate every signature, so they never change. The “v1” or “v2” inside a label names that label’s format, not the protocol version. New cryptography would get new labels and a new protocol version.

3. Keys

Recovery secret and words

Derivation

All derivations use HKDF-SHA256 (RFC 5869) with no salt (equivalent to 32 zero bytes) and the label as the info string, in ASCII.

KeyInputInfo labelLength
Account master key (AMK)recovery secretferrykey v1 account master key32
Root signing key seedAMKferrykey v1 account signing key32
Recovery key seedAMKferrykey v1 recovery kem seed64
Reserved, unusedAMKferrykey v1 collection key: + collection name32

Device keys

4. Encrypted blobs (the envelope)

Every piece of collection data on the server is one envelope: a commit’s change, or a snapshot of the whole collection. All integers are big-endian.

offset size  field
0      3     magic "FKE" (46 4b 45)
3      1     version 0x01
4      1     algorithm 0x01
5      4     key epoch (u32)
9      32    salt (random, fresh for every blob)
41     n+16  AES-256-GCM ciphertext of the padded plaintext, then the 16-byte tag

Key and nonce

HKDF-SHA256(ikm = collection key for that epoch, salt = the 32-byte salt, info = "ferrykey v1 envelope message key", length 44). The first 32 bytes are the AES-256 key, the last 12 bytes the GCM nonce. A fresh key and nonce per blob means the usual limit on random GCM nonces doesn’t apply.

Associated data

The AAD binds the blob to where it lives:

"ferrykey v1 envelope aad"    24 bytes, no length prefix
header                         the first 41 bytes of the blob
u32 len(accountID) | accountID
u32 len(collection) | collection
kind                           1 byte: 1 = change, 2 = snapshot (3 is reserved)
seq                            u64

For a change, seq is the commit’s number. For a snapshot, it is the number of the last commit the snapshot includes (0 for an empty collection). The epoch in the header must be the epoch of the key used. Readers must reject a blob whose header epoch isn’t the one they expect.

Padding

Before encryption the plaintext P becomes u32 len(P) | P | zero bytes, padded to a whole number of 1024-byte blocks. So a blob is 41 + 1024 × ceil((4 + len(P)) / 1024) + 16 bytes. The server sees only the padded size. When opening, reject a padded length that isn’t a multiple of 1024 or a length prefix larger than the data.

The plaintext is JSON (see Data formats). The server takes blobs of at most 5 MiB (5,242,880 bytes).

5. Signatures

All signatures are Ed25519 over a byte string. Each kind of signed message starts with its own label, and every variable-length field is length-prefixed, so a signature for one thing can never be read as another.

Notation used below: str(x) is u32 len(x) | x (bytes or UTF-8 text). strs(list) is u32 count followed by str of each item. u32 and u64 are big-endian. Hashes are raw 32 bytes. Labels are encoded with str() here (unlike the envelope AAD).

API requests

str("ferrykey v1 request")
str(method)        "POST"
str(host)          "api.ferrykey.com"
str(pathQuery)     the request path, plus "?query" if there is one, e.g. "/v1/pull"
str(accountID)
str(deviceID)      a device ID, or "root"
u64 timestamp      unix seconds
nonce              16 random bytes, new for every request
SHA-256(body)      of the exact body bytes sent

Sent in headers: X-Fk-Account, X-Fk-Device, X-Fk-Time (decimal), X-Fk-Nonce (32 hex characters) and X-Fk-Signature (128 hex characters). The host is always api.ferrykey.com, whatever address you connect to. The timestamp must be within 5 minutes of the server’s clock. Each nonce can be used once per account (the server remembers it for at least 10 minutes), so never retry a request with the same nonce: sign it again.

Heads (commits)

A head is a device’s signed pointer to one commit. Version 2 heads:

str("ferrykey v2 head")
str(accountID)
str(collection)
u64 seq           this commit's number (the first commit is 1)
entryHash         SHA-256 of the commit's envelope blob
prev              hash of the head at seq-1; 32 zero bytes when seq is 1
u64 logSeq        length of the membership log the device acted under
logHash           hash of that log's last entry
u32 epoch         key epoch of the blob (the log's epoch at logSeq)
str(deviceID)
u64 time          unix seconds, informational

The head hash, used for prev and by snapshot statements, is SHA-256(message | u32 len(sig) | sig), so it covers the signature too.

Every head must also satisfy: Version is 2, and prev is zero exactly when seq is 1. Reject any head with another version.

Snapshot statements

A snapshot is signed by the device (or the recovery words) that uploaded it:

str("ferrykey v2 snapshot")
str(accountID)
str(collection)
u64 seq           the head the snapshot is at (0 for an empty collection)
headHash          hash of the head at seq; zero when seq is 0
blobHash          SHA-256 of the snapshot's envelope blob
u64 logSeq
logHash
u32 epoch
str(signerID)     a device ID, or "root"
u64 time

Membership entries and device proofs

See Membership log for their encodings.

6. Membership log

Each account has one append-only, hash-chained log of signed entries. Replaying it from the first entry gives the account’s current state: its root key, recovery key, collections, member devices, removed devices and current key epoch, plus the current epoch’s wrapped keys. The server replays it too, and refuses requests from non-members. Nobody needs a secret to check it.

Entry fields and signed message

str("ferrykey v1 membership entry")
str(accountID)
u64 seq                 1 for the first entry
prev                    hash of entry seq-1; zero for seq 1
u64 time                unix seconds, informational
str(signer)             "root" or a member's device ID
op                      1 byte: 1 Init, 2 Add, 3 Remove, 4 Epoch, 5 RotateRoot
str(rootPub)            Init, RotateRoot (else empty)
str(recoveryKEM)        Init, RotateRoot (else empty)
device                  0x00 if absent, else 0x01 | str(signPub) | str(kemPub) | strs(collections) | str(proof)
str(deviceID)           Remove (else empty)
u32 epoch               Init/Epoch: the new epoch; Add/RotateRoot: the current one; Remove: 0
strs(collections)       Init, Epoch (else empty)
u32 number of wraps, then for each: str(recipient) | str(collection) | str(ct)

The entry hash is SHA-256(message | u32 len(sig) | sig). The signer signs with the root key (signer root) or its device key.

Device proof. An Add carries the new device’s proof that it holds its signing key: its own signature over str("ferrykey v1 device key proof") | str(accountID) | str(signPub) | str(kemPub) | strs(collections).

Key wraps

A wrap is one 32-byte collection key encrypted to one recipient (a device ID, or recovery for the recovery key) with HPKE base mode, single shot: KEM MLKEM768-X25519, KDF HKDF-SHA256, AEAD AES-256-GCM, empty AAD, and

info = str("ferrykey v1 epoch key wrap") | str(accountID) | u32 epoch | str(collection) | str(recipient)

ct is the encapsulated key (1120 bytes) followed by the ciphertext and tag (48 bytes): exactly 1168 bytes.

Rules for each entry

An entry is valid only if all of these hold. Clients and the server apply the same rules.

OpRulesWraps required
1 InitEpoch 1. Sets root key, recovery key and collections.recovery × every collection
2 AddDevice keys valid, proof valid, its collections a subset of the account’s and of the signer’s. Epoch = current. The device ID is neither a member nor ever removed (IDs are never reused). Refused while a rotation is pending.new device × each of its collections, current epoch
3 RemoveTarget is a current member whose collections are within the signer’s. No wraps. Sets “rotation pending”. If signed by root, also sets the root lock.none
4 EpochEpoch = current + 1. Collections must include every existing one (new ones may be added). Signer’s scope must cover all of them, so only the root or a device holding every collection can rotate. Clears “rotation pending”. If signed by root, clears the root lock.recovery × every collection, plus each member × each of its collections
5 RotateRootRoot only. New root key (one never used before on this account) and new recovery key. Epoch = current. The account ID stays the same. Sets “rotation pending” and the root lock.new recovery key × every collection, current epoch

Root lock. When the words remove a device or replace themselves, only the words may act until they sign an Epoch. This stops a thief’s devices from re-adding each other while the owner removes them.

Server limit: the server also refuses an Add when the account already has 20 devices.

Common flows

While a rotation is pending the server refuses commits (rotation_required), but takes snapshots in the current epoch (the seal). Any write in the old epoch is refused once a new epoch starts.

7. Syncing a collection

Each collection is a numbered chain of commits. Commit n is an envelope (kind 1, seq n) holding a change, plus a version 2 head signed by the device that wrote it. Now and then a device uploads a snapshot: the whole content at some commit, sealed as kind 2 at that seq, with a signed statement. A device catching up starts from the latest snapshot and applies the commits after it.

Writing

  1. Read and verify the log. Pull and verify the collection up to the server’s head.
  2. Merge your local edits with what you pulled (a three-way merge against the last state you synced).
  3. Seal the change at seq = head + 1 in the log’s current epoch. Sign a version 2 head naming the current log length and hash, and prev = hash of the head you pulled.
  4. Post it to /v1/commit. On conflict or log_changed, someone else got in first: pull, merge and try again with a fresh signature.
  5. Our clients upload a snapshot after 32 commits since the last one. Commits and snapshots superseded by a newer snapshot are deleted within about 7 days, so snapshots keep pulls short.

What a client must check when reading

This is what stops a malicious server. Our implementation does all of it.

  1. Log. Replay the whole log from entry 1 with the rules above, and check its account ID is yours. Remember the log length and last-entry hash you last accepted. Refuse a log that is shorter, or whose entry at that position has a different hash (a rollback).
  2. Never write with an old key. If you hold a key for an epoch newer than the log’s current epoch, the log was rolled back: refuse to write.
  3. Head numbers. Refuse a pull whose HeadSeq is below the commit you last synced, or a snapshot below what you already have.
  4. Every head. Version is 2. Account and collection match. Its logSeq must exist in the log with that logHash. The signer must have been a member at that point, allowed this collection, and epoch must be the log’s epoch at that point and the blob’s header epoch. The signature must verify. It must link to the previous head (seq + 1 and prev = previous head hash), and entryHash must equal SHA-256 of the blob.
  5. No going back. Keep a floor: the highest log point named by any head or statement you’ve accepted for this collection, and store it. A later head or statement may not name an earlier point.
  6. Nothing from before the latest rotation. Let R be the log position of the entry that started the current epoch (the Init or the latest Epoch). Commits you apply as data, and snapshot statements, must name a log point at or after R. A snapshot statement from before R by a device that is still a member is the seal of a rotation whose own snapshot hasn’t arrived yet: retry shortly.
  7. A removed device’s data needs a voucher. For a device removed after R (its rotation is still pending), don’t apply a change it signed, a snapshot it signed, or a snapshot reached by skipping heads it signed, unless that snapshot’s statement names a log point at or after its Remove (the seal). Its heads name a log point from before its removal either way, so they can’t show when it signed them. Retry shortly instead: the seal or the rotation is on its way. Only the device that signed the Remove, while it seals or rotates, and root take such data, because they are about to vouch for it. A device that removed itself is exempt. Anything of the removed device’s after a seal names an earlier log point than the floor, so it is tampering.
  8. Snapshot statements. Every snapshot must have one: reject a snapshot without it. Account, collection, seq, head hash (of the snapshot’s anchor head) and blob hash must match. The signer must have been a member allowed this collection at the named point, or be root (checked against the root key at that point). Epochs must match as for heads.
  9. No gaps across a snapshot jump. When you trust head T and the server sends a snapshot at S > T, it first sends the signed heads T+1 to S−1. Check they link from T to the snapshot’s anchor head. If you trust a head at S already, the anchor must be identical to it (otherwise the server is showing you a fork). On a device’s first sync, ask for no skipped heads. The anchor head and the snapshot statement are still verified in full; there is just nothing earlier to link them to (trust on first use).
  10. Pull structure. Commits must be contiguous, starting right after what you have, and each commit’s Head.Seq must equal its Seq. When a snapshot comes, Commits[0] must be its anchor, at exactly the snapshot’s seq (except for a snapshot at seq 0). Skipped heads with no snapshot after them in a response whose More is false mean tampering. When a pull ends, the last head you verified must be the head of the last commit you applied.
  11. Decrypt with the exact location. Open each blob with your account ID, the collection, the right kind, the commit or snapshot seq and the header’s epoch. Any failure means tampering.
  12. Validate the content. Apply each change and check the result is a valid document (see Data formats). Refuse anything invalid.

Rotation in progress. A rotation appends the Epoch entry first and uploads the new snapshots after it. So if the newest log entry is an Epoch and a collection has no snapshot in that epoch yet, a rotation is probably still running. Don’t apply a change whose head names a log point before the latest Epoch; retry shortly instead of reporting tampering. If the rotating device stopped before uploading, any device that holds the collection’s new key may finish it: when its newest data is still in an older epoch and it hasn’t seen a snapshot in the current one, it uploads a snapshot of what it has. Our clients do both.

Save, per collection: the synced content, its seq, the last trusted head, the keys you’ve unwrapped (by epoch, so older blobs still open), the floor, and the log length and hash.

8. Data formats

Envelope plaintexts are UTF-8 JSON. A commit holds a change. A snapshot holds the whole document.

Bookmarks (bookmarks)

A tree of nodes. Every node has a random sync ID (ours are 10 random bytes in upper-case base32, 16 characters; treat IDs as opaque strings). Four fixed root folders always exist and can’t be moved, renamed or deleted: toolbar, menu (Firefox’s bookmarks menu; others keep it untouched), other and mobile. Kinds: 1 folder, 2 bookmark, 3 separator. A folder’s child list is its order.

Snapshot (whole tree), with nodes sorted by ID:

{"nodes":[
  {"id":"K5QX3M2PZ7RTA4BC","k":1,"t":"Reading","c":["M3VQ7Z2KD6LWE5PA"]},
  {"id":"M3VQ7Z2KD6LWE5PA","k":2,"t":"Example","u":"https://example.com/"},
  {"id":"menu","k":1},{"id":"mobile","k":1},{"id":"other","k":1},
  {"id":"toolbar","k":1,"c":["K5QX3M2PZ7RTA4BC"]}],
 "tombs":{"Q2L7...":{"Fingerprint":[97,123,...],"DeletedAt":1790000000000}}}

id, k kind, t title, u URL (bookmarks only), c child IDs (folders only). A valid tree has all four roots as folders, every other node reachable from a root exactly once, a URL on every bookmark and on nothing else, and children only on folders.

Tombstones remember deletions, so a device that missed one (or a browser’s own sync putting a bookmark back) doesn’t upload it again. Fingerprint is SHA-256 of one kind byte followed by the URL (bookmarks) or the title (folders and separators), as a JSON array of 32 numbers. DeletedAt is unix milliseconds. An unknown browser bookmark matching a tombstone deleted at or after the bookmark’s own creation time is a stale copy, and is removed rather than uploaded.

Change (one commit). Note the field names inside add and update are long:

{"add":[{"ID":"K5QX3M2PZ7RTA4BC","Kind":1,"Title":"Reading","URL":"","Children":null},
        {"ID":"M3VQ7Z2KD6LWE5PA","Kind":2,"Title":"Example","URL":"https://example.com/","Children":null}],
 "children":{"K5QX3M2PZ7RTA4BC":["M3VQ7Z2KD6LWE5PA"],"toolbar":["K5QX3M2PZ7RTA4BC"]}}

{"children":{"K5QX3M2PZ7RTA4BC":[]},
 "delete":["M3VQ7Z2KD6LWE5PA"],
 "tombs":{"M3VQ7Z2KD6LWE5PA":{"Fingerprint":[97,123,163,...],"DeletedAt":1790000000000}}}

Fields, all optional: add (new nodes, without children), update (new title and URL for existing nodes), children (the full new child list of every folder whose children changed), delete (every removed node, subtrees included), tombs (tombstones added or changed) and untomb (tombstones dropped). Roots may not be added, updated or deleted.

Apply a change in exactly this order, or devices will diverge: (1) add, (2) update, (3) delete, (4) children, folder by folder in sorted folder-ID order, (5) remove references to deleted nodes from every folder’s child list, (6) tombs, (7) untomb. Then validate the whole tree, and refuse the change if anything fails.

Merging. Our merge is deterministic so devices converge: a change on one side only is kept; if both sides changed the same field, the side already on the server wins; an edit or move beats a delete; the side that reordered a folder wins its order; a move that would make a cycle is undone; tombstones from all sides are kept except for nodes that survived. Your client may merge differently, but it must always produce a valid tree.

Device names (meta)

The same tree format. Each device adds a bookmark node under other whose ID is its device ID, whose title is its display name and whose URL is ferrykey:device. A device without one shows as “Unnamed device”.

Passwords (vault)

The whole document is encrypted. The server sees nothing inside it, only the padded blob size, which roughly reveals how many items are stored. Document:

{"items":{"q3k7m2xz5p4wb6tn5rcy2hjd":{"type":"login","title":"Example","user":"alex",
   "pass":"correct horse","urls":["https://example.com/login"],
   "created":1790000000000,"mod":1790000000000}},
 "folders":{"imported":{"name":"Imported","mod":0}}}
Item fieldMeaning
typelogin, note, card, identity or sshkey
ffolder ID; absent means imported
title, user, pass, notestext
urls, tagslists of text
totpan otpauth:// URI
fieldscustom fields: {"name","value","concealed","section"}
favfavourite (true or absent)
srcwhere the item came from, e.g. import:chrome; display only
created, mod, trashunix milliseconds; mod is set by the device that changed the item; trash absent or 0 means not in the trash

A folder is {"name","mod","trash"}. The folder imported (named “Imported” until renamed) always exists and can’t be deleted. Item and folder IDs are 1 to 64 characters of a-z, 0-9, - and _ (ours are 24 random base32 characters). Limits: 50,000 items and 1,000 folders. An item put by a change may be at most 256 KiB as JSON (checked when a change is applied, not when a snapshot is loaded).

Change: {"put":{id: item}, "del":[ids], "folders":{id: folder}, "delFolders":[ids]}, all optional. Items and folders are always replaced whole. Apply del, then put, then delFolders, then folders, then check the limits. Merging is per item and per field: the side with the newer mod wins, and for content the losing version is kept as a conflict copy, so no password is lost. An edit beats a delete.

Only devices whose collections include vault hold its key. An account created by a browser extension has no vault collection until a device with the words adds one with an Epoch entry.

9. Live updates (MQTT)

Live updates are only a doorbell. A notice tells a device to sync; it carries nothing to trust.

  1. A member device gets a token from /v1/push-token: {"URL":"wss://mqtt.ferrykey.com/","Token":"…","Filter":"fk/<topic>/+","Expires":unix seconds}. Tokens last 30 minutes.
  2. Connect with MQTT 3.1.1 (MQTT 5 also works) over a secure WebSocket to that URL, with the WebSocket subprotocol mqtt. Send the token as the MQTT user name. The password is ignored. Use a clean session and no will (connections with a will are refused). Keep-alive is at most 300 seconds (0 is raised to 300). Packets are at most 4096 bytes.
  3. Subscribe at QoS 0 to the filter, or to fk/<topic>/<collection>. Nothing else is allowed, and clients may never publish.
  4. Fetch a new token before Expires and reconnect. The token is checked again on every delivery, so an expired connection simply stops receiving.

Messages are retained (the latest per topic, kept in memory only), on topic fk/<topic>/<collection>, with payload {"c":"bookmarks","s":42}: the collection and its new commit number. Collection log means the membership log changed (for example a lock-out); s is then the log length.

What a message reveals: that a collection of one account changed, and its new number. The topic ID is a keyed hash of the account ID made with a server secret, so topics can’t be linked to accounts by others. Tokens are bearer tokens: treat them as secrets until they expire.

Push can be missed (restarts, sleeping devices). Clients must also poll.

10. Writing your own client

You may use your own software to sync your own account, for personal use, under the same terms and limits as our apps. We don’t offer support for it, and you’re responsible for keeping your keys and data safe in it. Protocol changes are handled as described in Versions and support.

Musts

Be nice

Accounts unused by any device for 12 months are deleted. There is no email to warn you, so use your account now and then.

Changes

DateChange
18 October 2026Lock-out seal: the remover snapshots every collection the removed device could write right after the Remove (the server now takes current-epoch snapshots while a rotation is pending), and clients refuse a removed device’s data that no seal or rotation snapshot vouches for. Closes the window between a removal and its rotation. A lock-out without a seal (older apps) is sealed by the locking-out device once it updates. No wire format change; no new version.
17 October 2026This specification published.
16 October 2026Additive: /v1/log responses gained Seen (when each device was last active, to the hour). No new version.
14 October 2026Protocol 2: version 2 heads, signed snapshot statements, skipped heads in pulls, and the X-Fk-Protocol header. Protocol 1 retired the same day under the security exception (log rollback, old-key data and dropped commits).