[tor-commits] [torspec/main] Fix typos and cleanup

commit 29245fd50d1ee3d96cca52154da4d888f34fedea Author: Dimitris Apostolou dimitris.apostolou@icloud.com Date: Mon Oct 25 23:03:20 2021 +0300

Fix typos and cleanup --- README.md | 2 +- bandwidth-file-spec.txt | 2 +- bridgedb-spec.txt | 2 +- control-spec.txt | 6 +++--- dir-list-spec.txt | 4 ++-- dos-spec.md | 2 +- ext-orport-spec.txt | 6 +++--- guard-spec.txt | 2 +- param-spec.txt | 6 +++--- path-spec.txt | 8 ++++---- pt-spec.txt | 8 ++++---- rend-spec-v3.txt | 24 ++++++++++++------------ srv-spec.txt | 12 ++++++------ tor-spec.txt | 6 +++--- 14 files changed, 45 insertions(+), 45 deletions(-)

diff --git a/README.md b/README.md index 1a02a37..bce6bcf 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ the reader to implement a compatible implementation of Tor without ever having to read the Tor source code.

The [proposals](/proposals) directory holds our design proposals. These -include historical documents that have now been merged into . For more +include historical documents that have now been merged into. For more information on the proposal process, including an explanation of how to make new proposals, see, see [001-process.txt](/proposals/001-process.txt). diff --git a/bandwidth-file-spec.txt b/bandwidth-file-spec.txt index 58ce83c..d9f4db6 100644 --- a/bandwidth-file-spec.txt +++ b/bandwidth-file-spec.txt @@ -1161,7 +1161,7 @@ B.1. Scaling requirements

B.2. A linear scaling method

- If scaling is required, here is a simple linear bandwith scaling + If scaling is required, here is a simple linear bandwidth scaling method, which ensures that all bandwidth votes contain approximately the same total bandwidth:

diff --git a/bridgedb-spec.txt b/bridgedb-spec.txt index 5ccce92..51f6e5d 100644 --- a/bridgedb-spec.txt +++ b/bridgedb-spec.txt @@ -94,7 +94,7 @@ Table of Contents in the bridge network status parsed earlier or if the bridge does not have the Running flag. BridgeDB discards bridge descriptors which have a different purpose - than "bridge". BridgeDB can be configured to only accept descriptors + than "bridge". BridgeDB can be configured to only accept descriptors with another purpose or not discard descriptors based on purpose at all. BridgeDB memorizes the IP addresses and OR ports of the remaining diff --git a/control-spec.txt b/control-spec.txt index 1feb250..0e2add3 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1023,7 +1023,7 @@ Table of Contents

"net/listeners/dir"

- Listeners for Tor directory protocol, as decribed in dir-spec.txt. + Listeners for Tor directory protocol, as described in dir-spec.txt.

"net/listeners/socks"

@@ -2699,7 +2699,7 @@ Table of Contents

[NOTE: This feature was removed in Tor 0.3.2.1-alpha.]

- Tor generates this event when it's an directory authority, and + Tor generates this event when it's a directory authority, and somebody has just uploaded a server descriptor.

Syntax: @@ -3736,7 +3736,7 @@ Table of Contents

Program = The program path as defined in the *TransportPlugin configuration option. Tor accepts relative and full path. - Transport = This value indicate a hint on what the PT is such as the + Transport = This value indicates a hint on what the PT is such as the name or the protocol used for instance. Message = The status message that the PT sends back to the tor parent process minus the "STATUS" string prefix. Formatted as diff --git a/dir-list-spec.txt b/dir-list-spec.txt index c2d83f4..65af536 100644 --- a/dir-list-spec.txt +++ b/dir-list-spec.txt @@ -358,7 +358,7 @@ Table of Contents recent Tor versions.

weight was removed in version 2.0.0, but is documented because it - may be of interest to libraries implementing Tor's fallaback + may be of interest to libraries implementing Tor's fallback behaviour.

DQUOTE SP+ key_value DQUOTE SP* NL @@ -457,7 +457,7 @@ Table of Contents Libraries SHOULD consider the potential load on the authorities, and whether other sources can meet their needs.

- Libraries that require high-uptime availablility of Tor directory + Libraries that require high-uptime availability of Tor directory information should investigate the following options:

* OnionOO: https://metrics.torproject.org/onionoo.html diff --git a/dos-spec.md b/dos-spec.md index d1ca55c..04470b2 100644 --- a/dos-spec.md +++ b/dos-spec.md @@ -46,7 +46,7 @@ kinds of allocation: * Half-open stream records. * Cached onion service descriptors (hsdir only). * Cached DNS resolves (relay only). - * GEOIP-based usage activity statistics. + * GEOIP-based usage activity statistics.

Note that directory caches aren't counted, since those are stored on disk and accessed via mmap. diff --git a/ext-orport-spec.txt b/ext-orport-spec.txt index ec88244..6b8f8e1 100644 --- a/ext-orport-spec.txt +++ b/ext-orport-spec.txt @@ -63,14 +63,14 @@ Table of Contents

We define one authentication type: SAFE_COOKIE. Its AuthType value is 1. It is based on the client proving to the bridge that - it can access a given "cookie" file on disk. The purpose of + it can access a given "cookie" file on disk. The purpose of authentication is to defend against cross-protocol attacks.

If the Extended ORPort is enabled, Tor should regenerate the cookie file on startup and store it in $DataDirectory/extended_orport_auth_cookie.

- The location of the cookie can be overriden by using the + The location of the cookie can be overridden by using the configuration file parameter ExtORPortCookieAuthFile, which is defined as:

@@ -139,7 +139,7 @@ Table of Contents Status [1 octet]

Where, - + Status is 1 if the authentication was successfull. If the + + Status is 1 if the authentication was successful. If the authentication failed, Status is 0.

3. The extended ORPort protocol diff --git a/guard-spec.txt b/guard-spec.txt index e0f61d1..357583b 100644 --- a/guard-spec.txt +++ b/guard-spec.txt @@ -429,7 +429,7 @@ Table of Contents That is: if a non-primary guard becomes confirmed and not every primary guard is confirmed, then the list of primary guards list is regenerated, first from the confirmed guards (as before), and then from any - non-confirmed primary guards guards. + non-confirmed primary guards.

Note that {PRIMARY_GUARDS} do not have to be in {USABLE_FILTERED_GUARDS}: they might be unreachable. diff --git a/param-spec.txt b/param-spec.txt index 3cf36b2..f420944 100644 --- a/param-spec.txt +++ b/param-spec.txt @@ -83,7 +83,7 @@ Table of Contents

"perconnbwrate" and "perconnbwburst" -- if set, each relay sets up a separate token bucket for every client OR connection, and rate limits - that connection indepedently. Typically left unset, except when used for + that connection independently. Typically left unset, except when used for performance experiments around trac entry 1750. Only honored by relays running Tor 0.2.2.16-alpha and later. (Note that relays running 0.2.2.7-alpha through 0.2.2.14-alpha looked for bwconnrate and @@ -324,7 +324,7 @@ Table of Contents Min: 0. Max: 1. Default: 0. First appeared: 0.2.6

- "guard-lifetime-days" -- Controls guard lifetime. If a unconfirmed + "guard-lifetime-days" -- Controls guard lifetime. If an unconfirmed guard has been sampled more than this many days ago, it should be removed from the guard sample. Min: 1. Max: 3650. Default: 120. @@ -395,7 +395,7 @@ Table of Contents Min: 1. Max: INT32_MAX. Default: 15 First appeared: 0.3.0

- "guard-nonprimary-guard-idle-timeout" -- When trying to confirm + "guard-nonprimary-guard-idle-timeout" -- When trying to confirm nonprimary guards, if a guard doesn't answer for more than this long in seconds, treat it as down. Min: 1. Max: INT32_MAX. Default: 600 diff --git a/path-spec.txt b/path-spec.txt index 6d2df4f..4422be4 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -192,7 +192,7 @@ Tables of Contents * The fraction of descriptors that we have for nodes with the Guard flag, weighted by their bandwidth for the guard position. * The fraction of descriptors that we have for all nodes, - weighted by their bandwidth for the middle position position. + weighted by their bandwidth for the middle position. * The fraction of descriptors that we have for nodes with the Exit flag, weighted by their bandwidth for the exit position.

@@ -491,7 +491,7 @@ Tables of Contents used directly as Xm.

Instead of using the mode of discrete build times directly, Tor clients - compute the Xm parameter using the weighted average of the the midpoints + compute the Xm parameter using the weighted average of the midpoints of the 'cbtnummodes' (10) most frequently occurring 10ms histogram bins. Ties are broken in favor of earlier bins (that is, in favor of bins corresponding to shorter build times). @@ -511,7 +511,7 @@ Tables of Contents

All times below Xm are counted as having the Xm value via the MAX(), because in Pareto estimators, Xm is supposed to be the lowest value. - However, since clients use mode averaging to estimatre Xm, there can be + However, since clients use mode averaging to estimate Xm, there can be values below our Xm. Effectively, the Pareto estimator then treats that everything smaller than Xm happened at Xm. One can also see that if clients did not do this, alpha could underflow to become negative, which @@ -577,7 +577,7 @@ Tables of Contents to the point 'cbtclosequantile' (default 99) on the Pareto curve, or 60 seconds, whichever is greater.

- The actual completion times for these measurements circuits should be + The actual completion times for these measurement circuits should be recorded.

Implementations should completely abandon a circuit and ignore the circuit diff --git a/pt-spec.txt b/pt-spec.txt index e43a3f7..05421c1 100644 --- a/pt-spec.txt +++ b/pt-spec.txt @@ -452,7 +452,7 @@ Table of Contents

The "VERSION" message is used to signal the Pluggable Transport Specification version (as in "TOR_PT_MANAGED_TRANSPORT_VER") - that the PT proxy will use to configure it's transports and + that the PT proxy will use to configure its transports and communicate with the parent process.

The version for the environment values and reply messages @@ -644,7 +644,7 @@ Table of Contents

For example, the tor daemon logs those messages at the Severity level and sends them onto the control port using the PT_LOG (see control-spec.txt) - event so any third part can pick them up for debugging. + event so any third party can pick them up for debugging.

The format of the message:

@@ -670,7 +670,7 @@ Table of Contents

STATUS TRANSPORT=Transport <K_1>=<V_1> [<K_2>=<V_2>, ...]

- The TRANSPORT value indicate a hint on what the PT is such has the name or + The TRANSPORT value indicates a hint on what the PT is such has the name or the protocol used for instance. As an example, obfs4proxy would use "obfs4". Thus, the Transport value can be anything the PT itself defines and it can be a String or CString (see section 2 in control-spec.txt). @@ -711,7 +711,7 @@ Table of Contents causes cleanup and a graceful shutdown if able).

- PT proxies SHOULD attempt to detect when the parent has - terminated (eg: via detecting that it's parent process ID haso + terminated (eg: via detecting that its parent process ID has changed on U*IX systems), and gracefully terminate.

3.5. Pluggable Transport Client Per-Connection Arguments diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index 2abc732..6a120eb 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -35,7 +35,7 @@ Table of contents: 2.2.5. Expiring hidden service descriptors [EXPIRE-DESC] 2.2.6. URLs for anonymous uploading and downloading 2.3. Publishing shared random values [PUB-SHAREDRANDOM] - 2.3.1. Client behavior in the absense of shared random values + 2.3.1. Client behavior in the absence of shared random values 2.3.2. Hidden services and changing shared random values 2.4. Hidden service descriptors: outer wrapper [DESC-OUTER] 2.5. Hidden service descriptors: encryption format [HS-DESC-ENC] @@ -457,7 +457,7 @@ Table of contents:

To learn the introduction points, clients must decrypt the body of the hidden service descriptor. To do so, clients must know the _unblinded_ - public key of the service, which makes the descriptor unuseable by entities + public key of the service, which makes the descriptor unusable by entities without that knowledge (e.g. HSDirs that don't know the onion address).

Also, if optional client authorization is enabled, hidden service @@ -626,7 +626,7 @@ Table of contents: 1.9.1. In even more detail: Client authorization keys [CLIENT-AUTH]

When client authorization is enabled, each authorized client of a hidden - service has two more assymetric keypairs which are shared with the hidden + service has two more asymmetric keypairs which are shared with the hidden service. An entity without those keys is not able to use the hidden service. Throughout this document, we assume that these pre-shared keys are exchanged between the hidden service and its clients in a secure out-of-band @@ -746,7 +746,7 @@ Table of contents: HSDirs. The set of responsible HSDirs is determined as specified in [WHERE-HSDESC].

- Specifically, everytime a hidden service publishes its descriptor, it also + 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. @@ -831,7 +831,7 @@ Table of contents: 2.2.4. 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 successfuly fetch and upload + and shared random values (SRVs) to successfully fetch and upload descriptors. Furthermore, to avoid problems with skewed clocks, both clients and services use the 'valid-after' time of a live consensus as a way to take decisions with regards to uploading and fetching descriptors. By using the @@ -894,7 +894,7 @@ Table of contents:

As discussed above, services maintain two active descriptors at any time. We call these the "first" and "second" service descriptors. Services rotate - their descriptor everytime they receive a consensus with a valid_after time + their descriptor every time they receive a consensus with a valid_after time past the next SRV calculation time. They rotate their descriptors by discarding their first descriptor, pushing the second descriptor to the first, and rebuilding their second descriptor with the latest data. @@ -1008,7 +1008,7 @@ Table of contents: with a torsion component).

The right way for clients to detect such fraudulent addresses (which should - only occur malevolently and never natutally) is to extract the ed25519 + 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]. @@ -1028,7 +1028,7 @@ Table of contents: "shared-rand-previous-value" SP NUM_REVEALS SP VALUE NL "shared-rand-current-value" SP NUM_REVEALS SP VALUE NL

-2.3.1. Client behavior in the absense of shared random values +2.3.1. Client behavior in the absence of shared random values

If the previous or current shared random value cannot be found in a consensus, then Tor clients and services need to generate their own random @@ -1424,7 +1424,7 @@ Table of contents: MUST be present if "legacy-key" is present.

The certificate is a proposal 220 RSA->Ed cross-certificate wrapped - in "-----BEGIN CROSSCERT-----" armor, cross-certifying the the RSA + in "-----BEGIN CROSSCERT-----" armor, cross-certifying the RSA public key found in "legacy-key" using the descriptor signing key.

To remain compatible with future revisions to the descriptor format, @@ -1433,7 +1433,7 @@ Table of contents: should ignore ones they do not recognize.

Clients who manage to extract the introduction points of the hidden service - can prroceed with the introduction protocol as specified in [INTRO-PROTOCOL]. + can proceed with the introduction protocol as specified in [INTRO-PROTOCOL].

2.5.3. Deriving hidden service descriptor encryption keys [HS-DESC-ENCRYPTION-KEYS]

@@ -1448,7 +1448,7 @@ Table of contents:

Here is the key generation logic:

- SALT = 16 bytes from H(random), changes each time we rebuld the + SALT = 16 bytes from H(random), changes each time we rebuild the descriptor even if the content of the descriptor hasn't changed. (So that we don't leak whether the intro point list etc. changed)

@@ -1615,7 +1615,7 @@ Table of contents: The burst per second of INTRODUCE2 cell relayed to the service.

- The PARAM_VALUE size is 8 bytes in order to accomodate 64bit values. + The PARAM_VALUE size is 8 bytes in order to accommodate 64bit values. It MUST match the specified limit for the following PARAM_TYPE:

[01] -- Min: 0, Max: 2147483647 diff --git a/srv-spec.txt b/srv-spec.txt index a8bb878..a68ef3e 100644 --- a/srv-spec.txt +++ b/srv-spec.txt @@ -98,7 +98,7 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. 2.1. Ten thousand feet view of the protocol

Our commit-and-reveal protocol aims to produce a fresh shared random value - everyday at 00:00UTC. The final fresh random value is embedded in the + every day at 00:00UTC. The final fresh random value is embedded in the consensus document at that time.

Our protocol has two phases and uses the hourly voting procedure of Tor. @@ -124,11 +124,11 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. At 00:00UTC, the shared random value is computed from the agreed revealed values and added to the consensus.

- This concludes the commit-and-reveal protocol at 00:00UTC everyday. + This concludes the commit-and-reveal protocol every day at 00:00UTC.

2.3. How we use the consensus [CONS]

- The produced shared random values needs to be readily available to + The produced shared random values need to be readily available to clients. For this reason we include them in the consensus documents.

Every hour the consensus documents need to include the shared random value @@ -403,7 +403,7 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. from the COMMIT message. We say that the COMMIT and REVEAL messages correspond, if the comparison was successful.

- Pariticipants MUST also check that corresponding COMMIT and REVEAL values + Participants MUST also check that corresponding COMMIT and REVEAL values have the same timestamp value.

Authorities should ignore reveal values during the Reveal Phase that don't @@ -578,7 +578,7 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. different shared randomness value than the others.

We claim that this attack is not particularly fruitful: Alice ends up - having two shared random values to chose from which is a fundamental + having two shared random values to choose from which is a fundamental problem of commit-and-reveal protocols as well (since the last person can always abort or reveal). The attacker can also sabotage the consensus, but there are other ways this can be done with the current voting system. @@ -587,7 +587,7 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. First of all, it requires the authority to sabotage two consensuses which will cause quite some noise. Furthermore, the authority needs to send different votes to different auths which is detectable. Like the commit - phase attack, the detection here is to make sure that the commiment values + phase attack, the detection here is to make sure that the commitment values in a vote coming from an authority are always the same for each authority.

6. Discussion diff --git a/tor-spec.txt b/tor-spec.txt index d0d2f73..4467221 100644 --- a/tor-spec.txt +++ b/tor-spec.txt @@ -944,12 +944,12 @@ see tor-design.pdf. TIME (Timestamp) [4 bytes] OTHERADDR (Other OR's address) [variable] ATYPE (Address type) [1 byte] - ALEN (Adress length) [1 byte] + ALEN (Address length) [1 byte] AVAL (Address value in NBO) [ALEN bytes] NMYADDR (Number of this OR's addresses) [1 byte] NMYADDR times: ATYPE (Address type) [1 byte] - ALEN (Adress length) [1 byte] + ALEN (Address length) [1 byte] AVAL (Address value in NBO)) [ALEN bytes]

Recognized address types (ATYPE) are: @@ -1849,7 +1849,7 @@ see tor-design.pdf. and relays MUST ignore the payload.

In response to a RELAY_BEGIN_DIR cell, relays respond either with a - RELAY_CONNECTED cell on succcess, or a RELAY_END cell on failure. They + RELAY_CONNECTED cell on success, or a RELAY_END cell on failure. They MUST send a RELAY_CONNECTED cell all-zero payload, and clients MUST ignore the payload.