diff options
Diffstat (limited to 'rend-spec-v3.txt')
| -rw-r--r-- | rend-spec-v3.txt | 106 |
1 files changed, 52 insertions, 54 deletions
diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index fb570b4..13eb758 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -592,7 +592,7 @@ Table of contents: the public blinded identity key for a service. This key is used as an index in the DHT-like structure of the directory system (see [SUBCRED]). - KP_blind_id, KS_blind_id. + KP_hs_blind_id, KS_hs_blind_id. Descriptor signing key -- A key used to sign hidden service descriptors. This is signed by blinded signing keys. Unlike @@ -603,33 +603,38 @@ 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 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 can get their introduction requests sent to the right service. No keypair is ever used with more than one introduction point. (previously called a "service key" in rend-spec.txt) - KP_hs_intro_tid, KS_hs_intro_tid - ("hidden service introduction point temporary id"). + KP_hs_ipt_sid, KS_hs_ipt_sid + ("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. - KP_hs_intro_ntor, KS_hs_intro_ntor. + 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. - Symmetric keys defined in this document: + 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 - Descriptor encryption keys -- A symmetric encryption key used to - encrypt the body of hidden service descriptors. Derived from the - 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_onion_ntor, KP_onion_ntor). + Onion key -- Short-term encryption keypair (KS_ntor, KP_ntor). (Node) identity key (KP_relayid). @@ -651,7 +656,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 @@ -811,7 +817,7 @@ Table of contents: derived, the uploading or downloading party calculates: for replicanum in 1...hsdir_n_replicas: - hs_index(replicanum) = H("store-at-idx" | + hs_service_index(replicanum) = H("store-at-idx" | blinded_public_key | INT_8(replicanum) | INT_8(period_length) | @@ -825,7 +831,7 @@ Table of contents: Then, for each node listed in the current consensus with the HSDir flag, we compute a directory index for that node as: - hsdir_index(node) = H("node-idx" | node_identity | + hs_relay_index(node) = H("node-idx" | node_identity | shared_random_value | INT_8(period_num) | INT_8(period_length) ) @@ -836,7 +842,7 @@ Table of contents: Finally, for replicanum in 1...hsdir_n_replicas, the hidden service host uploads descriptors to the first hsdir_spread_store nodes whose - indices immediately follow hs_index(replicanum). If any of those + indices immediately follow hs_service_index(replicanum). If any of those nodes have already been selected for a lower-numbered replica of the service, any nodes already chosen are disregarded (i.e. skipped over) when choosing a replica's hsdir_spread_store nodes. @@ -1187,10 +1193,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 @@ -1208,13 +1215,13 @@ Table of contents: If client authorization is disabled, the value here should be "x25519". - "desc-auth-ephemeral-key" SP key NL + "desc-auth-ephemeral-key" SP KP_hs_desc_ephem NL [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,23 +1236,16 @@ 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. - - We now describe the descriptor cookie encryption scheme. Here are the - relevant keys: - - client_x = private x25519 key of authorized client - client_X = public x25519 key of authorized client - hs_y = private key of ephemeral x25519 keypair of hidden service - hs_Y = public key of ephemeral x25519 keypair of hidden service - descriptor_cookie = descriptor cookie used to encrypt the descriptor + 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. - And here is what the hidden service computes: + We now describe the descriptor cookie encryption scheme. Here is what + the hidden service computes: - SECRET_SEED = x25519(hs_y, client_X) + SECRET_SEED = x25519(KS_hs_desc_ephem, KP_hsc_desc_enc) KEYS = KDF(N_hs_subcred | SECRET_SEED, 40) CLIENT-ID = fist 8 bytes of KEYS COOKIE-KEY = last 32 bytes of KEYS @@ -1258,7 +1258,7 @@ Table of contents: - The "encrypted-cookie" field contains the descriptor cookie ciphertext as follows and is encoded in base64: - encrypted-cookie = STREAM(iv, COOKIE-KEY) XOR descriptor_cookie + encrypted-cookie = STREAM(iv, COOKIE-KEY) XOR N_hs_desc_enc. See section [FIRST-LAYER-CLIENT-BEHAVIOR] for the client-side logic of how to decrypt the descriptor cookie. @@ -1348,10 +1348,10 @@ Table of contents: [Exactly once] - A space-separated list of integers denoting CREATE2 cell format numbers - that the server recognizes. Must include at least ntor as described in - tor-spec.txt. See tor-spec section 5.1 for a list of recognized - handshake types. + A space-separated list of integers denoting CREATE2 cell HTYPEs + (handshake types) that the server recognizes. Must include at least + ntor as described in tor-spec.txt. See tor-spec section 5.1 for a list + of recognized handshake types. "intro-auth-required" SP types NL @@ -1360,7 +1360,7 @@ Table of contents: A space-separated list of introduction-layer authentication types; see section [INTRO-AUTH] for more info. A client that does not support at least one of these authentication types will not be able to contact the - host. Defined types are: 'password' and 'ed25519'. + host. Recognized types are: 'ed25519'. "single-onion-service" @@ -1419,7 +1419,7 @@ Table of contents: The certificate is a proposal 220 certificate wrapped in "-----BEGIN ED25519 CERT-----". It contains the introduction - point authentication key (`KP_hs_intro_tid`), signed by + point authentication key (`KP_hs_ipt_sid`), signed by the descriptor signing key (`KP_hs_desc_sign`). The certificate type must be [09], and the signing key extension is mandatory. @@ -1438,7 +1438,7 @@ Table of contents: [Exactly once per introduction point] The key is a base64 encoded curve25519 public key used to encrypt - the introduction request to service. (`KP_hs_intro_ntor`) + the introduction request to service. (`KP_hss_ntor`) "enc-key" SP KeyType SP key.. NL @@ -1458,7 +1458,7 @@ Table of contents: For "ntor" keys, certificate is a proposal 220 certificate wrapped in "-----BEGIN ED25519 CERT-----" armor. The subject key is the the ed25519 equivalent of a curve25519 public - encryption key (`KP_hs_intro_ntor`), with the ed25519 key + encryption key (`KP_hss_ntor`), with the ed25519 key derived using the process in proposal 228 appendix A. The signing key is the descriptor signing key (`KP_hs_desc_sign`). The certificate type must be [0B], and the signing-key @@ -1468,7 +1468,7 @@ Table of contents: constructed the other way around. However, for compatibility with C tor, implementations need to construct it this way. It serves even less point than "auth-key", however, since the - encryption key `KP_hs_intro_ntor` is already available from + encryption key `KP_hss_ntor` is already available from the `enc-key` entry. "legacy-key" NL key NL @@ -2071,10 +2071,8 @@ Table of contents: One mechanism to do so is the credential mechanism, where only users who know the credential for a hidden service may connect at all. - There are two defined authentication types, `ed25519` and `password`. + There is one defined authentication type: `ed25519`. - However, the `password` authentication type is not documented - and ??? ??? ???. 3.4.1. Ed25519-based authentication `ed25519`. |