From e8ce135a411e5fa2715f9d1cbd57f0fc232bc98f Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubert@uhoreg.ca>
Date: Thu, 7 Nov 2019 19:00:33 -0500
Subject: [PATCH] add clarification and examples

---
 proposals/1946-secure_server-side_storage.md | 29 ++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/proposals/1946-secure_server-side_storage.md b/proposals/1946-secure_server-side_storage.md
index 4c5f9b4dd..aa4fd8f91 100644
--- a/proposals/1946-secure_server-side_storage.md
+++ b/proposals/1946-secure_server-side_storage.md
@@ -57,8 +57,9 @@ clients will try to use the default key to decrypt secrets.
 Clients MUST ensure that the key is trusted before using it to encrypt secrets.
 One way to do that is to have the client that creates the key sign the key
 description (as signed JSON) using the user's master cross-signing key.
-Another way to do that is to prompt the user to enter the passphrase and ensure
-that the generated private key correponds to the public key.
+Another way to do that is to prompt the user to enter the passphrase used to
+generate the encryption key and ensure that the generated private key
+corresponds to the public key.
 
 #### Secret storage
 
@@ -79,6 +80,8 @@ Example:
 
 Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
 
+`org.example.some.secret`:
+
 ```json
 {
   "encrypted": {
@@ -95,6 +98,28 @@ Some secret is encrypted using keys with ID `key_id_1` and `key_id_2`:
 }
 ```
 
+and the key descriptions for the keys would be:
+
+`m.secret_storage.key.key_id_1`:
+
+```json
+{
+  "name": "Some key",
+  "algorithm": "m.secret_storage.v1.curve25519-aes-sha2",
+  // ... other properties according to algorithm
+}
+```
+
+`m.secret_storage.key.key_id_2`:
+
+```json
+{
+  "name": "Some other key",
+  "algorithm": "m.secret_storage.v1.curve25519-aes-sha2",
+  // ... other properties according to algorithm
+}
+```
+
 #### Encryption algorithms
 
 ##### `m.secret_storage.v1.curve25519-aes-sha2`