Cryptographic design

Every key from 24 words. Only the phone holds the root.

Every key comes from 24 words. The phone holds the root and derives a key per object. A machine gets a key only after the phone approves, sealed so that only that machine's one-time key opens it. The relay carries sealed messages and sees no keys.

Describes protocol version 1 at revision 6e606d1, for the phone version of sealctl (0.7, in development). The current release, 0.5.0, uses a Ledger and a different derivation: derived-keys.md. Items the protocol marks as planned carry a Planned pill.

Derivation tree

derive(root, label) is HKDF-SHA256 of the root with "sealctl/v1/" and the label. Keys in sealing-wax colour open data; keys in ink sign or identify.

Derivation tree: every key from the 24 words The 24 words give the BIP39 seed, and the seed gives the root with HKDF-SHA256. From the root, derive(root, label) gives one key per purpose: phone identity (phone:identity), phone box key (phone:box), store key (secrets:<store-id>), own-approval key (secret:<file-id>), volume key (volume:<volume-id>), backup key (backup:<repository-id>), state key (state) and the words fingerprint (fingerprint). Under the store key, each file key is HKDF of the store key with sealctl/v1/file:<file-id>, computed on the machine. Separately, the machine's pairing key, machine box key and per-request one-time key are random and made on the machine; they never come from the words. 24 words BIP39 English, on paper seed computed, then wiped root on the phone only PBKDF2 (BIP39) HKDF "sealctl/v1/root" derive(root, "phone:identity") Phone identity · Ed25519, signs replies and calls derive(root, "phone:box") Phone box key · X25519, opens requests to the phone derive(root, "secrets:<store-id>") Store key · opens the secret store HKDF(store key, "sealctl/v1/file:<file-id>") File key · one .sealed file, computed on the machine derive(root, "secret:<file-id>") Own-approval key · one --own-approval secret derive(root, "volume:<volume-id>") Volume key · the volume passphrase derive(root, "backup:<repository-id>") Backup key · the restic password derive(root, "state") State key · seals the phone's backup on the relay derive(root, "fingerprint") Words fingerprint · 4 characters, not secret random, made on the machine Pairing key Ed25519, signs requests Machine box key X25519, opens phone messages One-time key X25519, one per request Derivation tree: every key from the 24 words The 24 words give the BIP39 seed, and the seed gives the root with HKDF-SHA256. From the root, derive(root, label) gives one key per purpose: phone identity (phone:identity), phone box key (phone:box), store key (secrets:<store-id>), own-approval key (secret:<file-id>), volume key (volume:<volume-id>), backup key (backup:<repository-id>), state key (state) and the words fingerprint (fingerprint). Under the store key, each file key is HKDF of the store key with sealctl/v1/file:<file-id>, computed on the machine. Separately, the machine's pairing key, machine box key and per-request one-time key are random and made on the machine; they never come from the words. 24 words BIP39, on paper PBKDF2 (BIP39) seed computed, then wiped HKDF "sealctl/v1/root" root on the phone only derive(root, label): "phone:identity" Phone identity "phone:box" Phone box key "secrets:<store-id>" Store key HKDF(store key, "sealctl/v1/file: <file-id>") File key "secret:<file-id>" Own-approval key "volume:<volume-id>" Volume key "backup:<repository-id>" Backup key "state" State key "fingerprint" Words fingerprint random, made on the machine Pairing key Ed25519, signs requests Machine box key X25519, opens phone messages One-time key X25519, one per request

The id is generated and read from the object itself; no hostnames, users or labels enter the derivation. An encrypted object plus the 24 words is enough to open it.

Source: Derivation and test vectors · Keys at a glance · Store format · Pairing QR code and proof

One approval, as a sequence

One approval as a sequence: machine, relay, push services (planned) and phone 1. The machine makes a one-time key, signs the request with its pairing key, seals it with HPKE to the phone's box key, signs the relay call and opens a WebSocket wait. The relay sees the machine key, request id, sealed size, time and network address, not which key or command. 2. The relay checks the signature and pairing, holds the sealed request in memory and tells the phone over its socket; push through APNs and FCM is planned and carries only type, id and expiry. 3. The phone opens the request, shows the card, and derives the key after the tap; the relay sees nothing of this. 4. The phone seals the key with HPKE to the machine's one-time key, signs the reply with its identity key and posts it; the relay sees the phone key, request id, size, time and network address, not the key. 5. The relay passes the sealed reply to the waiting socket and forgets both. 6. The machine checks the phone's signature, opens the reply with its one-time key, wipes the one-time key and keeps the key in memory. Machine Relay Push services Phone planned Relay sees: nothing yet. one-time key; sign; HPKE-seal to the phone box key 1 Relay sees: machine key, request id, sealed size, time, network address. Not which key or command. wait socket: {id, sealed} 1 Relay holds the sealed request in memory only. Push carries only type, id and expiry (planned). phone socket: {id, machine, sealed} 2 Relay sees: nothing. Opening and deriving happen on the phone. open request; show card; you tap Allow; derive key 3 Relay sees: phone key, request id, sealed reply size, time, network address. Not the key. reply sealed to one-time key, signed 4 Relay passes the reply on and forgets both; the approval path writes nothing to storage. reply on the wait socket 5 Relay sees: nothing. check signature; open with one-time key; key in memory 6 One approval as a sequence: machine, relay, push services (planned) and phone 1. The machine makes a one-time key, signs the request with its pairing key, seals it with HPKE to the phone's box key, signs the relay call and opens a WebSocket wait. The relay sees the machine key, request id, sealed size, time and network address, not which key or command. 2. The relay checks the signature and pairing, holds the sealed request in memory and tells the phone over its socket; push through APNs and FCM is planned and carries only type, id and expiry. 3. The phone opens the request, shows the card, and derives the key after the tap; the relay sees nothing of this. 4. The phone seals the key with HPKE to the machine's one-time key, signs the reply with its identity key and posts it; the relay sees the phone key, request id, size, time and network address, not the key. 5. The relay passes the sealed reply to the waiting socket and forgets both. 6. The machine checks the phone's signature, opens the reply with its one-time key, wipes the one-time key and keeps the key in memory. 1 Machine → Relay Makes a one-time key, signs with its pairing key, seals to the phone box key (HPKE), opens a signed wait socket. Relay sees: machine key, id, size, time, network address. 2 Relay → Phone Checks signature and pairing, holds the sealed request in memory, tells the phone's socket. Push: planned. Relay never sees which key or which command. 3 On the phone Opens the request, shows the card; after your tap derives the key. Relay sees: nothing. 4 Phone → Relay Seals the key to the one-time key (HPKE), signs the reply with its identity key, posts. Relay sees: phone key, id, size, time. Not the key. 5 Relay → Machine Passes the sealed reply to the waiting socket, then forgets both. Nothing is written to storage on this path. 6 On the machine Checks the phone's signature, opens with the one-time key, wipes it, keeps the key in memory for the session. Relay sees: nothing.
The six hops of one approval and what the relay sees at each
HopWhat happensRelay sees
1The machine makes a one-time key, signs the request with its pairing key and seals it with HPKE to the phone's box key; signs the relay call; opens a WebSocket wait.Machine public key, request id, size, time, network address
2The relay checks the signature and the pairing, holds the sealed request in memory, and tells the phone over its socket. Push through APNs and FCM Planned carries only the type, the request id and its expiry.Which phone it goes to; the sealed string
3The phone opens the request, shows the card, and derives the key after the tap.Nothing
4The phone seals the key with HPKE to the machine's one-time key, signs the reply with its identity key, and posts it.Phone public key, request id, size, time, network address
5The relay passes the sealed reply to the waiting socket and forgets both. The approval path writes nothing to storage.That a reply was delivered
6The machine checks the phone's signature, opens the reply with its one-time key, wipes the one-time key, and keeps the key in memory.Nothing

Because the one-time key lives only in memory until the reply arrives, a machine stolen later cannot open a reply someone recorded. The relay never sees the request content or the key.

Source: Request and reply encryption · Relay API → Requests and replies · Push (planned)

What the relay sees

The relay routes sealed strings by public key. Everything that says what is being done sits inside HPKE ciphertext sealed to the phone's box key or to a one-time key.

The network address is used in memory while serving a call. Comparing the phone's and the machine's addresses, as keyed hashes, gives the near flag Planned; no address is stored.

The phone's backup on the relay is sealed with the state key, which comes from the root.

Source: Request and reply encryption · State blob · Requests and replies · Privacy: the relay

What the relay sees and what it never sees Outside the seal the relay sees machine public keys, the phone's public key, machine names from pairing, request ids, sizes and times, and the network address while serving a call. Inside the HPKE ciphertext, which it cannot open, are which key is asked for, the key values, the command, the working directory, the agent and the repository. Relay sees (outside) machine keys phone key machine names request ids sizes, times IP address Inside the seal: HPKE which the relay can't open which key key values the command working dir agent repository

Who sees what

Who can read each kind of material
WhoRootStore and purpose keysSecret valuesRequest contentMetadataEncrypted phone state
Machine, Opennoin memory while Openin memory while Open¹its ownits ownno
Machine, Lockednonosealed onlyits ownits ownno
Relaynonononoyes²sealed only
Push services Plannednonononorequest id and expiry³no
Phone, unlockedyesyesno⁴yesyesyes
Phone, lockedno⁵nono⁴yes⁵yesno⁵
Paper cardyesyeswith the objects⁶nonowith the relay's copy⁶
Attacker with the laptopnoin memory while Open⁷sealed only⁷its ownits ownno
Attacker with the relay databasenonononostored part²sealed only
Attacker with the 24 wordsyesyeswith the objects⁶nonowith the relay's copy⁶
  1. A value is opened when a command uses it and goes into that command's environment; the store key stays in memory for the session.
  2. Public keys, machine names, OS and model, when each machine last called, request ids, sizes and times. The network address only in memory while serving a call; it is not stored.
  3. A push carries only the type, the request id and its expiry; the app fetches and opens the sealed request itself.
  4. The phone hands out keys; secret values live in sealed files on the machines.
  5. The root is readable only while the phone is unlocked. The phone keys are readable after the first unlock, so a locked phone can open a request to show it on the lock screen, but they cannot make any derived key. App spec, key storage.
  6. The words open an object when they have the object: a sealed file, a volume, a repository, or the phone's state blob from the relay.
  7. Locked or powered off, the laptop holds only sealed files. During an open session, past the screen lock, keys in memory are usable.

Confirmation levels

The level of asking says when the phone is asked; the confirmation level says how hard the approval is. The phone computes the level and applies the higher of its own and the machine's; a machine can raise its level, never lower it.

Levels don't change which keys a machine can get. They make deliberate the steps that remove sealctl's protection or are hard to undo.

The number match: the terminal shows a two-digit number exported from the request's HPKE context; the phone offers three. A wrong pick holds that machine's sensitive requests for an hour. The relay holds a delayed approval for its hour Planned.

Source: Confirmation levels · Number match · Delayed approvals

Confirmation levels 1 to 3 Level 1, Routine: sealctl run, SSH signing, opening a volume; one tap, or automatic at a trusted place. Level 2, Sensitive: pairing a machine, unseal of one object, sealctl seal of an existing object, rewrap; biometrics every time with no passcode fallback, the exact objects listed, and the phone near the machine. Level 3, Leaving: unseal --all, Leave sealctl, showing the 24 words, deleting the phone's relay data; everything in level 2 plus the number match, a signed plan, a one-hour delay away from a trusted place, and a report. 1 · Routine sealctl run, SSH signing, opening a volume One tap; Automatic at a trusted place 2 · Sensitive Pairing, unseal <object>, seal of an existing object, rewrap Biometrics every time, no passcode; objects listed; phone near the machine 3 · Leaving unseal --all, Leave sealctl, showing the words, deleting the phone's relay data Level 2 plus number match, signed plan, 1 h delay away from a trusted place, report

Key lifetimes

Each key, how it is made, where it lives and for how long
KeyMade howLives whereHow long
RootFrom the 24 words (BIP39, then HKDF)Phone keychain, readable only while the phone is unlocked; a synced backup itemUntil the words change
Phone identityderive(root, "phone:identity")Phone, readable after first unlockUntil the words change
Pairing keyRandom, on the machineOS keychain or a 0600 fileUntil unpaired
One-time keyRandom, per requestMachine memoryOne request
Store key and file keysderive(root, "secrets:<store-id>"); file keys from the store keyMachine memoryThe session: idle allowance, hard stop at 02:00 or 14 h
Own-approval keyderive(root, "secret:<file-id>")Machine memoryOne command
Volume keyderive(root, "volume:<volume-id>")Machine memoryWhile mounted
Backup keyderive(root, "backup:<repository-id>")Machine memoryWhile the session is Open, for backups
State keyderive(root, "state")PhoneUntil the words change
When the store key exists in machine memory over one workday Locked until 09:00. One tap at 09:00 opens the session and the store key is in machine memory from 09:00 to 14:00. Leaving for lunch at 14:00 locks it. Back at the desk at 15:00 it reopens by itself and stays until going home at 19:00, which locks it. The 02:00 hard stop resets the credit. Store key in machine memory Open Open 06 09 12 15 18 21 00 03 02:00 09:00 one tap · 14:00 lunch locks 15:00 reopens · 19:00 home locks 02:00 hard stop resets credit
One workday from How it works.

Source: Keys at a glance · Reply body (allowance and hard stop)

Primitives and libraries

Cryptographic primitives, their standards, where they are used and which implementation provides them
PrimitiveStandardWhere usedImplementation
BIP39BIP-0039Words to seed (PBKDF2-HMAC-SHA512, empty passphrase)Rust core sealctl-core, shared by the CLI and both apps Planned. Crates and versions are listed here from its Cargo.lock when it ships.
HKDF-SHA256RFC 5869Root, every derived key, file keys, key checks
HPKERFC 9180, X25519 (RFC 7748)Requests, replies, machine status and messages; the number match
ChaCha20-Poly1305RFC 8439The AEAD of .sealed files and the state blob
Ed25519RFC 8032Relay calls, requests, replies, pairing moves
Ed25519 verify, SHA-256RFC 8032, FIPS 180-4Relay checks signed callsRelay: WebCrypto (crypto.subtle) on Cloudflare Workers
HMAC-SHA256RFC 2104Paddle webhook signatures; the pairing proofRelay: WebCrypto; pairing proof: Rust core

The test vectors in Appendix A were computed by a dependency-free Node.js script (Appendix B) that checks its HKDF and HPKE against Node's own HKDF and RFC 9180's published vectors. The script and the relay signing vectors are in docs/vectors/. Cross-implementation tests against these vectors Planned arrive with the Rust core.

What is deliberately not protected

  • A process given a key can leak it.
  • Malware can use what is open while the session is open.
  • A thief who gets past the screen lock during an open session.
  • A thief with the phone and its passcode.
  • Copies an attacker already took before a change of words.
  • The relay operator can see metadata (which machines ask, when, from which network address) and can withhold or delay messages, but cannot forge a phone's reply or read a key.
  • No independent audit yet.

Where to check