add details on recovery key format, and some cleanups/fixes

proposals/1219-storing-megolm-keys-serverside.md

@@ -45,8 +45,7 @@ On receipt of encryption keys (1st time):
       1. if yes:
          1. generate new curve25519 key pair
          2. create new backup version: `POST /room_keys/version`
-         3. display private key to user to save TODO: specify how the key is
-            displayed
+         3. display private key to user to save (see below for the format)
       2. if no, exit and remember decision (user can change their mind later)
       3. while prompting, continue to poll `GET /room_keys/versions`, as
          another device may have created a backup.  If so, go to 1.2.
@@ -80,6 +79,30 @@ On receipt of undecryptable message:
 Users can also set up, disable, or rotate backups, or restore from backup via user
 settings.
 
+### Recovery key
+
+The recovery key is can either be saved by the user directly, or stored
+encrypted on the server (as proposed in
+[MSC1687](https://github.com/matrix-org/matrix-doc/issues/1687)).  If the key
+is saved directly by the user, then it the code is constructed as follows:
+
+1. The 256-bit curve25519 private key is prepended by the bytes `0x8B` and
+   `0x01`
+2. All the bytes in the string are above are XORed together to form a parity
+   byte. This parity byte is appended to the byte string.
+3. The byte string is encoded using base58, using the same mapping as is used
+   for Bitcoin addresses.
+
+This 58-character string is presented to the user to save.  Implementations may
+add whitespace to the recovery key.
+
+When reading in a recovery key, clients must disregard whitespace.  Clients
+must base58-decode the code, ensure that the first two bytes of the decoded
+string are `0x8B` and `0x01`, ensure that XOR-ing all the bytes together
+results in 0, and ensure that the total length of the decoded string
+is 35 bytes.  Clients must then remove the first two bytes and the last byte,
+and use the resulting string as the private key to decrypt backups.
+
 ### API
 
 #### Backup versions
@@ -118,9 +141,10 @@ On success, returns a JSON object with keys:
 
 - `version` (integer): the backup version
 
-##### `GET /room_keys/version`
+##### `GET /room_keys/version/{version}`
 
-Get information about the current version.
+Get information about the given version, or the current version if `{version}`
+is omitted.
 
 On success, returns a JSON object with keys:
 
@@ -128,12 +152,11 @@ On success, returns a JSON object with keys:
   /room_keys/version`.
 - `auth_data` (string or object): Required. Same as in the body parameters for
   `POST /room_keys/version`.
-- `version` (integer): the backup version
+- `version` (integer): Required. The backup version.
 
 Error codes:
 
-- `M_UNKNOWN`: No backup version has been created. FIXME: why not
-  `M_NOT_FOUND`?
+- `M_NOT_FOUND`: No backup version has been created.
 
 #### Storing keys