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.
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
| Hop | What happens | Relay sees |
|---|---|---|
| 1 | The 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 |
| 2 | The 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 |
| 3 | The phone opens the request, shows the card, and derives the key after the tap. | Nothing |
| 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. | Phone public key, request id, size, time, network address |
| 5 | The relay passes the sealed reply to the waiting socket and forgets both. The approval path writes nothing to storage. | That a reply was delivered |
| 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. | 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
Who sees what
| Who | Root | Store and purpose keys | Secret values | Request content | Metadata | Encrypted phone state |
|---|---|---|---|---|---|---|
| Machine, Open | no | in memory while Open | in memory while Open¹ | its own | its own | no |
| Machine, Locked | no | no | sealed only | its own | its own | no |
| Relay | no | no | no | no | yes² | sealed only |
| Push services Planned | no | no | no | no | request id and expiry³ | no |
| Phone, unlocked | yes | yes | no⁴ | yes | yes | yes |
| Phone, locked | no⁵ | no | no⁴ | yes⁵ | yes | no⁵ |
| Paper card | yes | yes | with the objects⁶ | no | no | with the relay's copy⁶ |
| Attacker with the laptop | no | in memory while Open⁷ | sealed only⁷ | its own | its own | no |
| Attacker with the relay database | no | no | no | no | stored part² | sealed only |
| Attacker with the 24 words | yes | yes | with the objects⁶ | no | no | with the relay's copy⁶ |
- 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.
- 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.
- A push carries only the type, the request id and its expiry; the app fetches and opens the sealed request itself.
- The phone hands out keys; secret values live in sealed files on the machines.
- 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.
- 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.
- 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
Key lifetimes
| Key | Made how | Lives where | How long |
|---|---|---|---|
| Root | From the 24 words (BIP39, then HKDF) | Phone keychain, readable only while the phone is unlocked; a synced backup item | Until the words change |
| Phone identity | derive(root, "phone:identity") | Phone, readable after first unlock | Until the words change |
| Pairing key | Random, on the machine | OS keychain or a 0600 file | Until unpaired |
| One-time key | Random, per request | Machine memory | One request |
| Store key and file keys | derive(root, "secrets:<store-id>"); file keys from the store key | Machine memory | The session: idle allowance, hard stop at 02:00 or 14 h |
| Own-approval key | derive(root, "secret:<file-id>") | Machine memory | One command |
| Volume key | derive(root, "volume:<volume-id>") | Machine memory | While mounted |
| Backup key | derive(root, "backup:<repository-id>") | Machine memory | While the session is Open, for backups |
| State key | derive(root, "state") | Phone | Until the words change |
Source: Keys at a glance · Reply body (allowance and hard stop)
Primitives and libraries
| Primitive | Standard | Where used | Implementation |
|---|---|---|---|
| BIP39 | BIP-0039 | Words 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-SHA256 | RFC 5869 | Root, every derived key, file keys, key checks | |
| HPKE | RFC 9180, X25519 (RFC 7748) | Requests, replies, machine status and messages; the number match | |
| ChaCha20-Poly1305 | RFC 8439 | The AEAD of .sealed files and the state blob | |
| Ed25519 | RFC 8032 | Relay calls, requests, replies, pairing moves | |
| Ed25519 verify, SHA-256 | RFC 8032, FIPS 180-4 | Relay checks signed calls | Relay: WebCrypto (crypto.subtle) on Cloudflare Workers |
| HMAC-SHA256 | RFC 2104 | Paddle webhook signatures; the pairing proof | Relay: 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
- docs/protocol.md at
6e606d1 - Test vectors: Appendix A and
docs/vectors/ - SECURITY.md and Security
- Releases and their
SHA256SUMS