add clarifications

pull/977/head
Hubert Chathi 6 years ago
parent 8777232987
commit 846e9e8fdc

@ -43,7 +43,7 @@ On receipt of encryption keys (1st time):
1. client checks if there is an existing backup: `GET /room_keys/version` 1. client checks if there is an existing backup: `GET /room_keys/version`
1. if not, ask if the user wants to back up keys 1. if not, ask if the user wants to back up keys
1. if yes: 1. if yes:
1. generate new key pair 1. generate new curve25519 key pair
2. create new backup version: `POST /room_keys/version` 2. create new backup version: `POST /room_keys/version`
3. display private key to user to save TODO: specify how the key is 3. display private key to user to save TODO: specify how the key is
displayed displayed
@ -91,18 +91,18 @@ Create a new backup version.
Body parameters: Body parameters:
- `algorithm` (string): Required. The algorithm used for storing backups. - `algorithm` (string): Required. The algorithm used for storing backups.
Currently, only `m.megolm_backup.v1` is defined. (FIXME: change the algorithm Currently, only `m.megolm_backup.v1.curve25519-aes-sha2` is defined.
name to include the encryption method)
- `auth_data` (string or object): Required. algorithm-dependent data. For - `auth_data` (string or object): Required. algorithm-dependent data. For
`m.megolm_backup.v1`, this is a signedjson object with the following keys: `m.megolm_backup.v1.curve25519-aes-sha2`, this is a signedjson object with
- `public_key` (string): the public key used to encrypt the backups the following keys:
- `public_key` (string): the curve25519 public key used to encrypt the backups
- `signatures` (object): signatures of the public key - `signatures` (object): signatures of the public key
Example: Example:
```javascript ```javascript
{ {
"algorithm": "m.megolm_backup.v1", "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
"auth_data": { "auth_data": {
"public_key": "abcdefg", "public_key": "abcdefg",
"signatures": { "signatures": {
@ -143,7 +143,10 @@ Store the key for the given session in the given room, using the given backup
version. version.
If the server already has a backup in the backup version for the given session If the server already has a backup in the backup version for the given session
and room, then it will keep the "better" one ... and room, then it will keep the "better" one. To determine which one is
"better", key backups are compared first by the `is_verified` flag (`true` is
better than `false`), then by the `first_message_index` (a lower number is better),
and finally by `forwarded_count` (a lower number is better).
Body parameters: Body parameters:
@ -154,15 +157,16 @@ Body parameters:
- `is_verified` (boolean): Whether the device backing up the key has verified - `is_verified` (boolean): Whether the device backing up the key has verified
the device that the key is from. the device that the key is from.
- `session_data` (string or object): Algorithm-dependent data. For - `session_data` (string or object): Algorithm-dependent data. For
`m.megolm_backup.v1`, this is an object with the following keys: `m.megolm_backup.v1.curve25519-aes-sha2`, this is an object with the
- `ciphertext` (string): the encrypted version of the session key. See below following keys (TODO: this stuff should be moved):
for how the session key is encoded. - `ciphertext` (string): the encrypted version of the session key, as an
- `ephemeral` (string): the public ephemeral key that was used to encrypt the unpadded base64 string. See below for how the session key is encoded.
session key. - `ephemeral` (string): the public ephemeral curve25519 key that was used to
encrypt the session key, as an unpadded base64 string.
- `mac` (string): the message authentication code for the ciphertext. FIXME: - `mac` (string): the message authentication code for the ciphertext. FIXME:
more details more details
On success, returns ... ? On success, returns the empty JSON object.
Error codes: Error codes:
@ -176,7 +180,7 @@ Store several keys for the given room, using the given backup version.
Behaves the same way as if the keys were added individually using `PUT Behaves the same way as if the keys were added individually using `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`. /room_keys/keys/${roomId}/${sessionId}?version=$v`.
Body paremeters: Body parameters:
- `sessions` (object): an object where the keys are the session IDs, and the - `sessions` (object): an object where the keys are the session IDs, and the
values are objects of the same form as the body in `PUT values are objects of the same form as the body in `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`. /room_keys/keys/${roomId}/${sessionId}?version=$v`.
@ -184,15 +188,43 @@ Body paremeters:
Returns the same as `PUT Returns the same as `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v` /room_keys/keys/${roomId}/${sessionId}?version=$v`
##### `PUT /room_keys/keys/?version=$v` ##### `PUT /room_keys/keys?version=$v`
Store several keys, using the given backup version.
Behaves the same way as if the keys were added individually using `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`.
Body parameters:
- `rooms` (object): an object where the keys are the room IDs, and the values
are objects of the same form as the body in `PUT
/room_keys/keys/${roomId}/?version=$v`.
... Returns the same as `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`
#### Retrieving keys #### Retrieving keys
##### `GET /room_keys/keys/${roomId}/${sessionId}?version=$v` ##### `GET /room_keys/keys/${roomId}/${sessionId}?version=$v`
Retrieve the key for the given session in the given room from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys/${roomId}/${sessionId}?version=$v`.
##### `GET /room_keys/keys/${roomId}?version=$v` ##### `GET /room_keys/keys/${roomId}?version=$v`
##### `GET /room_keys/keys/?version=$v`
Retrieve the all the keys for the given room from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys/${roomId}?version=$v`.
##### `GET /room_keys/keys?version=$v`
Retrieve all the keys from the backup.
On success, returns a JSON object in the same form as the request body of `PUT
/room_keys/keys?version=$v`.
#### Deleting keys #### Deleting keys
@ -200,7 +232,11 @@ Returns the same as `PUT
##### `DELETE /room_keys/keys/${roomId}?version=$v` ##### `DELETE /room_keys/keys/${roomId}?version=$v`
##### `DELETE /room_keys/keys/?version=$v` ##### `DELETE /room_keys/keys/?version=$v`
#### Key format Deletes keys from the backup.
On success, returns the empty JSON object.
#### `m.megolm_backup.v1.curve25519-aes-sha2` Key format
Each session key is encoded as a JSON object with the properties: Each session key is encoded as a JSON object with the properties:
@ -210,9 +246,11 @@ Each session key is encoded as a JSON object with the properties:
sending device sending device
- `forwardingCurve25519KeyChain` (array): zero or more curve25519 keys for - `forwardingCurve25519KeyChain` (array): zero or more curve25519 keys for
devices who forwarded the session key devices who forwarded the session key
- `session_key` (string): base64-encoded session key - `session_key` (string): base64-encoded (unpadded) session key
... The JSON object is then encrypted by generating an ephemeral curve25519 key,
performing an ECDH with the ephemeral key and the backup's public key to
generate an AES key, and encrypting the stringified object using AES.
Tradeoffs Tradeoffs
--------- ---------

Loading…
Cancel
Save