Choosing your key custody: one key file, or a split key
Your break-glass key, identity.key, is generated in your browser during the key ceremony and is the one universal way back into your data. Nobody else holds it: not Cloudflare, and not Maelstrom. So the only real question about it is a custody question, how you keep that single file safe and recoverable over years. This page sets out the two shapes custody can take, one file or a split across several custodians, and helps you pick between them. It is the sibling of choosing your key posture: posture is about what your engine holds, custody is about how you hold the offline key, and the two decisions do not constrain each other.
Both shapes recover the same data with the same key, so this is not a choice about whether you can recover. It is a choice about how many people and places must fail before recovery becomes impossible, weighed against the effort of running more custodians. Whichever you choose, the mechanics run entirely in your browser: the encryption and the split run on your machine, and the encrypted key file never leaves it. Each share is yours to download and hand over, or, if you prefer, to have your own engine email to a custodian; either way Maelstrom receives nothing. For where the key comes from and what else lands in your recovery kit, see the key ceremony and recovery kit.
One key or a split key
Keeping one key file is the simplest custody, and it fits most teams. You take the downloaded identity.key and store it well, in a corporate password manager or on a hardware-encrypted drive with a printed companion. For defence in depth, the console can first encrypt it in your browser. You then store two files apart: the encrypted key file and a random wrapping key, identity.wrapping-key.txt. From console 0.2.7, the console names a file that your browser did not deliver and gives each file a Re-download button. Without that step, there is one file to protect, and anyone who can open its store holds the key.
A split spreads custody across several holders instead. No single custodian can recover alone, and no single lost share ends recovery. The cost is ceremony and coordination: you decide how many shares exist and how many are needed, hand one to each custodian, and record who holds what. The table weighs the two side by side.
| Consideration | One key file | Split key (M of N) |
|---|---|---|
| Operational effort | Lower: one file to store and protect | Higher: you set up N custodians, distribute a share to each, and record the holders |
| Single point of loss | The one stored copy is the single point; losing it with no retained backup ends recovery | No single loss is decisive; up to N minus M shares can be lost and the key still reconstructs |
| Single point of compromise | Whoever can open the store obtains the key | No one custodian can reconstruct alone; it takes a quorum of M |
| Who can recover | Anyone holding the file, plus its wrapping key file if you encrypted it first | Any M of the N custodians together, plus the small encrypted key file |
| Ceremony | Store the downloaded file | Encrypt the key file in the browser, split the wrapping key, and hand a share to each custodian |
Both options leave you holding the same identity.key at the end of recovery, so you can start with one file and move to a split later by re-running the custody step in the console. A split earns its ceremony when no single person and no single vault should be able to end, or to perform, a recovery alone.
How the split works
A break-glass identity’s private half is 96 bytes, an X25519 scalar (32 bytes) followed by a compact 64-byte ML-KEM-1024 seed. Splitting those bytes directly still works mathematically, but it ties the split scheme to whatever size the identity format happens to be, and most Shamir tooling and interoperable formats are built around a fixed short secret rather than a variable one. So the console splits a stand-in instead. In your browser it generates a fresh random 256-bit key, encrypts identity.key under it with AES-256-GCM, and splits only that fixed 32-byte wrapping key.
The step produces separate downloads: the encrypted key file (identity.key.enc), one share file per custodian (downpipe-share-1-of-N.txt and so on), and a plain-text recovery readme (RECOVER-SPLIT.txt) that records the scheme and the offline recovery procedure. The encrypted key file is small, so you store it the way you would a one-key file, in a vault or on an encrypted drive, and the shares go to your custodians. On its own the encrypted file carries no usable key, and one share on its own carries nothing either. Each share file also carries a short public checksum of the wrapping key: it is one-way and reveals nothing usable about the key, and its only job is to let recovery catch a wrong or mistyped share early, before the decryption step.
Every byte is produced in your browser
The wrapping key, the encryption and every share are generated on your machine from the platform random source. The private key, the wrapping key and the encrypted key file are never transmitted; the only thing that can leave, and only when you choose it for a given share, is that one share, which your own engine emails to a custodian you name. Maelstrom holds neither the key, the encrypted file, nor any share, and a share on its own reveals nothing. The encryption is authenticated, so a wrong key or a tampered file makes the later decryption fail rather than return corrupt bytes.
Choosing the threshold
A split has two numbers: N, how many shares exist, and M, the threshold, how many are needed to reconstruct. Any M shares rebuild the key. Up to N minus M shares can be lost, or held by custodians who are unavailable, and recovery still succeeds. Any M minus 1 shares together reveal nothing at all about the key, which is a property of the mathematics rather than a policy. That property is covered in the next section.
The split accepts a threshold of at least 2 (a threshold of 1 would make any single share the whole key) and at most N, with N as large as 255, so the full bound is 2 <= M <= N <= 255. The console caps N at 16 in its picker, because more than a handful of custodians is an operational choice rather than a cryptographic limit; the underlying split allows the rest.
Pick M and N by the failure you most want to prevent. A higher threshold resists collusion, since more custodians must combine to rebuild the key, but it is more fragile to loss. A lower threshold survives more lost or absent shares, but a smaller group can reconstruct. The examples show the two sides of that trade.
| Scheme | Shares you can lose and still recover | Custodians who must combine |
|---|---|---|
| 2 of 3 | up to 1 | any 2 |
| 3 of 5 | up to 2 | any 3 |
| 4 of 7 | up to 3 | any 4 |
| 5 of 9 | up to 4 | any 5 |
What a single share reveals
Below the threshold, a share reveals nothing at all. Each wrapping-key byte is the constant term of a separate polynomial of degree M minus 1 whose other coefficients are drawn from fresh random bytes. With only M minus 1 shares in hand, every possible key stays equally consistent with what you hold, so no amount of computation extracts the key or narrows it. This is why distinct custodians are the whole point: the security comes from the shares being held apart, not from any share being hard to read. A share file is small, a single non-zero index byte and 32 payload bytes, wrapped with public labels (its index, the N and M parameters, and the checksum); only the payload is secret.
Two facts follow from that. A custodian who holds a share holds it wherever they keep it, so a share stored carelessly is exposed there, which is why each share should live apart from the encrypted key file and from the other shares. And the threshold cuts both ways: any M minus 1 custodians learn nothing, but any M of them, working together, reconstruct the key in full. Choose your custodians and your threshold with that in mind, so that no group you would not trust with a recovery can reach M, and no loss you think likely can drop you below it.
What the recovery sheet records
When you record who holds each share, those names and dates are written to the recovery sheet as public metadata, never a share value or a key. The sheet is safe to print and store: it says who to gather for a recovery, not how to perform one without them.
Distributing and recovering
The console produces each share as a separate, clearly labelled download. The most private route, and the recommended default, is to download each share and hand it to its custodian yourself. Keep every share apart from the encrypted key file. If a custodian is remote, you can instead have your own engine email a share to them; that stays no-custody because the encrypted key file is never sent, only the one share, and it needs your outbound email to be set up first, described in sending shares by email below. Store the small encrypted key file the way you would a one-key file, and keep the recovery readme beside it. For a paper copy, print the whole file, because recovery needs its iv line as well as its ciphertext line.
Recovery reverses the split. You gather a quorum of M custodians, rebuild the wrapping key from their shares, decrypt the encrypted key file back to identity.key, and then recover with neither Cloudflare nor Maelstrom in the loop. The reassembly runs in your browser, and on five of the six surfaces that offer it the recovered key stays in the tab and is never handed back as a file, so a split key can drive a restore, a prune, an attended verification, a re-split or an estate import directly without ever producing a file on disk. The path a recovered key follows from there is break-glass offline recovery.
Reconstruction is a console action, and it usually produces no file
The console reassembles a split key in your browser, and it does so in two different ways. In the ordinary case the reassembly is built into the screen you are already on: the break-glass restore, the break-glass prune, the attended verification runner, the re-split ceremony on the Keys screen and the estate import each take a quorum in place, use the key for that one action, and offer no download at all, so the whole break-glass key never becomes a file you then have to look after. The standalone /restore/recover-key screen is the exception, and the only one that hands identity.key back as a download. Reach for it when you need the file, which means the offline reader or a rehearsal.
Nothing is uploaded on either route: the recover-key screen holds no engine client at all, so it cannot reach the network even if asked to. RECOVER-SPLIT.txt still ships beside the shares and states the procedure. As a fallback to the browser, it points to a compatible Shamir-over-GF(256) tool. From console 0.2.7, the readme also states the share format that such a tool must read: the field and its polynomial (0x11b), the x values (1 to N), the layout of the share and checksum lines, and the AES-256-GCM envelope in identity.key.enc. A readme from an earlier console does not state the format. Rehearse whichever route you intend to depend on.
Gather a quorum of custodians
Bring together any M of the N custodians and their share files. Fewer than M cannot rebuild the key, and by design reveal nothing about it.
Take the quorum on the screen that needs it
If you are recovering in the console, open the break-glass restore panel and add the quorum of shares and the encrypted key file there. It rebuilds the wrapping key, decrypts
identity.key.encin the tab, and passes only the per-run key for the run being recovered to your own engine. Because the encryption is authenticated, a wrong or mistyped share fails the decryption rather than returning a corrupt file, so the step is self-checking. The key is never written to disk, which is the point of having split it.Only download the key if the offline reader is the plan
If you are recovering with the offline reader instead, open
/restore/recover-key, reassemble there and downloadidentity.key. You now hold the whole break-glass key as a file, so treat it as key material for as long as it exists: keep it on the machine that will run the reader, and destroy it when the recovery is done. Off-console, a compatible Shamir-over-GF(256) tool plus an AES-256-GCM decrypt can do the same thing. That tool must read the console’s share format.RECOVER-SPLIT.txtstates it from console 0.2.7; a readme from an earlier console does not. Neither route sends your shares or the wrapping key anywhere.
Sending shares by email
Downloading a share and handing it over keeps it off every network, so it stays the most private way to distribute, and the recommended default. When a custodian is remote, the console can email a share to them instead. A browser cannot send email, so the share is sent by your own engine, over your own outbound email on your own domain; Maelstrom is never in the path and receives nothing. Each share has an Email action, but the send works only after you configure your engine’s outbound email. That is the same sending domain your licence and notification emails use. Until you do, the console says so and does not send the share.
The share travels through your engine and your email provider to the custodian’s inbox, where it rests until they move it, so it is exposed along that path in a way a hand-carried download is not. What does not change is the thing that makes the split safe: the encrypted key file is never emailed, so anyone who intercepts an emailed share, or even every emailed share, still cannot decrypt identity.key without that file. Keep the encrypted key file well away from your engine and your inboxes, and give each share to a different custodian. Reserve email for the shares whose exposure you can accept.
Each share is emailed as text in the body of the message, with no attachment. The email names the M-of-N scheme so the custodian understands a single share reveals nothing on its own. The email asks them to save the share offline or in a password manager like Bitwarden, then delete the email so it does not linger. You address each share to one custodian: a real address on a custom domain (a workers.dev address is refused, as is a malformed one), plus an optional custodian name that rides only in the email itself. The engine sends one share per request and records only the scheme counts in its audit log; it never logs or stores the share value or the address.
Before the engine sends a share, it checks that you authenticated recently. A passkey or recovery-code sign-in from the last five minutes passes. After that, and always on an OIDC or SAML session, the console asks you to confirm with your passkey. On a Cloudflare Access session, the Access sign-in must be from the last five minutes.
From console 0.2.7, a send that fails this check says that nothing was sent and tells you what to do next. A reload clears the split from the page, so to email shares after a reload, you split the key again. Shares from two different splits do not work together.
Because the share passes through your engine on its way out, treat a successful send as sent, not as proven recoverable: rehearse a reconstruction from a quorum before you depend on the scheme, the same rehearsal a download-distributed split deserves.
Where this fits
Custody is one of two independent choices about your break-glass key. This page is about how you hold the offline key; choosing your key posture is about what your engine holds alongside it. For where the key and the recovery sheet come from, see the key ceremony and recovery kit. For why no split ever puts the key in Maelstrom’s hands, see the no-custody trust model. For the offline recovery that both a single-file key and a reconstructed key feed into, see break-glass offline recovery.
Last updated .