Name and clarify a few more objects.

1 files changed, 35 insertions, 17 deletions

diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt
index 76d02cf..c9928e5 100644
--- a/rend-spec-v3.txt
+++ b/rend-spec-v3.txt
@@ -603,8 +603,8 @@ Table of contents:
         KP_hs_desc_sign, KS_hs_desc_sign.
 
       Introduction point authentication key -- A short-term signing
-        keypair used to identify a hidden service to a given
-        introduction point. A fresh keypair is made for each
+        keypair used to identify a hidden service's session at a given
+        introduction point. The service makes a fresh keypair is made for each
         introduction point; these are used to sign the request that a
         hidden service host makes when establishing an introduction
         point, so that clients who know the public component of this key
@@ -612,14 +612,20 @@ Table of contents:
         service. No keypair is ever used with more than one introduction
         point. (previously called a "service key" in rend-spec.txt)
         KP_hs_ipt_sid, KS_hs_ipt_sid
-	("hidden service introduction point temporary id").
+	("hidden service introduction point session id").
 
       Introduction point encryption key -- A short-term encryption
         keypair used when establishing connections via an introduction
-        point. Plays a role analogous to Tor nodes' onion keys. A fresh
-        keypair is made for each introduction point.
+        point. Plays a role analogous to Tor nodes' onion keys. The service
+        makes a fresh keypair is made for each introduction point.
         KP_hss_ntor, KS_hss_ntor.
 
+      Ephemeral descriptor encryption key -- A short-lived encryption
+        keypair made by the service, and used to encrypt the inner layer
+        of hidden service descriptors when client authentication is in
+        use.
+        KP_hss_desc_enc, KS_hss_desc_enc
+
    Symmetric keys defined in this document:
 
       Descriptor encryption keys -- A symmetric encryption key used to
@@ -627,6 +633,12 @@ Table of contents:
         current period and the hidden service credential.
         K_desc_enc.
 
+   Nonces defined in this document:
+
+      N_hs_desc_enc -- a nonce used to derive keys to decrypt the inner
+        encryption layer of hidden service descriptors.  This is
+        sometimes also called a "descriptor cookie".
+
    Public/private keypairs defined elsewhere:
 
       Onion key -- Short-term encryption keypair (KS_ntor, KP_ntor).
@@ -651,7 +663,8 @@ Table of contents:
    Specifically, each authorized client possesses:
 
    - An x25519 keypair used to compute decryption keys that allow the client to
-     decrypt the hidden service descriptor. See [HS-DESC-ENC].
+     decrypt the hidden service descriptor. See [HS-DESC-ENC].  This is
+     the client's counterpart to KP_hss_desc_enc.
      KP_hsc_desc_enc, KS_hsd_desc_enc.
 
    - An ed25519 keypair which allows the client to compute signatures which
@@ -1187,10 +1200,11 @@ Table of contents:
    "encrypted" field.
 
    If client auth is enabled, the hidden service generates a fresh
-   descriptor_cookie key (32 random bytes) and encrypts it using each
-   authorized client's identity x25519 key. Authorized clients can use the
-   descriptor cookie to decrypt the second layer of encryption. Our encryption
-   scheme requires the hidden service to also generate an ephemeral x25519
+   descriptor_cookie key (`N_hs_desc_enc`, 32 random bytes) and encrypts
+   it using each authorized client's identity x25519 key. Authorized
+   clients can use the descriptor cookie (`N_hs_desc_enc`) to decrypt
+   the second (inner) layer of encryption. Our encryption scheme
+   requires the hidden service to also generate an ephemeral x25519
    keypair for each new descriptor.
 
    If client auth is disabled, fake data is placed in each of the fields below
@@ -1212,9 +1226,9 @@ Table of contents:
 
       [Exactly once]
 
-      This field contains an ephemeral x25519 public key generated by the
-      hidden service and encoded in base64. The key is used by the encryption
-      scheme below.
+      This field contains `KP_hss_desc_enc`, an ephemeral x25519 public
+      key generated by the hidden service and encoded in base64. The key
+      is used by the encryption scheme below.
 
       If client authorization is disabled, the value here should be a fresh
       x25519 pubkey that will remain unused.
@@ -1229,18 +1243,22 @@ Table of contents:
       data of the right size (that's 8 bytes for 'client-id', 16 bytes for 'iv'
       and 16 bytes for 'encrypted-cookie' all encoded with base64).
 
-      When client authorization is enabled, each "auth-client" line contains
-      the descriptor cookie encrypted to each individual client. We assume that
-      each authorized client possesses a pre-shared x25519 keypair which is
-      used to decrypt the descriptor cookie.
+      When client authorization is enabled, each "auth-client" line
+      contains the descriptor cookie `N_hs_desc_enc` encrypted to each
+      individual client. We assume that each authorized client possesses
+      a pre-shared x25519 keypair (`KP_hsc_desc_enc`) which is used to
+      decrypt the descriptor cookie.
 
       We now describe the descriptor cookie encryption scheme. Here are the
       relevant keys:
 
+          # KS/KP_hsc_desc_enc
           client_x = private x25519 key of authorized client
           client_X = public x25519 key of authorized client
+          # KS/KP_hss_desc_enc
           hs_y = private key of ephemeral x25519 keypair of hidden service
           hs_Y = public key of ephemeral x25519 keypair of hidden service
+          # N_hs_desc_enc
           descriptor_cookie = descriptor cookie used to encrypt the descriptor
 
       And here is what the hidden service computes: