diff --git a/proposals/3834-tofu.md b/proposals/3834-tofu.md new file mode 100644 index 000000000..08c3031bf --- /dev/null +++ b/proposals/3834-tofu.md @@ -0,0 +1,144 @@ +# MSC3834: Opportunistic user key pinning (TOFU) + +In the Matrix spec at present, there are no real provisions for +properly authenticating devices belonging to other users, aside from +the fairly rare cases where users actually take the time to verify +each other out-of-band. Most clients encourage users to cross-sign +their own devices, but this has little practical value for most users +in the ecosystem at present, unless you're willing to verify all of +your contacts or trust the user keys reported by homeservers. + +The goal of this proposal is to establish a TOFU-style mechanism where +users' signing keys are pinned when they're first encountered; +internally, this will look similar to user verification, but will +require no action on either user's part, and correspondingly will not +be considered as high a level of trust. Nevertheless, this at least +raises the bar for Mallory-in-the-middle attacks by malicious +homeservers, as they can no longer quietly falsify signing keys for +users who are already in contact with each other. + +## Proposal + +This proposal adds a fourth ed25519 keypair to a user's set of +cross-signing keys: the TOFU Signing Key (TSK), identified by +`m.cross_signing.tofu_signing`. This key will be uploaded and stored +alongside the MSK, SSK, and USK; it will be published to the +`keys/device_signing/upload` using the new optional field +`tofu_signing_key`. + +Whenever a user Alice and a user Bob are in a room together for the +first time, Alice's device will automatically and silently cross-sign +Bob's MSK using her TSK. This effectively pins Bob's MSK; in future +interactions, Alice will be able to check that any device of Bob's is +signed by Bob's SSK which is signed by the pinned MSK, confirming that +the device really does belong to Bob as long as that very first +interaction wasn't tampered with. If Alice's device later observes an +MSK for Bob that differs from the one signed by her TSK, the device +may warn Alice that Bob's key has changed, and could potentially +refuse to share keys with devices that aren't signed under the +original SSK/MSK until Alice chooses to accept the new key. + +After a device signs one or several new MSKs with the TSK (on joining +a new room, or observing a new member join a room), it should upload +these new signatures to the homeserver via the +`keys/signatures/upload` API endpoint. However, it is important to +ensure that the homeserver cannot perform a denial-of-service attack +on key pinning by simply dropping TOFU signatures. For this reason, a +user's devices should periodically ask each other to confirm a hash of +the complete set of all cross-signing signatures created by that +user. At any point, a device may send any or all of the user's other +devices an encrypted to-device message, with event type +`m.signatures_hash_request` and no fields. When the device receives +the message, it should reply with an encrypted to-device message with +event type `m.signatures_hash` and one field `sha256`. This field +contains a SHA256 hash of the canonical JSON encoding of the complete +set of cross-signing signatures known to that device, in the format +for uploading to `keys/signatures/upload`, excluding any unsigned +fields - that is, a map from user ID, to key ID, to a signed JSON +object for that key. + +## Potential issues + +If a client does choose to warn users every time a pinned MSK changes, +users in many large rooms could be overwhelmed with warnings from +random people losing their devices and performing key resets. There +are several things clients can do to alleviate this. First, rather +than popping up a warning immediately in a toast or dialog as soon as +a key changes, clients should only warn the user when they actually +open one of the rooms where the changed key is present. In addition, +users should be given the option to automatically accept all future +key changes in a particular room, and the option to accept all key +changes globally if that's in line with the user's threat +model. Clients could still display a small state-event-like message in +room timelines notifying the user of a key change, or could simply +accept all key changes silently. + +## Security considerations + +In the malicious homeserver scenario that this proposal aims to +mitigate, the homeserver could attempt to simply exclude TSK +signatures from its responses to key queries, preventing the +propagation of pinned keys between devices, and possibly even causing +a device to lose track of pinned keys over time. To prevent this, +it's important that clients maintain a persistent record of TSK +signatures without relying on the homeserver to store that +information. Signatures must never be removed from this record, even +if they aren't present in homeserver responses. However, if multiple +valid signatures for the same key from the same TSK have been created +due to race conditions, only the signature whose base64 representation +comes first lexicographically should be kept. + +When devices ask each other to confirm the hash of the set of +cross-signing signatures, they may not receive a response; this could +be because the other device is offline, it could be because the device +is using an older version of the spec and doesn't understand the +request, or it could be because the homeserver is performing a +denial-of-service attack. If a device doesn't get a response, and does +see other activity from the other device, it could possibly eventually +display a warning encouraging the user to upgrade their other +device. If the device observes too many missing key indices in its +to-device Olm session, however, that may be a sign that the homeserver +is dropping messages. + +In this threat model, another thing the homeserver can do is falsely +claim that the user's cross-signing keys have been reset by another +device. For the most part, this simply amounts to a denial-of-service +attack on cross-signing, which is difficult to prevent in +general. However, it's important to note that if a formerly-verified +device is told by the server that there's been a key reset, it must +still hold onto its record of signatures created with the old TSK, and +re-sign those with the new TSK once it has been able to confirm the +new MSK as part of becoming re-verified. + +## Unstable prefix + +This proposal does not add any new API endpoints, but does add some +new fields and message types to existing data structures. These field +names and message types will be prefixed with `org.matrix.msc3834.v1`. +Test implementations can identify the TSK as +`org.matrix.msc3834.v1.cross_signing.tofu_signing`, use the optional +field `org.matrix.msc3834.v1.tofu_signing_key` for the +`keys/device_signing/upload` endpoint, and use the message types +`org.matrix.msc3834.v1.signatures_hash_request` and +`org.matrix.msc3834.v1.signatures_hash` for exchanging hashes of the +set of cross-signing signatures. + +## Migration notes + +When a device with this functionality first comes online, if the user +doesn't already have a TSK and if the device possesses the private +MSK, it should create a new TSK, sign it with the MSK, and publish it +to `keys/device_signing/upload`. This endpoint requires +authentication, and therefore the user may need to be prompted for a +password when they open their upgraded client. If the user already has +server-side secret storage set up, the device should also store the +private TSK encrypted in secret storage. + +If the user does already have a TSK, devices should obtain the private +key either from secret storage or by requesting the secret from other +devices. In the event of a race condition where multiple devices have +upgraded and created TSKs, the TSK whose base64 representation comes +first lexicographically will take precedence. Once other devices have +received the private key for the winning TSK, they should use it to +re-sign and re-submit any TOFU signatures they've already created, and +replace any signatures by the old TSK in their persistent records.