[tor-commits] [torspec/master] convert text blocks into widely compatible "blockquote" syntax

commit 9c86f54ba07355a968f982aed295e8b6597b4b89 Author: Hans-Christoph Steiner hans@eds.org Date: Wed Nov 27 12:59:04 2019 +0100

convert text blocks into widely compatible "blockquote" syntax

This only adds newline characters to make the existing text blocks act like "blockquote" or "code block" syntax in Markdown, asciidoc, and others. This was accomplished by manually reviewing the output of this script:

```bash for f in *.txt; do cat $f | python -c "import sys,re;print(re.sub(r'(\n {0,3}[^ \n][^\n]*\n)( {4,}[^\n]*)', r'\1\n\2', sys.stdin.read()))" > ${f}.tmp mv ${f}.tmp $f done ``` --- bridgedb-spec.txt | 3 ++ control-spec.txt | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ dir-list-spec.txt | 2 ++ dir-spec.txt | 59 ++++++++++++++++++++++++++++++++++ guard-spec.txt | 3 ++ padding-spec.txt | 2 ++ path-spec.txt | 4 +++ rend-spec-v2.txt | 12 +++++++ rend-spec-v3.txt | 14 +++++++++ srv-spec.txt | 3 ++ tor-spec.txt | 51 ++++++++++++++++++++++++++++++ version-spec.txt | 4 +++ 12 files changed, 251 insertions(+)

diff --git a/bridgedb-spec.txt b/bridgedb-spec.txt index 89f850a..a4c4708 100644 --- a/bridgedb-spec.txt +++ b/bridgedb-spec.txt @@ -209,6 +209,7 @@ the requirements. This ring is then used to select bridges as described.

"Mapping X to Y based on an HMAC" above means one of the following: + - We keep all of the elements of Y in some order, with a mapping from all 160-bit strings to positions in Y. - We take an HMAC of X using some fixed string as a key to get a @@ -219,6 +220,7 @@ BridgeDB may be configured to "Give out at least L bridges with port 443, and at least M bridges with Stable, and at most N bridges total." To do this, BridgeDB combines to the results: + - The first L bridges in the ring after the position that have the port 443, and - The first M bridges in the ring after the position that have the @@ -299,6 +301,7 @@

To map previously unseen email addresses to a set of bridges, BridgeDB proceeds as follows: + - It normalizes the email address as above, by stripping out dots, removing all of the localpart after the +, and putting it all in lowercase. (Example: "John.Doe+bridges@example.COM" becomes diff --git a/control-spec.txt b/control-spec.txt index 18e815e..5fec617 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -313,9 +313,12 @@

If all of the listed keywords exist in the Tor configuration, Tor replies with a series of reply lines of the form: + 250 keyword=value + If any option is set to a 'default' value semantically different from an empty string, Tor may reply with a reply line of the form: + 250 keyword

Value may be a raw value or a quoted string. Tor will try to use unquoted @@ -363,10 +366,12 @@ 3.5. AUTHENTICATE

Sent from the client to the server. The syntax is: + "AUTHENTICATE" [ SP 1*HEXDIG / QuotedString ] CRLF

This command is used to authenticate to the server. The provided string is one of the following: + * (For the HASHEDPASSWORD authentication method; see 3.21) The original password represented as a QuotedString.

@@ -404,6 +409,7 @@ 3.6. SAVECONF

Sent from the client to the server. The syntax is: + "SAVECONF" [SP "FORCE"] CRLF

Instructs the server to write out its config options into its torrc. Server @@ -482,6 +488,7 @@ address should be replaced with connections to the specified replacement address. If the addresses are well-formed, and the server is able to fulfill the request, the server replies with a 250 message: + 250-OldAddress1=NewAddress1 250 OldAddress2=NewAddress2

@@ -504,6 +511,7 @@ address.

Example: + C: MAPADDRESS 0.0.0.0=torproject.org 1.2.3.4=tor.freehaven.net S: 250-127.192.10.10=torproject.org S: 250 1.2.3.4=tor.freehaven.net @@ -511,6 +519,7 @@ {Note: This feature is designed to be used to help Tor-ify applications that need to use SOCKS4 or hostname-less SOCKS5. There are three approaches to doing this: + 1. Somehow make them use SOCKS4a or SOCKS5-with-hostnames instead. 2. Use tor-resolve (or another interface to Tor's resolve-over-SOCKS feature) to resolve the hostname remotely. This doesn't work @@ -518,6 +527,7 @@ 3. Use MAPADDRESS to map an IP address to the desired hostname, and then arrange to fool the application into thinking that the hostname has resolved to that IP. + This functionality is designed to help implement the 3rd approach.}

Mappings set by the controller last until the Tor process exits: @@ -528,14 +538,17 @@ 3.9. GETINFO

Sent from the client to the server. The syntax is as for GETCONF: + "GETINFO" 1*(SP keyword) CRLF

Unlike GETCONF, this message is used for data that are not stored in the Tor configuration file, and that may be longer than a single line. On success, one ReplyLine is sent for each requested value, followed by a final 250 OK ReplyLine. If a value fits on a single line, the format is: + 250-keyword=value If a value must be split over multiple lines, the format is: + 250+keyword= value . @@ -1140,6 +1153,7 @@ the MaxMemInQueues option. (Introduced in 0.2.5.4-alpha)

Examples: + C: GETINFO version desc/name/moria1 S: 250+desc/name/moria= S: [Descriptor for moria] @@ -1150,6 +1164,7 @@ 3.10. EXTENDCIRCUIT

Sent from the client to the server. The format is: + "EXTENDCIRCUIT" SP CircuitID [SP ServerSpec *("," ServerSpec)] [SP "purpose=" Purpose] CRLF @@ -1176,6 +1191,7 @@ 3.11. SETCIRCUITPURPOSE

Sent from the client to the server. The format is: + "SETCIRCUITPURPOSE" SP CircuitID SP "purpose=" Purpose CRLF

This changes the circuit's purpose. See EXTENDCIRCUIT above for details. @@ -1183,6 +1199,7 @@ 3.12. SETROUTERPURPOSE

Sent from the client to the server. The format is: + "SETROUTERPURPOSE" SP NicknameOrKey SP Purpose CRLF

This changes the descriptor's purpose. See +POSTDESCRIPTOR below @@ -1195,6 +1212,7 @@ 3.13. ATTACHSTREAM

Sent from the client to the server. The syntax is: + "ATTACHSTREAM" SP StreamID SP CircuitID [SP "HOP=" HopNum] CRLF

This message informs the server that the specified stream should be @@ -1234,6 +1252,7 @@ 3.14. POSTDESCRIPTOR

Sent from the client to the server. The syntax is: + "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache] CRLF Descriptor CRLF "." CRLF

@@ -1258,6 +1277,7 @@ 3.15. REDIRECTSTREAM

Sent from the client to the server. The syntax is: + "REDIRECTSTREAM" SP StreamID SP Address [SP Port] CRLF

Tells the server to change the exit address on the specified stream. If @@ -1287,6 +1307,7 @@ 3.17. CLOSECIRCUIT

The syntax is: + "CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF Flag = "IfUnused"

@@ -1351,6 +1372,7 @@ 3.20. RESOLVE

The syntax is + "RESOLVE" *Option *Address CRLF Option = "mode=reverse" Address = a hostname or IPv4 address @@ -1365,9 +1387,11 @@ 3.21. PROTOCOLINFO

The syntax is: + "PROTOCOLINFO" *(SP PIVERSION) CRLF

The server reply format is: + "250-PROTOCOLINFO" SP PIVERSION CRLF *InfoLine "250 OK" CRLF

InfoLine = AuthLine / VersionLine / OtherLine @@ -1436,6 +1460,7 @@ 3.22. LOADCONF

The syntax is: + "+LOADCONF" CRLF ConfigText CRLF "." CRLF

This command allows a controller to upload the text of a config file @@ -1447,6 +1472,7 @@ 3.23. TAKEOWNERSHIP

The syntax is: + "TAKEOWNERSHIP" CRLF

This command instructs Tor to shut down when this control @@ -1492,6 +1518,7 @@ 3.24. AUTHCHALLENGE

The syntax is: + "AUTHCHALLENGE" SP "SAFECOOKIE" SP ClientNonce CRLF @@ -1502,6 +1529,7 @@ SAFECOOKIE method of authentication.

If the server accepts the command, the server reply format is: + "250 AUTHCHALLENGE" SP "SERVERHASH=" ServerHash SP "SERVERNONCE=" ServerNonce @@ -1515,14 +1543,17 @@ AUTHENTICATE command. ServerNonce MUST be 32 bytes long.

ServerHash is computed as: + HMAC-SHA256("Tor safe cookie authentication server-to-controller hash", CookieString | ClientNonce | ServerNonce) + (with the HMAC key as its first argument)

After a controller sends a successful AUTHCHALLENGE command, the next command sent on the connection must be an AUTHENTICATE command, and the only authentication string which that AUTHENTICATE command will accept is: + HMAC-SHA256("Tor safe cookie authentication controller-to-server hash", CookieString | ClientNonce | ServerNonce)

@@ -1534,6 +1565,7 @@ 3.25. DROPGUARDS

The syntax is: + "DROPGUARDS" CRLF

Tells the server to drop all guard nodes. Do not invoke this command @@ -1546,6 +1578,7 @@ 3.26. HSFETCH

The syntax is: + "HSFETCH" SP (HSAddress / "v" Version "-" DescId) *[SP "SERVER=" Server] CRLF

@@ -1579,6 +1612,7 @@ SERVER is specified then events are emitted for each location.

Examples are: + C: HSFETCH v2-gezdgnbvgy3tqolbmjrwizlgm5ugs2tl SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 S: 250 OK @@ -1595,6 +1629,7 @@ 3.27. ADD_ONION

The syntax is: + "ADD_ONION" SP KeyType ":" KeyBlob [SP "Flags=" Flag *("," Flag)] [SP "MaxStreams=" NumStreams] @@ -1648,6 +1683,7 @@ specific to the authorization method (v2 only).

The server reply format is: + "250-ServiceID=" ServiceID CRLF ["250-PrivateKey=" KeyType ":" KeyBlob CRLF] *("250-ClientAuth=" ClientName ":" ClientBlob CRLF) @@ -1711,6 +1747,7 @@ importing an ED25519-V3 key.]

Examples: + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80 S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad S: 250 OK @@ -1757,6 +1794,7 @@ 3.28. DEL_ONION

The syntax is: + "DEL_ONION" SP ServiceID CRLF

ServiceID = The Onion Service address without the trailing ".onion" @@ -1784,6 +1822,7 @@ 3.29. HSPOST

The syntax is: + "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress] CRLF Descriptor CRLF "." CRLF

@@ -1809,6 +1848,7 @@ this with a HS_DESC event with the result for each upload location.

Examples are: + C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 [DESCRIPTOR] . @@ -1819,6 +1859,7 @@ 3.30. ONION_CLIENT_AUTH_ADD

The syntax is: + "ONION_CLIENT_AUTH_ADD" SP HSAddress SP KeyType ":" PrivateKeyBlob [SP "ClientName=" Nickname] @@ -1835,6 +1876,7 @@

FLAGS is a comma-separated tuple of flags for this new client. For now, the currently supported flags are: + "Permanent" - This client's credentials should be stored in the filesystem. If this is not set, the client's credentials are epheremal and stored in memory. @@ -1847,6 +1889,7 @@ decrypt those descriptors as soon as this command succeeds.

On success, "250 OK" is returned. Otherwise, the following error codes exist: + 251 - Client auth credentials for this onion service already existed and replaced. 252 - Added client auth credentials and successfully decrypted a cached descriptor. 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" @@ -1856,6 +1899,7 @@ 3.31. ONION_CLIENT_AUTH_REMOVE

The syntax is: + "ONION_CLIENT_AUTH_REMOVE" SP HSAddress

KeyType = "x25519" is the only one supported right now @@ -1864,12 +1908,14 @@ for the onion service with "HSAddress".

On success "250 OK" is returned. Otherwise, the following error codes exist: + 512 - Syntax error in "HSAddress". 251 - Client credentials for "HSAddress" did not exist.

3.32. ONION_CLIENT_AUTH_VIEW

The syntax is: + "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF

Tells the connected Tor to list all the stored client-side v3 client auth @@ -1877,6 +1923,7 @@ stored client-side v3 client auth credentials.

The server reply format is: + "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF *("250-CLIENT" SP HSAddress SP KeyType ":" PrivateKeyBlob [SP "ClientName=" Nickname] @@ -1893,14 +1940,17 @@

FLAGS is a comma-separated field of flags for this client, the currently supported flags are: + "Permanent" - This client's credentials are stored in the filesystem.

On success "250 OK" is returned. Otherwise, the following error codes exist: + 512 - Syntax error in "HSAddress".

3.33. DROPOWNERSHIP

The syntax is: + "DROPOWNERSHIP" CRLF

This command instructs Tor to relinquish ownership of its control @@ -2003,6 +2053,7 @@ S: 250 ORPORT=0

But this sequence is disallowed: + C: SETEVENTS CIRC S: 250 OK C: GETCONF SOCKSPORT ORPORT @@ -2013,8 +2064,11 @@ Clients MUST tolerate more arguments in an asynchronous reply than expected, and MUST tolerate more lines in an asynchronous reply than expected. For instance, a client that expects a CIRC message like: + 650 CIRC 1000 EXTENDED moria1,moria2 + must tolerate: + 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF 650-EXTRAMAGIC=99 650 ANONYMITY=high @@ -2024,8 +2078,11 @@ Tor 0.2.2.x and later), then each event line as specified below may be followed by additional arguments and additional lines. Additional lines will be of the form: + "650" ("-"/" ") KEYWORD ["=" ARGUMENTS] CRLF + Additional arguments will be of the form + SP KEYWORD ["=" ( QuotedString / * NonSpDquote ) ]

Clients MUST tolerate events with arguments and keywords they do not @@ -2261,7 +2318,9 @@ reasons not listed above. Reasons are as listed in tor-spec.txt.

"REMAP" events include a Source if extended events are enabled: + Source = "CACHE" / "EXIT" + Clients MUST accept sources not listed above. "CACHE" is given if the Tor client decided to remap the address because of a cached answer, and "EXIT" is given if the remote node we queried gave us @@ -2353,6 +2412,7 @@ NumCircuits counts both established and pending circuits.

The ORStatus values are as follows: + NEW -- We have received a new incoming OR connection, and are starting the server-side handshake. LAUNCHED -- We have launched a new outgoing OR connection, and are @@ -2363,6 +2423,7 @@ CLOSED -- The OR connection closed in an unremarkable way.

The Reason values for closed/failed OR connections are: + DONE -- The OR connection has shut down cleanly. CONNECTREFUSED -- We got an ECONNREFUSED while connecting to the target OR. @@ -2386,6 +2447,7 @@ 4.1.4. Bandwidth used in the last second

The syntax is: + "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF BytesRead = 1*DIGIT BytesWritten = 1*DIGIT @@ -2399,8 +2461,11 @@ 4.1.5. Log messages

The syntax is: + "650" SP Severity SP ReplyText CRLF + or + "650+" Severity CRLF Data 650 SP "OK" CRLF

Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR" @@ -2419,6 +2484,7 @@ extrainfos or anything else) are received.

Syntax: + "650" SP "NEWDESC" 1*(SP LongName) CRLF ; In Tor versions 0.1.2.2-alpha through 0.2.2.1-alpha with feature ; VERBOSE_NAMES turned off and before version 0.1.2.2-alpha, it @@ -2435,6 +2501,7 @@ TrackHostExits feature.

Syntax: + "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] [SP "CACHED=" Cached] CRLF @@ -2467,6 +2534,7 @@ somebody has just uploaded a server descriptor.

Syntax: + "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF Descriptor CRLF "." CRLF "650" SP "OK" CRLF Action = "ACCEPTED" / "DROPPED" / "REJECTED" @@ -2483,6 +2551,7 @@ 4.1.9. Our descriptor changed

Syntax: + "650" SP "DESCCHANGED" CRLF

[First added in 0.1.2.2-alpha.] @@ -2496,6 +2565,7 @@ specified interface.

Syntax: + "650" SP StatusType SP StatusSeverity SP StatusAction [SP StatusArguments] CRLF

@@ -2926,6 +2996,7 @@ 4.1.11. Our set of guard nodes has changed

Syntax: + "650" SP "GUARD" SP Type SP Name SP Status ... CRLF Type = "ENTRY" Name = ServerSpec @@ -2936,6 +3007,7 @@ network.

The Status values are: + "NEW" -- This node was not previously used as a guard; now we have picked it as one. "DROPPED" -- This node is one we previously picked as a guard; we @@ -2952,6 +3024,7 @@ 4.1.12. Network status has changed

Syntax: + "650" "+" "NS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF

The event is used whenever our local view of a relay status changes. @@ -2965,6 +3038,7 @@ 4.1.13. Bandwidth used on an application stream

The syntax is: + "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead SP Time CRLF BytesWritten = 1*DIGIT @@ -2989,6 +3063,7 @@ 4.1.14. Per-country client stats

The syntax is: + "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary SP IPVersions CRLF

@@ -3021,6 +3096,7 @@ 4.1.15. New consensus networkstatus has arrived

The syntax is: + "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP "OK" CRLF

@@ -3034,6 +3110,7 @@ 4.1.16. New circuit buildtime has been set

The syntax is: + "650" SP "BUILDTIMEOUT_SET" SP Type SP "TOTAL_TIMES=" Total SP "TIMEOUT_MS=" Timeout SP "XM=" Xm SP "ALPHA=" Alpha SP "CUTOFF_QUANTILE=" Quantile SP "TIMEOUT_RATE=" TimeoutRate SP @@ -3071,6 +3148,7 @@ 4.1.17. Signal received

The syntax is: + "650" SP "SIGNAL" SP Signal CRLF

Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE" @@ -3092,6 +3170,7 @@ 4.1.18. Configuration changed

The syntax is: + StartReplyLine *(MidReplyLine) EndReplyLine

StartReplyLine = "650-CONF_CHANGED" CRLF @@ -3144,6 +3223,7 @@ 4.1.21. Bandwidth used on an OR or DIR or EXIT connection

The syntax is: + "650" SP "CONN_BW" SP "ID=" ConnID SP "TYPE=" ConnType SP "READ=" BytesRead SP "WRITTEN=" BytesWritten CRLF

@@ -3172,6 +3252,7 @@ 4.1.22. Bandwidth used by all streams attached to a circuit

The syntax is: + "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP "WRITTEN=" BytesWritten SP "TIME=" Time SP "DELIVERED_READ=" DeliveredBytesRead SP @@ -3223,6 +3304,7 @@ 4.1.23. Per-circuit cell stats

The syntax is: + "650" SP "CELL_STATS" [ SP "ID=" CircuitID ] [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ] @@ -3238,6 +3320,7 @@ CellType = 1*( "a" - "z" / "0" - "9" / "_" )

Examples are: + 650 CELL_STATS ID=14 OutboundQueue=19403 OutboundConn=15 OutboundAdded=create_fast:1,relay_early:2 OutboundRemoved=create_fast:1,relay_early:2 @@ -3289,6 +3372,7 @@ 4.1.24. Token buckets refilled

The syntax is: + "650" SP "TB_EMPTY" SP BucketName [ SP "ID=" ConnID ] SP "READ=" ReadBucketEmpty SP "WRITTEN=" WriteBucketEmpty SP "LAST=" LastRefill CRLF @@ -3299,6 +3383,7 @@ LastRefill = 1*DIGIT

Examples are: + 650 TB_EMPTY ORCONN ID=16 READ=0 WRITTEN=0 LAST=100 650 TB_EMPTY GLOBAL READ=93 WRITTEN=93 LAST=100 650 TB_EMPTY RELAY READ=93 WRITTEN=93 LAST=100 @@ -3436,6 +3521,7 @@ 4.1.27. Network liveness has changed

Syntax: + "650" SP "NETWORK_LIVENESS" SP Status CRLF Status = "UP" / ; The network now seems to be reachable. "DOWN" / ; The network now seems to be unreachable. @@ -3447,6 +3533,7 @@ 4.1.28. Pluggable Transport Logs

Syntax: + "650" SP "PT_LOG" SP PT=Program SP Message

Program = The program path as defined in the *TransportPlugin @@ -3470,6 +3557,7 @@ 4.1.29. Pluggable Transport Status

Syntax: + "650" SP "PT_STATUS" SP PT=Program SP TRANSPORT=Transport SP Message

Program = The program path as defined in the *TransportPlugin @@ -3507,6 +3595,7 @@ contents of the cookie file:

* Current versions of Tor support cookie authentication + using the "COOKIE" authentication method: the controller sends the contents of the cookie file, encoded in hexadecimal. This authentication method exposes the user running a controller to an @@ -3520,6 +3609,7 @@ Tor before some future version of Tor.

* 0.2.2.x versions of Tor starting with 0.2.2.36, and all versions of + Tor after 0.2.3.12-alpha, support cookie authentication using the "SAFECOOKIE" authentication method, which discloses much less information about the contents of the cookie file. @@ -3529,12 +3619,16 @@ S2K algorithm in RFC 2440 (OpenPGP), and prefixed with the s2k specifier. This is then encoded in hexadecimal, prefixed by the indicator sequence "16:". Thus, for example, the password 'foo' could encode to: + 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2 ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ salt hashed value indicator + You can generate the salt of a password by calling + 'tor --hash-password <password>' + or by using the example code in the Python and Java controller libraries. To authenticate under this scheme, the controller sends Tor the original secret that was used to generate the password, either as a quoted string diff --git a/dir-list-spec.txt b/dir-list-spec.txt index 063fc24..c118040 100644 --- a/dir-list-spec.txt +++ b/dir-list-spec.txt @@ -102,6 +102,7 @@ 2. Format Details

Directory lists contain the following sections: + - List Header (exactly once) - List Generation (exactly once, may be empty) - Directory Entry (zero or more times) @@ -421,6 +422,7 @@

Libraries that require high-uptime availablility of Tor directory information should investigate the following options: + * OnionOO: https://metrics.torproject.org/onionoo.html * Third-party OnionOO mirrors are also available * CollecTor: https://collector.torproject.org/ diff --git a/dir-spec.txt b/dir-spec.txt index 17e2419..034149e 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -262,12 +262,19 @@ For forward compatibility, each item MUST allow extra arguments at the end of the line unless otherwise noted. So if an item's description below is given as: + "thing" int int int NL + then implementations SHOULD accept this string as well: + "thing 5 9 11 13 16 12" NL + but not this string: + "thing 5" NL + and not this string: + "thing 5 10 thing" NL .

@@ -1429,6 +1436,7 @@ If the authority _does_ have a descriptor with the same public key, the newly uploaded descriptor is remembered if its publication time is more recent than the most recent old descriptor for that router, and either: + - There are non-cosmetic differences between the old descriptor and the new one. - Enough time has passed between the descriptors' publication times. @@ -1628,8 +1636,11 @@ An authority SHOULD publish its vote immediately at the start of each voting period (minus VoteSeconds+DistSeconds). It does this by making it available at + http://<hostname>/tor/status-vote/next/authority.z + and sending it in an HTTP POST request to each other authority at the URL + http://<hostname>/tor/post/vote

If, at the start of the voting period, minus DistSeconds, an authority @@ -1638,10 +1649,14 @@

Once an authority has a vote from another authority, it makes it available at + http://<hostname>/tor/status-vote/next/<fp>.z + where <fp> is the fingerprint of the other authority's identity key. And at + http://<hostname>/tor/status-vote/next/d/<d>.z + where <d> is the digest of the vote document.

Also, once an authority receives a vote from another authority, it @@ -2566,10 +2581,12 @@ "Running" -- A router is 'Running' if the authority managed to connect to it successfully within the last 45 minutes on all its published ORPorts. Authorities check reachability on: + * the IPv4 ORPort in the "r" line, and * the IPv6 ORPort considered for the "a" line, if: * the router advertises at least one IPv6 ORPort, and * AuthDirHasIPv6Connectivity 1 is set on the authority. + A minority of voting authorities that set AuthDirHasIPv6Connectivity will drop unreachable IPv6 ORPorts from the full consensus. Consensus method 27 in 0.3.3.x puts IPv6 ORPorts in the microdesc consensus, so that @@ -2600,6 +2617,7 @@ the top 7/8ths for known active routers or at least 100KB/s.

"Guard" -- A router is a possible Guard if all of the following apply: + - It is Fast, - It is Stable, - Its Weighted Fractional Uptime is at least the median for "familiar" @@ -2757,6 +2775,7 @@

The consensus status, along with as many signatures as the server currently knows (see section 3.10 below), should be available at + http://<hostname>/tor/status-vote/next/consensus.z

The contents of the consensus document are as follows: @@ -3000,6 +3019,7 @@ To achieve this, authorities list in their votes their supported methods for generating consensuses from votes. Later methods will be assigned higher numbers. Currently specified methods: + "1" -- The first implemented version. "2" -- Added support for the Unnamed flag. "3" -- Added legacy ID key support to aid in authority ID key rollovers @@ -3051,6 +3071,7 @@

The following methods have incorrect implementations; authorities SHOULD NOT advertise support for them: + "21" -- Did not correctly enable support for ed25519 key collation.

3.8.2. Encoding port lists @@ -3236,9 +3257,11 @@ assignments:

Directory requests use middle weights: + Wbd=Wmd, Wbg=Wmg, Wbe=Wme, Wbm=Wmm

Handle bridges and strange exit policies: + Wgm=Wgg, Wem=Wee, Weg=Wed

3.9. Computing consensus flavors @@ -3256,6 +3279,7 @@ instead wouldn't be too onerous.

Examples for consensus flavors include: + - Publishing hashes of microdescriptors instead of hashes of full descriptors (see section 3.9.2). - Including different digests of descriptors, instead of the @@ -3359,12 +3383,14 @@ Once an authority has computed and signed a consensus network status, it should send its detached signature to each other authority in an HTTP POST request to the URL: + http://<hostname>/tor/post/consensus-signature

[XXX Note why we support push-and-then-pull.]

All of the detached signatures it knows for consensus status should be available at: + http://<hostname>/tor/status-vote/next/consensus-signatures.z

Assuming full connectivity, every authority should compute and sign the @@ -3431,9 +3457,13 @@ The voting period ends at the valid-after time. If the consensus has been signed by a majority of authorities, these documents are made available at + http://<hostname>/tor/status-vote/current/consensus.z + and + http://<hostname>/tor/status-vote/current/consensus-signatures.z + [XXX current/consensus-signatures is not currently implemented, as it is not used in the voting protocol.]

@@ -3441,14 +3471,17 @@ consensuses.]

The other vote documents are analogously made available under + http://<hostname>/tor/status-vote/current/authority.z http://<hostname>/tor/status-vote/current/<fp>.z http://<hostname>/tor/status-vote/current/d/<d>.z http://<hostname>/tor/status-vote/current/bandwidth.z + once the voting period ends, regardless of the number of signatures.

The authorities serve another consensus of each flavor "F" from the locations + /tor/status-vote/(current|next)/consensus-F.z. and /tor/status-vote/(current|next)/consensus-F/<FP1>+....z.

@@ -3463,8 +3496,10 @@ All directory caches try to keep a recent network-status consensus document to serve to clients. A cache ALWAYS downloads a network-status consensus if any of the following are true: + - The cache has no consensus document. - The cache's consensus document is no longer valid. + Otherwise, the cache downloads a new consensus document at a randomly chosen time in the first half-interval after its current consensus stops being fresh. (This time is chosen at random to avoid swarming @@ -3512,6 +3547,7 @@

The microdescriptors with base64 hashes <D1>,<D2>,<D3> are available at: + http://<hostname>/tor/micro/d/<D1>-<D2>-<D3>[.z]

<Dn> are base64 encoded with trailing =s omitted for size and for @@ -3556,6 +3592,7 @@ The first line is "network-status-diff-version 1" NL

The second line is + "hash" SP FromDigest SP ToDigest NL

where FromDigest is the hex-encoded SHA3-256 digest of the _signed @@ -3676,10 +3713,12 @@

Clients try to have the best descriptor for each router. A descriptor is "best" if: + * It is listed in the consensus network-status document.

Periodically (currently every 10 seconds) clients check whether there are any "downloadable" descriptors. A descriptor is downloadable if: + - It is the "best" descriptor for some router. - The descriptor was published at least 10 minutes in the past. (This prevents clients from trying to fetch descriptors that the @@ -3696,6 +3735,7 @@

When downloading multiple server descriptors, the client chooses multiple mirrors so that: + - At least 3 different mirrors are used, except when this would result in more than one request for under 4 descriptors. - No more than 128 descriptors are requested from a single mirror. @@ -3814,6 +3854,7 @@

Servers SHOULD set Content-Encoding to the algorithm used to compress the document(s) being served. Recognized algorithms are: + - "identity" -- RFC2616 section 3.5 - "deflate" -- RFC2616 section 3.5 - "gzip" -- RFC2616 section 3.5 @@ -3894,12 +3935,15 @@ B. General-use HTTP URLs "Fingerprints" in these URLs are base16-encoded SHA1 hashes.

The most recent v3 consensus should be available at: + http://<hostname>/tor/status-vote/current/consensus.z

Similarly, the v3 microdescriptor consensus should be available at: + http://<hostname>/tor/status-vote/current/consensus-microdesc.z

Starting with Tor version 0.2.1.1-alpha is also available at: + http://<hostname>/tor/status-vote/current/consensus/<F1>+<F2>+<F3>.z

(NOTE: Due to squid proxy url limitations at most 96 fingerprints can be @@ -3921,18 +3965,22 @@ B. General-use HTTP URLs

A concatenated set of all the current key certificates should be available at: + http://<hostname>/tor/keys/all.z

The key certificate for this server (if it is an authority) should be available at: + http://<hostname>/tor/keys/authority.z

The key certificate for an authority whose authority identity fingerprint is <F> should be available at: + http://<hostname>/tor/keys/fp/<F>.z

The key certificate whose signing key fingerprint is <F> should be available at: + http://<hostname>/tor/keys/sk/<F>.z

The key certificate whose identity key fingerprint is <F> and whose signing @@ -3941,15 +3989,19 @@ B. General-use HTTP URLs http://<hostname>/tor/keys/fp-sk/<F>-<S>.z

(As usual, clients may request multiple certificates using: + http://<hostname>/tor/keys/fp-sk/<F1>-<S1>+<F2>-<S2>.z ) + [The above fp-sk format was not supported before Tor 0.2.1.9-alpha.]

The most recent descriptor for a server whose identity key has a fingerprint of <F> should be available at: + http://<hostname>/tor/server/fp/<F>.z

The most recent descriptors for servers with identity fingerprints <F1>,<F2>,<F3> should be available at: + http://<hostname>/tor/server/fp/<F1>+<F2>+<F3>.z

(NOTE: Due to squid proxy url limitations at most 96 fingerprints can be @@ -3962,14 +4014,18 @@ B. General-use HTTP URLs

The server descriptor with (descriptor) digest <D> (in hex) should be available at: + http://<hostname>/tor/server/d/<D>.z

The most recent descriptors with digests <D1>,<D2>,<D3> should be available at: + http://<hostname>/tor/server/d/<D1>+<D2>+<D3>.z

The most recent descriptor for this server should be at: + http://<hostname>/tor/server/authority.z + [Nothing in the Tor protocol uses this resource yet, but it is useful for debugging purposes. Also, the official Tor implementations (starting at 0.1.1.x) use this resource to test whether a server's @@ -3977,9 +4033,11 @@ B. General-use HTTP URLs

A concatenated set of the most recent descriptors for all known servers should be available at: + http://<hostname>/tor/server/all.z

Extra-info documents are available at the URLS + http://<hostname>/tor/extra/d/... http://<hostname>/tor/extra/fp/... http://<hostname>/tor/extra/all[.z] @@ -4086,6 +4144,7 @@ E. Limited ed diff format ed commands.

We support the following ed commands, each on a line by itself: + - "<n1>d" Delete line n1 - "<n1>,<n2>d" Delete lines n1 through n2, inclusive - "<n1>,$d" Delete line n1 through the end of the file, inclusive. diff --git a/guard-spec.txt b/guard-spec.txt index 4f2e3d3..db1ae32 100644 --- a/guard-spec.txt +++ b/guard-spec.txt @@ -268,6 +268,7 @@

We maintain another set, {set:FILTERED_GUARDS}, that does not persist. It is derived from: + - {SAMPLED_GUARDS} - our current configuration, - the path bias information. @@ -417,6 +418,7 @@ 4.6. Selecting guards for circuits. [Section:SELECTING]

Every origin circuit is now in one of these states: + state:usable_on_completion, state:usable_if_no_better_guard, state:waiting_for_better_guard, or @@ -494,6 +496,7 @@

We're getting to the core of the algorithm here. Our main goals are to make sure that + 1. If it's possible to use a primary guard, we do. 2. We probably use the first primary guard.

diff --git a/padding-spec.txt b/padding-spec.txt index b3e401a..22ed171 100644 --- a/padding-spec.txt +++ b/padding-spec.txt @@ -428,10 +428,12 @@ the anonymity and load-balancing implications of their choices. This means that up to the sixth cell (first line of each sequence above), both general and intro circuits have identical cell sequences. After that we want to mimic the second line sequence of + -> [DATA] -> [DATA] -> DATA -> DATA...(inbound data cells continue)

We achieve this by starting padding INTRODUCE1 has been sent. With padding negotiation cells, in the common case of the second line looks like: + -> [INTRO1] -> [PADDING_NEGOTIATE] -> PADDING_NEGOTIATED -> INTRO_ACK

Then, the middle node will send between INTRO_MACHINE_MINIMUM_PADDING (7) and diff --git a/path-spec.txt b/path-spec.txt index 82f07cd..d728131 100644 --- a/path-spec.txt +++ b/path-spec.txt @@ -233,6 +233,7 @@ of their choices. We choose the path for each new circuit before we build it. We choose the exit node first, followed by the other nodes in the circuit. All paths we generate obey the following constraints: + - We do not choose the same router twice for the same path. - We do not choose any router in the same family as another in the same path. (Two routers are in the same family if each one lists the other @@ -595,6 +596,7 @@ of their choices. client as appropriate (e.g., by closing the SOCKS connection).

XXX Timeouts and when Tor auto-retries. + * What stream-end-reasons are appropriate for retrying.

If no reply to BEGIN/RESOLVE, then the stream will timeout and fail. @@ -631,6 +633,7 @@ of their choices. increasing w.r.t. the router's non-guard bandwidth and bandwidth weight (calculated without taking the guard flag into account). From proposal #236: + | | Let Wpf denote the weight from the 'bandwidth-weights' line a | client would apply to N for position p if it had the guard @@ -888,6 +891,7 @@ X.3. Some stuff that worries me about entry guards. 2006 Jun, Nickm. Observing a user is sufficient to learn its entry guards. So, as we move around, entry guards make us linkable. If we want to change guards when our location (IP? subnet?) changes, we have two bad options. We could + - Drop the old guards. But if we go back to our old location, we'll not use our old guards. For a laptop that sometimes gets used from work and sometimes from home, this is pretty fatal. diff --git a/rend-spec-v2.txt b/rend-spec-v2.txt index d3a93e1..7ea0362 100644 --- a/rend-spec-v2.txt +++ b/rend-spec-v2.txt @@ -103,6 +103,7 @@ 0.3. Constants and new cell types

Relay cell types + 32 -- RELAY_COMMAND_ESTABLISH_INTRO 33 -- RELAY_COMMAND_ESTABLISH_RENDEZVOUS 34 -- RELAY_COMMAND_INTRODUCE1 @@ -166,9 +167,13 @@ To prevent replay attacks, the HS field contains a SHA-1 hash based on the shared secret KH between Bob's OP and the introduction point, as follows: + HS = H(KH | "INTRODUCE") + That is: + HS = H(KH | [49 4E 54 52 4F 44 55 43 45]) + (KH, as specified in tor-spec.txt, is H(g^xy | [00]) .)

Upon receiving such a cell, the OR first checks that the signature is @@ -713,6 +718,7 @@ Bob's OP builds a new Tor circuit ending at Alice's chosen rendezvous point, and sends a RELAY_COMMAND_RENDEZVOUS1 cell along this circuit, containing: + RC Rendezvous cookie [20 octets] g^y Diffie-Hellman [128 octets] KH Handshake digest [20 octets] @@ -740,7 +746,9 @@ has sent a RELAY_COMMAND_ESTABLISH_RENDEZVOUS cell but which has not yet received a reply, it uses g^y and H(g^xy) to complete the handshake as in the Tor circuit extend process: they establish a 60-octet string as + K = SHA1(g^xy | [00]) | SHA1(g^xy | [01]) | SHA1(g^xy | [02]) + and generate KH, Df, Db, Kf, and Kb as in the KDF-TOR key derivation approach documented in tor-spec.txt.

@@ -905,10 +913,14 @@

ATYPE Authorization type: set to 1. [1 octet] ALEN Number of clients := 1 + ((clients - 1) div 16) [1 octet] + for each symmetric descriptor cookie: + ID Client ID: H(descriptor cookie | IV)[:4] [4 octets] SKEY Session key encrypted with descriptor cookie [16 octets] + (end of client-specific part) + RND Random data [(15 - ((clients - 1) mod 16)) * 20 octets] IV AES initialization vector [16 octets] IPOS Intro points, encrypted with session key [remaining octets] diff --git a/rend-spec-v3.txt b/rend-spec-v3.txt index 169de74..ccd5992 100644 --- a/rend-spec-v3.txt +++ b/rend-spec-v3.txt @@ -316,6 +316,7 @@ Table of contents: 0.6. Acknowledgments

This design includes ideas from many people, including + Christopher Baines, Daniel J. Bernstein, Matthew Finkel, @@ -333,6 +334,7 @@ Table of contents: It's based on Tor's original hidden service design by Roger Dingledine, Nick Mathewson, and Paul Syverson, and on improvements to that design over the years by people including + Tobias Kamm, Thomas Lauterbach, Karsten Loesing, @@ -344,20 +346,24 @@ Table of contents:

We wouldn't be able to do any of this work without good attack designs from researchers including + Alex Biryukov, Lasse Øverlier, Ivan Pustogarov, Paul Syverson Ralf-Philipp Weinmann, + See [ATTACK-REFS] for their papers.

Several of these ideas have come from conversations with + Christian Grothoff, Brian Warner, Zooko Wilcox-O'Hearn,

And if this document makes any sense at all, it's thanks to editing help from + Matthew Finkel George Kadianakis, Peter Palfrader, @@ -1488,6 +1494,7 @@ Table of contents:

Single Onion Services attempt to build a non-anonymous single-hop circuit, but use an anonymous 3-hop circuit if: + * the intro point is on an address that is configured as unreachable via a direct connection, or * the initial attempt to connect to the intro point over a single-hop @@ -1737,6 +1744,7 @@ Table of contents: EXT_FIELD [EXT_FIELD_LEN bytes]

Recognized status values are: + [00 00] -- Success: cell relayed to hidden service host. [00 01] -- Failure: service ID not recognized [00 02] -- Bad message format @@ -1864,8 +1872,11 @@ Table of contents: To make an INTRODUCE1 cell, the client must know a public encryption key B for the hidden service on this introduction circuit. The client generates a single-use keypair: + x,X = KEYGEN() + and computes: + intro_secret_hs_input = EXP(B,x) | AUTH_KEY | X | B | PROTOID info = m_hsexpand | subcredential hs_keys = KDF(intro_secret_hs_input | t_hsenc | info, S_KEY_LEN+MAC_LEN) @@ -1938,6 +1949,7 @@ Table of contents: (The above are used to finish the ntor handshake.)

The server's handshake reply is: + SERVER_PK Y [PK_PUBKEY_LEN bytes] AUTH AUTH_INPUT_MAC [MAC_LEN bytes]

@@ -1996,6 +2008,7 @@ Table of contents:

Single Onion Services attempt to build a non-anonymous single-hop circuit, but use an anonymous 3-hop circuit if: + * the rend point is on an address that is configured as unreachable via a direct connection, or * the initial attempt to connect to the rend point over a single-hop @@ -2257,6 +2270,7 @@ A.2. Tor's key derivation scheme clear writeup.)

Let B be the ed25519 basepoint as found in section 5 of [ED25519-B-REF]: + B = (15112221349535400772501151409588531511454012693041857206046113283949847762202, 46316835694926478169428394003475163141307993866256225615783033603165251855960)

diff --git a/srv-spec.txt b/srv-spec.txt index 6916020..a8bb878 100644 --- a/srv-spec.txt +++ b/srv-spec.txt @@ -197,6 +197,7 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. 2.5. Protocol Illustration

An illustration for better understanding the protocol can be found here: + https://people.torproject.org/~asn/hs_notes/shared_rand.jpg

It reads left-to-right. @@ -365,7 +366,9 @@ Tor works. This text used to be proposal 250-commit-reveal-consensus.txt. optional.

Participating authorities need to include the line: + "shared-rand-participate" + in their votes to announce that they take part in the protocol.

4.1.1. Computing commitments and reveals [COMMITREVEAL] diff --git a/tor-spec.txt b/tor-spec.txt index 552a453..6881436 100644 --- a/tor-spec.txt +++ b/tor-spec.txt @@ -226,6 +226,7 @@ see tor-design.pdf. certificate containing its identity key. The other party sends a similar certificate chain. The initiator's ClientHello MUST NOT include any ciphersuites other than: + TLS_DHE_RSA_WITH_AES_256_CBC_SHA TLS_DHE_RSA_WITH_AES_128_CBC_SHA SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA @@ -248,12 +249,14 @@ see tor-design.pdf. which the initiator can use to learn that the in-protocol handshake is in use. Specifically, at least one of these properties must be true of the certificate: + * The certificate is self-signed * Some component other than "commonName" is set in the subject or issuer DN of the certificate. * The commonName of the subject or issuer of the certificate ends with a suffix other than ".net". * The certificate's public key modulus is longer than 1024 bits. + The initiator then sends a VERSIONS cell to the responder, which then replies with a VERSIONS cell; they have then negotiated a Tor protocol version. Assuming that the version they negotiate is 3 or higher @@ -355,6 +358,7 @@ see tor-design.pdf. cipher is one not supported by OpenSSL 1.0.1.

The fixed ciphersuite list is: + TLS1_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS1_ECDHE_RSA_WITH_AES_256_CBC_SHA TLS1_DHE_RSA_WITH_AES_256_SHA @@ -450,6 +454,7 @@ see tor-design.pdf.

The 'Command' field of a fixed-length cell holds one of the following values: + 0 -- PADDING (Padding) (See Sec 7.2) 1 -- CREATE (Create a circuit) (See Sec 5.1) 2 -- CREATED (Acknowledge create) (See Sec 5.1) @@ -464,6 +469,7 @@ see tor-design.pdf. 12 -- PADDING_NEGOTIATE (Padding negotiation) (See Sec 7.2)

Variable-length command values are: + 7 -- VERSIONS (Negotiate proto version) (See Sec 4) 128 -- VPADDING (Variable-length padding) (See Sec 7.2) 129 -- CERTS (Certificates) (See Sec 4.2) @@ -472,6 +478,7 @@ see tor-design.pdf. 132 -- AUTHORIZE (Client authorization) (Not yet used)

The interpretation of 'Payload' depends on the type of the cell. + VPADDING/PADDING: Payload contains padding bytes. CREATE/CREATE2: Payload contains the handshake challenge. @@ -479,6 +486,7 @@ see tor-design.pdf. RELAY/RELAY_EARLY: Payload contains the relay header and relay body. DESTROY: Payload contains a reason for closing the circuit. (see 5.4) + Upon receiving any other value for the command field, an OR must drop the cell. Since more cell types may be added in the future, ORs should generally not warn when encountering unrecognized commands. @@ -486,6 +494,7 @@ see tor-design.pdf. The cell is padded up to the cell length with padding bytes.

Senders set padding bytes depending on the cell's command: + VERSIONS: Payload MUST NOT contain padding bytes. AUTHORIZE: Payload is unspecified and reserved for future use. Other variable-length cells: @@ -496,6 +505,7 @@ see tor-design.pdf. Other fixed-length cells: Payload MUST be padded to PAYLOAD_LEN with padding bytes. Padding bytes SHOULD be set to NUL. + We recommend random padding in RELAY/RELAY_EARLY cells, so that the cell content is unpredictable. See proposal 289 for details. For other cells, TLS authenticates cell content, so randomised padding bytes are @@ -594,6 +604,7 @@ see tor-design.pdf. list at least version 3.

Link protocols differences are: + 1 -- The "certs up front" handshake. 2 -- Uses the renegotiation-based handshake. Introduces variable-length cells. @@ -633,6 +644,7 @@ see tor-design.pdf.

To authenticate the responder as having a given Ed25519,RSA identity key combination, the initiator MUST check the following. + * The CERTS cell contains exactly one CertType 2 "ID" certificate. * The CERTS cell contains exactly one CertType 4 Ed25519 "Id->Signing" cert. @@ -658,6 +670,7 @@ see tor-design.pdf.

To authenticate the responder as having a given RSA identity only, the initiator MUST check the following: + * The CERTS cell contains exactly one CertType 1 "Link" certificate. * The CERTS cell contains exactly one CertType 2 "ID" certificate. * Both certificates have validAfter and validUntil dates that @@ -678,6 +691,7 @@ see tor-design.pdf.

To authenticate the initiator as having a given Ed25519,RSA identity key combination, the responder MUST check the following: + * The CERTS cell contains exactly one CertType 2 "ID" certificate. * The CERTS cell contains exactly one CertType 4 Ed25519 "Id->Signing" certificate. @@ -701,6 +715,7 @@ see tor-design.pdf.

To authenticate the initiator as having an RSA identity key only, the responder MUST check the following: + * The CERTS cell contains exactly one CertType 3 "AUTH" certificate. * The CERTS cell contains exactly one CertType 2 "ID" certificate. * Both certificates have validAfter and validUntil dates that @@ -712,6 +727,7 @@ see tor-design.pdf. * The auth certificate is correctly signed with the key in the ID certificate. * The ID certificate is correctly self-signed. + Checking these conditions is NOT sufficient to authenticate that the initiator has the ID it claims; to do so, the cells in 4.3 and 4.4 below must be exchanged. @@ -721,6 +737,7 @@ see tor-design.pdf.

An AUTH_CHALLENGE cell is a variable-length cell with the following fields: + Challenge [32 octets] N_Methods [2 octets] Methods [2 * N_Methods octets] @@ -864,6 +881,7 @@ see tor-design.pdf. AVAL (Address value in NBO)) [ALEN bytes]

Recognized address types (ATYPE) are: + [04] IPv4. [06] IPv6.

@@ -903,23 +921,29 @@ see tor-design.pdf. newer format is extensible by design; the older one is not.

A CREATE2 cell contains: + HTYPE (Client Handshake Type) [2 bytes] HLEN (Client Handshake Data Len) [2 bytes] HDATA (Client Handshake Data) [HLEN bytes]

A CREATED2 cell contains: + HLEN (Server Handshake Data Len) [2 bytes] HDATA (Server Handshake Data) [HLEN bytes]

Recognized handshake types are: + 0x0000 TAP -- the original Tor handshake; see 5.1.3 0x0001 reserved 0x0002 ntor -- the ntor+curve25519+sha256 handshake; see 5.1.4

The format of a CREATE cell is one of the following: + HDATA (Client Handshake Data) [TAP_C_HANDSHAKE_LEN bytes] + or + HTAG (Client Handshake Type Tag) [16 bytes] HDATA (Client Handshake Data) [TAP_C_HANDSHAKE_LEN-16 bytes]

@@ -931,7 +955,9 @@ see tor-design.pdf. ntor -- 'ntorNTORntorNTOR'

The format of a CREATED cell is: + HDATA (Server Handshake Data) [TAP_S_HANDSHAKE_LEN bytes] + (It's equivalent to a CREATED2 cell with length of TAP_S_HANDSHAKE_LEN.)

As usual with DH, x and y MUST be generated randomly. @@ -979,6 +1005,7 @@ see tor-design.pdf. relay cell to the last node in the circuit.

An EXTEND2 cell's relay payload contains: + NSPEC (Number of link specifiers) [1 byte] NSPEC times: LSTYPE (Link specifier type) [1 byte] @@ -990,6 +1017,7 @@ see tor-design.pdf.

Link specifiers describe the next node in the circuit and how to connect to it. Recognized specifiers are: + [00] TLS-over-TCP, IPv4 address A four-byte IPv4 address plus two-byte ORPort [01] TLS-over-TCP, IPv6 address @@ -1004,6 +1032,7 @@ see tor-design.pdf. instances of specifiers other than 'legacy identity'.

The relay payload for an EXTEND relay cell consists of: + Address [4 bytes] Port [2 bytes] Onion skin [TAP_C_HANDSHAKE_LEN bytes] @@ -1080,6 +1109,7 @@ see tor-design.pdf.

The payload for a CREATED cell, or the relay payload for an EXTENDED cell, contains: + DH data (g^y) [DH_LEN bytes] Derivative key data (KH) [HASH_LEN bytes] <see 5.2 below>

@@ -1112,6 +1142,7 @@ see tor-design.pdf. [The ntor handshake was added in Tor 0.2.4.8-alpha.]

In this section, define: + H(x,t) as HMAC_SHA256 with message x and key t. H_LENGTH = 32. ID_LENGTH = 20. @@ -1132,8 +1163,11 @@ see tor-design.pdf. digest for the server, and an ntor onion key (a curve25519 public key) for that server. Call the ntor onion key "B". The client generates a temporary keypair: + x,X = KEYGEN() + and generates a client-side handshake with contents: + NODEID Server identity digest [ID_LENGTH bytes] KEYID KEYID(B) [H_LENGTH bytes] CLIENT_PK X [G_LENGTH bytes] @@ -1147,6 +1181,7 @@ see tor-design.pdf. auth_input = verify | ID | B | Y | X | PROTOID | "Server"

The server's handshake reply is: + SERVER_PK Y [G_LENGTH bytes] AUTH H(auth_input, t_mac) [H_LENGTH bytes]

@@ -1214,6 +1249,7 @@ see tor-design.pdf.

From the base key material K0, they compute KEY_LEN*2+HASH_LEN*3 bytes of derivative key data as + K = H(K0 | [00]) | H(K0 | [01]) | H(K0 | [02]) | ...

The first HASH_LEN bytes of K form KH; the next HASH_LEN form the forward @@ -1333,6 +1369,7 @@ see tor-design.pdf. To prevent this, when an OR gets an extend request, it SHOULD use an existing OR connection if the ID matches, and ANY of the following conditions hold: + - The IP matches the requested IP. - The OR knows that the IP of the connection it's using is canonical because it was listed in the NETINFO cell. @@ -1346,12 +1383,14 @@ see tor-design.pdf. circuit's intended lifetime is over.

ORs SHOULD also tear down circuits which attempt to create: + * streams with RELAY_BEGIN, or * rendezvous points with ESTABLISH_RENDEZVOUS, ending at the first hop. Letting Tor be used as a single hop proxy makes exit and rendezvous nodes a more attractive target for compromise.

ORs MAY use multiple methods to check if they are the first hop: + * If an OR sees a circuit created with CREATE_FAST, the OR is sure to be the first hop of a circuit. * If an OR is the responder, and the initiator: @@ -1401,6 +1440,7 @@ see tor-design.pdf. this error code to 0, to avoid leaking its version.

The error codes are: + 0 -- NONE (No reason given.) 1 -- PROTOCOL (Tor protocol violation.) 2 -- INTERNAL (Internal error.) @@ -1438,6 +1478,7 @@ see tor-design.pdf.

When a relay cell is sent from an OP, the OP encrypts the payload with the stream cipher as follows: + OP sends relay cell: For I=N...1, where N is the destination node: Encrypt with Kf_I. @@ -1447,6 +1488,7 @@ see tor-design.pdf.

When a forward relay cell is received by an OR, it decrypts the payload with the stream cipher, as follows: + 'Forward' relay cell: Use Kf as key; decrypt.

@@ -1469,6 +1511,7 @@ see tor-design.pdf.

When a backward relay cell is received by an OR, it encrypts the payload with the stream cipher, as follows: + 'Backward' relay cell: Use Kb as key; encrypt.

@@ -1476,6 +1519,7 @@ see tor-design.pdf.

When a relay cell arrives at an OP, the OP decrypts the payload with the stream cipher as follows: + OP receives relay cell from node 1: For I=1...N, where N is the final node on the circuit: Decrypt with Kb_I. @@ -1517,6 +1561,7 @@ see tor-design.pdf. * onion services (RELAY_BEGIN, anonymous via a rendezvous point).

The payload of each unencrypted RELAY cell consists of: + Relay command [1 byte] 'Recognized' [2 bytes] StreamID [2 bytes] @@ -1525,6 +1570,7 @@ see tor-design.pdf. Data [PAYLOAD_LEN-11 bytes]

The relay commands are: + 1 -- RELAY_BEGIN [forward] 2 -- RELAY_DATA [forward or backward] 3 -- RELAY_END [forward or backward] @@ -1633,9 +1679,12 @@ see tor-design.pdf. exit node replies with a RELAY_END cell. (See 6.4 below.) Otherwise, the exit node replies with a RELAY_CONNECTED cell, whose payload is in one of the following formats: + The IPv4 address to which the connection was made [4 octets] A number of seconds (TTL) for which the address may be cached [4 octets] + or + Four zero-valued octets [4 octets] An address type (6) [1 octet] The IPv6 address to which the connection was made [16 octets] @@ -1783,6 +1832,7 @@ see tor-design.pdf. TTL (4 octets) "Length" is the length of the Value field. "Type" is one of: + 0x00 -- Hostname 0x04 -- IPv4 address 0x06 -- IPv6 address @@ -1842,6 +1892,7 @@ see tor-design.pdf. enabled as per padding-spec.txt. On these connections, clients may negotiate the use of padding with a CELL_PADDING_NEGOTIATE command whose format is as follows: + Version [1 byte] Command [1 byte] ito_low_ms [2 bytes] diff --git a/version-spec.txt b/version-spec.txt index f4db300..e7f855c 100644 --- a/version-spec.txt +++ b/version-spec.txt @@ -4,7 +4,9 @@ 1. The Old Way

Before 0.1.0, versions were of the format: + MAJOR.MINOR.MICRO(status(PATCHLEVEL))?(-cvs)? + where MAJOR, MINOR, MICRO, and PATCHLEVEL are numbers, status is one of "pre" (for an alpha release), "rc" (for a release candidate), or "." for a release. As a special case, "a.b.c" was equivalent to @@ -21,7 +23,9 @@ 2. The New Way

After 0.1.0, versions are of the format: + MAJOR.MINOR.MICRO[.PATCHLEVEL][-STATUS_TAG][ (EXTRA_INFO)]* + The stuff in parentheses is optional. As before, MAJOR, MINOR, MICRO, and PATCHLEVEL are numbers, with an absent number equivalent to 0. All versions should be distinguishable purely by those four