diff options
Diffstat (limited to 'spec/rend-spec-v3')
17 files changed, 132 insertions, 132 deletions
diff --git a/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md b/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md index 2a1cb72..201fc92 100644 --- a/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md +++ b/spec/rend-spec-v3/deriving-blinded-keys-subcredentials-subcred.md @@ -1,13 +1,13 @@ <a id="rend-spec-v3.txt-2.1"></a> -## Deriving blinded keys and subcredentials [SUBCRED] +## Deriving blinded keys and subcredentials \[SUBCRED\] -In each time period (see [TIME-PERIODS] for a definition of time +In each time period (see \[TIME-PERIODS\] for a definition of time periods), a hidden service host uses a different blinded private key to sign its directory information, and clients use a different blinded public key as the index for fetching that information. -For a candidate for a key derivation method, see Appendix [KEYBLIND]. +For a candidate for a key derivation method, see Appendix \[KEYBLIND\]. Additionally, clients and hosts derive a subcredential for each period. Knowledge of the subcredential is needed to decrypt hidden @@ -58,7 +58,7 @@ Which Tor servers hosts a hidden service depends on: <a id="rend-spec-v3.txt-2.2.1"></a> -### Dividing time into periods [TIME-PERIODS] +### Dividing time into periods \[TIME-PERIODS\] To prevent a single set of hidden service directory from becoming a target by adversaries looking to permanently censor a hidden service, @@ -79,7 +79,7 @@ dividing by the time period (effectively making "our" epoch start at Jan Example: If the current time is 2016-04-13 11:15:01 UTC, making the seconds since the epoch 1460546101, and the number of minutes since the epoch -24342435. We then subtract the "rotation time offset" of 12*60 minutes from +24342435\. We then subtract the "rotation time offset" of 12\*60 minutes from the minutes since the epoch, to get 24341715. If the current time period length is 1440 minutes, by doing the division we see that we are currently in time period number 16903. @@ -90,17 +90,17 @@ after the epoch, at 2016-04-12 12:00 UTC, and ended at 16904*1440*60 + <a id="rend-spec-v3.txt-2.2.2"></a> -### When to publish a hidden service descriptor [WHEN-HSDESC] +### When to publish a hidden service descriptor \[WHEN-HSDESC\] Hidden services periodically publish their descriptor to the responsible HSDirs. The set of responsible HSDirs is determined as specified in -[WHERE-HSDESC]. +\[WHERE-HSDESC\]. Specifically, every time a hidden service publishes its descriptor, it also sets up a timer for a random time between 60 minutes and 120 minutes in the future. When the timer triggers, the hidden service needs to publish its descriptor again to the responsible HSDirs for that time period. -[TODO: Control republish period using a consensus parameter?] +\[TODO: Control republish period using a consensus parameter?\] <a id="rend-spec-v3.txt-2.2.2.1"></a> @@ -118,14 +118,14 @@ Hence, services maintain two active descriptors at every point. Clients on the other hand, don't have a notion of overlapping descriptors, and instead always download the descriptor for the current time period and shared random value. It's the job of the service to ensure that descriptors will be -available for all clients. See section [FETCHUPLOADDESC] for how this is +available for all clients. See section \[FETCHUPLOADDESC\] for how this is achieved. -[TODO: What to do when we run multiple hidden services in a single host?] +\[TODO: What to do when we run multiple hidden services in a single host?\] <a id="rend-spec-v3.txt-2.2.3"></a> -### Where to publish a hidden service descriptor [WHERE-HSDESC] +### Where to publish a hidden service descriptor \[WHERE-HSDESC\] This section specifies how the HSDir hash ring is formed at any given time. Whenever a time value is needed (e.g. to get the current time period @@ -155,10 +155,10 @@ derived, the uploading or downloading party calculates: INT_8(period_num) ) ``` -where blinded_public_key is specified in section [KEYBLIND], period_length +where blinded_public_key is specified in section \[KEYBLIND\], period_length is the length of the time period in minutes, and period_num is calculated using the current consensus "valid-after" as specified in section -[TIME-PERIODS]. +\[TIME-PERIODS\]. Then, for each node listed in the current consensus with the HSDir flag, we compute a directory index for that node as: @@ -171,7 +171,7 @@ we compute a directory index for that node as: ``` where shared_random_value is the shared value generated by the authorities -in section [PUB-SHAREDRANDOM], and node_identity is the ed25519 identity +in section \[PUB-SHAREDRANDOM\], and node_identity is the ed25519 identity key of the node. Finally, for replicanum in 1...hsdir_n_replicas, the hidden service @@ -190,7 +190,7 @@ choosing the spread for a replica. <a id="rend-spec-v3.txt-2.2.4"></a> -### Using time periods and SRVs to fetch/upload HS descriptors [FETCHUPLOADDESC] +### Using time periods and SRVs to fetch/upload HS descriptors \[FETCHUPLOADDESC\] Hidden services and clients need to make correct use of time periods (TP) and shared random values (SRVs) to successfully fetch and upload @@ -202,7 +202,7 @@ of clients and services due to system clock. Whenever time-based decisions are taken in this section, assume that they are consensus times and not system times. -As [PUB-SHAREDRANDOM] specifies, consensuses contain two shared random +As \[PUB-SHAREDRANDOM\] specifies, consensuses contain two shared random values (the current one and the previous one). Hidden services and clients are asked to match these shared random values with descriptor time periods and use the right SRV when fetching/uploading descriptors. This section @@ -228,7 +228,7 @@ Let's start with an illustration of the system: <a id="rend-spec-v3.txt-2.2.4.1"></a> -#### Client behavior for fetching descriptors [CLIENTFETCH] +#### Client behavior for fetching descriptors \[CLIENTFETCH\] And here is how clients use TPs and SRVs to fetch descriptors: @@ -258,7 +258,7 @@ after SRV#2, it will still use TP#1 and SRV#1. <a id="rend-spec-v3.txt-2.2.4.2"></a> -#### Service behavior for uploading descriptors [SERVICEUPLOAD] +#### Service behavior for uploading descriptors \[SERVICEUPLOAD\] As discussed above, services maintain two active descriptors at any time. We call these the "first" and "second" service descriptors. Services rotate @@ -272,7 +272,7 @@ values based on their position in the graph above. Here is the logic: <a id="rend-spec-v3.txt-2.2.4.2.1"></a> -##### First descriptor upload logic [FIRSTDESCUPLOAD] +##### First descriptor upload logic \[FIRSTDESCUPLOAD\] Here is the service logic for uploading its first descriptor: @@ -308,7 +308,7 @@ first descriptor using TP#1 and SRV#1. <a id="rend-spec-v3.txt-2.2.4.2.2"></a> -##### Second descriptor upload logic [SECONDDESCUPLOAD] +##### Second descriptor upload logic \[SECONDDESCUPLOAD\] Here is the service logic for uploading its second descriptor: @@ -342,7 +342,7 @@ second descriptor using TP#2 and SRV#2. <a id="rend-spec-v3.txt-2.2.4.3"></a> -#### Directory behavior for handling descriptor uploads [DIRUPLOAD] +#### Directory behavior for handling descriptor uploads \[DIRUPLOAD\] Upon receiving a hidden service descriptor publish request, directories MUST check the following: @@ -368,12 +368,12 @@ necessary client credentials (for decrypting the second layer). <a id="rend-spec-v3.txt-2.2.5"></a> -### Expiring hidden service descriptors [EXPIRE-DESC] +### Expiring hidden service descriptors \[EXPIRE-DESC\] Hidden services set their descriptor's "descriptor-lifetime" field to 180 minutes (3 hours). Hidden services ensure that their descriptor will remain valid in the HSDir caches, by republishing their descriptors periodically as -specified in [WHEN-HSDESC]. +specified in \[WHEN-HSDESC\]. Hidden services MUST also keep their introduction circuits alive for as long as descriptors including those intro points are valid (even if that's after @@ -415,4 +415,4 @@ The right way for clients to detect such fraudulent addresses (which should only occur malevolently and never naturally) is to extract the ed25519 public key from the onion address and multiply it by the ed25519 group order and ensure that the result is the ed25519 identity element. For more -details, please see [TORSION-REFS]. +details, please see \[TORSION-REFS\]. diff --git a/spec/rend-spec-v3/encoding-onion-addresses-onionaddress.md b/spec/rend-spec-v3/encoding-onion-addresses-onionaddress.md index 7919b73..14b3c44 100644 --- a/spec/rend-spec-v3/encoding-onion-addresses-onionaddress.md +++ b/spec/rend-spec-v3/encoding-onion-addresses-onionaddress.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-6"></a> -# Encoding onion addresses [ONIONADDRESS] +# Encoding onion addresses \[ONIONADDRESS\] The onion address of a hidden service includes its identity public key, a version field and a basic checksum. All this information is then base32 @@ -24,4 +24,4 @@ encoded as shown below: ``` For more information about this encoding, please see our discussion thread -at [ONIONADDRESS-REFS]. +at \[ONIONADDRESS-REFS\]. diff --git a/spec/rend-spec-v3/generating-publishing-hidden-service-descriptors.md b/spec/rend-spec-v3/generating-publishing-hidden-service-descriptors.md index a540bec..8b1d75a 100644 --- a/spec/rend-spec-v3/generating-publishing-hidden-service-descriptors.md +++ b/spec/rend-spec-v3/generating-publishing-hidden-service-descriptors.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2"></a> -# Generating and publishing hidden service descriptors [HSDIR] +# Generating and publishing hidden service descriptors \[HSDIR\] Hidden service descriptors follow the same metaformat as other Tor directory objects. They are published anonymously to Tor servers with the diff --git a/spec/rend-spec-v3/hidden-service-descriptors-encryption-format-hs-desc-enc.md b/spec/rend-spec-v3/hidden-service-descriptors-encryption-format-hs-desc-enc.md index 719d4fa..834aceb 100644 --- a/spec/rend-spec-v3/hidden-service-descriptors-encryption-format-hs-desc-enc.md +++ b/spec/rend-spec-v3/hidden-service-descriptors-encryption-format-hs-desc-enc.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2.5"></a> -## Hidden service descriptors: encryption format [HS-DESC-ENC] +## Hidden service descriptors: encryption format \[HS-DESC-ENC\] Hidden service descriptors are protected by two layers of encryption. Clients need to decrypt both layers to connect to the hidden service. @@ -12,7 +12,7 @@ and protects against entities that do not possess valid client credentials. <a id="rend-spec-v3.txt-2.5.1"></a> -### First layer of encryption [HS-DESC-FIRST-LAYER] +### First layer of encryption \[HS-DESC-FIRST-LAYER\] The first layer of HS descriptor encryption is designed to protect descriptor confidentiality against entities who don't know the public @@ -23,7 +23,7 @@ identity key of the hidden service. #### First layer encryption logic The encryption keys and format for the first layer of encryption are -generated as specified in [HS-DESC-ENCRYPTION-KEYS] with customization +generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization parameters: ```text @@ -31,8 +31,8 @@ parameters: STRING_CONSTANT = "hsdir-superencrypted-data" ``` -The encryption scheme in [HS-DESC-ENCRYPTION-KEYS] uses the service -credential which is derived from the public identity key (see [SUBCRED]) to +The encryption scheme in \[HS-DESC-ENCRYPTION-KEYS\] uses the service +credential which is derived from the public identity key (see \[SUBCRED\]) to ensure that only entities who know the public identity key can decrypt the first descriptor layer. @@ -64,7 +64,7 @@ Here are all the supported fields: "desc-auth-type" SP type NL -[Exactly once] +\[Exactly once\] ```text This field contains the type of authorization used to protect the @@ -138,7 +138,7 @@ Here are all the supported fields: <a id="rend-spec-v3.txt-2.5.1.3"></a> -#### Client behavior [FIRST-LAYER-CLIENT-BEHAVIOR] +#### Client behavior \[FIRST-LAYER-CLIENT-BEHAVIOR\] ```text The goal of clients at this stage is to decrypt the "encrypted" field as @@ -183,7 +183,7 @@ Here are all the supported fields: <a id="rend-spec-v3.txt-2.5.2"></a> -### Second layer of encryption [HS-DESC-SECOND-LAYER] +### Second layer of encryption \[HS-DESC-SECOND-LAYER\] The second layer of descriptor encryption is designed to protect descriptor confidentiality against unauthorized clients. If client authorization is @@ -199,7 +199,7 @@ does not offer any additional security, but is still used. #### Second layer encryption keys The encryption keys and format for the second layer of encryption are -generated as specified in [HS-DESC-ENCRYPTION-KEYS] with customization +generated as specified in \[HS-DESC-ENCRYPTION-KEYS\] with customization parameters as follows: ```text @@ -220,7 +220,7 @@ list of intro points etc. The plaintext has the following format: "create2-formats" SP formats NL -[Exactly once] +\[Exactly once\] ```text A space-separated list of integers denoting CREATE2 cell HTYPEs @@ -387,7 +387,7 @@ Other encryption and authentication key formats are allowed; clients should ignore ones they do not recognize. Clients who manage to extract the introduction points of the hidden service -can proceed with the introduction protocol as specified in [INTRO-PROTOCOL]. +can proceed with the introduction protocol as specified in \[INTRO-PROTOCOL\]. Compatibility note: At least some versions of OnionBalance do not include a final newline when generating this inner plaintext section; other @@ -396,7 +396,7 @@ newline. <a id="rend-spec-v3.txt-2.5.3"></a> -### Deriving hidden service descriptor encryption keys [HS-DESC-ENCRYPTION-KEYS] +### Deriving hidden service descriptor encryption keys \[HS-DESC-ENCRYPTION-KEYS\] In this section we present the generic encryption format for hidden service descriptors. We use the same encryption format in both encryption layers, @@ -439,7 +439,7 @@ Here is the key generation logic: <a id="rend-spec-v3.txt-2.5.4"></a> -### Number of introduction points [NUM_INTRO_POINT] +### Number of introduction points \[NUM_INTRO_POINT\] This section defines how many introduction points an hidden service descriptor can have at minimum, by default and the maximum: diff --git a/spec/rend-spec-v3/hidden-service-descriptors-outer-wrapper-desc-outer.md b/spec/rend-spec-v3/hidden-service-descriptors-outer-wrapper-desc-outer.md index f981e11..5f4b5de 100644 --- a/spec/rend-spec-v3/hidden-service-descriptors-outer-wrapper-desc-outer.md +++ b/spec/rend-spec-v3/hidden-service-descriptors-outer-wrapper-desc-outer.md @@ -1,13 +1,13 @@ <a id="rend-spec-v3.txt-2.4"></a> -## Hidden service descriptors: outer wrapper [DESC-OUTER] +## Hidden service descriptors: outer wrapper \[DESC-OUTER\] The format for a hidden service descriptor is as follows, using the meta-format from dir-spec.txt. "hs-descriptor" SP version-number NL -[At start, exactly once.] +\[At start, exactly once.\] ```text The version-number is a 32 bit unsigned integer indicating the version diff --git a/spec/rend-spec-v3/hidden-service-directory-format-hidservdir-format.md b/spec/rend-spec-v3/hidden-service-directory-format-hidservdir-format.md index 9f6cfc6..f5c06f4 100644 --- a/spec/rend-spec-v3/hidden-service-directory-format-hidservdir-format.md +++ b/spec/rend-spec-v3/hidden-service-directory-format-hidservdir-format.md @@ -1,17 +1,17 @@ <a id="rend-spec-v3.txt-F"></a> -# Appendix F: Hidden service directory format [HIDSERVDIR-FORMAT] +# Appendix F: Hidden service directory format \[HIDSERVDIR-FORMAT\] This appendix section specifies the contents of the HiddenServiceDir directory: -- "hostname" [FILE] +- "hostname" \[FILE\] This file contains the onion address of the onion service. -- "private_key_ed25519" [FILE] +- "private_key_ed25519" \[FILE\] This file contains the private master ed25519 key of the onion service. -[TODO: Offline keys] +\[TODO: Offline keys\] ```text - "./authorized_clients/" [DIRECTORY] @@ -25,6 +25,6 @@ file for each authorized client. Each such file contains the public key of the respective client. The files are transmitted to the service operator by the client. -See section [CLIENT-AUTH-MGMT] for more details and the format of the client file. +See section \[CLIENT-AUTH-MGMT\] for more details and the format of the client file. (NOTE: client authorization is implemented as of 0.3.5.1-alpha.) diff --git a/spec/rend-spec-v3/hidden-services-overview-preliminaries.md b/spec/rend-spec-v3/hidden-services-overview-preliminaries.md index 382c732..cf16ff4 100644 --- a/spec/rend-spec-v3/hidden-services-overview-preliminaries.md +++ b/spec/rend-spec-v3/hidden-services-overview-preliminaries.md @@ -70,8 +70,8 @@ We write sequences of bytes in two ways: ``` We use INT_N(val) to denote the network (big-endian) encoding of the -unsigned integer "val" in N bytes. For example, INT_4(1337) is [00 00 -05 39]. Values are truncated like so: val % (2 ^ (N * 8)). For example, +unsigned integer "val" in N bytes. For example, INT_4(1337) is \[00 00 +05 39\]. Values are truncated like so: val % (2 ^ (N * 8)). For example, INT_4(42) is 42 % 4294967296 (32 bit). <a id="rend-spec-v3.txt-0.3"></a> @@ -133,21 +133,21 @@ This specification uses the following cryptographic building blocks: where k_len is htonll(len(k)). ``` - When we need a particular MAC key length below, we choose - MAC_KEY_LEN=32 (256 bits). +When we need a particular MAC key length below, we choose +MAC_KEY_LEN=32 (256 bits). For legacy purposes, we specify compatibility with older versions of the Tor introduction point and rendezvous point protocols. These used RSA1024, DH1024, AES128, and SHA1, as discussed in rend-spec.txt. -As in [proposal 220], all signatures are generated not over strings +As in \[proposal 220\], all signatures are generated not over strings themselves, but over those strings prefixed with a distinguishing value. <a id="rend-spec-v3.txt-0.4"></a> -## Protocol building blocks [BUILDING-BLOCKS] +## Protocol building blocks \[BUILDING-BLOCKS\] In sections below, we need to transmit the locations and identities of Tor nodes. We do so in the link identification format used by @@ -162,8 +162,8 @@ EXTEND2 cells in the Tor protocol. ``` Link specifier types are as described in tor-spec.txt. Every set of -link specifiers SHOULD include at minimum specifiers of type [00] -(TLS-over-TCP, IPv4), [02] (legacy node identity) and [03] (ed25519 +link specifiers SHOULD include at minimum specifiers of type \[00\] +(TLS-over-TCP, IPv4), \[02\] (legacy node identity) and \[03\] (ed25519 identity key). Sets of link specifiers without these three types SHOULD be rejected. @@ -308,8 +308,8 @@ editing help from Tim Wilson-Brown ("teor"), ``` -[XXX Acknowledge the huge bunch of people working on 8106.] -[XXX Acknowledge the huge bunch of people working on 8244.] +\[XXX Acknowledge the huge bunch of people working on 8106.\] +\[XXX Acknowledge the huge bunch of people working on 8244.\] Please forgive me if I've missed you; please forgive me if I've misunderstood your best ideas here too. diff --git a/spec/rend-spec-v3/introduction-protocol-intro-protocol.md b/spec/rend-spec-v3/introduction-protocol-intro-protocol.md index e1977fc..f4e6358 100644 --- a/spec/rend-spec-v3/introduction-protocol-intro-protocol.md +++ b/spec/rend-spec-v3/introduction-protocol-intro-protocol.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-3"></a> -# The introduction protocol [INTRO-PROTOCOL] +# The introduction protocol \[INTRO-PROTOCOL\] The introduction protocol proceeds in three steps. @@ -30,11 +30,11 @@ the introduction request to the client. <a id="rend-spec-v3.txt-3.1"></a> -## Registering an introduction point [REG_INTRO_POINT] +## Registering an introduction point \[REG_INTRO_POINT\] <a id="rend-spec-v3.txt-3.1.1"></a> -### Extensible ESTABLISH_INTRO protocol. [EST_INTRO] +### Extensible ESTABLISH_INTRO protocol. \[EST_INTRO\] When a hidden service is establishing a new introduction point, it sends an ESTABLISH_INTRO cell with the following contents: @@ -115,7 +115,7 @@ later in INTRODUCE1 cells. <a id="rend-spec-v3.txt-3.1.1.1"></a> -#### Denial-of-Service Defense Extension. [EST_INTRO_DOS_EXT] +#### Denial-of-Service Defense Extension. \[EST_INTRO_DOS_EXT\] This extension can be used to send Denial-of-Service (DoS) parameters to the introduction point in order for it to apply them for the introduction @@ -127,7 +127,7 @@ defined as follow: EXT_FIELD_TYPE: -[01] -- Denial-of-Service Parameters. +\[01\] -- Denial-of-Service Parameters. ```text If this flag is set, the extension should be used by the introduction @@ -189,7 +189,7 @@ Introduced in tor-0.4.2.1-alpha. Tor nodes should also support an older version of the ESTABLISH_INTRO cell, first documented in rend-spec.txt. New hidden service hosts must use this format when establishing introduction points at older -Tor nodes that do not support the format above in [EST_INTRO]. +Tor nodes that do not support the format above in \[EST_INTRO\]. In this older protocol, an ESTABLISH_INTRO cell contains: @@ -215,7 +215,7 @@ authentication keys. <a id="rend-spec-v3.txt-3.1.3"></a> -### Acknowledging establishment of introduction point [INTRO_ESTABLISHED] +### Acknowledging establishment of introduction point \[INTRO_ESTABLISHED\] After setting up an introduction circuit, the introduction point reports its status back to the hidden service host with an INTRO_ESTABLISHED cell. @@ -232,15 +232,15 @@ The INTRO_ESTABLISHED cell has the following contents: Older versions of Tor send back an empty INTRO_ESTABLISHED cell instead. Services must accept an empty INTRO_ESTABLISHED cell from a legacy relay. -[The above paragraph is obsolete and refers to a workaround for -now-obsolete Tor relay versions. It is included for historical reasons.] +\[The above paragraph is obsolete and refers to a workaround for +now-obsolete Tor relay versions. It is included for historical reasons.\] The same rules for multiplicity, ordering, and handling unknown types -apply to the extension fields here as described [EST_INTRO] above. +apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2"></a> -## Sending an INTRODUCE1 cell to the introduction point. [SEND_INTRO1] +## Sending an INTRODUCE1 cell to the introduction point. \[SEND_INTRO1\] In order to participate in the introduction protocol, a client must know the following: @@ -267,7 +267,7 @@ or that its request will not succeed. <a id="rend-spec-v3.txt-3.2.1"></a> -### INTRODUCE1 cell format [FMT_INTRO1] +### INTRODUCE1 cell format \[FMT_INTRO1\] When a client is connecting to an introduction point, INTRODUCE1 cells should be of the form: @@ -285,8 +285,8 @@ should be of the form: ENCRYPTED [Up to end of relay payload] ``` -AUTH_KEY_TYPE is defined as in [EST_INTRO]. Currently, the only value of -AUTH_KEY_TYPE for this cell is an Ed25519 public key [02]. +AUTH_KEY_TYPE is defined as in \[EST_INTRO\]. Currently, the only value of +AUTH_KEY_TYPE for this cell is an Ed25519 public key \[02\]. The LEGACY_KEY_ID field is used to distinguish between legacy and new style INTRODUCE1 cells. In new style INTRODUCE1 cells, LEGACY_KEY_ID is 20 zero @@ -306,11 +306,11 @@ change the order or multiplicity of the extensions sent by the client.) The same rules for multiplicity, ordering, and handling unknown types -apply to the extension fields here as described [EST_INTRO] above. +apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.2.2"></a> -### INTRODUCE_ACK cell format. [INTRO_ACK] +### INTRODUCE_ACK cell format. \[INTRO_ACK\] An INTRODUCE_ACK cell has the following fields: @@ -331,11 +331,11 @@ An INTRODUCE_ACK cell has the following fields: ``` The same rules for multiplicity, ordering, and handling unknown types -apply to the extension fields here as described [EST_INTRO] above. +apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.3"></a> -## Processing an INTRODUCE2 cell at the hidden service. [PROCESS_INTRO2] +## Processing an INTRODUCE2 cell at the hidden service. \[PROCESS_INTRO2\] Upon receiving an INTRODUCE2 cell, the hidden service host checks whether the AUTH_KEY or LEGACY_KEY_ID field matches the keys for this @@ -353,8 +353,8 @@ contents of the cell as having been unmodified since they left the client. There may be multiple ways of decrypting the ENCRYPTED field, depending on the chosen type of the encryption key. Requirements for an introduction handshake protocol are described in -[INTRO-HANDSHAKE-REQS]. We specify one below in section -[NTOR-WITH-EXTRA-DATA]. +\[INTRO-HANDSHAKE-REQS\]. We specify one below in section +\[NTOR-WITH-EXTRA-DATA\]. The decrypted plaintext must have the form: @@ -380,7 +380,7 @@ Upon processing this plaintext, the hidden service makes sure that any required authentication is present in the extension fields, and then extends a rendezvous circuit to the node described in the LSPEC fields, using the ONION_KEY to complete the extension. As mentioned -in [BUILDING-BLOCKS], the "TLS-over-TCP, IPv4" and "Legacy node +in \[BUILDING-BLOCKS\], the "TLS-over-TCP, IPv4" and "Legacy node identity" specifiers must be present. As of 0.4.1.1-alpha, clients include both IPv4 and IPv6 link specifiers @@ -402,7 +402,7 @@ NOT modify it. The ONION_KEY_TYPE field is: -[01] NTOR: ONION_KEY is 32 bytes long. +\[01\] NTOR: ONION_KEY is 32 bytes long. The ONION_KEY field describes the onion key that must be used when extending to the rendezvous point. It must be of a type listed as @@ -428,11 +428,11 @@ will have: ``` The same rules for multiplicity, ordering, and handling unknown types -apply to the extension fields here as described [EST_INTRO] above. +apply to the extension fields here as described \[EST_INTRO\] above. <a id="rend-spec-v3.txt-3.3.1"></a> -### Introduction handshake encryption requirements [INTRO-HANDSHAKE-REQS] +### Introduction handshake encryption requirements \[INTRO-HANDSHAKE-REQS\] When decoding the encrypted information in an INTRODUCE2 cell, a hidden service host must be able to: @@ -504,7 +504,7 @@ and computes: ``` Substituting those fields into the INTRODUCE1 cell body format -described in [FMT_INTRO1] above, we have +described in \[FMT_INTRO1\] above, we have ```text LEGACY_KEY_ID [20 bytes] @@ -522,7 +522,7 @@ described in [FMT_INTRO1] above, we have MAC [MAC_LEN bytes] ``` -(This format is as documented in [FMT_INTRO1] above, except that here +(This format is as documented in \[FMT_INTRO1\] above, except that here we describe how to build the ENCRYPTED portion.) Here, the encryption key plays the role of B in the regular ntor @@ -570,7 +570,7 @@ introduction point encryption key 'b' to compute: ``` These fields will be sent to the client in a RENDEZVOUS1 cell using the -HANDSHAKE_INFO element (see [JOIN_REND]). +HANDSHAKE_INFO element (see \[JOIN_REND\]). The hidden service host now also knows the keys generated by the handshake, which it will use to encrypt and authenticate data @@ -580,7 +580,7 @@ AES-128 and SHA1 for this hop, we use AES-256 and SHA3-256. <a id="rend-spec-v3.txt-3.4"></a> -## Authentication during the introduction phase. [INTRO-AUTH] +## Authentication during the introduction phase. \[INTRO-AUTH\] Hidden services may restrict access only to authorized users. One mechanism to do so is the credential mechanism, where only users who @@ -601,7 +601,7 @@ the number of keys a user needs to have.) To authenticate with an Ed25519 private key, the user must include an extension field in the encrypted part of the INTRODUCE1 cell with an -EXT_FIELD_TYPE type of [02] and the contents: +EXT_FIELD_TYPE type of \[02\] and the contents: ```text Nonce [16 bytes] @@ -610,8 +610,8 @@ EXT_FIELD_TYPE type of [02] and the contents: ``` Nonce is a random value. Pubkey is the public key that will be used -to authenticate. [TODO: should this be an identifier for the public -key instead?] Signature is the signature, using Ed25519, of: +to authenticate. \[TODO: should this be an identifier for the public +key instead?\] Signature is the signature, using Ed25519, of: ```text "hidserv-userauth-ed25519" diff --git a/spec/rend-spec-v3/managing-authorized-client-data-client-auth-mgmt.md b/spec/rend-spec-v3/managing-authorized-client-data-client-auth-mgmt.md index 2051e86..1cffce4 100644 --- a/spec/rend-spec-v3/managing-authorized-client-data-client-auth-mgmt.md +++ b/spec/rend-spec-v3/managing-authorized-client-data-client-auth-mgmt.md @@ -1,11 +1,11 @@ <a id="rend-spec-v3.txt-G"></a> -# Appendix G: Managing authorized client data [CLIENT-AUTH-MGMT] +# Appendix G: Managing authorized client data \[CLIENT-AUTH-MGMT\] Hidden services and clients can configure their authorized client data either using the torrc, or using the control port. This section presents a suggested scheme for configuring client authorization. Please see appendix -[HIDSERVDIR-FORMAT] for more information about relevant hidden service files. +\[HIDSERVDIR-FORMAT\] for more information about relevant hidden service files. (NOTE: client authorization is implemented as of 0.3.5.1-alpha.) diff --git a/spec/rend-spec-v3/numeric-values-reserved-this-document.md b/spec/rend-spec-v3/numeric-values-reserved-this-document.md index 1e11c73..7a2f01f 100644 --- a/spec/rend-spec-v3/numeric-values-reserved-this-document.md +++ b/spec/rend-spec-v3/numeric-values-reserved-this-document.md @@ -2,4 +2,4 @@ # Appendix D: Numeric values reserved in this document -[TODO: collect all the lists of commands and values mentioned above] +\[TODO: collect all the lists of commands and values mentioned above\] diff --git a/spec/rend-spec-v3/open-questions.md b/spec/rend-spec-v3/open-questions.md index 140b1f5..b95717a 100644 --- a/spec/rend-spec-v3/open-questions.md +++ b/spec/rend-spec-v3/open-questions.md @@ -3,18 +3,18 @@ # Open Questions Scaling hidden services is hard. There are on-going discussions that -you might be able to help with. See [SCALING-REFS]. +you might be able to help with. See \[SCALING-REFS\]. How can we improve the HSDir unpredictability design proposed in -[SHAREDRANDOM]? See [SHAREDRANDOM-REFS] for discussion. +\[SHAREDRANDOM\]? See \[SHAREDRANDOM-REFS\] for discussion. How can hidden service addresses become memorable while retaining their self-authenticating and decentralized nature? See -[HUMANE-HSADDRESSES-REFS] for some proposals; many more are possible. +\[HUMANE-HSADDRESSES-REFS\] for some proposals; many more are possible. Hidden Services are pretty slow. Both because of the lengthy setup procedure and because the final circuit has 6 hops. How can we make -the Hidden Service protocol faster? See [PERFORMANCE-REFS] for some +the Hidden Service protocol faster? See \[PERFORMANCE-REFS\] for some suggestions. References: diff --git a/spec/rend-spec-v3/protocol-overview.md b/spec/rend-spec-v3/protocol-overview.md index 1c03e49..173240e 100644 --- a/spec/rend-spec-v3/protocol-overview.md +++ b/spec/rend-spec-v3/protocol-overview.md @@ -47,7 +47,7 @@ communicate data on those streams, and so forth. <a id="rend-spec-v3.txt-1.2"></a> -## In more detail: naming hidden services [NAMING] +## In more detail: naming hidden services \[NAMING\] A hidden service's name is its long term master identity key. This is encoded as a hostname by encoding the entire key in Base 32, including a @@ -73,7 +73,7 @@ their length. An older name might look like: <a id="rend-spec-v3.txt-1.3"></a> -## In more detail: Access control [IMD:AC] +## In more detail: Access control \[IMD:AC\] Access control for a hidden service is imposed at multiple points through the process above. Furthermore, there is also the option to impose @@ -108,7 +108,7 @@ require the client to prove knowledge of a pre-shared private key. <a id="rend-spec-v3.txt-1.4"></a> -## In more detail: Distributing hidden service descriptors. [IMD:DIST] +## In more detail: Distributing hidden service descriptors. \[IMD:DIST\] Periodically, hidden service descriptors become stored at different locations to prevent a single directory or small set of directories @@ -118,14 +118,14 @@ For each period, the Tor directory authorities agree upon a collaboratively generated random value. (See section 2.3 for a description of how to incorporate this value into the voting practice; generating the value is described in other proposals, -including [SHAREDRANDOM-REFS].) That value, combined with hidden service +including \[SHAREDRANDOM-REFS\].) That value, combined with hidden service directories' public identity keys, determines each HSDir's position in the hash ring for descriptors made in that period. Each hidden service's descriptors are placed into the ring in positions based on the key that was used to sign them. Note that hidden service descriptors are not signed with the services' public -keys directly. Instead, we use a key-blinding system [KEYBLIND] to +keys directly. Instead, we use a key-blinding system \[KEYBLIND\] to create a new key-of-the-day for each hidden service. Any client that knows the hidden service's public identity key can derive these blinded signing keys for a given period. It should be impossible to derive @@ -159,7 +159,7 @@ This design is compatible with our current approaches for scaling hidden services. Specifically, hidden service operators can use onionbalance to achieve high availability between multiple nodes on the HSDir layer. Furthermore, operators can use proposal 255 to load balance their -hidden services on the introduction layer. See [SCALING-REFS] for further +hidden services on the introduction layer. See \[SCALING-REFS\] for further discussions on this topic and alternative designs. ```text @@ -183,7 +183,7 @@ which are used to sign descriptor signing keys. In order to operate a hidden service, the operator can generate in advance a number of blinded signing keys and descriptor signing -keys (and their credentials; see [DESC-OUTER] and [HS-DESC-ENC] +keys (and their credentials; see \[DESC-OUTER\] and \[HS-DESC-ENC\] below), and their corresponding descriptor encryption keys, and export those to the hidden service hosts. @@ -215,9 +215,9 @@ discussion.) ## In more detail: A menagerie of keys -[In the text below, an "encryption keypair" is roughly "a keypair you +\[In the text below, an "encryption keypair" is roughly "a keypair you can do Diffie-Hellman with" and a "signing keypair" is roughly "a -keypair you can do ECDSA with."] +keypair you can do ECDSA with."\] Public/private keypairs defined in this document: @@ -292,7 +292,7 @@ Public/private keypairs defined in this document: <a id="rend-spec-v3.txt-1.9.1"></a> -### In even more detail: Client authorization keys [CLIENT-AUTH] +### In even more detail: Client authorization keys \[CLIENT-AUTH\] When client authorization is enabled, each authorized client of a hidden service has two more asymmetric keypairs which are shared with the hidden @@ -320,9 +320,9 @@ The right way to exchange these keys is to have the client generate keys and send the corresponding public keys to the hidden service out-of-band. An easier but less secure way of doing this exchange would be to have the hidden service generate the keypairs and pass the corresponding private keys -to its clients. See section [CLIENT-AUTH-MGMT] for more details on how these +to its clients. See section \[CLIENT-AUTH-MGMT\] for more details on how these keys should be managed. -[TODO: Also specify stealth client authorization.] +\[TODO: Also specify stealth client authorization.\] (NOTE: client authorization is implemented as of 0.3.5.1-alpha.) diff --git a/spec/rend-spec-v3/publishing-shared-random-values-pub-sharedrandom.md b/spec/rend-spec-v3/publishing-shared-random-values-pub-sharedrandom.md index dce072c..707c7da 100644 --- a/spec/rend-spec-v3/publishing-shared-random-values-pub-sharedrandom.md +++ b/spec/rend-spec-v3/publishing-shared-random-values-pub-sharedrandom.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-2.3"></a> -## Publishing shared random values [PUB-SHAREDRANDOM] +## Publishing shared random values \[PUB-SHAREDRANDOM\] Our design for limiting the predictability of HSDir upload locations relies on a shared random value (SRV) that isn't predictable in advance or @@ -8,7 +8,7 @@ too influenceable by an attacker. The authorities must run a protocol to generate such a value at least once per hsdir period. Here we describe how they publish these values; the procedure they use to generate them can change independently of the rest of this -specification. For more information see [SHAREDRANDOM-REFS]. +specification. For more information see \[SHAREDRANDOM-REFS\]. According to proposal 250, we add two new lines in consensuses: @@ -31,7 +31,7 @@ SRV = H("shared-random-disaster" | INT_8(period_length) | INT_8(period_num)) where period_length is the length of a time period in minutes, rounded down; period_num is calculated as specified in -[TIME-PERIODS] for the wanted shared random value that could not be +\[TIME-PERIODS\] for the wanted shared random value that could not be found originally. <a id="rend-spec-v3.txt-2.3.2"></a> diff --git a/spec/rend-spec-v3/recommendations-for-searching-for-vanity-onions.md b/spec/rend-spec-v3/recommendations-for-searching-for-vanity-onions.md index 3c7142b..f07d108 100644 --- a/spec/rend-spec-v3/recommendations-for-searching-for-vanity-onions.md +++ b/spec/rend-spec-v3/recommendations-for-searching-for-vanity-onions.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-C"></a> -# Appendix C: Recommendations for searching for vanity .onions [VANITY] +# Appendix C: Recommendations for searching for vanity .onions \[VANITY\] EDITORIAL NOTE: The author thinks that it's silly to brute-force the keyspace for a key that, when base-32 encoded, spells out the name of @@ -30,16 +30,16 @@ While pk does not satisfy X: Return sk, pk. ``` -We add 8 and 8*B, rather than 1 and B, so that sk is always a valid +We add 8 and 8\*B, rather than 1 and B, so that sk is always a valid Curve25519 private key, with the lowest 3 bits equal to 0. -This algorithm is safe [source: djb, personal communication] [TODO: -Make sure I understood correctly!] so long as only the final (sk,pk) +This algorithm is safe \[source: djb, personal communication\] \[TODO: +Make sure I understood correctly!\] so long as only the final (sk,pk) pair is used, and all previous values are discarded. To parallelize this algorithm, start with an independent (sk,pk) pair generated for each independent thread, and let each search proceed independently. -See [VANITY-REFS] for a reference implementation of this vanity .onion +See \[VANITY-REFS\] for a reference implementation of this vanity .onion search scheme. diff --git a/spec/rend-spec-v3/rendezvous-protocol.md b/spec/rend-spec-v3/rendezvous-protocol.md index 316bcf2..683d9e4 100644 --- a/spec/rend-spec-v3/rendezvous-protocol.md +++ b/spec/rend-spec-v3/rendezvous-protocol.md @@ -21,12 +21,12 @@ but use an anonymous 3-hop circuit if: <a id="rend-spec-v3.txt-4.1"></a> -## Establishing a rendezvous point [EST_REND_POINT] +## Establishing a rendezvous point \[EST_REND_POINT\] The client sends the rendezvous point a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell containing a 20-byte value. -RENDEZVOUS_COOKIE [20 bytes] +RENDEZVOUS_COOKIE \[20 bytes\] Rendezvous points MUST ignore any extra bytes in an ESTABLISH_RENDEZVOUS cell. (Older versions of Tor did not.) @@ -50,7 +50,7 @@ connect to a hidden service. <a id="rend-spec-v3.txt-4.2"></a> -## Joining to a rendezvous point [JOIN_REND] +## Joining to a rendezvous point \[JOIN_REND\] To complete a rendezvous, the hidden service host builds a circuit to the rendezvous point and sends a RENDEZVOUS1 cell containing: @@ -62,8 +62,8 @@ the rendezvous point and sends a RENDEZVOUS1 cell containing: ``` where RENDEZVOUS_COOKIE is the cookie suggested by the client during the -introduction (see [PROCESS_INTRO2]) and HANDSHAKE_INFO is defined in -[NTOR-WITH-EXTRA-DATA]. +introduction (see \[PROCESS_INTRO2\]) and HANDSHAKE_INFO is defined in +\[NTOR-WITH-EXTRA-DATA\]. If the cookie matches the rendezvous cookie set on any not-yet-connected circuit on the rendezvous point, the rendezvous @@ -73,7 +73,7 @@ client containing the HANDSHAKE_INFO field of the RENDEZVOUS1 cell. Upon receiving the RENDEZVOUS2 cell, the client verifies that HANDSHAKE_INFO correctly completes a handshake. To do so, the client parses SERVER_PK from HANDSHAKE_INFO and reverses the final operations of section -[NTOR-WITH-EXTRA-DATA] as shown here: +\[NTOR-WITH-EXTRA-DATA\] as shown here: ```text rend_secret_hs_input = EXP(Y,x) | EXP(B,x) | AUTH_KEY | B | X | Y | PROTOID @@ -112,16 +112,16 @@ keys for the ORs in Alice's side of the circuit, then decrypts them with Kb, and checks integrity with Db. Bob's OP does the same, with Kf and Kb interchanged. -[TODO: Should we encrypt HANDSHAKE_INFO as we did INTRODUCE2 +\[TODO: Should we encrypt HANDSHAKE_INFO as we did INTRODUCE2 contents? It's not necessary, but it could be wise. Similarly, we -should make it extensible.] +should make it extensible.\] <a id="rend-spec-v3.txt-4.3"></a> ## Using legacy hosts as rendezvous points -[This section is obsolete and refers to a workaround for now-obsolete Tor -relay versions. It is included for historical reasons.] +\[This section is obsolete and refers to a workaround for now-obsolete Tor +relay versions. It is included for historical reasons.\] The behavior of ESTABLISH_RENDEZVOUS is unchanged from older versions of this protocol, except that relays should now ignore unexpected diff --git a/spec/rend-spec-v3/selecting-nodes-picknodes.md b/spec/rend-spec-v3/selecting-nodes-picknodes.md index ef5edb4..8b0973c 100644 --- a/spec/rend-spec-v3/selecting-nodes-picknodes.md +++ b/spec/rend-spec-v3/selecting-nodes-picknodes.md @@ -1,6 +1,6 @@ <a id="rend-spec-v3.txt-B"></a> -# Appendix B: Selecting nodes [PICKNODES] +# Appendix B: Selecting nodes \[PICKNODES\] Picking introduction points Picking rendezvous points diff --git a/spec/rend-spec-v3/signature-scheme-with-key-blinding-keyblind.md b/spec/rend-spec-v3/signature-scheme-with-key-blinding-keyblind.md index d0393dd..8a7b1a2 100644 --- a/spec/rend-spec-v3/signature-scheme-with-key-blinding-keyblind.md +++ b/spec/rend-spec-v3/signature-scheme-with-key-blinding-keyblind.md @@ -1,12 +1,12 @@ <a id="rend-spec-v3.txt-A"></a> -# Appendix A: Signature scheme with key blinding [KEYBLIND] +# Appendix A: Signature scheme with key blinding \[KEYBLIND\] <a id="rend-spec-v3.txt-A.1"></a> ## Key derivation overview -As described in [IMD:DIST] and [SUBCRED] above, we require a "key +As described in \[IMD:DIST\] and \[SUBCRED\] above, we require a "key blinding" system that works (roughly) as follows: There is a master keypair (sk, pk). @@ -43,10 +43,10 @@ We propose the following scheme for key blinding, based on Ed25519. (This is an ECC group, so remember that scalar multiplication is the trapdoor function, and it's defined in terms of iterated point -addition. See the Ed25519 paper [Reference ED25519-REFS] for a fairly +addition. See the Ed25519 paper \[Reference ED25519-REFS\] for a fairly clear writeup.) -Let B be the ed25519 basepoint as found in section 5 of [ED25519-B-REF]: +Let B be the ed25519 basepoint as found in section 5 of \[ED25519-B-REF\]: ```text B = (15112221349535400772501151409588531511454012693041857206046113283949847762202, @@ -99,6 +99,6 @@ Verifying the signature: Check whether SB = R+hash(R,A',M)A'. This boils down to regular Ed25519 with key pair (a', A'). ``` -See [KEYBLIND-REFS] for an extensive discussion on this scheme and -possible alternatives. Also, see [KEYBLIND-PROOF] for a security +See \[KEYBLIND-REFS\] for an extensive discussion on this scheme and +possible alternatives. Also, see \[KEYBLIND-PROOF\] for a security proof of this scheme. |