Public Access
jaap-jan
6185d74800
Two plans, both for the same class of defect: a control or a code that a user is told to rely on, backed by storage and by nothing else. Neither is started; what follows is the reasoning, so that starting is not where it gets thought about. ── UNLOCKING WITHOUT THE PASSPHRASE ───────────────────────────────────────────────────────────────────── Every account is issued a recovery code at enrollment. The client generates it, wraps the identity bundle under KEK_rc, the server stores that wrap as UserKeyWrapKind.Recovery, and both heads work to make sure the user writes it down — the phone raises FLAG_SECURE for that screen alone and will not let anybody past it. Nothing can use it. SessionOpener has UnlockAsync and UnlockWithDeviceAsync, and there is no third. Walk the failure through: forget the passphrase, and the bundle cannot be unwrapped, so no vault key opens and every item is unreadable. Signing out and back in returns the same passphrase wrap. The device key would be the other door, and sign-out withdraws it — which is the advice the unlock screen gives for exactly this situation. The loss is total and permanent, and the thing built to prevent it is inert. The docs already disagree with each other about this, which is how it surfaced. manual-checks §10.2 calls the code "the only thing standing between a forgotten passphrase and an unrecoverable vault"; android-port says losing it *along with* the passphrase is what makes a vault unrecoverable; README says signing out is the only answer and nothing can recover one. The third is the true one today. More than half the work is already done and one piece of it was done on purpose: LocalCacheKey derives from the identity bundle rather than from MK — crypto.md §3.2, changed 2026-07-30 — specifically so an unlock that never computes MK can still read the cache it wrote. What is missing is an endpoint to serve the wrap, an unlock path, and a way to set a new passphrase afterwards, without which the account unlocks with a one-time code forever. That last step is the same re-wrap a change-passphrase feature needs, so it delivers both. Two traps are recorded because both would produce a code that verifies nowhere. The derivation uses the displayed string *including its dashes*, so the unlock must canonicalise to the printed form rather than strip it; and the recovery wrap uses a different Argon2 profile to the passphrase one (64 MiB against 256), so it must derive from the parameters served with the wrap rather than from a profile constant. ── REACHING A HOST YOU CANNOT DIAL ────────────────────────────────────────────────────────────────────── This started as "delete the dead jump-host field" and inverted twice. HostSecret.JumpHostIds is stored, validated, encoded and three-way merged, and nothing reads it or writes it — the ssh_config importer looks like the writer and is not; it records ProxyJump as an option and a note saying DodoSSH cannot honour it. The first draft recommended deleting it. That was wrong twice over. ADR 0004's last consequence had already designed the implementation — a loopback TCP bridge for the relay, and "the same bridge provides ProxyJump via a SOCKS5 dynamic forward", one mechanism and two features — which the pinned SSH.NET 2025.1.0 supports through ForwardedPortDynamic and ProxyTypes.Socks5, checked in Renci.SshNet.xml rather than remembered. And the stored shape is right: an ordered list of host ids is what a chain is, the merge arm is correct, and the missing schema version is a line to add. ◆ Looking properly found the same shape one field over, where it costs something. RelayEnabled is also stored, merged and never read by the connect path — but it is user-settable, and both heads draw a checkbox promising it. Ticking it moves the host's address and port out of the encrypted payload into plaintext columns, which ADR 0004 calls the single deliberate concession in the design, and then the client dials directly anyway. The privacy is spent and the feature is not delivered. That is a defect rather than a gap, and it is step 0. The comparison the plan turns on: the relay reaches what the *deployment* can reach and the jump host reaches what a *machine in the keychain* can reach, so they are not substitutes. On a self-hosted box outside the target's network the relay reaches nothing the laptop could not. And the privacy ordering is the opposite way round from the ADR's framing — the relay costs a plaintext address, the jump host costs nothing, because the operator is not in it. Both documents carry a section on what their own earlier reasoning got wrong, which for the second one is the load-bearing part: "nothing reads this field" was read as evidence of a mistake when it was evidence of an unfinished feature — and the same sentence one field over would have found the checkbox that is lying.
196 lines
13 KiB
Markdown
196 lines
13 KiB
Markdown
# Unlocking without the passphrase
|
|
|
|
Every account here is issued a recovery code at enrollment. It is generated on the client, it wraps the
|
|
identity bundle, the server stores that wrap, and both heads go to some trouble to make sure the user writes
|
|
it down — the phone raises `FLAG_SECURE` for that screen alone and refuses to let anybody click past it.
|
|
|
|
**Nothing can use it.** There is no code path in this product that opens a recovery wrap. This document is
|
|
the plan for the change that fixes that, and it is written to be picked up cold.
|
|
|
|
> **Status: planned. None of the six steps below is built.**
|
|
>
|
|
> | Step | State | Notes |
|
|
> | --- | --- | --- |
|
|
> | 1. The endpoint that serves the wrap | Not started | `GET /api/v1/me/recovery-wrap`, and deliberately not `/me` |
|
|
> | 2. `SessionOpener.UnlockWithRecoveryAsync` | Not started | The unwrap, then the path `UnlockAsync` already takes |
|
|
> | 3. Setting a new passphrase | Not started | `PUT /api/v1/me/wrap`. Delivers *change passphrase* as well |
|
|
> | 4. Both heads | Not started | A way in from the unlock screen, and a box for the code |
|
|
> | 5. The prose that becomes false | Not started | Three shipped claims disagree with each other today |
|
|
> | 6. `crypto.md`'s status note | Not started | "One of four ways" is one of two, and will be one of three |
|
|
|
|
## What is wrong
|
|
|
|
Walk the failure through, because it is worse than a missing feature.
|
|
|
|
Forget the passphrase and the identity bundle cannot be unwrapped. No bundle means no vault keys, and no
|
|
vault keys means every item in every vault is unreadable. Signing out and back in does not help: the server
|
|
hands back the same passphrase wrap. The device key would be the other door, and **sign-out withdraws it** —
|
|
which is the advice the unlock screen gives for exactly this situation. The recovery wrap sitting on the
|
|
server is the only thing left, and nothing opens it.
|
|
|
|
So the loss is total and permanent, and the thing built to prevent it is inert.
|
|
|
|
Meanwhile the product says three things about this, and they do not agree with one another:
|
|
|
|
| What it says | Where | True today |
|
|
| --- | --- | --- |
|
|
| "The code is the only thing standing between a forgotten passphrase and an unrecoverable vault" | `docs/manual-checks.md` §10.2 | **No.** It stands between nothing |
|
|
| "losing it *along with* the passphrase means the vault is unrecoverable" | `docs/android-port.md`, state 4 | **No.** It implies the code alone is enough |
|
|
| "Signing out … is the only answer to a forgotten passphrase — nothing can recover one" | `README.md`, Locking | Yes, and it contradicts both of the above |
|
|
|
|
The third is the honest one. That is the state this plan changes, and until it does, the first two are the
|
|
two sentences in this repository most likely to cost somebody their keychain.
|
|
|
|
## What already exists
|
|
|
|
More than half of it, which is why this is worth doing now rather than treating as a feature.
|
|
|
|
- **The code.** `ClientEnrollment.GenerateRecoveryCode` — 160 bits, base32 over a 32-character alphabet with
|
|
`I`, `L`, `O` and `U` left out so a transcription cannot land on a different valid code, printed as
|
|
32 characters in groups of five.
|
|
- **The wrap.** The same class derives `KEK_rc` under `Argon2Profile.RandomSecret` (64 MiB, 3 passes) and
|
|
sends `RecoveryWrappedPrivateKey` and `RecoveryKdfParameters` with the enrollment.
|
|
- **The row.** `EnrollmentService` stores it as `UserKeyWrapKind.Recovery`, beside the passphrase and device
|
|
wraps.
|
|
- **The specification.** `docs/crypto.md` §2 gives the parameters for `KEK_rc` and §3 puts the wrap in the
|
|
key hierarchy beside the passphrase and device ones. Nothing below needs a spec change.
|
|
- **The cache.** `LocalCacheKey` derives from the identity bundle under `dsh1/localcache/v2`, not from `MK`
|
|
— see the changed-2026-07-30 note in `crypto.md` §3.2. That change was made partly *for* this: a recovery
|
|
unlock derives a different `MK` and would otherwise open the identity and then fail to read the cache it
|
|
had itself written. It is already paid for and currently untested from this direction.
|
|
|
|
## What is missing, exactly
|
|
|
|
| | Gap | Where it lands |
|
|
| --- | --- | --- |
|
|
| A | Nothing serves the wrap. `MeResponse` carries `WrappedPrivateKey` and `KdfParameters` — the passphrase pair, and only that | `DodoSSH.Contracts`, `Api/Features/Identity` |
|
|
| B | No unlock path. `SessionOpener` has `UnlockAsync` and `UnlockWithDeviceAsync`, and nothing else | `Client.Session` |
|
|
| C | No way to set a new passphrase afterwards. No endpoint, no client path, no UI | server + client |
|
|
| D | No way in from either unlock screen | `UnlockCard.axaml`, Android `LockedScreen.axaml` |
|
|
|
|
The device wrap is not a precedent for A: it is cached locally in `StoredUnlockMaterial` at the moment it is
|
|
registered, so it never has to be fetched.
|
|
|
|
## The decisions, and the reasons
|
|
|
|
**A separate endpoint, not `/me`.** `GET /api/v1/me/recovery-wrap`, called only when somebody has said they
|
|
have forgotten their passphrase. `/me` is fetched by every client at every launch, and putting the recovery
|
|
wrap in it would hand that blob to anybody holding a stolen OIDC session, permanently, for no benefit. The
|
|
wrap's real defence is Argon2id over 160 bits and it does not stop being safe in the response — this is the
|
|
cheaper rule of not serving what nothing needs. It answers 404 for an account with no recovery row, which is
|
|
every account enrolled by a client that did not send one.
|
|
|
|
**Online only, and the screen says so.** The wrap is deliberately *not* added to `StoredUnlockMaterial`.
|
|
Caching it would put a second door on every laptop, protected by a weaker KDF profile than the passphrase
|
|
one, for a case that already requires a network — recovery begins with signing in.
|
|
|
|
**Setting a new passphrase is part of the flow, not a follow-up.** Without it the account unlocks with a
|
|
one-time code forever, and the code is a thing people keep on paper. This is the same re-wrap a *change
|
|
passphrase* feature needs, so step 3 delivers both; change-passphrase is then a button, not a project.
|
|
|
|
**The identity key is not rotated.** Rotating it would invalidate every vault key grant the account holds
|
|
and force a rekey of every vault it can read — see [ADR 0010](adr/0010-vault-key-rotation.md) for what one
|
|
of those costs, and it is per vault. Nothing about the bundle is compromised by its owner proving possession
|
|
of it, so there is nothing to rotate away from. Identity key rotation is M5 and stays there.
|
|
|
|
**The recovery code is not re-issued after use.** Issuing a new one means asking somebody to write down a
|
|
new code at the exact moment they have demonstrated they lose things, and the old code is not weakened by
|
|
having been typed. "Issue a new recovery code" is a separate feature with its own screen, and it is the
|
|
right place for that question.
|
|
|
|
**Rate limiting is wanted here and is not a blocker.** This is the first endpoint in the product with a
|
|
guessable secret behind it, and `docs/platform-flags.md` records that rate limiting is unimplemented (M2).
|
|
Argon2id at 64 MiB is the cost that matters — a guessing attack pays it per attempt — so this ships without
|
|
and the endpoint is the reason to do the M2 item next.
|
|
|
|
## The work, in order
|
|
|
|
Each step compiles with the whole suite green before the next begins.
|
|
|
|
1. **The endpoint.** `GET /api/v1/me/recovery-wrap`, returning the wrap and its `KdfParameters`, or 404. A
|
|
contract type, an entry in `PublicAPI.Unshipped.txt`, and a `SyncEndpointTests`-style refusal test for an
|
|
account without one.
|
|
2. **The unlock.** `SessionOpener.UnlockWithRecoveryAsync(string code)`: canonicalise the code, derive
|
|
`KEK_rc` from the served parameters, unwrap the bundle, and then join the path `UnlockAsync` already
|
|
takes from the moment it holds one. Nothing after the unwrap should be new code — if it is, the two
|
|
unlocks have diverged and one of them is wrong.
|
|
3. **The re-wrap.** `PUT /api/v1/me/wrap` taking a new passphrase wrap and its parameters, and the client
|
|
half that derives the new `KEK_pp` and calls it. Forced as the last step of a recovery: the session is
|
|
open, so refusing to go further until a passphrase is set costs nothing and is the only moment the user
|
|
is certainly present.
|
|
4. **Both heads.** A "forgotten your passphrase?" route from `UnlockCard` and from Android's
|
|
`LockedScreen`, a box that accepts the code as printed, and the new-passphrase form after it. The phone's
|
|
version has to survive the keyboard covering the box — `docs/manual-checks.md` §10.3 lists the five boxes
|
|
that already do, and this is a sixth.
|
|
5. **The prose.** Below.
|
|
6. **`crypto.md`.** A status note, not a spec change — see the last section.
|
|
|
|
## Traps already known
|
|
|
|
**◆ The code is derived from the string exactly as displayed, dashes included.** `GenerateRecoveryCode`
|
|
says so where it builds the groups: the separators are not decoration to be stripped before hashing, they
|
|
are part of the input. So step 2 must *canonicalise to the printed form* rather than normalise it away —
|
|
up-case, then re-group in fives — and it must not simply strip dashes and hash what is left. Getting this
|
|
wrong produces a code that verifies nowhere and an error message that says the code is wrong.
|
|
|
|
**The alphabet has holes in it.** `I`, `L`, `O` and `U` are not in it. A user who writes `O` for `0` should
|
|
be met with a code that works, so the canonicaliser should fold the four missing letters onto their
|
|
look-alikes before deriving. That is a deliberate leniency and belongs beside the alphabet's own comment.
|
|
|
|
**The two KDF profiles are not the same, and the stored parameters are what to use.** The passphrase wrap is
|
|
`PassphraseDefault` (256 MiB, 4 passes) and the recovery wrap is `RandomSecret` (64 MiB, 3), which is
|
|
correct — 160 random bits do not need the same stretching as a chosen phrase. Derive from the parameters the
|
|
server served with the wrap, never from a profile constant, or an account enrolled by a client with
|
|
different settings will refuse a valid code.
|
|
|
|
**The cache property is untested from this direction.** A recovery unlock derives a different `MK` and must
|
|
still read a cache written under a passphrase unlock. That works today because `LocalCacheKey` hangs off the
|
|
bundle, and no test asserts it, because nothing could reach the state. Assert it in step 2 rather than
|
|
trusting the note in `crypto.md`.
|
|
|
|
**Sign-out is the neighbouring path and must stay reachable.** The unlock screen offers signing out as the
|
|
answer to a forgotten passphrase. It stays: recovery needs the code, and somebody without it still needs a
|
|
way to hand a laptop on. What changes is that it stops being the *only* answer, so the copy on both screens
|
|
has to place them beside each other rather than replacing one with the other.
|
|
|
|
## Tests
|
|
|
|
- Round trip: enrol, recover, unlock, set a new passphrase, unlock again with it.
|
|
- The old passphrase stops working after step 3, and the recovery code still does.
|
|
- A wrong code is refused without disclosing whether the account has a recovery wrap at all.
|
|
- The cache written under a passphrase unlock is readable after a recovery unlock — the `localcache/v2`
|
|
property, asserted rather than assumed.
|
|
- An account with no recovery row: the endpoint 404s and the screen says the code was never issued rather
|
|
than that it is wrong.
|
|
- One `SystemTests` pass against the real API, because this is a two-endpoint flow and that suite is the one
|
|
that consumes the artefacts that ship.
|
|
- Mutations to confirm each test can fail: reverse the canonicalisation so dashes are stripped; derive from
|
|
`Argon2Profile.RandomSecret` instead of from the served parameters; and skip the forced re-wrap in step 3.
|
|
|
|
## Prose that becomes false
|
|
|
|
Not a tidy-up. Each of these currently tells a user something that this change makes wrong in the other
|
|
direction, and two of them are wrong right now.
|
|
|
|
- `docs/manual-checks.md` §10.2 — "the only thing standing between a forgotten passphrase and an
|
|
unrecoverable vault". True once this ships, false today. It also needs a new check: typing a code from
|
|
paper, which is the one part of this no test can perform.
|
|
- `docs/android-port.md`, state 4 — "losing it along with the passphrase means the vault is unrecoverable".
|
|
- `README.md`, Locking — "Signing out … is the only answer to a forgotten passphrase — nothing can recover
|
|
one." Correct today and the sentence this change exists to falsify.
|
|
- `docs/design-import-gaps.md`, Preferences — "a forgotten passphrase — which is unrecoverable by
|
|
construction, so the unlock screen would otherwise be a dead end", which is the stated justification for
|
|
signing out being on that screen. The justification survives; the parenthesis does not.
|
|
- Both unlock screens, wherever they name signing out as the answer.
|
|
|
|
## The spec's "four ways"
|
|
|
|
`docs/crypto.md` §3.2 says a passphrase is "only one of four ways to open a vault" — passphrase, device,
|
|
recovery and escrow. Two exist. This change makes it three; escrow is M5 by decision and has an enum member
|
|
and nothing else.
|
|
|
|
**Do not edit that sentence.** It is normative and it is about the DSH1 format, where four ways is exactly
|
|
right. What is missing is a statement about *this build*, so add a short table under §3.2 saying which wrap
|
|
kinds this client can create and which it can open, and update it here rather than in the frozen prose. Land
|
|
it in the same commit as step 2, so the two can never disagree again.
|