tor-commits January 2020

tor-commits@lists.torproject.org

19 participants
1596 discussions

[translation/support-portal] https://gitweb.torproject.org/translation.git/commit/?h=support-portal
by translation＠torproject.org 13 Jan '20

13 Jan '20

commit c2211a5c483e73f3befcff91e7471feeb1ac90bc Author: Translation commit bot <translation(a)torproject.org> Date: Mon Jan 13 18:53:57 2020 +0000 https://gitweb.torproject.org/translation.git/commit/?h=support-portal --- contents+ru.po | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/contents+ru.po b/contents+ru.po index b5417b156b..45bdca0d22 100644 --- a/contents+ru.po +++ b/contents+ru.po @@ -1,7 +1,6 @@ # Translators: # diana azaryan <dianazryn(a)gmail.com>, 2018 # JZDLin, 2019 -# Andrey, 2019 # Sergey Leschina <mail(a)putnik.tech>, 2019 # Тимур Нагорских <timnagorskikh2k18(a)gmail.com>, 2019 # Legenden Rifk <rekytcsgo(a)gmail.com>, 2019 @@ -152,7 +151,7 @@ msgid "" "do." msgstr "" "Иногда другие (например, ваш интернет-провайдер) могут узнать, что вы " -"используете Tor, но не посещаемые вами сайты. " +"используете Tor, но не видеть посещаемые вами сайты. " #: https//support.torproject.org/faq/faq-2/ #: (content/faq/faq-2/contents+en.lrquestion.title) @@ -192,7 +191,7 @@ msgid "" "to the blocked site will allow access." msgstr "" "В большинстве случаев достаточно скачать [Tor " -"Browser](https://www.torproject.org/download) и открыть в нем " +"Browser](https://www.torproject.org/ru/download/) и открыть в нем " "заблокированный сайт." #: https//support.torproject.org/faq/faq-2/ @@ -222,7 +221,7 @@ msgid "" "manual.torproject.org/circumvention/)." msgstr "" "Подробнее см. [Руководство пользователя Tor Browser](https://tb-" -"manual.torproject.org/ru/) , раздел [о цензуре](https://tb-" +"manual.torproject.org/ru/), раздел [о цензуре](https://tb-" "manual.torproject.org/ru/circumvention/)." #: https//support.torproject.org/faq/faq-3/ @@ -614,7 +613,7 @@ msgid "" "recommended](/tbb/tbb-9/)." msgstr "" "Использовать Tor с другими браузерами [опасно и не " -"рекомендуется](/tbb/tbb-9/)." +"рекомендуется](/ru/tbb/tbb-9/)." #: https//support.torproject.org/about/distribute-tor/ #: (content/about/distribute-tor/contents+en.lrquestion.title) @@ -729,7 +728,7 @@ msgid "" "details." msgstr "" "Подробнее о торговой марке можно почитать в этом " -"[FAQ](https://www.torproject.org/about/trademark/)." +"[FAQ](https://www.torproject.org/ru/about/trademark/)." #: https//support.torproject.org/about/how-is-tor-different-from-other-proxies/ #: (content/about/how-is-tor-different-from-other-proxies/contents+en.lrquestion.title) @@ -936,8 +935,8 @@ msgid "" "See this visualization of [Tor and HTTPS](/https/https-1/) to understand how" " Tor and HTTPS interact." msgstr "" -"[Эта иллюстрация](/https/https-1/) поможет понять, как вместе используются " -"Tor и HTTPS." +"[Эта иллюстрация](/ru/https/https-1/) поможет понять, как вместе " +"используются Tor и HTTPS." #: https//support.torproject.org/about/no-data-scrubbing/ #: (content/about/no-data-scrubbing/contents+en.lrquestion.title) @@ -1033,7 +1032,7 @@ msgid "" "[about](https://www.torproject.org/about/history/) page." msgstr "" "Подробнее о Tor можно почитать " -"[здесь](https://www.torproject.org/about/history/)." +"[здесь](https://www.torproject.org/ru/about/history/)." #: https//support.torproject.org/about/what-is-tor/ #: (content/about/what-is-tor/contents+en.lrquestion.description) @@ -1052,7 +1051,7 @@ msgstr "Откуда взялось название \"Tor\"?" #: https//support.torproject.org/about/why-is-it-called-tor/ #: (content/about/why-is-it-called-tor/contents+en.lrquestion.description) msgid "Because Tor is the onion routing network." -msgstr "Tor = сеть на основе The Onion Routing (\"луковой маршрутизации\")." +msgstr "Tor – сеть на основе The Onion Routing (\"луковой маршрутизации\")." #: https//support.torproject.org/about/why-is-it-called-tor/ #: (content/about/why-is-it-called-tor/contents+en.lrquestion.description) @@ -1079,7 +1078,7 @@ msgstr "" #: https//support.torproject.org/about/why-is-it-called-tor/ #: (content/about/why-is-it-called-tor/contents+en.lrquestion.description) msgid "(It's also got a fine translation from German and Turkish.)" -msgstr "" +msgstr "(Есть интересный перевод с немецкого и турецкого)." #: https//support.torproject.org/about/why-is-it-called-tor/ #: (content/about/why-is-it-called-tor/contents+en.lrquestion.description) @@ -1605,7 +1604,7 @@ msgstr "" msgid "" "My antivirus or malware protection is blocking me from accessing Tor " "Browser." -msgstr "Мой антивирус блокирует доступ к Tor Browser." +msgstr "Мой антивирус блокирует доступ к Tor Browser" #: https//support.torproject.org/tbb/tbb-10/ #: (content/tbb/tbb-10/contents+en.lrquestion.description) @@ -3043,7 +3042,7 @@ msgid "" "manual.torproject.org/installation/) section in the Tor Browser Manual." msgstr "" "Пожалуйста, обратите внимание на [раздел об установке](https://tb-" -"manual.torproject.org/installation/) руководства Tor Browser." +"manual.torproject.org/ru/installation/) руководства Tor Browser." #: https//support.torproject.org/tbb/tbb-47/ #: (content/tbb/tbb-47/contents+en.lrquestion.title) @@ -3121,7 +3120,7 @@ msgstr "" #: https//support.torproject.org/censorship/censorship-2/ #: (content/censorship/censorship-2/contents+en.lrquestion.title) msgid "A website I am trying to reach is blocking access over Tor." -msgstr "Сайт, на который я пытаюсь попасть, блокирует доступ из Tor." +msgstr "Сайт, на который я пытаюсь попасть, блокирует доступ из Tor" #: https//support.torproject.org/tbb/tbb-7/ #: (content/tbb/tbb-7/contents+en.lrquestion.description) @@ -3226,7 +3225,7 @@ msgid "" "If you are unable to connect to an onion service, please see <a " "href=\"/#onionservices-3\">I cannot reach X.onion!</a>" msgstr "" -"Если вы не можете подключиться к onion-сервису, пожалуйста, см. страницу <a " +"Если вы не можете подключиться к onion-ресурсу, пожалуйста, см. страницу <a " "href=\"/#onionservices-3\">Не удается подключиться к X.onion!</a>" #: https//support.torproject.org/tbb/tbb-9/ @@ -4213,7 +4212,7 @@ msgid "" "If you are still unable to connect to the onion service, please try again " "later." msgstr "" -"Если вы по-прежнему не можете подключиться к onion-сервису, пожалуйста, " +"Если вы по-прежнему не можете подключиться к onion-ресурсу, пожалуйста, " "попробуйте позже." #: https//support.torproject.org/connecting/connecting-3/

1 0

[torspec/master] build HTML GitLab Pages site with GitLab CI
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit fdfa3a5458d605d563637343dd58ac444dcf6dff Author: Hans-Christoph Steiner <hans(a)eds.org> Date: Tue Nov 26 22:16:04 2019 +0100 build HTML GitLab Pages site with GitLab CI This does a rough conversion to Markdown using regexps, then uses pandoc to convert the Markdown to HTML. An index.html is also generated to make it easy to find the various documents. This will create a site in any GitLab fork that has CI/CD and Pages setup, which is the default on gitlab.com. --- .gitlab-ci.yml | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 0000000..9211ec2 --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,33 @@ + +pages: + image: debian:buster + script: + - apt-get update + - apt-get -qy install --no-install-recommends pandoc + - test -d public || mkdir public + - printf '<!DOCTYPE html>\n\n<html><body><h1>%s</h1><ul>' $CI_PROJECT_PATH > public/index.html + - for f in *.txt; do + set -x; + name=`echo $f | sed s,\.txt$,,`; + md=${name}.md; + cat $f | sed --regexp-extended + -e '0,/^ +/{s/^ +/# /}' + -e 's/^ {1,3}([^ ])/\1/' + -e '/^[0-9]+\. +http/! s/^([0-9]+\. )/## \1/' + -e 's/^([0-9]+\.[0-9]+\. )/### \1/' + -e 's/^([0-9]+\.[0-9]+\.[0-9]+\. )/#### \1/' + -e 's/^([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+\. )/##### \1/' + > $md; + printf "\n---\n\noriginal source\x3a [$f](https://gitweb.torproject.org/torspec.git/tree/$f)\n" >> $md; + title=`sed -En '0,/^# /s/^# (.*)/\1/p' $md`; + printf "<li><a href=\"${name}.html\"><tt>$name</tt>&colon; $title</a></li>" >> public/index.html; + pandoc --from=markdown $md --output=public/${name}.html; + mkdir public/$name; + cp public/${name}.html public/$name/index.html; + done + - printf '</ul></body></html>' >> public/index.html + artifacts: + paths: + - public + only: + - master

1 0

[torspec/master] convert text blocks into widely compatible "blockquote" syntax
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit 9c86f54ba07355a968f982aed295e8b6597b4b89 Author: Hans-Christoph Steiner <hans(a)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(a)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

1 0

[torspec/master] gitlab-ci: add header/footer blocks to generate complete HTML
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit 2df60b7f6f2e02276c7b276115309a6c0f9fb4d7 Author: Hans-Christoph Steiner <hans(a)eds.org> Date: Sat Nov 30 14:25:32 2019 +0100 gitlab-ci: add header/footer blocks to generate complete HTML --- .gitlab-ci.yml | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9211ec2..d40f0e1 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,11 +1,27 @@ +variables: + HEADER: | + <!DOCTYPE html> + <html lang="en-US"> + <head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge"> + <meta name="viewport" content="width\=device-width, initial-scale=1"> + <meta name="author" content="The Tor Project, Inc."> + <title>torspec</title> + <link href="https://2019.www.torproject.org/css/master.min.css" rel="stylesheet"> + </head> + <body> + <div id="wrap"><div id="content"><div id="maincol"> + FOOTER: "</div></div></div></body></html>" + pages: image: debian:buster script: - apt-get update - apt-get -qy install --no-install-recommends pandoc - test -d public || mkdir public - - printf '<!DOCTYPE html>\n\n<html><body><h1>%s</h1><ul>' $CI_PROJECT_PATH > public/index.html + - printf "${HEADER}<h1>%s</h1><ul>" $CI_PROJECT_PATH > public/index.html - for f in *.txt; do set -x; name=`echo $f | sed s,\.txt$,,`; @@ -21,11 +37,14 @@ pages: printf "\n---\n\noriginal source\x3a [$f](https://gitweb.torproject.org/torspec.git/tree/$f)\n" >> $md; title=`sed -En '0,/^# /s/^# (.*)/\1/p' $md`; printf "<li><a href=\"${name}.html\"><tt>$name</tt>&colon; $title</a></li>" >> public/index.html; - pandoc --from=markdown $md --output=public/${name}.html; + pandoc --from=markdown $md --output=${name}.html; + printf "$HEADER" > public/${name}.html; + cat ${name}.html >> public/${name}.html; + printf "$FOOTER" >> public/${name}.html; mkdir public/$name; cp public/${name}.html public/$name/index.html; done - - printf '</ul></body></html>' >> public/index.html + - printf "</ul>$FOOTER" >> public/index.html artifacts: paths: - public

1 0

[torspec/master] Merge remote-tracking branch 'tor-github/pr/96'
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit 36b3b2cc06d50c3290c445501a3ceb8d55bb0415 Merge: 54346bf 2df60b7 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jan 13 13:31:23 2020 -0500 Merge remote-tracking branch 'tor-github/pr/96' .gitlab-ci.yml | 52 ++++++++++++++++++++++++++++++ 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 +++ 13 files changed, 303 insertions(+)

1 0

[tor/master] manpage: GuardfractionFile is authority-only
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit 4e597673b727a059550ddbdfe9b0c6f38f717f61 Author: Taylor Yu <catalyst(a)torproject.org> Date: Thu Jan 9 10:41:26 2020 -0600 manpage: GuardfractionFile is authority-only Only directory authorities use the GuardfractionFile option, so move it to that section. Part of ticket 32846. --- doc/tor.1.txt | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index c843112d0..26098f734 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -1954,12 +1954,6 @@ The following options are useful only for clients (that is, if Authorities or Single Onion Services. In these cases, this option is ignored. (Default: 1) -//Out of order because it logically belongs with the UseGuardFraction option -[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: - V3 authoritative directories only. Configures the location of the - guardfraction file which contains information about how long relays - have been guards. (Default: unset) - [[UseGuardFraction]] **UseGuardFraction** **0**|**1**|**auto**:: This option specifies whether clients should use the guardfraction information found in the consensus during path @@ -2994,6 +2988,11 @@ on the public Tor network. be written to temporary file, then renamed to the configured filename. (Default: unset) +[[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: + V3 authoritative directories only. Configures the location of the + guardfraction file which contains information about how long relays + have been guards. (Default: unset) + [[V3AuthUseLegacyKey]] **V3AuthUseLegacyKey** **0**|**1**:: If set, the directory authority will sign consensuses not only with its own signing key, but also with a "legacy" key and certificate with a

1 0

[tor/master] manpage: alphabetize client options
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit ec52c8ed69da64a105f7f9dc7abfa59a3943ec64 Author: Swati Thacker <swati.kgp13(a)gmail.com> Date: Fri Dec 27 00:22:54 2019 +0530 manpage: alphabetize client options Alphabetize client options in tor.1.txt. Closes ticket32846. --- changes/ticket32846 | 3 + doc/tor.1.txt | 1168 ++++++++++++++++++++++++++------------------------- 2 files changed, 593 insertions(+), 578 deletions(-) diff --git a/changes/ticket32846 b/changes/ticket32846 new file mode 100644 index 000000000..5022c6145 --- /dev/null +++ b/changes/ticket32846 @@ -0,0 +1,3 @@ + o Documentation (manpage): + - Alphabetize the Client Options section of the tor manpage. + Closes ticket 32846. diff --git a/doc/tor.1.txt b/doc/tor.1.txt index e1738c9ba..c843112d0 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -954,10 +954,30 @@ forward slash (/) in the configuration file and on the command line. == CLIENT OPTIONS +// These options are in alphabetical order, with exceptions as noted. +// Please keep them that way! + The following options are useful only for clients (that is, if **SocksPort**, **HTTPTunnelPort**, **TransPort**, **DNSPort**, or **NATDPort** is non-zero): +[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**:: + When this option is disabled, Tor blocks hostnames containing illegal + characters (like @ and :) rather than sending them to an exit node to be + resolved. This helps trap accidental attempts to resolve URLs and so on. + (Default: 0) + +[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**:: + When this option is enabled, and we get a request to resolve an address + that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an + unused virtual address to that address, and return the new virtual address. + This is handy for making ".onion" addresses work with applications that + resolve an address and then connect to it. (Default: 0) + +[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__:: + A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. + The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). + [[Bridge]] **Bridge** [__transport__] __IP__:__ORPort__ [__fingerprint__]:: When set along with UseBridges, instructs Tor to use the relay at "IP:ORPort" as a "bridge" relaying into the Tor network. If "fingerprint" @@ -978,6 +998,7 @@ The following options are useful only for clients (that is, if the documentation of the pluggable transport for details of what arguments it supports. +// Out of order because it logically belongs before the CircuitBuildTimeout option [[LearnCircuitBuildTimeout]] **LearnCircuitBuildTimeout** **0**|**1**:: If 0, CircuitBuildTimeout adaptive learning is disabled. (Default: 1) @@ -989,6 +1010,14 @@ The following options are useful only for clients (that is, if LearnCircuitBuildTimeout is 0, this value is the only value used. (Default: 60 seconds) +[[CircuitPadding]] **CircuitPadding** **0**|**1**:: + If set to 0, Tor will not pad client circuits with additional cover + traffic. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. If + set to 1, padding will be negotiated as per the consensus and relay + support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). + (Default: 1) + [[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__:: Tor will attempt to keep at least one open, unused circuit available for this amount of time. This option governs how long idle circuits are kept @@ -1005,6 +1034,58 @@ The following options are useful only for clients (that is, if If your network is particularly slow, you might want to set this to a number like 60. (Default: 0) +[[ClientAutoIPv6ORPort]] **ClientAutoIPv6ORPort** **0**|**1**:: + If this option is set to 1, Tor clients randomly prefer a node's IPv4 or + IPv6 ORPort. The random preference is set every time a node is loaded + from a new consensus or bridge config. When this option is set to 1, + **ClientPreferIPv6ORPort** is ignored. (Default: 0) + +[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients fetching from a list of fallback + directory mirrors. This schedule is advanced by (potentially concurrent) + connection attempts, unlike other schedules, which are advanced by + connection failures. (Default: 6) + +[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from authorities + if they are bootstrapping (that is, they don't have a usable, reasonably + live consensus). Only used by clients which don't have or won't fetch + from a list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0) + +[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__:: + Initial delay in seconds for when clients should download consensuses from fallback + directory mirrors if they are bootstrapping (that is, they don't have a + usable, reasonably live consensus). Only used by clients fetching from a + list of fallback directory mirrors. This schedule is advanced by + (potentially concurrent) connection attempts, unlike other schedules, + which are advanced by connection failures. (Default: 0) + +[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: + Try this many simultaneous connections to download a consensus before + waiting for one to complete, timeout, or error out. (Default: 3) + +[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**:: + If true, Tor does not believe any anonymously retrieved DNS answer that + tells it that an address resolves to an internal address (like 127.0.0.1 or + 192.168.0.1). This option prevents certain browser-based attacks; it + is not allowed to be set on the default network. (Default: 1) + +[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: + Path to the directory containing v3 hidden service authorization files. + Each file is for a single onion address, and the files MUST have the suffix + ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: + + + <onion-address>:descriptor:x25519:<base32-encoded-privkey> + + + The <onion-address> MUST NOT have the ".onion" suffix. The + <base32-encoded-privkey> is the base32 representation of the raw key bytes + only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of + https://spec.torproject.org/[torspec] for more information. + [[ClientOnly]] **ClientOnly** **0**|**1**:: If set to 1, Tor will not run as a relay or serve directory requests, even if the ORPort, ExtORPort, or DirPort options are @@ -1014,6 +1095,43 @@ The following options are useful only for clients (that is, if and fast enough. The current behavior is simply that Tor is a client unless ORPort, ExtORPort, or DirPort are configured.) (Default: 0) +[[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: + If this option is set to 1, Tor prefers a directory port with an IPv6 + address over one with IPv4, for direct connections, if a given directory + server has both. (Tor also prefers an IPv6 DirPort if IPv4Client is set to + 0.) If this option is set to auto, clients prefer IPv4. Other things may + influence the choice. This option breaks a tie to the favor of IPv6. + (Default: auto) (DEPRECATED: This option has had no effect for some + time.) + +[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**|**auto**:: + If this option is set to 1, Tor prefers an OR port with an IPv6 + address over one with IPv4 if a given entry node has both. (Tor also + prefers an IPv6 ORPort if IPv4Client is set to 0.) If this option is set + to auto, Tor bridge clients prefer the configured bridge address, and + other clients prefer IPv4. Other things may influence the choice. This + option breaks a tie to the favor of IPv6. (Default: auto) + +[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**:: + If true, Tor does not try to fulfill requests to connect to an internal + address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is + specifically requested__ (for example, via a .exit hostname, or a + controller request). If true, multicast DNS hostnames for machines on the + local network (of the form *.local) are also rejected. (Default: 1) + +[[ClientUseIPv4]] **ClientUseIPv4** **0**|**1**:: + If this option is set to 0, Tor will avoid connecting to directory servers + and entry nodes over IPv4. Note that clients with an IPv4 + address in a **Bridge**, proxy, or pluggable transport line will try + connecting over IPv4 even if **ClientUseIPv4** is set to 0. (Default: 1) + +[[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: + If this option is set to 1, Tor might connect to directory servers or + entry nodes over IPv6. For IPv6 only hosts, you need to also set + **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with + an IPv6 address in a **Bridge**, proxy, or pluggable transportline will + try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) + [[ConnectionPadding]] **ConnectionPadding** **0**|**1**|**auto**:: This option governs Tor's use of padding to defend against some forms of traffic analysis. If it is set to 'auto', Tor will send padding only @@ -1024,25 +1142,74 @@ The following options are useful only for clients (that is, if for use where bandwidth may be expensive. (Default: auto) -[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: - If set to 1, Tor will not not hold OR connections open for very long, - and will send less padding on these connections. Only clients may set - this option. This option should be offered via the UI to mobile users - for use where bandwidth may be expensive. (Default: 0) +[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + If non-zero, open this port to listen for UDP DNS requests, and resolve + them anonymously. This port only handles A, AAAA, and PTR requests---it + doesn't handle arbitrary DNS request types. Set the port to "auto" to + have Tor pick a port for + you. This directive can be specified multiple times to bind to multiple + addresses/ports. See SocksPort for an explanation of isolation + flags. (Default: 0) -[[CircuitPadding]] **CircuitPadding** **0**|**1**:: - If set to 0, Tor will not pad client circuits with additional cover - traffic. Only clients may set this option. This option should be offered - via the UI to mobile users for use where bandwidth may be expensive. If - set to 1, padding will be negotiated as per the consensus and relay - support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). - (Default: 1) +[[DormantCanceledByStartup]] **DormantCanceledByStartup** **0**|**1**:: + By default, Tor starts in active mode if it was active the last time + it was shut down, and in dormant mode if it was dormant. But if + this option is true, Tor treats every startup event as user + activity, and Tor will never start in Dormant mode, even if it has + been unused for a long time on previous runs. (Default: 0) + + + Note: Packagers and application developers should change the value of + this option only with great caution: it has the potential to + create spurious traffic on the network. This option should only + be used if Tor is started by an affirmative user activity (like + clicking on an applcation or running a command), and not if Tor + is launched for some other reason (for example, by a startup + process, or by an application that launches itself on every login.) -[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: - If set to 1, Tor will only use circuit padding algorithms that have low - overhead. Only clients may set this option. This option should be offered - via the UI to mobile users for use where bandwidth may be expensive. - (Default: 0) +[[DormantClientTimeout]] **DormantClientTimeout** __N__ **minutes**|**hours**|**days**|**weeks**:: + If Tor spends this much time without any client activity, + enter a dormant state where automatic circuits are not built, and + directory information is not fetched. + Does not affect servers or onion services. Must be at least 10 minutes. + (Default: 24 hours) + +[[DormantOnFirstStartup]] **DormantOnFirstStartup** **0**|**1**:: + If true, then the first time Tor starts up with a fresh DataDirectory, + it starts in dormant mode, and takes no actions until the user has made + a request. (This mode is recommended if installing a Tor client for a + user who might not actually use it.) If false, Tor bootstraps the first + time it is started, whether it sees a user request or not. + + + After the first time Tor starts, it begins in dormant mode if it was + dormant before, and not otherwise. (Default: 0) + +[[DormantTimeoutDisabledByIdleStreams]] **DormantTimeoutDisabledByIdleStreams** **0**|**1**:: + If true, then any open client stream (even one not reading or writing) + counts as client activity for the purpose of DormantClientTimeout. + If false, then only network activity counts. (Default: 1) + +[[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: + If true, Tor downloads and caches "extra-info" documents. These documents + contain information about servers other than the information in their + regular server descriptors. Tor does not use this information for anything + itself; to save bandwidth, leave this option turned off. (Default: 0) + +[[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**:: + If 1, Tor will not put two servers whose IP addresses are "too close" on + the same circuit. Currently, two addresses are "too close" if they lie in + the same /16 range. (Default: 1) + +[[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: + A list of identity fingerprints and country codes of nodes + to use for the first hop in your normal circuits. + Normal circuits include all + circuits except for direct connections to directory servers. The Bridge + option overrides this option; if you have configured bridges and + UseBridges is 1, the Bridges are used as your entry nodes. + + + + The ExcludeNodes option overrides this option: any node listed in both + EntryNodes and ExcludeNodes is treated as excluded. See + the **ExcludeNodes** option for more information on how to specify nodes. [[ExcludeNodes]] **ExcludeNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address @@ -1068,7 +1235,7 @@ The following options are useful only for clients (that is, if country can't be identified. No country code, including \{??}, works if no GeoIPFile can be loaded. See also the GeoIPExcludeUnknown option below. - +// Out of order because it logically belongs after the ExcludeNodes option [[ExcludeExitNodes]] **ExcludeExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to never use when picking an exit node---that is, a @@ -1078,14 +1245,6 @@ The following options are useful only for clients (that is, if the **ExcludeNodes** option for more information on how to specify nodes. See also the caveats on the "ExitNodes" option below. -[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**:: - If this option is set to 'auto', then whenever any country code is set in - ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and - possibly \{A1}) are treated as excluded as well. If this option is set to - '1', then all unknown countries are treated as excluded in ExcludeNodes - and ExcludeExitNodes. This option has no effect when a GeoIP file isn't - configured or can't be found. (Default: auto) - [[ExitNodes]] **ExitNodes** __node__,__node__,__...__:: A list of identity fingerprints, country codes, and address patterns of nodes to use as exit node---that is, a @@ -1110,51 +1269,6 @@ The following options are useful only for clients (that is, if The .exit address notation, if enabled via MapAddress, overrides this option. -[[MiddleNodes]] **MiddleNodes** __node__,__node__,__...__:: - A list of identity fingerprints and country codes of nodes - to use for "middle" hops in your normal circuits. - Normal circuits include all circuits except for direct connections - to directory servers. Middle hops are all hops other than exit and entry. + -+ - This is an **experimental** feature that is meant to be used by researchers - and developers to test new features in the Tor network safely. Using it - without care will strongly influence your anonymity. This feature might get - removed in the future. -+ - The HSLayer2Node and HSLayer3Node options override this option for onion - service circuits, if they are set. The vanguards addon will read this - option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes - from this set. -+ - The ExcludeNodes option overrides this option: any node listed in both - MiddleNodes and ExcludeNodes is treated as excluded. See - the **ExcludeNodes** option for more information on how to specify nodes. - -[[EntryNodes]] **EntryNodes** __node__,__node__,__...__:: - A list of identity fingerprints and country codes of nodes - to use for the first hop in your normal circuits. - Normal circuits include all - circuits except for direct connections to directory servers. The Bridge - option overrides this option; if you have configured bridges and - UseBridges is 1, the Bridges are used as your entry nodes. + - + - The ExcludeNodes option overrides this option: any node listed in both - EntryNodes and ExcludeNodes is treated as excluded. See - the **ExcludeNodes** option for more information on how to specify nodes. - -[[StrictNodes]] **StrictNodes** **0**|**1**:: - If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option - as a requirement to follow for all the circuits you generate, even if - doing so will break functionality for you (StrictNodes does not apply to - ExcludeExitNodes, ExitNodes, MiddleNodes, or MapAddress). If StrictNodes - is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, - but it will err on the side of avoiding unexpected errors. - Specifically, StrictNodes 0 tells Tor that it is okay to use an excluded - node when it is *necessary* to perform relay reachability self-tests, - connect to a hidden service, provide a hidden service to a client, - fulfill a .exit request, upload directory information, or download - directory information. (Default: 0) - [[FascistFirewall]] **FascistFirewall** **0**|**1**:: If 1, Tor will only create outgoing connections to ORs running on ports that your firewall allows (defaults to 80 and 443; see **FirewallPorts**). @@ -1168,35 +1282,13 @@ The following options are useful only for clients (that is, if **FascistFirewall** is set. This option is deprecated; use ReachableAddresses instead. (Default: 80, 443) -[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...:: - A comma-separated list of IP addresses and ports that your firewall allows - you to connect to. The format is as for the addresses in ExitPolicy, except - that "accept" is understood unless "reject" is explicitly provided. For - example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept - \*:80' means that your firewall allows connections to everything inside net - 99, rejects port 80 connections to net 18, and accepts connections to port - 80 otherwise. (Default: \'accept \*:*'.) - -[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...:: - Like **ReachableAddresses**, a list of addresses and ports. Tor will obey - these restrictions when fetching directory information, using standard HTTP - GET requests. If not set explicitly then the value of - **ReachableAddresses** is used. If **HTTPProxy** is set then these - connections will go through that proxy. (DEPRECATED: This option has - had no effect for some time.) - -[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...:: - Like **ReachableAddresses**, a list of addresses and ports. Tor will obey - these restrictions when connecting to Onion Routers, using TLS/SSL. If not - set explicitly then the value of **ReachableAddresses** is used. If - **HTTPSProxy** is set then these connections will go through that proxy. + - + - The separation between **ReachableORAddresses** and - **ReachableDirAddresses** is only interesting when you are connecting - through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit - TLS connections (which Tor uses to connect to Onion Routers) to port 443, - and some limit HTTP GET requests (which Tor uses for fetching directory - information) to port 80. +[[GeoIPExcludeUnknown]] **GeoIPExcludeUnknown** **0**|**1**|**auto**:: + If this option is set to 'auto', then whenever any country code is set in + ExcludeNodes or ExcludeExitNodes, all nodes with unknown country (\{??} and + possibly \{A1}) are treated as excluded as well. If this option is set to + '1', then all unknown countries are treated as excluded in ExcludeNodes + and ExcludeExitNodes. This option has no effect when a GeoIP file isn't + configured or can't be found. (Default: auto) [[HidServAuth]] **HidServAuth** __onion-address__ __auth-cookie__ [__service-name__]:: Client authorization for a v2 hidden service. Valid onion addresses contain 16 @@ -1208,17 +1300,125 @@ The following options are useful only for clients (that is, if services can be configured to require authorization using the **HiddenServiceAuthorizeClient** option. -[[ClientOnionAuthDir]] **ClientOnionAuthDir** __path__:: - Path to the directory containing v3 hidden service authorization files. - Each file is for a single onion address, and the files MUST have the suffix - ".auth_private" (i.e. "bob_onion.auth_private"). The content format MUST be: +[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + second hop in all client or service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary guard node. + (Default: Any node in the network may be used in the second hop.) + - <onion-address>:descriptor:x25519:<base32-encoded-privkey> + (Example: + HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + - The <onion-address> MUST NOT have the ".onion" suffix. The - <base32-encoded-privkey> is the base32 representation of the raw key bytes - only (32 bytes for x25519). See Appendix G in the rend-spec-v3.txt file of - https://spec.torproject.org/[torspec] for more information. + When this is set, the resulting hidden service paths will + look like: + + + C - G - L2 - M - Rend + + C - G - L2 - M - HSDir + + C - G - L2 - M - Intro + + S - G - L2 - M - Rend + + S - G - L2 - M - HSDir + + S - G - L2 - M - Intro + + + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + This option may be combined with HSLayer3Nodes to create + paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer2Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + When either this option or HSLayer3Nodes are set, the /16 subnet + and node family restrictions are removed for hidden service + circuits. Additionally, we allow the guard node to be present + as the Rend, HSDir, and IP node, and as the hop before it. This + is done to prevent the adversary from inferring information + about our guard, layer2, and layer3 node choices at later points + in the path. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer2Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + +[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__:: + A list of identity fingerprints, nicknames, country codes, and + address patterns of nodes that are allowed to be used as the + third hop in all client and service-side Onion Service circuits. + This option mitigates attacks where the adversary runs middle nodes + and induces your client or service to create many circuits, in order + to discover your primary or Layer2 guard nodes. + (Default: Any node in the network may be used in the third hop.) + + + (Example: + HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + + + + When this is set by itself, the resulting hidden service paths + will look like: + + C - G - M - L3 - Rend + + C - G - M - L3 - M - HSDir + + C - G - M - L3 - M - Intro + + S - G - M - L3 - M - Rend + + S - G - M - L3 - HSDir + + S - G - M - L3 - Intro + + where C is this client, S is the service, G is the Guard node, + L2 is a node from this option, and M is a random middle node. + Rend, HSDir, and Intro point selection is not affected by this + option. + + + While it is possible to use this option by itself, it should be + combined with HSLayer2Nodes to create paths of the form: + + + C - G - L2 - L3 - Rend + + C - G - L2 - L3 - M - HSDir + + C - G - L2 - L3 - M - Intro + + S - G - L2 - L3 - M - Rend + + S - G - L2 - L3 - HSDir + + S - G - L2 - L3 - Intro + + + + ExcludeNodes have higher priority than HSLayer3Nodes, + which means that nodes specified in ExcludeNodes will not be + picked. + + + When either this option or HSLayer2Nodes are set, the /16 subnet + and node family restrictions are removed for hidden service + circuits. Additionally, we allow the guard node to be present + as the Rend, HSDir, and IP node, and as the hop before it. This + is done to prevent the adversary from inferring information + about our guard, layer2, and layer3 node choices at later points + in the path. + + + This option is meant to be managed by a Tor controller such as + https://github.com/mikeperry-tor/vanguards that selects and + updates this set of nodes for you. Hence it does not do load + balancing if fewer than 20 nodes are selected, and if no nodes in + HSLayer3Nodes are currently available for use, Tor will not work. + Please use extreme care if you are setting this option manually. + +[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for proxy connections using the "HTTP CONNECT" + protocol instead of SOCKS. Set this to + 0 if you don't want to allow "HTTP CONNECT" connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + SOCKSPort for an explanation of isolation flags. (Default: 0) [[LongLivedPorts]] **LongLivedPorts** __PORTS__:: A list of ports for services that tend to have long-running connections @@ -1281,10 +1481,6 @@ The following options are useful only for clients (that is, if for the original address. You can use a wildcard mapping to handle redirects within the same site. -[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__:: - Every NUM seconds consider whether to build a new circuit. (Default: 30 - seconds) - [[MaxCircuitDirtiness]] **MaxCircuitDirtiness** __NUM__:: Feel free to reuse a circuit that was first used at most NUM seconds ago, but never attach a new stream to a circuit that is too old. For hidden @@ -1299,6 +1495,42 @@ The following options are useful only for clients (that is, if client streams. A circuit is pending if we have begun constructing it, but it has not yet been completely constructed. (Default: 32) +[[MiddleNodes]] **MiddleNodes** __node__,__node__,__...__:: + A list of identity fingerprints and country codes of nodes + to use for "middle" hops in your normal circuits. + Normal circuits include all circuits except for direct connections + to directory servers. Middle hops are all hops other than exit and entry. + ++ + This is an **experimental** feature that is meant to be used by researchers + and developers to test new features in the Tor network safely. Using it + without care will strongly influence your anonymity. This feature might get + removed in the future. ++ + The HSLayer2Node and HSLayer3Node options override this option for onion + service circuits, if they are set. The vanguards addon will read this + option, and if set, it will set HSLayer2Nodes and HSLayer3Nodes to nodes + from this set. ++ + The ExcludeNodes option overrides this option: any node listed in both + MiddleNodes and ExcludeNodes is treated as excluded. See + the **ExcludeNodes** option for more information on how to specify nodes. + +[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for connections from old versions of ipfw (as + included in old versions of FreeBSD, etc) using the NATD protocol. + Use 0 if you don't want to allow NATD connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + SocksPort for an explanation of isolation flags. + + + + This option is only for people who cannot use TransPort. (Default: 0) + +[[NewCircuitPeriod]] **NewCircuitPeriod** __NUM__:: + Every NUM seconds consider whether to build a new circuit. (Default: 30 + seconds) + [[NodeFamily]] **NodeFamily** __node__,__node__,__...__:: The Tor servers, defined by their identity fingerprints, constitute a "family" of similar or co-administered servers, so never use @@ -1309,36 +1541,168 @@ The following options are useful only for clients (that is, if codes in {curly braces}. See the **ExcludeNodes** option for more information on how to specify nodes. -[[EnforceDistinctSubnets]] **EnforceDistinctSubnets** **0**|**1**:: - If 1, Tor will not put two servers whose IP addresses are "too close" on - the same circuit. Currently, two addresses are "too close" if they lie in - the same /16 range. (Default: 1) +[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: + When this option is set, and Tor is using an exit node that supports + the feature, it will try optimistically to send data to the exit node + without waiting for the exit node to report whether the connection + succeeded. This can save a round-trip time for protocols like HTTP + where the client talks first. If OptimisticData is set to **auto**, + Tor will look at the UseOptimisticData parameter in the networkstatus. + (Default: auto) -[[SocksPort]] **SocksPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: - Open this port to listen for connections from SOCKS-speaking - applications. Set this to 0 if you don't want to allow application - connections via SOCKS. Set it to "auto" to have Tor pick a port for - you. This directive can be specified multiple times to bind - to multiple addresses/ports. If a unix domain socket is used, you may - quote the path using standard C escape sequences. - (Default: 9050) + +// These are out of order because they logically belong together +[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + + +[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ + + +[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ + + +[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ + + +[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ + + +[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__:: + These options override the default behavior of Tor's (**currently + experimental**) path bias detection algorithm. To try to find broken or + misbehaving guard nodes, Tor looks for nodes where more than a certain + fraction of circuits through that guard fail to get built. + + - NOTE: Although this option allows you to specify an IP address - other than localhost, you should do so only with extreme caution. - The SOCKS protocol is unencrypted and (as we use it) - unauthenticated, so exposing it in this way could leak your - information to anybody watching your network, and allow anybody - to use your computer as an open proxy. + + The PathBiasCircThreshold option controls how many circuits we need to build + through a guard before we make these checks. The PathBiasNoticeRate, + PathBiasWarnRate and PathBiasExtremeRate options control what fraction of + circuits must succeed through a guard so we won't write log messages. + If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards + is set to 1, we disable use of that guard. + + - If multiple entries of this option are present in your configuration - file, Tor will perform stream isolation between listeners by default. - The _isolation flags_ arguments give Tor rules for which streams - received on this SocksPort are allowed to share circuits with one - another. Recognized isolation flags are: - **IsolateClientAddr**;; - Don't share circuits with streams from a different - client address. (On by default and strongly recommended when - supported; you can disable it with **NoIsolateClientAddr**. + When we have seen more than PathBiasScaleThreshold + circuits through a guard, we scale our observations by 0.5 (governed by + the consensus) so that new observations don't get swamped by old ones. + + + + By default, or if a negative value is provided for one of these options, + Tor uses reasonable defaults from the networkstatus consensus document. + If no defaults are available there, these options default to 150, .70, + .50, .30, 0, and 300 respectively. + +// These are out of order because they logically belong together +[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ + + +[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ + + +[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ + + +[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__:: + Similar to the above options, these options override the default behavior + of Tor's (**currently experimental**) path use bias detection algorithm. + + + + Where as the path bias parameters govern thresholds for successfully + building circuits, these four path use bias parameters govern thresholds + only for circuit usage. Circuits which receive no stream usage + are not counted by this detection algorithm. A used circuit is considered + successful if it is capable of carrying streams or otherwise receiving + well-formed responses to RELAY cells. + + + + By default, or if a negative value is provided for one of these options, + Tor uses reasonable defaults from the networkstatus consensus document. + If no defaults are available there, these options default to 20, .80, + .60, and 100, respectively. + +[[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: + Tor clients don't build circuits for user traffic until they know + about enough of the network so that they could potentially construct + enough of the possible paths through the network. If this option + is set to a fraction between 0.25 and 0.95, Tor won't build circuits + until it has enough descriptors or microdescriptors to construct + that fraction of possible paths. Note that setting this option too low + can make your Tor client less anonymous, and setting it too high can + prevent your Tor client from bootstrapping. If this option is negative, + Tor will use a default value chosen by the directory authorities. If the + directory authorities do not choose a value, Tor will default to 0.6. + (Default: -1) + +[[ReachableAddresses]] **ReachableAddresses** __IP__[/__MASK__][:__PORT__]...:: + A comma-separated list of IP addresses and ports that your firewall allows + you to connect to. The format is as for the addresses in ExitPolicy, except + that "accept" is understood unless "reject" is explicitly provided. For + example, \'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept + \*:80' means that your firewall allows connections to everything inside net + 99, rejects port 80 connections to net 18, and accepts connections to port + 80 otherwise. (Default: \'accept \*:*'.) + +[[ReachableDirAddresses]] **ReachableDirAddresses** __IP__[/__MASK__][:__PORT__]...:: + Like **ReachableAddresses**, a list of addresses and ports. Tor will obey + these restrictions when fetching directory information, using standard HTTP + GET requests. If not set explicitly then the value of + **ReachableAddresses** is used. If **HTTPProxy** is set then these + connections will go through that proxy. (DEPRECATED: This option has + had no effect for some time.) + +[[ReachableORAddresses]] **ReachableORAddresses** __IP__[/__MASK__][:__PORT__]...:: + Like **ReachableAddresses**, a list of addresses and ports. Tor will obey + these restrictions when connecting to Onion Routers, using TLS/SSL. If not + set explicitly then the value of **ReachableAddresses** is used. If + **HTTPSProxy** is set then these connections will go through that proxy. + + + + The separation between **ReachableORAddresses** and + **ReachableDirAddresses** is only interesting when you are connecting + through proxies (see **HTTPProxy** and **HTTPSProxy**). Most proxies limit + TLS connections (which Tor uses to connect to Onion Routers) to port 443, + and some limit HTTP GET requests (which Tor uses for fetching directory + information) to port 80. + +[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: + If set to 1, Tor will only use circuit padding algorithms that have low + overhead. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. + (Default: 0) + +[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: + If set to 1, Tor will not not hold OR connections open for very long, + and will send less padding on these connections. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. (Default: 0) + +[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: + Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor + will instead refuse to make the connection. (Default: None) + +[[SafeSocks]] **SafeSocks** **0**|**1**:: + When this option is enabled, Tor will reject application connections that + use unsafe variants of the socks protocol -- ones that only provide an IP + address, meaning the application is doing a DNS resolve first. + Specifically, these are socks4 and socks5 when not doing remote DNS. + (Default: 0) + +[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: + Set an entrance policy for this server, to limit who can connect to the + SocksPort and DNSPort ports. The policies have the same form as exit + policies below, except that port specifiers are ignored. Any address + not matched by some entry in the policy is accepted. + +[[SocksPort]] **SocksPort** ['address'**:**]{empty}__port__|**unix:**__path__|**auto** [_flags_] [_isolation flags_]:: + Open this port to listen for connections from SOCKS-speaking + applications. Set this to 0 if you don't want to allow application + connections via SOCKS. Set it to "auto" to have Tor pick a port for + you. This directive can be specified multiple times to bind + to multiple addresses/ports. If a unix domain socket is used, you may + quote the path using standard C escape sequences. + (Default: 9050) + + + + NOTE: Although this option allows you to specify an IP address + other than localhost, you should do so only with extreme caution. + The SOCKS protocol is unencrypted and (as we use it) + unauthenticated, so exposing it in this way could leak your + information to anybody watching your network, and allow anybody + to use your computer as an open proxy. + + + + If multiple entries of this option are present in your configuration + file, Tor will perform stream isolation between listeners by default. + The _isolation flags_ arguments give Tor rules for which streams + received on this SocksPort are allowed to share circuits with one + another. Recognized isolation flags are: + **IsolateClientAddr**;; + Don't share circuits with streams from a different + client address. (On by default and strongly recommended when + supported; you can disable it with **NoIsolateClientAddr**. Unsupported and force-disabled when using Unix domain sockets.) **IsolateSOCKSAuth**;; Don't share circuits with streams for which different @@ -1482,17 +1846,31 @@ The following options are useful only for clients (that is, if line is used, and all earlier flags are ignored. No error is issued for conflicting flags. -[[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: - Set an entrance policy for this server, to limit who can connect to the - SocksPort and DNSPort ports. The policies have the same form as exit - policies below, except that port specifiers are ignored. Any address - not matched by some entry in the policy is accepted. - [[SocksTimeout]] **SocksTimeout** __NUM__:: Let a socks connection wait NUM seconds handshaking, and NUM seconds unattached waiting for an appropriate circuit, before we fail it. (Default: 2 minutes) +[[StrictNodes]] **StrictNodes** **0**|**1**:: + If StrictNodes is set to 1, Tor will treat solely the ExcludeNodes option + as a requirement to follow for all the circuits you generate, even if + doing so will break functionality for you (StrictNodes does not apply to + ExcludeExitNodes, ExitNodes, MiddleNodes, or MapAddress). If StrictNodes + is set to 0, Tor will still try to avoid nodes in the ExcludeNodes list, + but it will err on the side of avoiding unexpected errors. + Specifically, StrictNodes 0 tells Tor that it is okay to use an excluded + node when it is *necessary* to perform relay reachability self-tests, + connect to a hidden service, provide a hidden service to a client, + fulfill a .exit request, upload directory information, or download + directory information. (Default: 0) + +[[TestSocks]] **TestSocks** **0**|**1**:: + When this option is enabled, Tor will make a notice-level log entry for + each connection to the Socks port indicating whether the request used a + safe socks protocol or an unsafe one (see above entry on SafeSocks). This + helps to determine whether an application using Tor is possibly leaking + DNS requests. (Default: 0) + [[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: Set the refill delay interval of Tor's token bucket to NUM milliseconds. NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth, @@ -1520,6 +1898,44 @@ The following options are useful only for clients (that is, if association between host and exit server after NUM seconds. The default is 1800 seconds (30 minutes). +[[TransPort]] **TransPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: + Open this port to listen for transparent proxy connections. Set this to + 0 if you don't want to allow transparent proxy connections. Set the port + to "auto" to have Tor pick a port for you. This directive can be + specified multiple times to bind to multiple addresses/ports. If multiple + entries of this option are present in your configuration file, Tor will + perform stream isolation between listeners by default. See + SOCKSPort for an explanation of isolation flags. + + + + TransPort requires OS support for transparent proxies, such as BSDs' pf or + Linux's IPTables. If you're planning to use Tor as a transparent proxy for + a network, you'll want to examine and change VirtualAddrNetwork from the + default setting. (Default: 0) + +[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: + TransProxyType may only be enabled when there is transparent proxy listener + enabled. + + + + Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module + to transparently proxy connections that are configured using the TransPort + option. Detailed information on how to configure the TPROXY + feature can be found in the Linux kernel source tree in the file + Documentation/networking/tproxy.txt. + + + + Set this option to "ipfw" to use the FreeBSD ipfw interface. + + + + On *BSD operating systems when using pf, set this to "pf-divert" to take + advantage of +divert-to+ rules, which do not modify the packets like + +rdr-to+ rules do. Detailed information on how to configure pf to use + +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD, + +divert-to+ is available to use on versions greater than or equal to + OpenBSD 4.4. + + + + Set this to "default", or leave it unconfigured, to use regular IPTables + on Linux, or to use pf +rdr-to+ rules on *BSD systems. + + + + (Default: "default") + [[UpdateBridgesFromAuthority]] **UpdateBridgesFromAuthority** **0**|**1**:: When set (along with UseBridges), Tor will try to fetch bridge descriptors from the configured bridge authorities when feasible. It will fall back to @@ -1538,6 +1954,7 @@ The following options are useful only for clients (that is, if Authorities or Single Onion Services. In these cases, this option is ignored. (Default: 1) +//Out of order because it logically belongs with the UseGuardFraction option [[GuardfractionFile]] **GuardfractionFile** __FILENAME__:: V3 authoritative directories only. Configures the location of the guardfraction file which contains information about how long relays @@ -1549,12 +1966,27 @@ The following options are useful only for clients (that is, if selection. If it's set to 'auto', clients will do what the UseGuardFraction consensus parameter tells them to do. (Default: auto) +//Out of order because it logically belongs after the UseEntryGuards option +[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**:: + If UseEntryGuards is set, minimum time to keep a guard on our guard list + before picking a new one. If less than one day, we use defaults from the + consensus directory. (Default: 0) + +//Out of order because it logically belongs after the UseEntryGuards option +[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: + If UseEntryGuards is set to 1, we try to make sure we have at least NUM + routers to use as directory guards. If this option is set to 0, use the + value from the guard-n-primary-dir-guards-to-use consensus parameter, and + default to 3 if the consensus parameter isn't set. (Default: 0) + +//Out of order because it logically belongs after the UseEntryGuards option [[NumEntryGuards]] **NumEntryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick a total of NUM routers as long-term entries for our circuits. If NUM is 0, we try to learn the number from the guard-n-primary-guards-to-use consensus parameter, and default to 1 if the consensus parameter isn't set. (Default: 0) +//Out of order because it logically belongs after the UseEntryGuards option [[NumPrimaryGuards]] **NumPrimaryGuards** __NUM__:: If UseEntryGuards is set to 1, we will try to pick NUM routers for our primary guard list, which is the set of routers we strongly prefer when @@ -1562,30 +1994,13 @@ The following options are useful only for clients (that is, if the guard-n-primary-guards consensus parameter, and default to 3 if the consensus parameter isn't set. (Default: 0) -[[NumDirectoryGuards]] **NumDirectoryGuards** __NUM__:: - If UseEntryGuards is set to 1, we try to make sure we have at least NUM - routers to use as directory guards. If this option is set to 0, use the - value from the guard-n-primary-dir-guards-to-use consensus parameter, and - default to 3 if the consensus parameter isn't set. (Default: 0) - -[[GuardLifetime]] **GuardLifetime** __N__ **days**|**weeks**|**months**:: - If UseEntryGuards is set, minimum time to keep a guard on our guard list - before picking a new one. If less than one day, we use defaults from the - consensus directory. (Default: 0) - -[[SafeSocks]] **SafeSocks** **0**|**1**:: - When this option is enabled, Tor will reject application connections that - use unsafe variants of the socks protocol -- ones that only provide an IP - address, meaning the application is doing a DNS resolve first. - Specifically, these are socks4 and socks5 when not doing remote DNS. - (Default: 0) - -[[TestSocks]] **TestSocks** **0**|**1**:: - When this option is enabled, Tor will make a notice-level log entry for - each connection to the Socks port indicating whether the request used a - safe socks protocol or an unsafe one (see above entry on SafeSocks). This - helps to determine whether an application using Tor is possibly leaking - DNS requests. (Default: 0) +[[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: + Microdescriptors are a smaller version of the information that Tor needs + in order to build its circuits. Using microdescriptors makes Tor clients + download less directory information, thus saving bandwidth. Directory + caches need to fetch regular descriptors and microdescriptors, so this + option doesn't save any bandwidth for them. For legacy reasons, auto is + accepted, but it has the same effect as 1. (Default: auto) [[VirtualAddrNetworkIPv4]] **VirtualAddrNetworkIPv4** __IPv4Address__/__bits__ + @@ -1606,415 +2021,12 @@ The following options are useful only for clients (that is, if used IP. For local use, no change to the default VirtualAddrNetwork setting is needed. -[[AllowNonRFC953Hostnames]] **AllowNonRFC953Hostnames** **0**|**1**:: - When this option is disabled, Tor blocks hostnames containing illegal - characters (like @ and :) rather than sending them to an exit node to be - resolved. This helps trap accidental attempts to resolve URLs and so on. - (Default: 0) - -[[HTTPTunnelPort]] **HTTPTunnelPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for proxy connections using the "HTTP CONNECT" - protocol instead of SOCKS. Set this to - 0 if you don't want to allow "HTTP CONNECT" connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - SOCKSPort for an explanation of isolation flags. (Default: 0) +[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: + Tells Tor to issue a warnings whenever the user tries to make an anonymous + connection to one of these ports. This option is designed to alert users + to services that risk sending passwords in the clear. (Default: + 23,109,110,143) -[[TransPort]] **TransPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for transparent proxy connections. Set this to - 0 if you don't want to allow transparent proxy connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - SOCKSPort for an explanation of isolation flags. + - + - TransPort requires OS support for transparent proxies, such as BSDs' pf or - Linux's IPTables. If you're planning to use Tor as a transparent proxy for - a network, you'll want to examine and change VirtualAddrNetwork from the - default setting. (Default: 0) - -[[TransProxyType]] **TransProxyType** **default**|**TPROXY**|**ipfw**|**pf-divert**:: - TransProxyType may only be enabled when there is transparent proxy listener - enabled. + - + - Set this to "TPROXY" if you wish to be able to use the TPROXY Linux module - to transparently proxy connections that are configured using the TransPort - option. Detailed information on how to configure the TPROXY - feature can be found in the Linux kernel source tree in the file - Documentation/networking/tproxy.txt. + - + - Set this option to "ipfw" to use the FreeBSD ipfw interface. + - + - On *BSD operating systems when using pf, set this to "pf-divert" to take - advantage of +divert-to+ rules, which do not modify the packets like - +rdr-to+ rules do. Detailed information on how to configure pf to use - +divert-to+ rules can be found in the pf.conf(5) manual page. On OpenBSD, - +divert-to+ is available to use on versions greater than or equal to - OpenBSD 4.4. + - + - Set this to "default", or leave it unconfigured, to use regular IPTables - on Linux, or to use pf +rdr-to+ rules on *BSD systems. + - + - (Default: "default") - -[[NATDPort]] **NATDPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - Open this port to listen for connections from old versions of ipfw (as - included in old versions of FreeBSD, etc) using the NATD protocol. - Use 0 if you don't want to allow NATD connections. Set the port - to "auto" to have Tor pick a port for you. This directive can be - specified multiple times to bind to multiple addresses/ports. If multiple - entries of this option are present in your configuration file, Tor will - perform stream isolation between listeners by default. See - SocksPort for an explanation of isolation flags. + - + - This option is only for people who cannot use TransPort. (Default: 0) - -[[AutomapHostsOnResolve]] **AutomapHostsOnResolve** **0**|**1**:: - When this option is enabled, and we get a request to resolve an address - that ends with one of the suffixes in **AutomapHostsSuffixes**, we map an - unused virtual address to that address, and return the new virtual address. - This is handy for making ".onion" addresses work with applications that - resolve an address and then connect to it. (Default: 0) - -[[AutomapHostsSuffixes]] **AutomapHostsSuffixes** __SUFFIX__,__SUFFIX__,__...__:: - A comma-separated list of suffixes to use with **AutomapHostsOnResolve**. - The "." suffix is equivalent to "all addresses." (Default: .exit,.onion). - -[[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: - If non-zero, open this port to listen for UDP DNS requests, and resolve - them anonymously. This port only handles A, AAAA, and PTR requests---it - doesn't handle arbitrary DNS request types. Set the port to "auto" to - have Tor pick a port for - you. This directive can be specified multiple times to bind to multiple - addresses/ports. See SocksPort for an explanation of isolation - flags. (Default: 0) - -[[ClientDNSRejectInternalAddresses]] **ClientDNSRejectInternalAddresses** **0**|**1**:: - If true, Tor does not believe any anonymously retrieved DNS answer that - tells it that an address resolves to an internal address (like 127.0.0.1 or - 192.168.0.1). This option prevents certain browser-based attacks; it - is not allowed to be set on the default network. (Default: 1) - -[[ClientRejectInternalAddresses]] **ClientRejectInternalAddresses** **0**|**1**:: - If true, Tor does not try to fulfill requests to connect to an internal - address (like 127.0.0.1 or 192.168.0.1) __unless an exit node is - specifically requested__ (for example, via a .exit hostname, or a - controller request). If true, multicast DNS hostnames for machines on the - local network (of the form *.local) are also rejected. (Default: 1) - -[[DownloadExtraInfo]] **DownloadExtraInfo** **0**|**1**:: - If true, Tor downloads and caches "extra-info" documents. These documents - contain information about servers other than the information in their - regular server descriptors. Tor does not use this information for anything - itself; to save bandwidth, leave this option turned off. (Default: 0) - -[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: - Tells Tor to issue a warnings whenever the user tries to make an anonymous - connection to one of these ports. This option is designed to alert users - to services that risk sending passwords in the clear. (Default: - 23,109,110,143) - -[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: - Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor - will instead refuse to make the connection. (Default: None) - -[[OptimisticData]] **OptimisticData** **0**|**1**|**auto**:: - When this option is set, and Tor is using an exit node that supports - the feature, it will try optimistically to send data to the exit node - without waiting for the exit node to report whether the connection - succeeded. This can save a round-trip time for protocols like HTTP - where the client talks first. If OptimisticData is set to **auto**, - Tor will look at the UseOptimisticData parameter in the networkstatus. - (Default: auto) - -[[HSLayer2Nodes]] **HSLayer2Nodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes, and - address patterns of nodes that are allowed to be used as the - second hop in all client or service-side Onion Service circuits. - This option mitigates attacks where the adversary runs middle nodes - and induces your client or service to create many circuits, in order - to discover your primary guard node. - (Default: Any node in the network may be used in the second hop.) - + - (Example: - HSLayer2Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - When this is set, the resulting hidden service paths will - look like: - + - C - G - L2 - M - Rend + - C - G - L2 - M - HSDir + - C - G - L2 - M - Intro + - S - G - L2 - M - Rend + - S - G - L2 - M - HSDir + - S - G - L2 - M - Intro + - + - where C is this client, S is the service, G is the Guard node, - L2 is a node from this option, and M is a random middle node. - Rend, HSDir, and Intro point selection is not affected by this - option. - + - This option may be combined with HSLayer3Nodes to create - paths of the form: - + - C - G - L2 - L3 - Rend + - C - G - L2 - L3 - M - HSDir + - C - G - L2 - L3 - M - Intro + - S - G - L2 - L3 - M - Rend + - S - G - L2 - L3 - HSDir + - S - G - L2 - L3 - Intro + - + - ExcludeNodes have higher priority than HSLayer2Nodes, - which means that nodes specified in ExcludeNodes will not be - picked. - + - When either this option or HSLayer3Nodes are set, the /16 subnet - and node family restrictions are removed for hidden service - circuits. Additionally, we allow the guard node to be present - as the Rend, HSDir, and IP node, and as the hop before it. This - is done to prevent the adversary from inferring information - about our guard, layer2, and layer3 node choices at later points - in the path. - + - This option is meant to be managed by a Tor controller such as - https://github.com/mikeperry-tor/vanguards that selects and - updates this set of nodes for you. Hence it does not do load - balancing if fewer than 20 nodes are selected, and if no nodes in - HSLayer2Nodes are currently available for use, Tor will not work. - Please use extreme care if you are setting this option manually. - -[[HSLayer3Nodes]] **HSLayer3Nodes** __node__,__node__,__...__:: - A list of identity fingerprints, nicknames, country codes, and - address patterns of nodes that are allowed to be used as the - third hop in all client and service-side Onion Service circuits. - This option mitigates attacks where the adversary runs middle nodes - and induces your client or service to create many circuits, in order - to discover your primary or Layer2 guard nodes. - (Default: Any node in the network may be used in the third hop.) - + - (Example: - HSLayer3Nodes ABCD1234CDEF5678ABCD1234CDEF5678ABCD1234, \{cc}, 255.254.0.0/8) + - + - When this is set by itself, the resulting hidden service paths - will look like: + - C - G - M - L3 - Rend + - C - G - M - L3 - M - HSDir + - C - G - M - L3 - M - Intro + - S - G - M - L3 - M - Rend + - S - G - M - L3 - HSDir + - S - G - M - L3 - Intro + - where C is this client, S is the service, G is the Guard node, - L2 is a node from this option, and M is a random middle node. - Rend, HSDir, and Intro point selection is not affected by this - option. - + - While it is possible to use this option by itself, it should be - combined with HSLayer2Nodes to create paths of the form: - + - C - G - L2 - L3 - Rend + - C - G - L2 - L3 - M - HSDir + - C - G - L2 - L3 - M - Intro + - S - G - L2 - L3 - M - Rend + - S - G - L2 - L3 - HSDir + - S - G - L2 - L3 - Intro + - + - ExcludeNodes have higher priority than HSLayer3Nodes, - which means that nodes specified in ExcludeNodes will not be - picked. - + - When either this option or HSLayer2Nodes are set, the /16 subnet - and node family restrictions are removed for hidden service - circuits. Additionally, we allow the guard node to be present - as the Rend, HSDir, and IP node, and as the hop before it. This - is done to prevent the adversary from inferring information - about our guard, layer2, and layer3 node choices at later points - in the path. - + - This option is meant to be managed by a Tor controller such as - https://github.com/mikeperry-tor/vanguards that selects and - updates this set of nodes for you. Hence it does not do load - balancing if fewer than 20 nodes are selected, and if no nodes in - HSLayer3Nodes are currently available for use, Tor will not work. - Please use extreme care if you are setting this option manually. - -[[UseMicrodescriptors]] **UseMicrodescriptors** **0**|**1**|**auto**:: - Microdescriptors are a smaller version of the information that Tor needs - in order to build its circuits. Using microdescriptors makes Tor clients - download less directory information, thus saving bandwidth. Directory - caches need to fetch regular descriptors and microdescriptors, so this - option doesn't save any bandwidth for them. For legacy reasons, auto is - accepted, but it has the same effect as 1. (Default: auto) - -[[PathBiasCircThreshold]] **PathBiasCircThreshold** __NUM__ + - -[[PathBiasNoticeRate]] **PathBiasNoticeRate** __NUM__ + - -[[PathBiasWarnRate]] **PathBiasWarnRate** __NUM__ + - -[[PathBiasExtremeRate]] **PathBiasExtremeRate** __NUM__ + - -[[PathBiasDropGuards]] **PathBiasDropGuards** __NUM__ + - -[[PathBiasScaleThreshold]] **PathBiasScaleThreshold** __NUM__:: - These options override the default behavior of Tor's (**currently - experimental**) path bias detection algorithm. To try to find broken or - misbehaving guard nodes, Tor looks for nodes where more than a certain - fraction of circuits through that guard fail to get built. + - + - The PathBiasCircThreshold option controls how many circuits we need to build - through a guard before we make these checks. The PathBiasNoticeRate, - PathBiasWarnRate and PathBiasExtremeRate options control what fraction of - circuits must succeed through a guard so we won't write log messages. - If less than PathBiasExtremeRate circuits succeed *and* PathBiasDropGuards - is set to 1, we disable use of that guard. + - + - When we have seen more than PathBiasScaleThreshold - circuits through a guard, we scale our observations by 0.5 (governed by - the consensus) so that new observations don't get swamped by old ones. + - + - By default, or if a negative value is provided for one of these options, - Tor uses reasonable defaults from the networkstatus consensus document. - If no defaults are available there, these options default to 150, .70, - .50, .30, 0, and 300 respectively. - -[[PathBiasUseThreshold]] **PathBiasUseThreshold** __NUM__ + - -[[PathBiasNoticeUseRate]] **PathBiasNoticeUseRate** __NUM__ + - -[[PathBiasExtremeUseRate]] **PathBiasExtremeUseRate** __NUM__ + - -[[PathBiasScaleUseThreshold]] **PathBiasScaleUseThreshold** __NUM__:: - Similar to the above options, these options override the default behavior - of Tor's (**currently experimental**) path use bias detection algorithm. + - + - Where as the path bias parameters govern thresholds for successfully - building circuits, these four path use bias parameters govern thresholds - only for circuit usage. Circuits which receive no stream usage - are not counted by this detection algorithm. A used circuit is considered - successful if it is capable of carrying streams or otherwise receiving - well-formed responses to RELAY cells. + - + - By default, or if a negative value is provided for one of these options, - Tor uses reasonable defaults from the networkstatus consensus document. - If no defaults are available there, these options default to 20, .80, - .60, and 100, respectively. - -[[ClientUseIPv4]] **ClientUseIPv4** **0**|**1**:: - If this option is set to 0, Tor will avoid connecting to directory servers - and entry nodes over IPv4. Note that clients with an IPv4 - address in a **Bridge**, proxy, or pluggable transport line will try - connecting over IPv4 even if **ClientUseIPv4** is set to 0. (Default: 1) - -[[ClientUseIPv6]] **ClientUseIPv6** **0**|**1**:: - If this option is set to 1, Tor might connect to directory servers or - entry nodes over IPv6. For IPv6 only hosts, you need to also set - **ClientUseIPv4** to 0 to disable IPv4. Note that clients configured with - an IPv6 address in a **Bridge**, proxy, or pluggable transportline will - try connecting over IPv6 even if **ClientUseIPv6** is set to 0. (Default: 0) - -[[ClientPreferIPv6DirPort]] **ClientPreferIPv6DirPort** **0**|**1**|**auto**:: - If this option is set to 1, Tor prefers a directory port with an IPv6 - address over one with IPv4, for direct connections, if a given directory - server has both. (Tor also prefers an IPv6 DirPort if IPv4Client is set to - 0.) If this option is set to auto, clients prefer IPv4. Other things may - influence the choice. This option breaks a tie to the favor of IPv6. - (Default: auto) (DEPRECATED: This option has had no effect for some - time.) - -[[ClientPreferIPv6ORPort]] **ClientPreferIPv6ORPort** **0**|**1**|**auto**:: - If this option is set to 1, Tor prefers an OR port with an IPv6 - address over one with IPv4 if a given entry node has both. (Tor also - prefers an IPv6 ORPort if IPv4Client is set to 0.) If this option is set - to auto, Tor bridge clients prefer the configured bridge address, and - other clients prefer IPv4. Other things may influence the choice. This - option breaks a tie to the favor of IPv6. (Default: auto) - -[[ClientAutoIPv6ORPort]] **ClientAutoIPv6ORPort** **0**|**1**:: - If this option is set to 1, Tor clients randomly prefer a node's IPv4 or - IPv6 ORPort. The random preference is set every time a node is loaded - from a new consensus or bridge config. When this option is set to 1, - **ClientPreferIPv6ORPort** is ignored. (Default: 0) - -[[PathsNeededToBuildCircuits]] **PathsNeededToBuildCircuits** __NUM__:: - Tor clients don't build circuits for user traffic until they know - about enough of the network so that they could potentially construct - enough of the possible paths through the network. If this option - is set to a fraction between 0.25 and 0.95, Tor won't build circuits - until it has enough descriptors or microdescriptors to construct - that fraction of possible paths. Note that setting this option too low - can make your Tor client less anonymous, and setting it too high can - prevent your Tor client from bootstrapping. If this option is negative, - Tor will use a default value chosen by the directory authorities. If the - directory authorities do not choose a value, Tor will default to 0.6. - (Default: -1) - -[[ClientBootstrapConsensusAuthorityDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from authorities - if they are bootstrapping (that is, they don't have a usable, reasonably - live consensus). Only used by clients fetching from a list of fallback - directory mirrors. This schedule is advanced by (potentially concurrent) - connection attempts, unlike other schedules, which are advanced by - connection failures. (Default: 6) - -[[ClientBootstrapConsensusFallbackDownloadInitialDelay]] **ClientBootstrapConsensusFallbackDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from fallback - directory mirrors if they are bootstrapping (that is, they don't have a - usable, reasonably live consensus). Only used by clients fetching from a - list of fallback directory mirrors. This schedule is advanced by - (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0) - -[[ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay]] **ClientBootstrapConsensusAuthorityOnlyDownloadInitialDelay** __N__:: - Initial delay in seconds for when clients should download consensuses from authorities - if they are bootstrapping (that is, they don't have a usable, reasonably - live consensus). Only used by clients which don't have or won't fetch - from a list of fallback directory mirrors. This schedule is advanced by - (potentially concurrent) connection attempts, unlike other schedules, - which are advanced by connection failures. (Default: 0) - -[[ClientBootstrapConsensusMaxInProgressTries]] **ClientBootstrapConsensusMaxInProgressTries** __NUM__:: - Try this many simultaneous connections to download a consensus before - waiting for one to complete, timeout, or error out. (Default: 3) - -[[DormantClientTimeout]] **DormantClientTimeout** __N__ **minutes**|**hours**|**days**|**weeks**:: - If Tor spends this much time without any client activity, - enter a dormant state where automatic circuits are not built, and - directory information is not fetched. - Does not affect servers or onion services. Must be at least 10 minutes. - (Default: 24 hours) - -[[DormantTimeoutDisabledByIdleStreams]] **DormantTimeoutDisabledByIdleStreams** **0**|**1**:: - If true, then any open client stream (even one not reading or writing) - counts as client activity for the purpose of DormantClientTimeout. - If false, then only network activity counts. (Default: 1) - -[[DormantOnFirstStartup]] **DormantOnFirstStartup** **0**|**1**:: - If true, then the first time Tor starts up with a fresh DataDirectory, - it starts in dormant mode, and takes no actions until the user has made - a request. (This mode is recommended if installing a Tor client for a - user who might not actually use it.) If false, Tor bootstraps the first - time it is started, whether it sees a user request or not. - + - After the first time Tor starts, it begins in dormant mode if it was - dormant before, and not otherwise. (Default: 0) - -[[DormantCanceledByStartup]] **DormantCanceledByStartup** **0**|**1**:: - By default, Tor starts in active mode if it was active the last time - it was shut down, and in dormant mode if it was dormant. But if - this option is true, Tor treats every startup event as user - activity, and Tor will never start in Dormant mode, even if it has - been unused for a long time on previous runs. (Default: 0) - + - Note: Packagers and application developers should change the value of - this option only with great caution: it has the potential to - create spurious traffic on the network. This option should only - be used if Tor is started by an affirmative user activity (like - clicking on an applcation or running a command), and not if Tor - is launched for some other reason (for example, by a startup - process, or by an application that launches itself on every login.) == SERVER OPTIONS

1 0

[tor/master] manpage: group some SafeSocks-related options
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit d99e7cebb9ba46657e748ef19ca68c829a3ebaf7 Author: Taylor Yu <catalyst(a)torproject.org> Date: Thu Jan 9 11:12:55 2020 -0600 manpage: group some SafeSocks-related options Move some SafeSocks-related options near each other. Part of ticket 32846. --- doc/tor.1.txt | 37 ++++++++++++++++++++----------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index eea303ce8..70397ae08 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -1663,10 +1663,6 @@ The following options are useful only for clients (that is, if and some limit HTTP GET requests (which Tor uses for fetching directory information) to port 80. -[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: - Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor - will instead refuse to make the connection. (Default: None) - [[SafeSocks]] **SafeSocks** **0**|**1**:: When this option is enabled, Tor will reject application connections that use unsafe variants of the socks protocol -- ones that only provide an IP @@ -1674,6 +1670,26 @@ The following options are useful only for clients (that is, if Specifically, these are socks4 and socks5 when not doing remote DNS. (Default: 0) +// Out of order because it logically belongs after SafeSocks +[[TestSocks]] **TestSocks** **0**|**1**:: + When this option is enabled, Tor will make a notice-level log entry for + each connection to the Socks port indicating whether the request used a + safe socks protocol or an unsafe one (see above entry on SafeSocks). This + helps to determine whether an application using Tor is possibly leaking + DNS requests. (Default: 0) + +// Out of order because it logically belongs with SafeSocks +[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: + Tells Tor to issue a warnings whenever the user tries to make an anonymous + connection to one of these ports. This option is designed to alert users + to services that risk sending passwords in the clear. (Default: + 23,109,110,143) + +// Out of order because it logically belongs with SafeSocks +[[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: + Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor + will instead refuse to make the connection. (Default: None) + [[SocksPolicy]] **SocksPolicy** __policy__,__policy__,__...__:: Set an entrance policy for this server, to limit who can connect to the SocksPort and DNSPort ports. The policies have the same form as exit @@ -1866,13 +1882,6 @@ The following options are useful only for clients (that is, if fulfill a .exit request, upload directory information, or download directory information. (Default: 0) -[[TestSocks]] **TestSocks** **0**|**1**:: - When this option is enabled, Tor will make a notice-level log entry for - each connection to the Socks port indicating whether the request used a - safe socks protocol or an unsafe one (see above entry on SafeSocks). This - helps to determine whether an application using Tor is possibly leaking - DNS requests. (Default: 0) - [[TokenBucketRefillInterval]] **TokenBucketRefillInterval** __NUM__ [**msec**|**second**]:: Set the refill delay interval of Tor's token bucket to NUM milliseconds. NUM must be between 1 and 1000, inclusive. When Tor is out of bandwidth, @@ -2017,12 +2026,6 @@ The following options are useful only for clients (that is, if used IP. For local use, no change to the default VirtualAddrNetwork setting is needed. -[[WarnPlaintextPorts]] **WarnPlaintextPorts** __port__,__port__,__...__:: - Tells Tor to issue a warnings whenever the user tries to make an anonymous - connection to one of these ports. This option is designed to alert users - to services that risk sending passwords in the clear. (Default: - 23,109,110,143) - == SERVER OPTIONS

1 0

[tor/master] manpge: reorder some padding-related options
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit cfd21cc213ee8202ce03db9a4ff1098c8f38e2ec Author: Taylor Yu <catalyst(a)torproject.org> Date: Thu Jan 9 10:57:40 2020 -0600 manpge: reorder some padding-related options Move ReducedCircuitPadding and ReducedConnectionPadding immediately after the corresponding non-Reduced options. Part of ticket 32846. --- doc/tor.1.txt | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/tor.1.txt b/doc/tor.1.txt index 26098f734..eea303ce8 100644 --- a/doc/tor.1.txt +++ b/doc/tor.1.txt @@ -1018,6 +1018,13 @@ The following options are useful only for clients (that is, if support (unlike ConnectionPadding, CircuitPadding cannot be force-enabled). (Default: 1) +// Out of order because it logically belongs after CircuitPadding +[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: + If set to 1, Tor will only use circuit padding algorithms that have low + overhead. Only clients may set this option. This option should be offered + via the UI to mobile users for use where bandwidth may be expensive. + (Default: 0) + [[CircuitsAvailableTimeout]] **CircuitsAvailableTimeout** __NUM__:: Tor will attempt to keep at least one open, unused circuit available for this amount of time. This option governs how long idle circuits are kept @@ -1142,6 +1149,13 @@ The following options are useful only for clients (that is, if for use where bandwidth may be expensive. (Default: auto) +// Out of order because it logically belongs after ConnectionPadding +[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: + If set to 1, Tor will not not hold OR connections open for very long, + and will send less padding on these connections. Only clients may set + this option. This option should be offered via the UI to mobile users + for use where bandwidth may be expensive. (Default: 0) + [[DNSPort]] **DNSPort** ['address'**:**]{empty}__port__|**auto** [_isolation flags_]:: If non-zero, open this port to listen for UDP DNS requests, and resolve them anonymously. This port only handles A, AAAA, and PTR requests---it @@ -1649,18 +1663,6 @@ The following options are useful only for clients (that is, if and some limit HTTP GET requests (which Tor uses for fetching directory information) to port 80. -[[ReducedCircuitPadding]] **ReducedCircuitPadding** **0**|**1**:: - If set to 1, Tor will only use circuit padding algorithms that have low - overhead. Only clients may set this option. This option should be offered - via the UI to mobile users for use where bandwidth may be expensive. - (Default: 0) - -[[ReducedConnectionPadding]] **ReducedConnectionPadding** **0**|**1**:: - If set to 1, Tor will not not hold OR connections open for very long, - and will send less padding on these connections. Only clients may set - this option. This option should be offered via the UI to mobile users - for use where bandwidth may be expensive. (Default: 0) - [[RejectPlaintextPorts]] **RejectPlaintextPorts** __port__,__port__,__...__:: Like WarnPlaintextPorts, but instead of warning about risky port uses, Tor will instead refuse to make the connection. (Default: None)

1 0

[tor/master] Merge branch 'pr_1643_squashed'
by nickm＠torproject.org 13 Jan '20

13 Jan '20

commit 8b46372f264450cb2a8876254c2ba4d0a64eb6dc Merge: 5888db496 d99e7cebb Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Jan 13 13:26:23 2020 -0500 Merge branch 'pr_1643_squashed' changes/ticket32846 | 3 + doc/tor.1.txt | 1276 ++++++++++++++++++++++++++------------------------- 2 files changed, 649 insertions(+), 630 deletions(-)

1 0

Jump to page:

2025

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

tor-commits January 2020