From 7595a63fb2cd42d68292a0e03aa45b7456b759ac Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 14 Aug 2020 16:32:29 -0400 Subject: [PATCH 1/7] initial version of olm fallback keys --- proposals/xxxx-olm-fallback-keys.md | 54 +++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 proposals/xxxx-olm-fallback-keys.md diff --git a/proposals/xxxx-olm-fallback-keys.md b/proposals/xxxx-olm-fallback-keys.md new file mode 100644 index 00000000000..75322bee19c --- /dev/null +++ b/proposals/xxxx-olm-fallback-keys.md @@ -0,0 +1,54 @@ +# MSCxxxx: Olm fallback keys + +Olm uses a set of one-time keys when initializing a session between two +devices: Alice uploads one-time keys to her homeserver, and Bob claims one of +them to perform a Diffie-Hellman to generate a shared key. As implied by the +name, a one-time key is only to be used once. However, if all of Alice's +one-time keys are claimed, Bob will not be able to create a session with Alice. + +This can be addressed by Alice uploading a fallback key that is used in place +of a one-time key when no one-time keys are available. + +## Proposal + +A new request parameter, `fallback_keys`, is added to the body of the +`/keys/upload` client-server API, which is in the same format as the +`one_time_keys` parameter with the exception that there must be at most one key +per key algorithm. If the user had previously uploaded a fallback key for a +given algorithm, it is replaced -- the server will only keep one fallback key +per algorithm for each user. + +When Bob calls `/keys/claim` to claim one of Alice's one-time keys, but Alice +has no one-time keys left, the homeserver will return the fallback key instead, +if Alice had previously uploaded one. Unlike with one-time keys, fallback keys +are not deleted when they are returned by `/keys/claim`. However, the server +marks that they have been used. + +A new response parameter, `device_unused_fallback_keys`, is added to `/sync`. +This is an array listing the key algorithms for which the server has an unused +fallback key for the user. If the client wants the server to have a fallback +key for a given key algorithm, but that algorithm is not listed in +`device_unused_fallback_keys`, the client will upload a new key as above. + +## Security considerations + +Using a fallback key rather than a one-time key has security implications. An +attacker can replay a message that was originally sent with a fallback key, and +the receiving client will accept it as a new message if the fallback key is +still active. Also, an attacker that compromises a client may be able to +retrieve the private part of the fallback key to decrypt past messages if the +client has still retained the private part of the fallback key. + +For this reason, clients should not store the private part of the fallback key +indefinitely. For example, client should only store at most two fallback keys: +the current fallback key (that it has not yet received any messages for) and +the previous fallback key, and should remove the previous fallback key once it +is reasonably certain that it has received all the messages that use it (for +example, one hour after receiving the first message that used it). + +For addressing replay attacks, clients can also keep track of inbound sessions +to detect replays. + +## Unstable prefix + +TODO: ... From 94465e06c2e7f473fe0eeff28c49cfdf5d560f36 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 14 Aug 2020 16:41:48 -0400 Subject: [PATCH 2/7] use MSC number --- .../{xxxx-olm-fallback-keys.md => 2732-olm-fallback-keys.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename proposals/{xxxx-olm-fallback-keys.md => 2732-olm-fallback-keys.md} (98%) diff --git a/proposals/xxxx-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md similarity index 98% rename from proposals/xxxx-olm-fallback-keys.md rename to proposals/2732-olm-fallback-keys.md index 75322bee19c..d24ef38008a 100644 --- a/proposals/xxxx-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -1,4 +1,4 @@ -# MSCxxxx: Olm fallback keys +# MSC2732: Olm fallback keys Olm uses a set of one-time keys when initializing a session between two devices: Alice uploads one-time keys to her homeserver, and Bob claims one of From f831162563ab3d87c77aecdb0a6fed4f730b31d5 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 24 Sep 2020 17:09:45 -0400 Subject: [PATCH 3/7] add clarifications, examples, etc --- proposals/2732-olm-fallback-keys.md | 45 ++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index d24ef38008a..d6be01f1286 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -18,6 +18,30 @@ per key algorithm. If the user had previously uploaded a fallback key for a given algorithm, it is replaced -- the server will only keep one fallback key per algorithm for each user. +When uploading fallback keys for algorithms whose key format is a signed JSON +object, client should include a property named `fallback` with a value of +`true`. + +Example: + +`POST /keys/upload` + +```json +{ + "fallback_keys": { + "signed_curve25519:AAAAAA": { + "key": "base64+public+key", + "fallback": true, + "signatures": { + "@alice:example.org": { + "ed25519:DEVICEID": "base64+signature" + } + } + } + } +} +``` + When Bob calls `/keys/claim` to claim one of Alice's one-time keys, but Alice has no one-time keys left, the homeserver will return the fallback key instead, if Alice had previously uploaded one. Unlike with one-time keys, fallback keys @@ -30,6 +54,24 @@ fallback key for the user. If the client wants the server to have a fallback key for a given key algorithm, but that algorithm is not listed in `device_unused_fallback_keys`, the client will upload a new key as above. +The `device_unused_fallback_keys` parameter must be present if the server +supports fallback keys. Clients can thus treat this field as an indication +that the server supports fallback keys, and so only upload fallback keys to +servers that support them. + +Example: + +`GET /sync` + +Response: + +```json +{ + // other fields... + "device_unused_fallback_keys": ["signed_curve25519"] +} +``` + ## Security considerations Using a fallback key rather than a one-time key has security implications. An @@ -51,4 +93,5 @@ to detect replays. ## Unstable prefix -TODO: ... +The `fallback_key` request parameter and the `device_unused_fallback_keys` +response parameter will be prefixed by `org.matrix.msc2732.`. From 48b0196ac6d2605a6f5a983621b81b74bd983c4d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 2 Oct 2020 15:52:35 -0400 Subject: [PATCH 4/7] update property name --- proposals/2732-olm-fallback-keys.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index d6be01f1286..854b48c7e83 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -48,13 +48,13 @@ if Alice had previously uploaded one. Unlike with one-time keys, fallback keys are not deleted when they are returned by `/keys/claim`. However, the server marks that they have been used. -A new response parameter, `device_unused_fallback_keys`, is added to `/sync`. -This is an array listing the key algorithms for which the server has an unused -fallback key for the user. If the client wants the server to have a fallback -key for a given key algorithm, but that algorithm is not listed in -`device_unused_fallback_keys`, the client will upload a new key as above. +A new response parameter, `device_unused_fallback_key_types`, is added to +`/sync`. This is an array listing the key algorithms for which the server has +an unused fallback key for the user. If the client wants the server to have a +fallback key for a given key algorithm, but that algorithm is not listed in +`device_unused_fallback_key_types`, the client will upload a new key as above. -The `device_unused_fallback_keys` parameter must be present if the server +The `device_unused_fallback_key_types` parameter must be present if the server supports fallback keys. Clients can thus treat this field as an indication that the server supports fallback keys, and so only upload fallback keys to servers that support them. @@ -68,7 +68,7 @@ Response: ```json { // other fields... - "device_unused_fallback_keys": ["signed_curve25519"] + "device_unused_fallback_key_types": ["signed_curve25519"] } ``` @@ -93,5 +93,5 @@ to detect replays. ## Unstable prefix -The `fallback_key` request parameter and the `device_unused_fallback_keys` +The `fallback_key` request parameter and the `device_unused_fallback_key_types` response parameter will be prefixed by `org.matrix.msc2732.`. From de65f4e1fed33100db7bb5aa59c4b0d32116e4f4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 26 Jan 2021 15:21:25 -0500 Subject: [PATCH 5/7] Add link to keys upload endpoint Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2732-olm-fallback-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index 854b48c7e83..fcc7350d9f0 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -12,7 +12,7 @@ of a one-time key when no one-time keys are available. ## Proposal A new request parameter, `fallback_keys`, is added to the body of the -`/keys/upload` client-server API, which is in the same format as the +[`/keys/upload` client-server API](https://matrix.org/docs/spec/client_server/r0.6.1#post-matrix-client-r0-keys-upload), which is in the same format as the `one_time_keys` parameter with the exception that there must be at most one key per key algorithm. If the user had previously uploaded a fallback key for a given algorithm, it is replaced -- the server will only keep one fallback key From ddbcba454c14336e550809bc12e0b26d550589d4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 15 Feb 2021 10:20:48 -0500 Subject: [PATCH 6/7] Fix typo Co-authored-by: Sorunome --- proposals/2732-olm-fallback-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index fcc7350d9f0..7b060bec792 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -93,5 +93,5 @@ to detect replays. ## Unstable prefix -The `fallback_key` request parameter and the `device_unused_fallback_key_types` +The `fallback_keys` request parameter and the `device_unused_fallback_key_types` response parameter will be prefixed by `org.matrix.msc2732.`. From 0841f31ce48c2f337f5407991b1281b2934e4209 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 24 Mar 2021 10:24:06 -0400 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2732-olm-fallback-keys.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2732-olm-fallback-keys.md b/proposals/2732-olm-fallback-keys.md index 7b060bec792..5ab90117cf3 100644 --- a/proposals/2732-olm-fallback-keys.md +++ b/proposals/2732-olm-fallback-keys.md @@ -50,7 +50,7 @@ marks that they have been used. A new response parameter, `device_unused_fallback_key_types`, is added to `/sync`. This is an array listing the key algorithms for which the server has -an unused fallback key for the user. If the client wants the server to have a +an unused fallback key for the device. If the client wants the server to have a fallback key for a given key algorithm, but that algorithm is not listed in `device_unused_fallback_key_types`, the client will upload a new key as above. @@ -65,7 +65,7 @@ Example: Response: -```json +```jsonc { // other fields... "device_unused_fallback_key_types": ["signed_curve25519"]