[tor-commits] [torspec/master] convert text blocks into widely compatible "blockquote" syntax
nickm at torproject.org
nickm at torproject.org
Mon Jan 13 18:31:28 UTC 2020
commit 9c86f54ba07355a968f982aed295e8b6597b4b89
Author: Hans-Christoph Steiner <hans at 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 at 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
More information about the tor-commits
mailing list