diff options
Diffstat (limited to 'spec/control-spec')
| -rw-r--r-- | spec/control-spec/commands.md | 1910 | ||||
| -rw-r--r-- | spec/control-spec/implementation-notes.md | 721 | ||||
| -rw-r--r-- | spec/control-spec/index.md | 24 | ||||
| -rw-r--r-- | spec/control-spec/message-format.md | 185 | ||||
| -rw-r--r-- | spec/control-spec/protocol-outline.md | 71 | ||||
| -rw-r--r-- | spec/control-spec/replies.md | 1796 |
6 files changed, 4707 insertions, 0 deletions
diff --git a/spec/control-spec/commands.md b/spec/control-spec/commands.md new file mode 100644 index 0000000..d087473 --- /dev/null +++ b/spec/control-spec/commands.md @@ -0,0 +1,1910 @@ +<a id="control-spec.txt-3"></a> + +# Commands + +All commands are case-insensitive, but most keywords are case-sensitive. + +<a id="control-spec.txt-3.1"></a> + +## SETCONF + +Change the value of one or more configuration variables. The syntax is: + +```text + "SETCONF" 1*(SP keyword ["=" value]) CRLF + value = String / QuotedString +``` + +Tor behaves as though it had just read each of the key-value pairs +from its configuration file. Keywords with no corresponding values have +their configuration values reset to 0 or NULL (use RESETCONF if you want +to set it back to its default). SETCONF is all-or-nothing: if there +is an error in any of the configuration settings, Tor sets none of them. + +Tor responds with a "250 OK" reply on success. +If some of the listed keywords can't be found, Tor replies with a +"552 Unrecognized option" message. Otherwise, Tor responds with a +"513 syntax error in configuration values" reply on syntax error, or a +"553 impossible configuration setting" reply on a semantic error. + +Some configuration options (e.g. "Bridge") take multiple values. Also, +some configuration keys (e.g. for hidden services and for entry +guard lists) form a context-sensitive group where order matters (see +GETCONF below). In these cases, setting _any_ of the options in a +SETCONF command is taken to reset all of the others. For example, +if two ORListenAddress values are configured, and a SETCONF command +arrives containing a single ORListenAddress value, the new command's +value replaces the two old values. + +Sometimes it is not possible to change configuration options solely by +issuing a series of SETCONF commands, because the value of one of the +configuration options depends on the value of another which has not yet +been set. Such situations can be overcome by setting multiple configuration +options with a single SETCONF command (e.g. SETCONF ORPort=443 +ORListenAddress=9001). + +<a id="control-spec.txt-3.2"></a> + +## RESETCONF + +Remove all settings for a given configuration option entirely, assign +its default value (if any), and then assign the String provided. +Typically the String is left empty, to simply set an option back to +its default. The syntax is: + +"RESETCONF" 1\*(SP keyword \["=" String\]) CRLF + +Otherwise it behaves like SETCONF above. + +<a id="control-spec.txt-3.3"></a> + +## GETCONF + +Request the value of zero or more configuration variable(s). +The syntax is: + +"GETCONF" \*(SP keyword) CRLF + +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 +values except when the value could be misinterpreted through not being +quoted. (Right now, Tor supports no such misinterpretable values for +configuration options.) + +If some of the listed keywords can't be found, Tor replies with a +"552 unknown configuration keyword" message. + +If an option appears multiple times in the configuration, all of its +key-value pairs are returned in order. + +If no keywords were provided, Tor responds with "250 OK" message. + +Some options are context-sensitive, and depend on other options with +different keywords. These cannot be fetched directly. Currently there +is only one such option: clients should use the "HiddenServiceOptions" +virtual keyword to get all HiddenServiceDir, HiddenServicePort, +HiddenServiceVersion, and HiddenserviceAuthorizeClient option settings. + +<a id="control-spec.txt-3.4"></a> + +## SETEVENTS + +Request the server to inform the client about interesting events. The +syntax is: + +"SETEVENTS" \[SP "EXTENDED"\] \*(SP EventCode) CRLF + +EventCode = 1\*(ALPHA / "\_") (see section 4.1.x for event types) + +Any events _not_ listed in the SETEVENTS line are turned off; thus, sending +SETEVENTS with an empty body turns off all event reporting. + +The server responds with a "250 OK" reply on success, and a "552 +Unrecognized event" reply if one of the event codes isn't recognized. (On +error, the list of active event codes isn't changed.) + +If the flag string "EXTENDED" is provided, Tor may provide extra +information with events for this connection; see 4.1 for more information. +NOTE: All events on a given connection will be provided in extended format, +or none. +NOTE: "EXTENDED" was first supported in Tor 0.1.1.9-alpha; it is +always-on in Tor 0.2.2.1-alpha and later. + +Each event is described in more detail in Section 4.1. + +<a id="control-spec.txt-3.5"></a> + +## 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: + +```text + * (For the HASHEDPASSWORD authentication method; see 3.21) + The original password represented as a QuotedString. + + * (For the COOKIE is authentication method; see 3.21) + The contents of the cookie file, formatted in hexadecimal + + * (For the SAFECOOKIE authentication method; see 3.21) + The HMAC based on the AUTHCHALLENGE message, in hexadecimal. +``` + +The server responds with "250 OK" on success or "515 Bad authentication" if +the authentication cookie is incorrect. Tor closes the connection on an +authentication failure. + +The authentication token can be specified as either a quoted ASCII string, +or as an unquoted hexadecimal encoding of that same string (to avoid escaping +issues). + +For information on how the implementation securely stores authentication +information on disk, see section 5.1. + +Before the client has authenticated, no command other than +PROTOCOLINFO, AUTHCHALLENGE, AUTHENTICATE, or QUIT is valid. If the +controller sends any other command, or sends a malformed command, or +sends an unsuccessful AUTHENTICATE command, or sends PROTOCOLINFO or +AUTHCHALLENGE more than once, Tor sends an error reply and closes +the connection. + +To prevent some cross-protocol attacks, the AUTHENTICATE command is still +required even if all authentication methods in Tor are disabled. In this +case, the controller should just send "AUTHENTICATE" CRLF. + +(Versions of Tor before 0.1.2.16 and 0.2.0.4-alpha did not close the +connection after an authentication failure.) + +<a id="control-spec.txt-3.6"></a> + +## 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 +returns "250 OK" if successful, or "551 Unable to write configuration +to disk" if it can't write the file or some other error occurs. + +If the %include option is used on torrc, SAVECONF will not write the +configuration to disk. If the flag string "FORCE" is provided, the +configuration will be overwritten even if %include is used. Using %include +on defaults-torrc does not affect SAVECONF. (Introduced in 0.3.1.1-alpha.) + +See also the "getinfo config-text" command, if the controller wants +to write the torrc file itself. + +See also the "getinfo config-can-saveconf" command, to tell if the FORCE +flag will be required. (Also introduced in 0.3.1.1-alpha.) + +<a id="control-spec.txt-3.7"></a> + +## SIGNAL + +Sent from the client to the server. The syntax is: + +"SIGNAL" SP Signal CRLF + +```text + Signal = "RELOAD" / "SHUTDOWN" / "DUMP" / "DEBUG" / "HALT" / + "HUP" / "INT" / "USR1" / "USR2" / "TERM" / "NEWNYM" / + "CLEARDNSCACHE" / "HEARTBEAT" / "ACTIVE" / "DORMANT" + + The meaning of the signals are: + + RELOAD -- Reload: reload config items. + SHUTDOWN -- Controlled shutdown: if server is an OP, exit immediately. + If it's an OR, close listeners and exit after + ShutdownWaitLength seconds. + DUMP -- Dump stats: log information about open connections and + circuits. + DEBUG -- Debug: switch all open logs to loglevel debug. + HALT -- Immediate shutdown: clean up and exit now. + CLEARDNSCACHE -- Forget the client-side cached IPs for all hostnames. + NEWNYM -- Switch to clean circuits, so new application requests + don't share any circuits with old ones. Also clears + the client-side DNS cache. (Tor MAY rate-limit its + response to this signal.) + HEARTBEAT -- Make Tor dump an unscheduled Heartbeat message to log. + DORMANT -- Tell Tor to become "dormant". A dormant Tor will + try to avoid CPU and network usage until it receives + user-initiated network request. (Don't use this + on relays or hidden services yet!) + ACTIVE -- Tell Tor to stop being "dormant", as if it had received + a user-initiated network request. +``` + +The server responds with "250 OK" if the signal is recognized (or simply +closes the socket if it was asked to close immediately), or "552 +Unrecognized signal" if the signal is unrecognized. + +Note that not all of these signals have POSIX signal equivalents. The +ones that do are as below. You may also use these POSIX names for the +signal that have them. + +```text + RELOAD: HUP + SHUTDOWN: INT + HALT: TERM + DUMP: USR1 + DEBUG: USR2 + + [SIGNAL DORMANT and SIGNAL ACTIVE were added in 0.4.0.1-alpha.] +``` + +<a id="control-spec.txt-3.8"></a> + +## MAPADDRESS + +Sent from the client to the server. The syntax is: + +"MAPADDRESS" 1\*(Address "=" Address SP) CRLF + +The first address in each pair is an "original" address; the second is a +"replacement" address. The client sends this message to the server in +order to tell it that future SOCKS requests for connections to the original +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: + +```text + 250-OldAddress1=NewAddress1 + 250 OldAddress2=NewAddress2 +``` + +containing the source and destination addresses. If request is +malformed, the server replies with "512 syntax error in command +argument". If the server can't fulfill the request, it replies with +"451 resource exhausted". + +The client may decline to provide a body for the original address, and +instead send a special null address ("0.0.0.0" for IPv4, "::0" for IPv6, or +"." for hostname), signifying that the server should choose the original +address itself, and return that address in the reply. The server +should ensure that it returns an element of address space that is unlikely +to be in actual use. If there is already an address mapped to the +destination address, the server may reuse that mapping. + +If the original address is already mapped to a different address, the old +mapping is removed. If the original address and the destination address +are the same, the server removes any mapping in place for the original +address. + +Example: + +```text + C: MAPADDRESS 1.2.3.4=torproject.org + S: 250 1.2.3.4=torproject.org + + C: GETINFO address-mappings/control + S: 250-address-mappings/control=1.2.3.4 torproject.org NEVER + S: 250 OK + + C: MAPADDRESS 1.2.3.4=1.2.3.4 + S: 250 1.2.3.4=1.2.3.4 + + C: GETINFO address-mappings/control + S: 250-address-mappings/control= + S: 250 OK +``` + +{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: + +```text + 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 + with special addresses like x.onion or x.y.exit. + 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: +they never expire. If the controller wants the mapping to last only +a certain time, then it must explicitly un-map the address when that +time has elapsed. + +MapAddress replies MAY contain mixed status codes. + +Example: + +```text + C: MAPADDRESS xxx=@@@ 0.0.0.0=bogus1.google.com + S: 512-syntax error: invalid address '@@@' + S: 250 127.199.80.246=bogus1.google.com +``` + +<a id="control-spec.txt-3.9"></a> + +## 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: + +```text + 250-keyword=value + If a value must be split over multiple lines, the format is: + + 250+keyword= + value + . + The server sends a 551 or 552 error on failure. + + Recognized keys and their values include: + + "version" -- The version of the server's software, which MAY include the + name of the software, such as "Tor 0.0.9.4". The name of the software, + if absent, is assumed to be "Tor". + + "config-file" -- The location of Tor's configuration file ("torrc"). + + "config-defaults-file" -- The location of Tor's configuration + defaults file ("torrc.defaults"). This file gets parsed before + torrc, and is typically used to replace Tor's default + configuration values. [First implemented in 0.2.3.9-alpha.] + + "config-text" -- The contents that Tor would write if you send it + a SAVECONF command, so the controller can write the file to + disk itself. [First implemented in 0.2.2.7-alpha.] + + "exit-policy/default" -- The default exit policy lines that Tor will + *append* to the ExitPolicy config option. + + "exit-policy/reject-private/default" -- The default exit policy lines + that Tor will *prepend* to the ExitPolicy config option when + ExitPolicyRejectPrivate is 1. + + "exit-policy/reject-private/relay" -- The relay-specific exit policy + lines that Tor will *prepend* to the ExitPolicy config option based + on the current values of ExitPolicyRejectPrivate and + ExitPolicyRejectLocalInterfaces. These lines are based on the public + addresses configured in the torrc and present on the relay's + interfaces. Will send 552 error if the server is not running as + onion router. Will send 551 on internal error which may be transient. + + "exit-policy/ipv4" + "exit-policy/ipv6" + "exit-policy/full" -- This OR's exit policy, in IPv4-only, IPv6-only, or + all-entries flavors. Handles errors in the same way as "exit-policy/ + reject-private/relay" does. + + "desc/id/<OR identity>" or "desc/name/<OR nickname>" -- the latest + server descriptor for a given OR. (Note that modern Tor clients + do not download server descriptors by default, but download + microdescriptors instead. If microdescriptors are enabled, you'll + need to use "md" instead.) + + "md/all" -- all known microdescriptors for the entire Tor network. + Each microdescriptor is terminated by a newline. + [First implemented in 0.3.5.1-alpha] + + "md/id/<OR identity>" or "md/name/<OR nickname>" -- the latest + microdescriptor for a given OR. Empty if we have no microdescriptor for + that OR (because we haven't downloaded one, or it isn't in the + consensus). [First implemented in 0.2.3.8-alpha.] + + "desc/download-enabled" -- "1" if we try to download router descriptors; + "0" otherwise. [First implemented in 0.3.2.1-alpha] + + "md/download-enabled" -- "1" if we try to download microdescriptors; + "0" otherwise. [First implemented in 0.3.2.1-alpha] + + "dormant" -- A nonnegative integer: zero if Tor is currently active and + building circuits, and nonzero if Tor has gone idle due to lack of use + or some similar reason. [First implemented in 0.2.3.16-alpha] + + "desc-annotations/id/<OR identity>" -- outputs the annotations string + (source, timestamp of arrival, purpose, etc) for the corresponding + descriptor. [First implemented in 0.2.0.13-alpha.] + + "extra-info/digest/<digest>" -- the extrainfo document whose digest (in + hex) is <digest>. Only available if we're downloading extra-info + documents. + + "ns/id/<OR identity>" or "ns/name/<OR nickname>" -- the latest router + status info (v3 directory style) for a given OR. Router status + info is as given in dir-spec.txt, and reflects the latest + consensus opinion about the + router in question. Like directory clients, controllers MUST + tolerate unrecognized flags and lines. The published date and + descriptor digest are those believed to be best by this Tor, + not necessarily those for a descriptor that Tor currently has. + [First implemented in 0.1.2.3-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + + "ns/all" -- Router status info (v3 directory style) for all ORs we + that the consensus has an opinion about, joined by newlines. + [First implemented in 0.1.2.3-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + + "ns/purpose/<purpose>" -- Router status info (v3 directory style) + for all ORs of this purpose. Mostly designed for /ns/purpose/bridge + queries. + [First implemented in 0.2.0.13-alpha.] + [In 0.2.0.9-alpha this switched from v2 directory style to v3] + [In versions before 0.4.1.1-alpha we set the Running flag on + bridges when /ns/purpose/bridge is accessed] + [In 0.4.1.1-alpha we set the Running flag on bridges when the + bridge networkstatus file is written to disk] + + "desc/all-recent" -- the latest server descriptor for every router that + Tor knows about. (See md note about "desc/id" and "desc/name" above.) + + "network-status" -- [Deprecated in 0.3.1.1-alpha, removed + in 0.4.5.1-alpha.] + + "address-mappings/all" + "address-mappings/config" + "address-mappings/cache" + "address-mappings/control" -- a \r\n-separated list of address + mappings, each in the form of "from-address to-address expiry". + The 'config' key returns those address mappings set in the + configuration; the 'cache' key returns the mappings in the + client-side DNS cache; the 'control' key returns the mappings set + via the control interface; the 'all' target returns the mappings + set through any mechanism. + Expiry is formatted as with ADDRMAP events, except that "expiry" is + always a time in UTC or the string "NEVER"; see section 4.1.7. + First introduced in 0.2.0.3-alpha. + + "addr-mappings/*" -- as for address-mappings/*, but without the + expiry portion of the value. Use of this value is deprecated + since 0.2.0.3-alpha; use address-mappings instead. + + "address" -- the best guess at our external IP address. If we + have no guess, return a 551 error. (Added in 0.1.2.2-alpha) + + "address/v4" + "address/v6" + the best guess at our respective external IPv4 or IPv6 address. + If we have no guess, return a 551 error. (Added in 0.4.5.1-alpha) + + "fingerprint" -- the contents of the fingerprint file that Tor + writes as a relay, or a 551 if we're not a relay currently. + (Added in 0.1.2.3-alpha) + + "circuit-status" + A series of lines as for a circuit status event. Each line is of + the form described in section 4.1.1, omitting the initial + "650 CIRC ". Note that clients must be ready to accept additional + arguments as described in section 4.1. + + "stream-status" + A series of lines as for a stream status event. Each is of the form: + StreamID SP StreamStatus SP CircuitID SP Target CRLF + + "orconn-status" + A series of lines as for an OR connection status event. In Tor + 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP ORStatus 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, each line + is of the form: + ServerID SP ORStatus CRLF + + "entry-guards" + A series of lines listing the currently chosen entry guards, if any. + In Tor 0.1.2.2-alpha with feature VERBOSE_NAMES enabled and in Tor + 0.2.2.1-alpha and later by default, each line is of the form: + LongName SP Status [SP ISOTime] 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, each line + is of the form: + ServerID2 SP Status [SP ISOTime] CRLF + ServerID2 = Nickname / 40*HEXDIG + + The definition of Status is the same for both: + Status = "up" / "never-connected" / "down" / + "unusable" / "unlisted" + + [From 0.1.1.4-alpha to 0.1.1.10-alpha, entry-guards was called + "helper-nodes". Tor still supports calling "helper-nodes", but it + is deprecated and should not be used.] + + [Older versions of Tor (before 0.1.2.x-final) generated 'down' instead + of unlisted/unusable. Between 0.1.2.x-final and 0.2.6.3-alpha, + 'down' was never generated.] + + [XXXX ServerID2 differs from ServerID in not prefixing fingerprints + with a $. This is an implementation error. It would be nice to add + the $ back in if we can do so without breaking compatibility.] + + "traffic/read" -- Total bytes read (downloaded). + + "traffic/written" -- Total bytes written (uploaded). + + "uptime" -- Uptime of the Tor daemon (in seconds). Added in + 0.3.5.1-alpha. + + "accounting/enabled" + "accounting/hibernating" + "accounting/bytes" + "accounting/bytes-left" + "accounting/interval-start" + "accounting/interval-wake" + "accounting/interval-end" + Information about accounting status. If accounting is enabled, + "enabled" is 1; otherwise it is 0. The "hibernating" field is "hard" + if we are accepting no data; "soft" if we're accepting no new + connections, and "awake" if we're not hibernating at all. The "bytes" + and "bytes-left" fields contain (read-bytes SP write-bytes), for the + start and the rest of the interval respectively. The 'interval-start' + and 'interval-end' fields are the borders of the current interval; the + 'interval-wake' field is the time within the current interval (if any) + where we plan[ned] to start being active. The times are UTC. + + "config/names" + A series of lines listing the available configuration options. Each is + of the form: + OptionName SP OptionType [ SP Documentation ] CRLF + OptionName = Keyword + OptionType = "Integer" / "TimeInterval" / "TimeMsecInterval" / + "DataSize" / "Float" / "Boolean" / "Time" / "CommaList" / + "Dependent" / "Virtual" / "String" / "LineList" + Documentation = Text + Note: The incorrect spelling "Dependant" was used from the time this key + was introduced in Tor 0.1.1.4-alpha until it was corrected in Tor + 0.3.0.2-alpha. It is recommended that clients accept both spellings. + + "config/defaults" + A series of lines listing default values for each configuration + option. Options which don't have a valid default don't show up + in the list. Introduced in Tor 0.2.4.1-alpha. + OptionName SP OptionValue CRLF + OptionName = Keyword + OptionValue = Text + + "info/names" + A series of lines listing the available GETINFO options. Each is of + one of these forms: + OptionName SP Documentation CRLF + OptionPrefix SP Documentation CRLF + OptionPrefix = OptionName "/*" + The OptionPrefix form indicates a number of options beginning with the + prefix. So if "config/*" is listed, other options beginning with + "config/" will work, but "config/*" itself is not an option. + + "events/names" + A space-separated list of all the events supported by this version of + Tor's SETEVENTS. + + "features/names" + A space-separated list of all the features supported by this version + of Tor's USEFEATURE. + + "signal/names" + A space-separated list of all the values supported by the SIGNAL + command. + + "ip-to-country/ipv4-available" + "ip-to-country/ipv6-available" + "1" if the relevant geoip or geoip6 database is present; "0" otherwise. + This field was added in Tor 0.3.2.1-alpha. + + "ip-to-country/*" + Maps IP addresses to 2-letter country codes. For example, + "GETINFO ip-to-country/18.0.0.1" should give "US". + + "process/pid" -- Process id belonging to the main tor process. + "process/uid" -- User id running the tor process, -1 if unknown (this is + unimplemented on Windows, returning -1). + "process/user" -- Username under which the tor process is running, + providing an empty string if none exists (this is unimplemented on + Windows, returning an empty string). + "process/descriptor-limit" -- Upper bound on the file descriptor limit, -1 + if unknown + + "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha] + "dir/status-vote/current/consensus-microdesc" [added in Tor 0.4.3.1-alpha] + "dir/status/authority" + "dir/status/fp/<F>" + "dir/status/fp/<F1>+<F2>+<F3>" + "dir/status/all" + "dir/server/fp/<F>" + "dir/server/fp/<F1>+<F2>+<F3>" + "dir/server/d/<D>" + "dir/server/d/<D1>+<D2>+<D3>" + "dir/server/authority" + "dir/server/all" + A series of lines listing directory contents, provided according to the + specification for the URLs listed in Section 4.4 of dir-spec.txt. Note + that Tor MUST NOT provide private information, such as descriptors for + routers not marked as general-purpose. When asked for 'authority' + information for which this Tor is not authoritative, Tor replies with + an empty string. + + Note that, as of Tor 0.2.3.3-alpha, Tor clients don't download server + descriptors anymore, but microdescriptors. So, a "551 Servers + unavailable" reply to all "GETINFO dir/server/*" requests is actually + correct. If you have an old program which absolutely requires server + descriptors to work, try setting UseMicrodescriptors 0 or + FetchUselessDescriptors 1 in your client's torrc. + + "status/circuit-established" + "status/enough-dir-info" + "status/good-server-descriptor" + "status/accepted-server-descriptor" + "status/..." + These provide the current internal Tor values for various Tor + states. See Section 4.1.10 for explanations. (Only a few of the + status events are available as getinfo's currently. Let us know if + you want more exposed.) + "status/reachability-succeeded/or" + 0 or 1, depending on whether we've found our ORPort reachable. + "status/reachability-succeeded/dir" + 0 or 1, depending on whether we've found our DirPort reachable. + 1 if there is no DirPort, and therefore no need for a reachability + check. + "status/reachability-succeeded" + "OR=" ("0"/"1") SP "DIR=" ("0"/"1") + Combines status/reachability-succeeded/*; controllers MUST ignore + unrecognized elements in this entry. + "status/bootstrap-phase" + Returns the most recent bootstrap phase status event + sent. Specifically, it returns a string starting with either + "NOTICE BOOTSTRAP ..." or "WARN BOOTSTRAP ...". Controllers should + use this getinfo when they connect or attach to Tor to learn its + current bootstrap state. + "status/version/recommended" + List of currently recommended versions. + "status/version/current" + Status of the current version. One of: new, old, unrecommended, + recommended, new in series, obsolete, unknown. + "status/clients-seen" + A summary of which countries we've seen clients from recently, + formatted the same as the CLIENTS_SEEN status event described in + Section 4.1.14. This GETINFO option is currently available only + for bridge relays. + "status/fresh-relay-descs" + Provides fresh server and extra-info descriptors for our relay. Note + this is *not* the latest descriptors we've published, but rather what we + would generate if we needed to make a new descriptor right now. + + "net/listeners/*" + + A quoted, space-separated list of the locations where Tor is listening + for connections of the specified type. These can contain IPv4 + network address... + + "127.0.0.1:9050" "127.0.0.1:9051" + + ... or local unix sockets... + + "unix:/home/my_user/.tor/socket" + + ... or IPv6 network addresses: + + "[2001:0db8:7000:0000:0000:dead:beef:1234]:9050" + + [New in Tor 0.2.2.26-beta.] + + "net/listeners/or" + + Listeners for OR connections. Talks Tor protocol as described in + tor-spec.txt. + + "net/listeners/dir" + + Listeners for Tor directory protocol, as described in dir-spec.txt. + + "net/listeners/socks" + + Listeners for onion proxy connections that talk SOCKS4/4a/5 protocol. + + "net/listeners/trans" + + Listeners for transparent connections redirected by firewall, such as + pf or netfilter. + + "net/listeners/natd" + + Listeners for transparent connections redirected by natd. + + "net/listeners/dns" + + Listeners for a subset of DNS protocol that Tor network supports. + + "net/listeners/control" + + Listeners for Tor control protocol, described herein. + + "net/listeners/extor" + + Listeners corresponding to Extended ORPorts for integration with + pluggable transports. See proposals 180 and 196. + + "net/listeners/httptunnel" + + Listeners for onion proxy connections that leverage HTTP CONNECT + tunnelling. + + [The extor and httptunnel lists were added in 0.3.2.12, 0.3.3.10, and + 0.3.4.6-rc.] + + "dir-usage" + A newline-separated list of how many bytes we've served to answer + each type of directory request. The format of each line is: + Keyword 1*SP Integer 1*SP Integer + where the first integer is the number of bytes written, and the second + is the number of requests answered. + + [This feature was added in Tor 0.2.2.1-alpha, and removed in + Tor 0.2.9.1-alpha. Even when it existed, it only provided + useful output when the Tor client was built with either the + INSTRUMENT_DOWNLOADS or RUNNING_DOXYGEN compile-time options.] + + "bw-event-cache" + A space-separated summary of recent BW events in chronological order + from oldest to newest. Each event is represented by a comma-separated + tuple of "R,W", R is the number of bytes read, and W is the number of + bytes written. These entries each represent about one second's worth + of traffic. + [New in Tor 0.2.6.3-alpha] + + "consensus/valid-after" + "consensus/fresh-until" + "consensus/valid-until" + Each of these produces an ISOTime describing part of the lifetime of + the current (valid, accepted) consensus that Tor has. + [New in Tor 0.2.6.3-alpha] + + "hs/client/desc/id/<ADDR>" + Prints the content of the hidden service descriptor corresponding to + the given <ADDR> which is an onion address without the ".onion" part. + The client's cache is queried to find the descriptor. The format of + the descriptor is described in section 1.3 of the rend-spec.txt + document. + + If <ADDR> is unrecognized or if not found in the cache, a 551 error is + returned. + + [New in Tor 0.2.7.1-alpha] + [HS v3 support added 0.3.3.1-alpha] + + "hs/service/desc/id/<ADDR>" + Prints the content of the hidden service descriptor corresponding to + the given <ADDR> which is an onion address without the ".onion" part. + The service's local descriptor cache is queried to find the descriptor. + The format of the descriptor is described in section 1.3 of the + rend-spec.txt document. + + If <ADDR> is unrecognized or if not found in the cache, a 551 error is + returned. + + [New in Tor 0.2.7.2-alpha] + [HS v3 support added 0.3.3.1-alpha] + + "onions/current" + "onions/detached" + A newline-separated list of the Onion ("Hidden") Services created + via the "ADD_ONION" command. The 'current' key returns Onion Services + belonging to the current control connection. The 'detached' key + returns Onion Services detached from the parent control connection + (as in, belonging to no control connection). + The format of each line is: + HSAddress + [New in Tor 0.2.7.1-alpha.] + [HS v3 support added 0.3.3.1-alpha] + + "network-liveness" + The string "up" or "down", indicating whether we currently believe the + network is reachable. + + "downloads/" + The keys under downloads/ are used to query download statuses; they all + return either a sequence of newline-terminated hex encoded digests, or + a "serialized download status" as follows: + + SerializedDownloadStatus = + -- when do we plan to next attempt to download this object? + "next-attempt-at" SP ISOTime CRLF + -- how many times have we failed since the last success? + "n-download-failures" SP UInt CRLF + -- how many times have we tried to download this? + "n-download-attempts" SP UInt CRLF + -- according to which schedule rule will we download this? + "schedule" SP DownloadSchedule CRLF + -- do we want to fetch this from an authority, or will any cache do? + "want-authority" SP DownloadWantAuthority CRLF + -- do we increase our download delay whenever we fail to fetch this, + -- or whenever we attempt fetching this? + "increment-on" SP DownloadIncrementOn CRLF + -- do we increase the download schedule deterministically, or at + -- random? + "backoff" SP DownloadBackoff CRLF + [ + -- with an exponential backoff, where are we in the schedule? + "last-backoff-position" Uint CRLF + -- with an exponential backoff, what was our last delay? + "last-delay-used UInt CRLF + ] + + where + + DownloadSchedule = + "DL_SCHED_GENERIC" / "DL_SCHED_CONSENSUS" / "DL_SCHED_BRIDGE" + DownloadWantAuthority = + "DL_WANT_ANY_DIRSERVER" / "DL_WANT_AUTHORITY" + DownloadIncrementOn = + "DL_SCHED_INCREMENT_FAILURE" / "DL_SCHED_INCREMENT_ATTEMPT" + DownloadBackoff = + "DL_SCHED_DETERMINISTIC" / "DL_SCHED_RANDOM_EXPONENTIAL" + + The optional last two lines must be present if DownloadBackoff is + "DL_SCHED_RANDOM_EXPONENTIAL" and must be absent if DownloadBackoff + is "DL_SCHED_DETERMINISTIC". + + In detail, the keys supported are: + + "downloads/networkstatus/ns" + The SerializedDownloadStatus for the NS-flavored consensus for + whichever bootstrap state Tor is currently in. + + "downloads/networkstatus/ns/bootstrap" + The SerializedDownloadStatus for the NS-flavored consensus at + bootstrap time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/ns/running" + + The SerializedDownloadStatus for the NS-flavored consensus when + running, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc" + The SerializedDownloadStatus for the microdesc-flavored consensus for + whichever bootstrap state Tor is currently in. + + "downloads/networkstatus/microdesc/bootstrap" + The SerializedDownloadStatus for the microdesc-flavored consensus at + bootstrap time, regardless of whether we are currently bootstrapping. + + "downloads/networkstatus/microdesc/running" + The SerializedDownloadStatus for the microdesc-flavored consensus when + running, regardless of whether we are currently bootstrapping. + + "downloads/cert/fps" + + A newline-separated list of hex-encoded digests for authority + certificates for which we have download status available. + + "downloads/cert/fp/<Fingerprint>" + A SerializedDownloadStatus for the default certificate for the + identity digest <Fingerprint> returned by the downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/sks" + A newline-separated list of hex-encoded signing key digests for the + authority identity digest <Fingerprint> returned by the + downloads/cert/fps key. + + "downloads/cert/fp/<Fingerprint>/<SKDigest>" + A SerializedDownloadStatus for the certificate for the identity + digest <Fingerprint> returned by the downloads/cert/fps key and signing + key digest <SKDigest> returned by the downloads/cert/fp/<Fingerprint>/ + sks key. + + "downloads/desc/descs" + A newline-separated list of hex-encoded router descriptor digests + [note, not identity digests - the Tor process may not have seen them + yet while downloading router descriptors]. If the Tor process is not + using a NS-flavored consensus, a 551 error is returned. + + "downloads/desc/<Digest>" + A SerializedDownloadStatus for the router descriptor with digest + <Digest> as returned by the downloads/desc/descs key. If the Tor + process is not using a NS-flavored consensus, a 551 error is returned. + + "downloads/bridge/bridges" + A newline-separated list of hex-encoded bridge identity digests. If + the Tor process is not using bridges, a 551 error is returned. + + "downloads/bridge/<Digest>" + A SerializedDownloadStatus for the bridge descriptor with identity + digest <Digest> as returned by the downloads/bridge/bridges key. If + the Tor process is not using bridges, a 551 error is returned. + + "sr/current" + "sr/previous" + The current or previous shared random value, as received in the + consensus, base-64 encoded. An empty value means that either + the consensus has no shared random value, or Tor has no consensus. + + "current-time/local" + "current-time/utc" + The current system or UTC time, as returned by the system, in ISOTime2 + format. (Introduced in 0.3.4.1-alpha.) + + "stats/ntor/requested" + "stats/ntor/assigned" + The NTor circuit onion handshake rephist values which are requested or + assigned. (Introduced in 0.4.5.1-alpha) + + "stats/tap/requested" + "stats/tap/assigned" + The TAP circuit onion handshake rephist values which are requested or + assigned. (Introduced in 0.4.5.1-alpha) + + "config-can-saveconf" + 0 or 1, depending on whether it is possible to use SAVECONF without the + FORCE flag. (Introduced in 0.3.1.1-alpha.) + + "limits/max-mem-in-queues" + The amount of memory that Tor's out-of-memory checker will allow + Tor to allocate (in places it can see) before it starts freeing memory + and killing circuits. See the MaxMemInQueues option for more + details. Unlike the option, this value reflects Tor's actual limit, and + may be adjusted depending on the available system memory rather than on + 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] + S: . + S: 250-version=Tor 0.1.1.0-alpha-cvs + S: 250 OK +``` + +<a id="control-spec.txt-3.10"></a> + +## EXTENDCIRCUIT + +Sent from the client to the server. The format is: + +```text + "EXTENDCIRCUIT" SP CircuitID + [SP ServerSpec *("," ServerSpec)] + [SP "purpose=" Purpose] CRLF +``` + +This request takes one of two forms: either the CircuitID is zero, in +which case it is a request for the server to build a new circuit, +or the CircuitID is nonzero, in which case it is a request for the +server to extend an existing circuit with that ID according to the +specified path. + +If the CircuitID is 0, the controller has the option of providing +a path for Tor to use to build the circuit. If it does not provide +a path, Tor will select one automatically from high capacity nodes +according to path-spec.txt. + +If CircuitID is 0 and "purpose=" is specified, then the circuit's +purpose is set. Two choices are recognized: "general" and +"controller". If not specified, circuits are created as "general". + +If the request is successful, the server sends a reply containing a +message body consisting of the CircuitID of the (maybe newly created) +circuit. The syntax is "250" SP "EXTENDED" SP CircuitID CRLF. + +<a id="control-spec.txt-3.11"></a> + +## 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. + +<a id="control-spec.txt-3.12"></a> + +## 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 +for details. + +NOTE: This command was disabled and made obsolete as of Tor +0.2.0.8-alpha. It doesn't exist anymore, and is listed here only for +historical interest. + +<a id="control-spec.txt-3.13"></a> + +## 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 +associated with the specified circuit. Each stream may be associated with +at most one circuit, and multiple streams may share the same circuit. +Streams can only be attached to completed circuits (that is, circuits that +have sent a circuit status 'BUILT' event or are listed as built in a +GETINFO circuit-status request). + +If the circuit ID is 0, responsibility for attaching the given stream is +returned to Tor. + +If HOP=HopNum is specified, Tor will choose the HopNumth hop in the +circuit as the exit node, rather than the last node in the circuit. +Hops are 1-indexed; generally, it is not permitted to attach to hop 1. + +Tor responds with "250 OK" if it can attach the stream, 552 if the +circuit or stream didn't exist, 555 if the stream isn't in an +appropriate state to be attached (e.g. it's already open), or 551 if +the stream couldn't be attached for another reason. + +{Implementation note: Tor will close unattached streams by itself, +roughly two minutes after they are born. Let the developers know if +that turns out to be a problem.} + +{Implementation note: By default, Tor automatically attaches streams to +circuits itself, unless the configuration variable +"\_\_LeaveStreamsUnattached" is set to "1". Attempting to attach streams +via TC when "\_\_LeaveStreamsUnattached" is false may cause a race between +Tor and the controller, as both attempt to attach streams to circuits.} + +{Implementation note: You can try to attachstream to a stream that +has already sent a connect or resolve request but hasn't succeeded +yet, in which case Tor will detach the stream from its current circuit +before proceeding with the new attach request.} + +<a id="control-spec.txt-3.14"></a> + +## POSTDESCRIPTOR + +Sent from the client to the server. The syntax is: + +```text + "+POSTDESCRIPTOR" [SP "purpose=" Purpose] [SP "cache=" Cache] + CRLF Descriptor CRLF "." CRLF +``` + +This message informs the server about a new descriptor. If Purpose is +specified, it must be either "general", "controller", or "bridge", +else we return a 552 error. The default is "general". + +If Cache is specified, it must be either "no" or "yes", else we +return a 552 error. If Cache is not specified, Tor will decide for +itself whether it wants to cache the descriptor, and controllers +must not rely on its choice. + +The descriptor, when parsed, must contain a number of well-specified +fields, including fields for its nickname and identity. + +If there is an error in parsing the descriptor, the server must send a +"554 Invalid descriptor" reply. If the descriptor is well-formed but +the server chooses not to add it, it must reply with a 251 message +whose body explains why the server was not added. If the descriptor +is added, Tor replies with "250 OK". + +<a id="control-spec.txt-3.15"></a> + +## 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 +Port is specified, changes the destination port as well. No remapping +is performed on the new provided address. + +To be sure that the modified address will be used, this event must be sent +after a new stream event is received, and before attaching this stream to +a circuit. + +Tor replies with "250 OK" on success. + +<a id="control-spec.txt-3.16"></a> + +## CLOSESTREAM + +Sent from the client to the server. The syntax is: + +"CLOSESTREAM" SP StreamID SP Reason \*(SP Flag) CRLF + +Tells the server to close the specified stream. The reason should be one +of the Tor RELAY_END reasons given in tor-spec.txt, as a decimal. Flags is +not used currently; Tor servers SHOULD ignore unrecognized flags. Tor may +hold the stream open for a while to flush any data that is pending. + +Tor replies with "250 OK" on success, or a 512 if there aren't enough +arguments, or a 552 if it doesn't recognize the StreamID or reason. + +<a id="control-spec.txt-3.17"></a> + +## CLOSECIRCUIT + +The syntax is: + +```text + "CLOSECIRCUIT" SP CircuitID *(SP Flag) CRLF + Flag = "IfUnused" +``` + +Tells the server to close the specified circuit. If "IfUnused" is +provided, do not close the circuit unless it is unused. + +Other flags may be defined in the future; Tor SHOULD ignore unrecognized +flags. + +Tor replies with "250 OK" on success, or a 512 if there aren't enough +arguments, or a 552 if it doesn't recognize the CircuitID. + +<a id="control-spec.txt-3.18"></a> + +## QUIT + +Tells the server to hang up on this controller connection. This command +can be used before authenticating. + +<a id="control-spec.txt-3.19"></a> + +## USEFEATURE + +Adding additional features to the control protocol sometimes will break +backwards compatibility. Initially such features are added into Tor and +disabled by default. USEFEATURE can enable these additional features. + +The syntax is: + +```text + "USEFEATURE" *(SP FeatureName) CRLF + FeatureName = 1*(ALPHA / DIGIT / "_" / "-") + + Feature names are case-insensitive. +``` + +Once enabled, a feature stays enabled for the duration of the connection +to the controller. A new connection to the controller must be opened to +disable an enabled feature. + +Features are a forward-compatibility mechanism; each feature will eventually +become a standard part of the control protocol. Once a feature becomes part +of the protocol, it is always-on. Each feature documents the version it was +introduced as a feature and the version in which it became part of the +protocol. + +Tor will ignore a request to use any feature that is always-on. Tor will give +a 552 error in response to an unrecognized feature. + +EXTENDED_EVENTS + +```text + Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to + request the extended event syntax. + + This feature was first introduced in 0.1.2.3-alpha. It is always-on + and part of the protocol in Tor 0.2.2.1-alpha and later. + + VERBOSE_NAMES + + Replaces ServerID with LongName in events and GETINFO results. LongName + provides a Fingerprint for all routers, an indication of Named status, + and a Nickname if one is known. LongName is strictly more informative + than ServerID, which only provides either a Fingerprint or a Nickname. + + This feature was first introduced in 0.1.2.2-alpha. It is always-on and + part of the protocol in Tor 0.2.2.1-alpha and later. +``` + +<a id="control-spec.txt-3.20"></a> + +## RESOLVE + +The syntax is + +```text + "RESOLVE" *Option *Address CRLF + Option = "mode=reverse" + Address = a hostname or IPv4 address +``` + +This command launches a remote hostname lookup request for every specified +request (or reverse lookup if "mode=reverse" is specified). Note that the +request is done in the background: to see the answers, your controller will +need to listen for ADDRMAP events; see 4.1.7 below. + +\[Added in Tor 0.2.0.3-alpha\] + +<a id="control-spec.txt-3.21"></a> + +## 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 + +```text + AuthLine = "250-AUTH" SP "METHODS=" AuthMethod *("," AuthMethod) + *(SP "COOKIEFILE=" AuthCookieFile) CRLF + VersionLine = "250-VERSION" SP "Tor=" TorVersion OptArguments CRLF + + AuthMethod = + "NULL" / ; No authentication is required + "HASHEDPASSWORD" / ; A controller must supply the original password + "COOKIE" / ; ... or supply the contents of a cookie file + "SAFECOOKIE" ; ... or prove knowledge of a cookie file's contents + + AuthCookieFile = QuotedString + TorVersion = QuotedString + + OtherLine = "250-" Keyword OptArguments CRLF + + PIVERSION: 1*DIGIT +``` + +This command tells the controller what kinds of authentication are +supported. + +Tor MAY give its InfoLines in any order; controllers MUST ignore InfoLines +with keywords they do not recognize. Controllers MUST ignore extraneous +data on any InfoLine. + +PIVERSION is there in case we drastically change the syntax one day. For +now it should always be "1". Controllers MAY provide a list of the +protocolinfo versions they support; Tor MAY select a version that the +controller does not support. + +AuthMethod is used to specify one or more control authentication +methods that Tor currently accepts. + +AuthCookieFile specifies the absolute path and filename of the +authentication cookie that Tor is expecting and is provided iff the +METHODS field contains the method "COOKIE" and/or "SAFECOOKIE". +Controllers MUST handle escape sequences inside this string. + +All authentication cookies are 32 bytes long. Controllers MUST NOT +use the contents of a non-32-byte-long file as an authentication +cookie. + +If the METHODS field contains the method "SAFECOOKIE", every +AuthCookieFile must contain the same authentication cookie. + +The COOKIE authentication method exposes the user running a +controller to an unintended information disclosure attack whenever +the controller has greater filesystem read access than the process +that it has connected to. (Note that a controller may connect to a +process other than Tor.) It is almost never safe to use, even if +the controller's user has explicitly specified which filename to +read an authentication cookie from. For this reason, the COOKIE +authentication method has been deprecated and will be removed from +a future version of Tor. + +The VERSION line contains the Tor version. + +\[Unlike other commands besides AUTHENTICATE, PROTOCOLINFO may be used (but +only once!) before AUTHENTICATE.\] + +\[PROTOCOLINFO was not supported before Tor 0.2.0.5-alpha.\] + +<a id="control-spec.txt-3.22"></a> + +## LOADCONF + +The syntax is: + +"+LOADCONF" CRLF ConfigText CRLF "." CRLF + +This command allows a controller to upload the text of a config file +to Tor over the control port. This config file is then loaded as if +it had been read from disk. + +\[LOADCONF was added in Tor 0.2.1.1-alpha.\] + +<a id="control-spec.txt-3.23"></a> + +## TAKEOWNERSHIP + +The syntax is: + +"TAKEOWNERSHIP" CRLF + +This command instructs Tor to shut down when this control +connection is closed. This command affects each control connection +that sends it independently; if multiple control connections send +the TAKEOWNERSHIP command to a Tor instance, Tor will shut down when +any of those connections closes. + +(As of Tor 0.2.5.2-alpha, Tor does not wait a while for circuits to +close when shutting down because of an exiting controller. If you +want to ensure a clean shutdown--and you should!--then send "SIGNAL +SHUTDOWN" and wait for the Tor process to close.) + +This command is intended to be used with the +\_\_OwningControllerProcess configuration option. A controller that +starts a Tor process which the user cannot easily control or stop +should 'own' that Tor process: + +```text + * When starting Tor, the controller should specify its PID in an + __OwningControllerProcess on Tor's command line. This will + cause Tor to poll for the existence of a process with that PID, + and exit if it does not find such a process. (This is not a + completely reliable way to detect whether the 'owning + controller' is still running, but it should work well enough in + most cases.) + + * Once the controller has connected to Tor's control port, it + should send the TAKEOWNERSHIP command along its control + connection. At this point, *both* the TAKEOWNERSHIP command and + the __OwningControllerProcess option are in effect: Tor will + exit when the control connection ends *and* Tor will exit if it + detects that there is no process with the PID specified in the + __OwningControllerProcess option. + + * After the controller has sent the TAKEOWNERSHIP command, it + should send "RESETCONF __OwningControllerProcess" along its + control connection. This will cause Tor to stop polling for the + existence of a process with its owning controller's PID; Tor + will still exit when the control connection ends. + + [TAKEOWNERSHIP was added in Tor 0.2.2.28-beta.] +``` + +<a id="control-spec.txt-3.24"></a> + +## AUTHCHALLENGE + +The syntax is: + +```text + "AUTHCHALLENGE" SP "SAFECOOKIE" + SP ClientNonce + CRLF + + ClientNonce = 2*HEXDIG / QuotedString +``` + +This command is used to begin the authentication routine for the +SAFECOOKIE method of authentication. + +If the server accepts the command, the server reply format is: + +```text + "250 AUTHCHALLENGE" + SP "SERVERHASH=" ServerHash + SP "SERVERNONCE=" ServerNonce + CRLF + + ServerHash = 64*64HEXDIG + ServerNonce = 64*64HEXDIG +``` + +The ClientNonce, ServerHash, and ServerNonce values are +encoded/decoded in the same way as the argument passed to the +AUTHENTICATE command. ServerNonce MUST be 32 bytes long. + +ServerHash is computed as: + +```text + 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: + +```text + HMAC-SHA256("Tor safe cookie authentication controller-to-server hash", + CookieString | ClientNonce | ServerNonce) +``` + +\[Unlike other commands besides AUTHENTICATE, AUTHCHALLENGE may be +used (but only once!) before AUTHENTICATE.\] + +\[AUTHCHALLENGE was added in Tor 0.2.3.13-alpha.\] + +<a id="control-spec.txt-3.25"></a> + +## DROPGUARDS + +The syntax is: + +"DROPGUARDS" CRLF + +Tells the server to drop all guard nodes. Do not invoke this command +lightly; it can increase vulnerability to tracking attacks over time. + +Tor replies with "250 OK" on success. + +\[DROPGUARDS was added in Tor 0.2.5.2-alpha.\] + +<a id="control-spec.txt-3.26"></a> + +## HSFETCH + +The syntax is: + +```text + "HSFETCH" SP (HSAddress / "v" Version "-" DescId) + *[SP "SERVER=" Server] CRLF + + HSAddress = 16*Base32Character / 56*Base32Character + Version = "2" / "3" + DescId = 32*Base32Character + Server = LongName +``` + +This command launches hidden service descriptor fetch(es) for the given +HSAddress or DescId. + +HSAddress can be version 2 or version 3 addresses. DescIDs can only be +version 2 IDs. Version 2 addresses consist of 16*Base32Character and +version 3 addresses consist of 56*Base32Character. + +If a DescId is specified, at least one Server MUST also be provided, +otherwise a 512 error is returned. If no DescId and Server(s) are specified, +it behaves like a normal Tor client descriptor fetch. If one or more +Server are given, they are used instead triggering a fetch on each of them +in parallel. + +The caching behavior when fetching a descriptor using this command is +identical to normal Tor client behavior. + +Details on how to compute a descriptor id (DescId) can be found in +rend-spec.txt section 1.3. + +If any values are unrecognized, a 513 error is returned and the command is +stopped. On success, Tor replies "250 OK" then Tor MUST eventually follow +this with both a HS_DESC and HS_DESC_CONTENT events with the results. If +SERVER is specified then events are emitted for each location. + +Examples are: + +```text + C: HSFETCH v2-gezdgnbvgy3tqolbmjrwizlgm5ugs2tl + SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 + S: 250 OK + + C: HSFETCH ajkhdsfuygaesfaa + S: 250 OK + + C: HSFETCH vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd + S: 250 OK +``` + +\[HSFETCH was added in Tor 0.2.7.1-alpha\] +\[HS v3 support added 0.4.1.1-alpha\] + +<a id="control-spec.txt-3.27"></a> + +## ADD_ONION + +The syntax is: + +```text + "ADD_ONION" SP KeyType ":" KeyBlob + [SP "Flags=" Flag *("," Flag)] + [SP "MaxStreams=" NumStreams] + 1*(SP "Port=" VirtPort ["," Target]) + *(SP "ClientAuth=" ClientName [":" ClientBlob]) CRLF + *(SP "ClientAuthV3=" V3Key) CRLF + + KeyType = + "NEW" / ; The server should generate a key of algorithm KeyBlob + "RSA1024" / ; The server should use the 1024 bit RSA key provided + in as KeyBlob (v2). + "ED25519-V3"; The server should use the ed25519 v3 key provided in as + KeyBlob (v3). + + KeyBlob = + "BEST" / ; The server should generate a key using the "best" + supported algorithm (KeyType == "NEW"). + [As of 0.4.2.3-alpha, ED25519-V3 is used] + "RSA1024" / ; The server should generate a 1024 bit RSA key + (KeyType == "NEW") (v2). + "ED25519-V3"; The server should generate an ed25519 private key + (KeyType == "NEW") (v3). + String ; A serialized private key (without whitespace) + + Flag = + "DiscardPK" / ; The server should not include the newly generated + private key as part of the response. + "Detach" / ; Do not associate the newly created Onion Service + to the current control connection. + "BasicAuth" / ; Client authorization is required using the "basic" + method (v2 only). + "V3Auth" / ; Version 3 client authorization is required (v3 only). + + "NonAnonymous" /; Add a non-anonymous Single Onion Service. Tor + checks this flag matches its configured hidden + service anonymity mode. + "MaxStreamsCloseCircuit"; Close the circuit is the maximum streams + allowed is reached. + + NumStreams = A value between 0 and 65535 which is used as the maximum + streams that can be attached on a rendezvous circuit. Setting + it to 0 means unlimited which is also the default behavior. + + VirtPort = The virtual TCP Port for the Onion Service (As in the + HiddenServicePort "VIRTPORT" argument). + + Target = The (optional) target for the given VirtPort (As in the + optional HiddenServicePort "TARGET" argument). + + ClientName = An identifier 1 to 16 characters long, using only + characters in A-Za-z0-9+-_ (no spaces) (v2 only). + + ClientBlob = Authorization data for the client, in an opaque format + specific to the authorization method (v2 only). + + V3Key = The client's base32-encoded x25519 public key, using only the key + part of rend-spec-v3.txt section G.1.2 (v3 only). + + The server reply format is: + + "250-ServiceID=" ServiceID CRLF + ["250-PrivateKey=" KeyType ":" KeyBlob CRLF] + *("250-ClientAuth=" ClientName ":" ClientBlob CRLF) + "250 OK" CRLF + + ServiceID = The Onion Service address without the trailing ".onion" + suffix +``` + +Tells the server to create a new Onion ("Hidden") Service, with the +specified private key and algorithm. If a KeyType of "NEW" is selected, +the server will generate a new keypair using the selected algorithm. +The "Port" argument's VirtPort and Target values have identical +semantics to the corresponding HiddenServicePort configuration values. + +The server response will only include a private key if the server was +requested to generate a new keypair, and also the "DiscardPK" flag was +not specified. (Note that if "DiscardPK" flag is specified, there is no +way to recreate the generated keypair and the corresponding Onion +Service at a later date). + +If client authorization is enabled using the "BasicAuth" flag (which is v2 +only), the service will not be accessible to clients without valid +authorization data (configured with the "HidServAuth" option). The list of +authorized clients is specified with one or more "ClientAuth" parameters. +If "ClientBlob" is not specified for a client, a new credential will be +randomly generated and returned. + +Tor instances can either be in anonymous hidden service mode, or +non-anonymous single onion service mode. All hidden services on the same +tor instance have the same anonymity. To guard against unexpected loss +of anonymity, Tor checks that the ADD_ONION "NonAnonymous" flag matches +the current hidden service anonymity mode. The hidden service anonymity +mode is configured using the Tor options HiddenServiceSingleHopMode and +HiddenServiceNonAnonymousMode. If both these options are 1, the +"NonAnonymous" flag must be provided to ADD_ONION. If both these options +are 0 (the Tor default), the flag must NOT be provided. + +Once created the new Onion Service will remain active until either the +Onion Service is removed via "DEL_ONION", the server terminates, or the +control connection that originated the "ADD_ONION" command is closed. +It is possible to override disabling the Onion Service on control +connection close by specifying the "Detach" flag. + +It is the Onion Service server application's responsibility to close +existing client connections if desired after the Onion Service is +removed. + +(The KeyBlob format is left intentionally opaque, however for "RSA1024" +keys it is currently the Base64 encoded DER representation of a PKCS#1 +RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is +the Base64 encoding of the concatenation of the 32-byte ed25519 secret +scalar in little-endian and the 32-byte ed25519 PRF secret.) + +\[Note: The ED25519-V3 format is not the same as, e.g., SUPERCOP +ed25519/ref, which stores the concatenation of the 32-byte ed25519 +hash seed concatenated with the 32-byte public key, and which derives +the secret scalar and PRF secret by expanding the hash seed with +SHA-512. Our key blinding scheme is incompatible with storing +private keys as seeds, so we store the secret scalar alongside the +PRF secret, and just pay the cost of recomputing the public key when +importing an ED25519-V3 key.\] + +Examples: + +```text + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK + + C: ADD_ONION RSA1024:[Blob Redacted] Port=80,192.168.1.1:8080 + S: 250-ServiceID=sampleonion12456 + S: 250 OK + + C: ADD_ONION NEW:BEST Port=22 Port=80,8080 + S: 250-ServiceID=sampleonion4t2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250-PrivateKey=ED25519-V3:[Blob Redacted] + S: 250 OK + + C: ADD_ONION NEW:RSA1024 Flags=DiscardPK,BasicAuth Port=22 + ClientAuth=alice:[Blob Redacted] ClientAuth=bob + S: 250-ServiceID=testonion1234567 + S: 250-ClientAuth=bob:[Blob Redacted] + S: 250 OK + + C: ADD_ONION NEW:ED25519-V3 ClientAuthV3=[Blob Redacted] Port=22 + S: 250-ServiceID=n35etu3yjxrqjpntmfziom5sjwspoydchmelc4xleoy4jk2u4lziz2yd + S: 250-ClientAuthV3=[Blob Redacted] + S: 250 OK + + Examples with Tor in anonymous onion service mode: + + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK + + C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 + S: 512 Tor is in anonymous hidden service mode + + Examples with Tor in non-anonymous onion service mode: + + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22 + S: 512 Tor is in non-anonymous hidden service mode + + C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250 OK +``` + +\[ADD_ONION was added in Tor 0.2.7.1-alpha.\] +\[MaxStreams and MaxStreamsCloseCircuit were added in Tor 0.2.7.2-alpha\] +\[ClientAuth was added in Tor 0.2.9.1-alpha. It is v2 only.\] +\[NonAnonymous was added in Tor 0.2.9.3-alpha.\] +\[HS v3 support added 0.3.3.1-alpha\] +\[ClientV3Auth support added 0.4.6.1-alpha\] + +<a id="control-spec.txt-3.28"></a> + +## DEL_ONION + +The syntax is: + +"DEL_ONION" SP ServiceID CRLF + +```text + ServiceID = The Onion Service address without the trailing ".onion" + suffix +``` + +Tells the server to remove an Onion ("Hidden") Service, that was +previously created via an "ADD_ONION" command. It is only possible to +remove Onion Services that were created on the same control connection +as the "DEL_ONION" command, and those that belong to no control +connection in particular (The "Detach" flag was specified at creation). + +If the ServiceID is invalid, or is neither owned by the current control +connection nor a detached Onion Service, the server will return a 552. + +It is the Onion Service server application's responsibility to close +existing client connections if desired after the Onion Service has been +removed via "DEL_ONION". + +Tor replies with "250 OK" on success, or a 512 if there are an invalid +number of arguments, or a 552 if it doesn't recognize the ServiceID. + +\[DEL_ONION was added in Tor 0.2.7.1-alpha.\] +\[HS v3 support added 0.3.3.1-alpha\] + +<a id="control-spec.txt-3.29"></a> + +## HSPOST + +The syntax is: + +```text + "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress] + CRLF Descriptor CRLF "." CRLF + + Server = LongName + HSAddress = 56*Base32Character + Descriptor = The text of the descriptor formatted as specified + in rend-spec.txt section 1.3. +``` + +The "HSAddress" key is optional and only applies for v3 descriptors. A 513 +error is returned if used with v2. + +This command launches a hidden service descriptor upload to the specified +HSDirs. If one or more Server arguments are provided, an upload is triggered +on each of them in parallel. If no Server options are provided, it behaves +like a normal HS descriptor upload and will upload to the set of responsible +HS directories. + +If any value is unrecognized, a 552 error is returned and the command is +stopped. If there is an error in parsing the descriptor, the server +must send a "554 Invalid descriptor" reply. + +On success, Tor replies "250 OK" then Tor MUST eventually follow +this with a HS_DESC event with the result for each upload location. + +Examples are: + +```text + C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 + [DESCRIPTOR] + . + S: 250 OK + + [HSPOST was added in Tor 0.2.7.1-alpha] +``` + +<a id="control-spec.txt-3.30"></a> + +## ONION_CLIENT_AUTH_ADD + +The syntax is: + +```text + "ONION_CLIENT_AUTH_ADD" SP HSAddress + SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" TYPE] CRLF + + HSAddress = 56*Base32Character + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key +``` + +Tells the connected Tor to add client-side v3 client auth credentials for the +onion service with "HSAddress". The "PrivateKeyBlob" is the x25519 private +key that should be used for this client, and "Nickname" is an optional +nickname for the client. + +FLAGS is a comma-separated tuple of flags for this new client. For now, the +currently supported flags are: + +```text + "Permanent" - This client's credentials should be stored in the filesystem. + If this is not set, the client's credentials are ephemeral + and stored in memory. +``` + +If client auth credentials already existed for this service, replace them +with the new ones. + +If Tor has cached onion service descriptors that it has been unable to +decrypt in the past (due to lack of client auth credentials), attempt to +decrypt those descriptors as soon as this command succeeds. + +On success, "250 OK" is returned. Otherwise, the following error codes exist: + +```text + 251 - Client auth credentials for this onion service already existed and replaced. + 252 - Added client auth credentials and successfully decrypted a cached descriptor. + 451 - We reached authorized client capacity + 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" + 551 - Client with with this "Nickname" already exists + 552 - Unrecognized KeyType + + [ONION_CLIENT_AUTH_ADD was added in Tor 0.4.3.1-alpha] +``` + +<a id="control-spec.txt-3.31"></a> + +## ONION_CLIENT_AUTH_REMOVE + +The syntax is: + +"ONION_CLIENT_AUTH_REMOVE" SP HSAddress + +KeyType = "x25519" is the only one supported right now + +Tells the connected Tor to remove the client-side v3 client auth credentials +for the onion service with "HSAddress". + +On success "250 OK" is returned. Otherwise, the following error codes exist: + +```text + 512 - Syntax error in "HSAddress". + 251 - Client credentials for "HSAddress" did not exist. + + [ONION_CLIENT_AUTH_REMOVE was added in Tor 0.4.3.1-alpha] +``` + +<a id="control-spec.txt-3.32"></a> + +## 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 +credentials for "HSAddress". If no "HSAddress" is provided, list all the +stored client-side v3 client auth credentials. + +The server reply format is: + +```text + "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + *("250-CLIENT" SP HSAddress SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" FLAGS] CRLF) + "250 OK" CRLF + + HSAddress = The onion address under which this credential is stored + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key +``` + +"Nickname" is an optional nickname for this client, which can be set either +through the ONION_CLIENT_AUTH_ADD command, or it's the filename of this +client if the credentials are stored in the filesystem. + +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". + +\[ONION_CLIENT_AUTH_VIEW was added in Tor 0.4.3.1-alpha\] + +<a id="control-spec.txt-3.33"></a> + +## DROPOWNERSHIP + +The syntax is: + +"DROPOWNERSHIP" CRLF + +This command instructs Tor to relinquish ownership of its control +connection. As such tor will not shut down when this control +connection is closed. + +This method is idempotent. If the control connection does not +already have ownership this method returns successfully, and +does nothing. + +The controller can call TAKEOWNERSHIP again to re-establish +ownership. + +\[DROPOWNERSHIP was added in Tor 0.4.0.0-alpha\] + +<a id="control-spec.txt-3.34"></a> + +## DROPTIMEOUTS + +```text + The syntax is: + "DROPTIMEOUTS" CRLF +``` + +Tells the server to drop all circuit build times. Do not invoke this command +lightly; it can increase vulnerability to tracking attacks over time. + +Tor replies with "250 OK" on success. Tor also emits the BUILDTIMEOUT_SET +RESET event right after this "250 OK". + +\[DROPTIMEOUTS was added in Tor 0.4.5.0-alpha.\] diff --git a/spec/control-spec/implementation-notes.md b/spec/control-spec/implementation-notes.md new file mode 100644 index 0000000..97ac811 --- /dev/null +++ b/spec/control-spec/implementation-notes.md @@ -0,0 +1,721 @@ +<a id="control-spec.txt-5"></a> + +# Implementation notes + +<a id="control-spec.txt-5.1"></a> + +## Authentication + +If the control port is open and no authentication operation is enabled, Tor +trusts any local user that connects to the control port. This is generally +a poor idea. + +If the 'CookieAuthentication' option is true, Tor writes a "magic +cookie" file named "control_auth_cookie" into its data directory (or +to another file specified in the 'CookieAuthFile' option). To +authenticate, the controller must demonstrate that it can read the +contents of the cookie file: + +- Current versions of Tor support cookie authentication + +```text + 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 + unintended information disclosure attack whenever the controller + has greater filesystem read access than the process that it has + connected to. (Note that a controller may connect to a process + other than Tor.) It is almost never safe to use, even if the + controller's user has explicitly specified which filename to read + an authentication cookie from. For this reason, the COOKIE + authentication method has been deprecated and will be removed from + 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. +``` + +If the 'HashedControlPassword' option is set, it must contain the salted +hash of a secret password. The salted hash is computed according to the +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: + +```text + 16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2 + ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + salt hashed value + indicator +``` + +You can generate the salt of a password by calling + +```text + '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 +or encoded in hexadecimal. + +<a id="control-spec.txt-5.2"></a> + +## Don't let the buffer get too big { #buffer-size } + +With old versions of Tor (before 0.2.0.16-alpha), if you ask for +lots of events, and 16MB of them queue up on the buffer, the Tor +process will close the socket. + +Newer Tor versions do not have this 16 MB buffer limit. However, +if you leave huge numbers of events unread, Tor may still run out +of memory, so you should still be careful about buffer size. + +<a id="control-spec.txt-5.3"></a> + +## Backward compatibility with v0 control protocol { #v0-compat } + +The 'version 0' control protocol was replaced in Tor 0.1.1.x. Support +was removed in Tor 0.2.0.x. Every non-obsolete version of Tor now +supports the version 1 control protocol. + +For backward compatibility with the "version 0" control protocol, +Tor used to check whether the third octet of the first command is zero. +(If it was, Tor assumed that version 0 is in use.) + +This compatibility was removed in Tor 0.1.2.16 and 0.2.0.4-alpha. + +<a id="control-spec.txt-5.4"></a> + +## Tor config options for use by controllers { #special-config-options } + +Tor provides a few special configuration options for use by controllers. +These options are not saved to disk by SAVECONF. Most can be set and +examined by the SETCONF and GETCONF commands, but some (noted below) can +only be given in a torrc file or on the command line. + +Generally, these options make Tor unusable by disabling a portion of Tor's +normal operations. Unless a controller provides replacement functionality +to fill this gap, Tor will not correctly handle user requests. + +\_\_AllDirActionsPrivate + +```text + If true, Tor will try to launch all directory operations through + anonymous connections. (Ordinarily, Tor only tries to anonymize + requests related to hidden services.) This option will slow down + directory access, and may stop Tor from working entirely if it does not + yet have enough directory information to build circuits. + + (Boolean. Default: "0".) + + __DisablePredictedCircuits + + If true, Tor will not launch preemptive "general-purpose" circuits for + streams to attach to. (It will still launch circuits for testing and + for hidden services.) + + (Boolean. Default: "0".) + + __LeaveStreamsUnattached + + If true, Tor will not automatically attach new streams to circuits; + instead, the controller must attach them with ATTACHSTREAM. If the + controller does not attach the streams, their data will never be routed. + + (Boolean. Default: "0".) + + __HashedControlSessionPassword + + As HashedControlPassword, but is not saved to the torrc file by + SAVECONF. Added in Tor 0.2.0.20-rc. + + __ReloadTorrcOnSIGHUP + + If this option is true (the default), we reload the torrc from disk + every time we get a SIGHUP (from the controller or via a signal). + Otherwise, we don't. This option exists so that controllers can keep + their options from getting overwritten when a user sends Tor a HUP for + some other reason (for example, to rotate the logs). + + (Boolean. Default: "1") + + __OwningControllerProcess + + If this option is set to a process ID, Tor will periodically check + whether a process with the specified PID exists, and exit if one + does not. Added in Tor 0.2.2.28-beta. This option's intended use + is documented in section 3.23 with the related TAKEOWNERSHIP + command. + + Note that this option can only specify a single process ID, unlike + the TAKEOWNERSHIP command which can be sent along multiple control + connections. + + (String. Default: unset.) + + __OwningControllerFD + + If this option is a valid socket, Tor will start with an open control + connection on this socket. Added in Tor 0.3.3.1-alpha. + + This socket will be an owning controller, as if it had already called + TAKEOWNERSHIP. It will be automatically authenticated. This option + should only be used by other programs that are starting Tor. + + This option cannot be changed via SETCONF; it must be set in a torrc or + via the command line. + + (Integer. Default: -1.) + + __DisableSignalHandlers + + If this option is set to true during startup, then Tor will not install + any signal handlers to watch for POSIX signals. The SIGNAL controller + command will still work. + + This option is meant for embedding Tor inside another process, when + the controlling process would rather handle signals on its own. + + This option cannot be changed via SETCONF; it must be set in a torrc or + via the command line. + + (Boolean. Default: 0.) +``` + +<a id="control-spec.txt-5.5"></a> + +## Phases from the Bootstrap status event { #bootstrap-phases } + +```text + [For the bootstrap phases reported by Tor prior to 0.4.0.x, see + Section 5.6.] +``` + +This section describes the various bootstrap phases currently reported +by Tor. Controllers should not assume that the percentages and tags +listed here will continue to match up, or even that the tags will stay +in the same order. Some phases might also be skipped (not reported) +if the associated bootstrap step is already complete, or if the phase +no longer is necessary. Only "starting" and "done" are guaranteed to +exist in all future versions. + +Current Tor versions enter these phases in order, monotonically. +Future Tors MAY revisit earlier phases, for example, if the network +fails. + +<a id="control-spec.txt-5.5.1"></a> + +### Overview of Bootstrap reporting { #bootstrap-overview } + +Bootstrap phases can be viewed as belonging to one of three stages: + +1. Initial connection to a Tor relay or bridge +1. Obtaining directory information +1. Building an application circuit + +Tor doesn't specifically enter Stage 1; that is a side effect of +other actions that Tor is taking. Tor could be making a connection +to a fallback directory server, or it could be making a connection +to a guard candidate. Either one counts as Stage 1 for the purposes +of bootstrap reporting. + +Stage 2 might involve Tor contacting directory servers, or it might +involve reading cached directory information from a previous +session. Large parts of Stage 2 might be skipped if there is already +enough cached directory information to build circuits. Tor will +defer reporting progress in Stage 2 until Stage 1 is complete. + +Tor defers this reporting because Tor can already have enough +directory information to build circuits, yet not be able to connect +to a relay. Without that deferral, a user might misleadingly see Tor +stuck at a large amount of progress when something as fundamental as +making a TCP connection to any relay is failing. + +Tor also doesn't specifically enter Stage 3; that is a side effect +of Tor building circuits for some purpose or other. In a typical +client, Tor builds predicted circuits to provide lower latency for +application connection requests. In Stage 3, Tor might make new +connections to relays or bridges that it did not connect to in Stage +1\. + +<a id="control-spec.txt-5.5.2"></a> + +### Phases in Bootstrap Stage 1 { #bootstrap-stage1 } + +Phase 0: +tag=starting summary="Starting" + +Tor starts out in this phase. + +```text + Phase 1: + tag=conn_pt summary="Connecting to pluggable transport" + [This phase is new in 0.4.0.x] +``` + +Tor is making a TCP connection to the transport plugin for a +pluggable transport. Tor will use this pluggable transport to make +its first connection to a bridge. + +```text + Phase 2: + tag=conn_done_pt summary="Connected to pluggable transport" + [New in 0.4.0.x] +``` + +Tor has completed its TCP connection to the transport plugin for the +pluggable transport. + +```text + Phase 3: + tag=conn_proxy summary="Connecting to proxy" + [New in 0.4.0.x] +``` + +Tor is making a TCP connection to a proxy to make its first +connection to a relay or bridge. + +```text + Phase 4: + tag=conn_done_proxy summary="Connected to proxy" + [New in 0.4.0.x] +``` + +Tor has completed its TCP connection to a proxy to make its first +connection to a relay or bridge. + +```text + Phase 5: + tag=conn summary="Connecting to a relay" + [New in 0.4.0.x; prior versions of Tor had a "conn_dir" phase that + sometimes but not always corresponded to connecting to a directory server] +``` + +Tor is making its first connection to a relay. This might be through +a pluggable transport or proxy connection that Tor has already +established. + +```text + Phase 10: + tag=conn_done summary="Connected to a relay" + [New in 0.4.0.x] + + Tor has completed its first connection to a relay. + + Phase 14: + tag=handshake summary="Handshaking with a relay" + [New in 0.4.0.x; prior versions of Tor had a "handshake_dir" phase] + + Tor is in the process of doing a TLS handshake with a relay. + + Phase 15: + tag=handshake_done summary="Handshake with a relay done" + [New in 0.4.0.x] + + Tor has completed its TLS handshake with a relay. +``` + +<a id="control-spec.txt-5.5.3"></a> + +### Phases in Bootstrap Stage 2 { #bootstrap-stage2 } + +```text + Phase 20: + tag=onehop_create summary="Establishing an encrypted directory connection" + [prior to 0.4.0.x, this was numbered 15] +``` + +Once TLS is finished with a relay, Tor will send a CREATE_FAST cell +to establish a one-hop circuit for retrieving directory information. +It will remain in this phase until it receives the CREATED_FAST cell +back, indicating that the circuit is ready. + +```text + Phase 25: + tag=requesting_status summary="Asking for networkstatus consensus" + [prior to 0.4.0.x, this was numbered 20] +``` + +Once we've finished our one-hop circuit, we will start a new stream +for fetching the networkstatus consensus. We'll stay in this phase +until we get the RELAY_CONNECTED message back, indicating that we've +established a directory connection. + +```text + Phase 30: + tag=loading_status summary="Loading networkstatus consensus" + [prior to 0.4.0.x, this was numbered 25] +``` + +Once we've established a directory connection, we will start fetching +the networkstatus consensus document. This could take a while; this +phase is a good opportunity for using the "progress" keyword to indicate +partial progress. + +This phase could stall if the directory server we picked doesn't +have a copy of the networkstatus consensus so we have to ask another, +or it does give us a copy but we don't find it valid. + +Phase 40: +tag=loading_keys summary="Loading authority key certs" + +Sometimes when we've finished loading the networkstatus consensus, +we find that we don't have all the authority key certificates for the +keys that signed the consensus. At that point we put the consensus we +fetched on hold and fetch the keys so we can verify the signatures. + +Phase 45 +tag=requesting_descriptors summary="Asking for relay descriptors" + +Once we have a valid networkstatus consensus and we've checked all +its signatures, we start asking for relay descriptors. We stay in this +phase until we have received a RELAY_CONNECTED message in response to +a request for descriptors. + +```text + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] +``` + +Phase 50: +tag=loading_descriptors summary="Loading relay descriptors" + +We will ask for relay descriptors from several different locations, +so this step will probably make up the bulk of the bootstrapping, +especially for users with slow connections. We stay in this phase until +we have descriptors for a significant fraction of the usable relays +listed in the networkstatus consensus (this can be between 25% and 95% +depending on Tor's configuration and network consensus parameters). +This phase is also a good opportunity to use the "progress" keyword to +indicate partial steps. + +```text + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] + + Phase 75: + tag=enough_dirinfo summary="Loaded enough directory info to build + circuits" + [New in 0.4.0.x; previously, Tor would misleadingly report the + "conn_or" tag once it had enough directory info.] +``` + +<a id="control-spec.txt-5.5.4"></a> + +### Phases in Bootstrap Stage 3 { #bootstrap-stage3 } + +```text + Phase 76: + tag=ap_conn_pt summary="Connecting to pluggable transport to build + circuits" + [New in 0.4.0.x] +``` + +This is similar to conn_pt, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 77: + tag=ap_conn_done_pt summary="Connected to pluggable transport to build circuits" + [New in 0.4.0.x] +``` + +This is similar to conn_done_pt, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 78: + tag=ap_conn_proxy summary="Connecting to proxy to build circuits" + [New in 0.4.0.x] +``` + +This is similar to conn_proxy, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 79: + tag=ap_conn_done_proxy summary="Connected to proxy to build circuits" + [New in 0.4.0.x] +``` + +This is similar to conn_done_proxy, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 80: + tag=ap_conn summary="Connecting to a relay to build circuits" + [New in 0.4.0.x] +``` + +This is similar to conn, except for making connections to additional +relays or bridges that Tor needs to use to build application +circuits. + +```text + Phase 85: + tag=ap_conn_done summary="Connected to a relay to build circuits" + [New in 0.4.0.x] +``` + +This is similar to conn_done, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 89: + tag=ap_handshake summary="Finishing handshake with a relay to build circuits" + [New in 0.4.0.x] +``` + +This is similar to handshake, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 90: + tag=ap_handshake_done summary="Handshake finished with a relay to build circuits" + [New in 0.4.0.x] +``` + +This is similar to handshake_done, except for making connections to +additional relays or bridges that Tor needs to use to build +application circuits. + +```text + Phase 95: + tag=circuit_create summary="Establishing a[n internal] Tor circuit" + [prior to 0.4.0.x, this was numbered 90] +``` + +Once we've finished our TLS handshake with the first hop of a circuit, +we will set about trying to make some 3-hop circuits in case we need them +soon. + +```text + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] +``` + +Phase 100: +tag=done summary="Done" + +A full 3-hop circuit has been established. Tor is ready to handle +application connections now. + +```text + [Some versions of Tor (starting with 0.2.6.2-alpha but before + 0.4.0.x): Tor could report having internal paths only; see Section + 5.6] +``` + +<a id="control-spec.txt-5.6"></a> + +## Bootstrap phases reported by older versions of Tor { #bootstrap-obsolete } + +These phases were reported by Tor older than 0.4.0.x. For newer +versions of Tor, see Section 5.5. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. When bootstrap completes, Tor will be ready + to handle an application requesting an exit circuit to services like the + World Wide Web. +``` + +If the consensus does not contain Exits, Tor will only build internal +circuits. In this case, earlier statuses will have included "internal" +as indicated above. When bootstrap completes, Tor will be ready to handle +an application requesting an internal circuit to hidden services at +".onion" addresses. + +If a future consensus contains Exits, exit circuits may become available.\] + +Phase 0: +tag=starting summary="Starting" + +Tor starts out in this phase. + +Phase 5: +tag=conn_dir summary="Connecting to directory server" + +Tor sends this event as soon as Tor has chosen a directory server -- +e.g. one of the authorities if bootstrapping for the first time or +after a long downtime, or one of the relays listed in its cached +directory information otherwise. + +Tor will stay at this phase until it has successfully established +a TCP connection with some directory server. Problems in this phase +generally happen because Tor doesn't have a network connection, or +because the local firewall is dropping SYN packets. + +Phase 10: +tag=handshake_dir summary="Finishing handshake with directory server" + +This event occurs when Tor establishes a TCP connection with a relay or +authority used as a directory server (or its https proxy if it's using +one). Tor remains in this phase until the TLS handshake with the relay +or authority is finished. + +Problems in this phase generally happen because Tor's firewall is +doing more sophisticated MITM attacks on it, or doing packet-level +keyword recognition of Tor's handshake. + +Phase 15: +tag=onehop_create summary="Establishing an encrypted directory connection" + +Once TLS is finished with a relay, Tor will send a CREATE_FAST cell +to establish a one-hop circuit for retrieving directory information. +It will remain in this phase until it receives the CREATED_FAST cell +back, indicating that the circuit is ready. + +Phase 20: +tag=requesting_status summary="Asking for networkstatus consensus" + +Once we've finished our one-hop circuit, we will start a new stream +for fetching the networkstatus consensus. We'll stay in this phase +until we get the RELAY_CONNECTED message back, indicating that we've +established a directory connection. + +Phase 25: +tag=loading_status summary="Loading networkstatus consensus" + +Once we've established a directory connection, we will start fetching +the networkstatus consensus document. This could take a while; this +phase is a good opportunity for using the "progress" keyword to indicate +partial progress. + +This phase could stall if the directory server we picked doesn't +have a copy of the networkstatus consensus so we have to ask another, +or it does give us a copy but we don't find it valid. + +Phase 40: +tag=loading_keys summary="Loading authority key certs" + +Sometimes when we've finished loading the networkstatus consensus, +we find that we don't have all the authority key certificates for the +keys that signed the consensus. At that point we put the consensus we +fetched on hold and fetch the keys so we can verify the signatures. + +```text + Phase 45 + tag=requesting_descriptors summary="Asking for relay descriptors + [ for internal paths]" +``` + +Once we have a valid networkstatus consensus and we've checked all +its signatures, we start asking for relay descriptors. We stay in this +phase until we have received a RELAY_CONNECTED message in response to +a request for descriptors. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will ask for + descriptors for both exit and internal paths. If not, Tor will only ask + for descriptors for internal paths. In this case, this status will + include "internal" as indicated above.] + + Phase 50: + tag=loading_descriptors summary="Loading relay descriptors[ for internal + paths]" +``` + +We will ask for relay descriptors from several different locations, +so this step will probably make up the bulk of the bootstrapping, +especially for users with slow connections. We stay in this phase until +we have descriptors for a significant fraction of the usable relays +listed in the networkstatus consensus (this can be between 25% and 95% +depending on Tor's configuration and network consensus parameters). +This phase is also a good opportunity to use the "progress" keyword to +indicate partial steps. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will download + descriptors for both exit and internal paths. If not, Tor will only + download descriptors for internal paths. In this case, this status will + include "internal" as indicated above.] +``` + +Phase 80: +tag=conn_or summary="Connecting to the Tor network\[ internally\]" + +Once we have a valid consensus and enough relay descriptors, we choose +entry guard(s) and start trying to build some circuits. This step +is similar to the "conn_dir" phase above; the only difference is +the context. + +If a Tor starts with enough recent cached directory information, +its first bootstrap status event will be for the conn_or phase. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. If not, Tor will only build internal circuits. + In this case, this status will include "internal(ly)" as indicated above.] + + Phase 85: + tag=handshake_or summary="Finishing handshake with first hop[ of internal + circuit]" +``` + +This phase is similar to the "handshake_dir" phase, but it gets reached +if we finish a TCP connection to a Tor relay and we have already reached +the "conn_or" phase. We'll stay in this phase until we complete a TLS +handshake with a Tor relay. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor may be finishing + a handshake with the first hop if either an exit or internal circuit. In + this case, it won't specify which type. If the consensus contains no Exits, + Tor will only build internal circuits. In this case, this status will + include "internal" as indicated above.] +``` + +Phase 90: +tag=circuit_create summary="Establishing a\[n internal\] Tor circuit" + +Once we've finished our TLS handshake with the first hop of a circuit, +we will set about trying to make some 3-hop circuits in case we need them +soon. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. If not, Tor will only build internal circuits. + In this case, this status will include "internal" as indicated above.] +``` + +Phase 100: +tag=done summary="Done" + +A full 3-hop circuit has been established. Tor is ready to handle +application connections now. + +```text + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build both + exit and internal circuits. At this stage, Tor will be ready to handle + an application requesting an exit circuit to services like the World + Wide Web. +``` + +If the consensus does not contain Exits, Tor will only build internal +circuits. In this case, earlier statuses will have included "internal" +as indicated above. At this stage, Tor will be ready to handle an +application requesting an internal circuit to hidden services at ".onion" +addresses. + +If a future consensus contains Exits, exit circuits may become available.\] diff --git a/spec/control-spec/index.md b/spec/control-spec/index.md new file mode 100644 index 0000000..8ce17b3 --- /dev/null +++ b/spec/control-spec/index.md @@ -0,0 +1,24 @@ +# TC: A Tor control protocol (Version 1) + +<a id="control-spec.txt-0"></a> + +## Scope + +This document describes an implementation-specific protocol that is used +for other programs (such as frontend user-interfaces) to communicate with a +locally running Tor process. It is not part of the Tor onion routing +protocol. + +This protocol replaces version 0 of TC, which is now deprecated. For +reference, TC is described in "control-spec-v0.txt". Implementors are +recommended to avoid using TC directly, but instead to use a library that +can easily be updated to use the newer protocol. (Version 0 is used by Tor +versions 0.1.0.x; the protocol in this document only works with Tor +versions in the 0.1.1.x series and later.) + +```text + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL + NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC 2119. +``` diff --git a/spec/control-spec/message-format.md b/spec/control-spec/message-format.md new file mode 100644 index 0000000..a9af669 --- /dev/null +++ b/spec/control-spec/message-format.md @@ -0,0 +1,185 @@ +<a id="control-spec.txt-2"></a> + +# Message format + +<a id="control-spec.txt-2.1"></a> + +## Description format + +The message formats listed below use ABNF as described in RFC 2234. +The protocol itself is loosely based on SMTP (see RFC 2821). + +We use the following nonterminals from RFC 2822: atom, qcontent + +We define the following general-use nonterminals: + +QuotedString = DQUOTE \*qcontent DQUOTE + +There are explicitly no limits on line length. All 8-bit characters +are permitted unless explicitly disallowed. In QuotedStrings, +backslashes and quotes must be escaped; other characters need not be +escaped. + +Wherever CRLF is specified to be accepted from the controller, Tor MAY also +accept LF. Tor, however, MUST NOT generate LF instead of CRLF. +Controllers SHOULD always send CRLF. + +<a id="control-spec.txt-2.1.1"></a> + +### Notes on an escaping bug + +CString = DQUOTE \*qcontent DQUOTE + +Note that although these nonterminals have the same grammar, they +are interpreted differently. In a QuotedString, a backslash +followed by any character represents that character. But +in a CString, the escapes "\\n", "\\t", "\\r", and the octal escapes +"\\0" ... "\\377" represent newline, tab, carriage return, and the +256 possible octet values respectively. + +The use of CString in this document reflects a bug in Tor; +they should have been QuotedString instead. In the future, they +may migrate to use QuotedString instead. If they do, the +QuotedString implementation will never place a backslash before a +"n", "t", "r", or digit, to ensure that old controllers don't get +confused. + +For future-proofing, controller implementors MAY use the following +rules to be compatible with buggy Tor implementations and with +future ones that implement the spec as intended: + +```text + Read \n \t \r and \0 ... \377 as C escapes. + Treat a backslash followed by any other character as that character. +``` + +Currently, many of the QuotedString instances below that Tor +outputs are in fact CStrings. We intend to fix this in future +versions of Tor, and document which ones were broken. (See +bugtracker ticket #14555 for a bit more information.) + +Note that this bug exists only in strings generated by Tor for the +Tor controller; Tor should parse input QuotedStrings from the +controller correctly. + +<a id="control-spec.txt-2.2"></a> + +## Commands from controller to Tor { #commands } + +```text + Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData + Keyword = 1*ALPHA + OptArguments = [ SP *(SP / VCHAR) ] +``` + +A command is either a single line containing a Keyword and arguments, or a +multiline command whose initial keyword begins with +, and whose data +section ends with a single "." on a line of its own. (We use a special +character to distinguish multiline commands so that Tor can correctly parse +multi-line commands that it does not recognize.) Specific commands and +their arguments are described below in section 3. + +<a id="control-spec.txt-2.3"></a> + +## Replies from Tor to the controller { #replies } + +```text + Reply = SyncReply / AsyncReply + SyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine + AsyncReply = *(MidReplyLine / DataReplyLine) EndReplyLine + + MidReplyLine = StatusCode "-" ReplyLine + DataReplyLine = StatusCode "+" ReplyLine CmdData + EndReplyLine = StatusCode SP ReplyLine + ReplyLine = [ReplyText] CRLF + ReplyText = XXXX + StatusCode = 3DIGIT +``` + +Unless specified otherwise, multiple lines in a single reply from +Tor to the controller are guaranteed to share the same status +code. Specific replies are mentioned below in section 3, and +described more fully in section 4. + +\[Compatibility note: versions of Tor before 0.2.0.3-alpha sometimes +generate AsyncReplies of the form "\*(MidReplyLine / DataReplyLine)". +This is incorrect, but controllers that need to work with these +versions of Tor should be prepared to get multi-line AsyncReplies with +the final line (usually "650 OK") omitted.\] + +<a id="control-spec.txt-2.4"></a> + +## General-use tokens { #tokens } + +; CRLF means, "the ASCII Carriage Return character (decimal value 13) +; followed by the ASCII Linefeed character (decimal value 10)." +CRLF = CR LF + +; How a controller tells Tor about a particular OR. There are four +; possible formats: +; $Fingerprint -- The router whose identity key hashes to the fingerprint. +; This is the preferred way to refer to an OR. +; $Fingerprint~Nickname -- The router whose identity key hashes to the +; given fingerprint, but only if the router has the given nickname. +; $Fingerprint=Nickname -- The router whose identity key hashes to the +; given fingerprint, but only if the router is Named and has the given +; nickname. +; Nickname -- The Named router with the given nickname, or, if no such +; router exists, any router whose nickname matches the one given. +; This is not a safe way to refer to routers, since Named status +; could under some circumstances change over time. +; +; The tokens that implement the above follow: + +ServerSpec = LongName / Nickname +LongName = Fingerprint \[ "~" Nickname \] + +; For tors older than 0.3.1.3-alpha, LongName may have included an equal +; sign ("=") in lieu of a tilde ("~"). The presence of an equal sign +; denoted that the OR possessed the "Named" flag: + +LongName = Fingerprint \[ ( "=" / "~" ) Nickname \] + +Fingerprint = "$" 40*HEXDIG +NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9" +Nickname = 1*19 NicknameChar + +; What follows is an outdated way to refer to ORs. +; Feature VERBOSE_NAMES replaces ServerID with LongName in events and +; GETINFO results. VERBOSE_NAMES can be enabled starting in Tor version +; 0.1.2.2-alpha and it is always-on in 0.2.2.1-alpha and later. +ServerID = Nickname / Fingerprint + +; Unique identifiers for streams or circuits. Currently, Tor only +; uses digits, but this may change +StreamID = 1*16 IDChar +CircuitID = 1*16 IDChar +ConnID = 1*16 IDChar +QueueID = 1*16 IDChar +IDChar = ALPHA / DIGIT + +Address = ip4-address / ip6-address / hostname (XXXX Define these) + +; A "CmdData" section is a sequence of octets concluded by the terminating +; sequence CRLF "." CRLF. The terminating sequence may not appear in the +; body of the data. Leading periods on lines in the data are escaped with +; an additional leading period as in RFC 2821 section 4.5.2. +CmdData = *DataLine "." CRLF +DataLine = CRLF / "." 1*LineItem CRLF / NonDotItem *LineItem CRLF +LineItem = NonCR / 1*CR NonCRLF +NonDotItem = NonDotCR / 1\*CR NonCRLF + +; ISOTime, ISOTime2, and ISOTime2Frac are time formats as specified in +; ISO8601. +; example ISOTime: "2012-01-11 12:15:33" +; example ISOTime2: "2012-01-11T12:15:33" +; example ISOTime2Frac: "2012-01-11T12:15:33.51" +IsoDatePart = 4*DIGIT "-" 2*DIGIT "-" 2*DIGIT +IsoTimePart = 2*DIGIT ":" 2*DIGIT ":" 2*DIGIT +ISOTime = IsoDatePart " " IsoTimePart +ISOTime2 = IsoDatePart "T" IsoTimePart +ISOTime2Frac = IsoTime2 \[ "." 1\*DIGIT \] + +; Numbers +LeadingDigit = "1" - "9" +UInt = LeadingDigit \*Digit diff --git a/spec/control-spec/protocol-outline.md b/spec/control-spec/protocol-outline.md new file mode 100644 index 0000000..0329b1d --- /dev/null +++ b/spec/control-spec/protocol-outline.md @@ -0,0 +1,71 @@ +<a id="control-spec.txt-1"></a> + +# Protocol outline + +TC is a bidirectional message-based protocol. It assumes an underlying +stream for communication between a controlling process (the "client" +or "controller") and a Tor process (or "server"). The stream may be +implemented via TCP, TLS-over-TCP, a Unix-domain socket, or so on, +but it must provide reliable in-order delivery. For security, the +stream should not be accessible by untrusted parties. + +In TC, the client and server send typed messages to each other over the +underlying stream. The client sends "commands" and the server sends +"replies". + +By default, all messages from the server are in response to messages from +the client. Some client requests, however, will cause the server to send +messages to the client indefinitely far into the future. Such +"asynchronous" replies are marked as such. + +Servers respond to messages in the order messages are received. + +<a id="control-spec.txt-1.1"></a> + +## Forward-compatibility + +This is an evolving protocol; new client and server behavior will be +allowed in future versions. To allow new backward-compatible behavior +on behalf of the client, we may add new commands and allow existing +commands to take new arguments in future versions. To allow new +backward-compatible server behavior, we note various places below +where servers speaking a future version of this protocol may insert +new data, and note that clients should/must "tolerate" unexpected +elements in these places. There are two ways that we do this: + +- Adding a new field to a message: + +```text + For example, we might say "This message has three space-separated + fields; clients MUST tolerate more fields." This means that a + client MUST NOT crash or otherwise fail to parse the message or + other subsequent messages when there are more than three fields, and + that it SHOULD function at least as well when more fields are + provided as it does when it only gets the fields it accepts. The + most obvious way to do this is by ignoring additional fields; the + next-most-obvious way is to report additional fields verbatim to the + user, perhaps as part of an expert UI. + + * Adding a new possible value to a list of alternatives: + + For example, we might say "This field will be OPEN, CLOSED, or + CONNECTED. Clients MUST tolerate unexpected values." This means + that a client MUST NOT crash or otherwise fail to parse the message + or other subsequent messages when there are unexpected values, and + that it SHOULD try to handle the rest of the message as well as it + can. The most obvious way to do this is by pretending that each + list of alternatives has an additional "unrecognized value" element, + and mapping any unrecognized values to that element; the + next-most-obvious way is to create a separate "unrecognized value" + element for each unrecognized value. + + Clients SHOULD NOT "tolerate" unrecognized alternatives by + pretending that the message containing them is absent. For example, + a stream closed for an unrecognized reason is nevertheless closed, + and should be reported as such. + + (If some list of alternatives is given, and there isn't an explicit + statement that clients must tolerate unexpected values, clients still + must tolerate unexpected values. The only exception would be if there + were an explicit statement that no future values will ever be added.) +``` diff --git a/spec/control-spec/replies.md b/spec/control-spec/replies.md new file mode 100644 index 0000000..ed76cbd --- /dev/null +++ b/spec/control-spec/replies.md @@ -0,0 +1,1796 @@ +<a id="control-spec.txt-4"></a> + +# Replies + +Reply codes follow the same 3-character format as used by SMTP, with the +first character defining a status, the second character defining a +subsystem, and the third designating fine-grained information. + +The TC protocol currently uses the following first characters: + +```text + 2yz Positive Completion Reply + The command was successful; a new request can be started. + + 4yz Temporary Negative Completion reply + The command was unsuccessful but might be reattempted later. + + 5yz Permanent Negative Completion Reply + The command was unsuccessful; the client should not try exactly + that sequence of commands again. + + 6yz Asynchronous Reply + Sent out-of-order in response to an earlier SETEVENTS command. + + The following second characters are used: + + x0z Syntax + Sent in response to ill-formed or nonsensical commands. + + x1z Protocol + Refers to operations of the Tor Control protocol. + + x5z Tor + Refers to actual operations of Tor system. + + The following codes are defined: + + 250 OK + 251 Operation was unnecessary + [Tor has declined to perform the operation, but no harm was done.] + + 451 Resource exhausted + + 500 Syntax error: protocol + + 510 Unrecognized command + 511 Unimplemented command + 512 Syntax error in command argument + 513 Unrecognized command argument + 514 Authentication required + 515 Bad authentication + + 550 Unspecified Tor error + + 551 Internal error + [Something went wrong inside Tor, so that the client's + request couldn't be fulfilled.] + + 552 Unrecognized entity + [A configuration key, a stream ID, circuit ID, event, + mentioned in the command did not actually exist.] + + 553 Invalid configuration value + [The client tried to set a configuration option to an + incorrect, ill-formed, or impossible value.] + + 554 Invalid descriptor + + 555 Unmanaged entity + + 650 Asynchronous event notification +``` + +Unless specified to have specific contents, the human-readable messages +in error replies should not be relied upon to match those in this document. + +<a id="control-spec.txt-4.1"></a> + +## Asynchronous events + +These replies can be sent after a corresponding SETEVENTS command has been +received. They will not be interleaved with other Reply elements, but they +can appear between a command and its corresponding reply. For example, +this sequence is possible: + +```text + C: SETEVENTS CIRC + S: 250 OK + C: GETCONF SOCKSPORT ORPORT + S: 650 CIRC 1000 EXTENDED moria1,moria2 + S: 250-SOCKSPORT=9050 + S: 250 ORPORT=0 + + But this sequence is disallowed: + + C: SETEVENTS CIRC + S: 250 OK + C: GETCONF SOCKSPORT ORPORT + S: 250-SOCKSPORT=9050 + S: 650 CIRC 1000 EXTENDED moria1,moria2 + S: 250 ORPORT=0 +``` + +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: + +```text + 650-CIRC 1000 EXTENDED moria1,moria2 0xBEEF + 650-EXTRAMAGIC=99 + 650 ANONYMITY=high +``` + +If clients receives extended events (selected by USEFEATUERE +EXTENDED_EVENTS in Tor 0.1.2.2-alpha..Tor-0.2.1.x, and always-on in +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 +recognize, and SHOULD process those events as if any unrecognized +arguments and keywords were not present. + +Clients SHOULD NOT depend on the order of keyword=value arguments, +and SHOULD NOT depend on there being no new keyword=value arguments +appearing between existing keyword=value arguments, though as of this +writing (Jun 2011) some do. Thus, extensions to this protocol should +add new keywords only after the existing keywords, until all +controllers have been fixed. At some point this "SHOULD NOT" might +become a "MUST NOT". + +<a id="control-spec.txt-4.1.1"></a> + +### Circuit status changed { #CIRC } + +The syntax is: + +```text + "650" SP "CIRC" SP CircuitID SP CircStatus [SP Path] + [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose] + [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress] + [SP "TIME_CREATED=" TimeCreated] + [SP "REASON=" Reason [SP "REMOTE_REASON=" Reason]] + [SP "SOCKS_USERNAME=" EscapedUsername] + [SP "SOCKS_PASSWORD=" EscapedPassword] + [SP "HS_POW=" HSPoW ] + CRLF + + CircStatus = + "LAUNCHED" / ; circuit ID assigned to new circuit + "BUILT" / ; all hops finished, can now accept streams + "GUARD_WAIT" / ; all hops finished, waiting to see if a + ; circuit with a better guard will be usable. + "EXTENDED" / ; one more hop has been completed + "FAILED" / ; circuit closed (was not built) + "CLOSED" ; circuit closed (was built) + + Path = LongName *("," LongName) + ; 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, Path + ; is as follows: + ; Path = ServerID *("," ServerID) + + BuildFlags = BuildFlag *("," BuildFlag) + BuildFlag = "ONEHOP_TUNNEL" / "IS_INTERNAL" / + "NEED_CAPACITY" / "NEED_UPTIME" + + Purpose = "GENERAL" / "HS_CLIENT_INTRO" / "HS_CLIENT_REND" / + "HS_SERVICE_INTRO" / "HS_SERVICE_REND" / "TESTING" / + "CONTROLLER" / "MEASURE_TIMEOUT" / + "HS_VANGUARDS" / "PATH_BIAS_TESTING" / + "CIRCUIT_PADDING" + + HSState = "HSCI_CONNECTING" / "HSCI_INTRO_SENT" / "HSCI_DONE" / + "HSCR_CONNECTING" / "HSCR_ESTABLISHED_IDLE" / + "HSCR_ESTABLISHED_WAITING" / "HSCR_JOINED" / + "HSSI_CONNECTING" / "HSSI_ESTABLISHED" / + "HSSR_CONNECTING" / "HSSR_JOINED" + + HSPoWType = "v1" + HSPoWEffort = 1*DIGIT + HSPoW = HSPoWType "," HSPoWEffort + + EscapedUsername = QuotedString + EscapedPassword = QuotedString + + HSAddress = 16*Base32Character / 56*Base32Character + Base32Character = ALPHA / "2" / "3" / "4" / "5" / "6" / "7" + + TimeCreated = ISOTime2Frac + Seconds = 1*DIGIT + Microseconds = 1*DIGIT + + Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" / + "HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" / + "OR_IDENTITY" / "OR_CONN_CLOSED" / "TIMEOUT" / + "FINISHED" / "DESTROYED" / "NOPATH" / "NOSUCHSERVICE" / + "MEASUREMENT_EXPIRED" + + The path is provided only when the circuit has been extended at least one + hop. + + The "BUILD_FLAGS" field is provided only in versions 0.2.3.11-alpha + and later. Clients MUST accept build flags not listed above. + Build flags are defined as follows: + + ONEHOP_TUNNEL (one-hop circuit, used for tunneled directory conns) + IS_INTERNAL (internal circuit, not to be used for exiting streams) + NEED_CAPACITY (this circuit must use only high-capacity nodes) + NEED_UPTIME (this circuit must use only high-uptime nodes) + + The "PURPOSE" field is provided only in versions 0.2.1.6-alpha and + later, and only if extended events are enabled (see 3.19). Clients + MUST accept purposes not listed above. Purposes are defined as + follows: + + GENERAL (circuit for AP and/or directory request streams) + HS_CLIENT_INTRO (HS client-side introduction-point circuit) + HS_CLIENT_REND (HS client-side rendezvous circuit; carries AP streams) + HS_SERVICE_INTRO (HS service-side introduction-point circuit) + HS_SERVICE_REND (HS service-side rendezvous circuit) + TESTING (reachability-testing circuit; carries no traffic) + CONTROLLER (circuit built by a controller) + MEASURE_TIMEOUT (circuit being kept around to see how long it takes) + HS_VANGUARDS (circuit created ahead of time when using + HS vanguards, and later repurposed as needed) + PATH_BIAS_TESTING (circuit used to probe whether our circuits are + being deliberately closed by an attacker) + CIRCUIT_PADDING (circuit that is being held open to disguise its + true close time) + + The "HS_STATE" field is provided only for hidden-service circuits, + and only in versions 0.2.3.11-alpha and later. Clients MUST accept + hidden-service circuit states not listed above. Hidden-service + circuit states are defined as follows: + + HSCI_* (client-side introduction-point circuit states) + HSCI_CONNECTING (connecting to intro point) + HSCI_INTRO_SENT (sent INTRODUCE1; waiting for reply from IP) + HSCI_DONE (received reply from IP relay; closing) + + HSCR_* (client-side rendezvous-point circuit states) + HSCR_CONNECTING (connecting to or waiting for reply from RP) + HSCR_ESTABLISHED_IDLE (established RP; waiting for introduction) + HSCR_ESTABLISHED_WAITING (introduction sent to HS; waiting for rend) + HSCR_JOINED (connected to HS) + + HSSI_* (service-side introduction-point circuit states) + HSSI_CONNECTING (connecting to intro point) + HSSI_ESTABLISHED (established intro point) + + HSSR_* (service-side rendezvous-point circuit states) + HSSR_CONNECTING (connecting to client's rend point) + HSSR_JOINED (connected to client's RP circuit) + + The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials + that were used by a SOCKS client to connect to Tor's SOCKS port and + initiate this circuit. (Streams for SOCKS clients connected with different + usernames and/or passwords are isolated on separate circuits if the + IsolateSOCKSAuth flag is active; see Proposal 171.) [Added in Tor + 0.4.3.1-alpha.] + + The "REND_QUERY" field is provided only for hidden-service-related + circuits, and only in versions 0.2.3.11-alpha and later. Clients + MUST accept hidden service addresses in formats other than that + specified above. [Added in Tor 0.4.3.1-alpha.] + + The "TIME_CREATED" field is provided only in versions 0.2.3.11-alpha and + later. TIME_CREATED is the time at which the circuit was created or + cannibalized. [Added in Tor 0.4.3.1-alpha.] + + The "REASON" field is provided only for FAILED and CLOSED events, and only + if extended events are enabled (see 3.19). Clients MUST accept reasons + not listed above. [Added in Tor 0.4.3.1-alpha.] Reasons are as given in + tor-spec.txt, except for: + + NOPATH (Not enough nodes to make circuit) + MEASUREMENT_EXPIRED (As "TIMEOUT", except that we had left the circuit + open for measurement purposes to see how long it + would take to finish.) + IP_NOW_REDUNDANT (Closing a circuit to an introduction point that + has become redundant, since some other circuit + opened in parallel with it has succeeded.) + + The "REMOTE_REASON" field is provided only when we receive a DESTROY cell or + RELAY_TRUNCATE message, and only if extended events are enabled. It contains the + actual reason given by the remote OR for closing the circuit. Clients MUST + accept reasons not listed above. Reasons are as listed in tor-spec.txt. + [Added in Tor 0.4.3.1-alpha.] +``` + +<a id="control-spec.txt-4.1.2"></a> + +### Stream status changed { #STREAM } + +The syntax is: + +```text + "650" SP "STREAM" SP StreamID SP StreamStatus SP CircuitID SP Target + [SP "REASON=" Reason [ SP "REMOTE_REASON=" Reason ]] + [SP "SOURCE=" Source] [ SP "SOURCE_ADDR=" Address ":" Port ] + [SP "PURPOSE=" Purpose] [SP "SOCKS_USERNAME=" EscapedUsername] + [SP "SOCKS_PASSWORD=" EscapedPassword] + [SP "CLIENT_PROTOCOL=" ClientProtocol] [SP "NYM_EPOCH=" NymEpoch] + [SP "SESSION_GROUP=" SessionGroup] [SP "ISO_FIELDS=" IsoFields] + CRLF + + StreamStatus = + "NEW" / ; New request to connect + "NEWRESOLVE" / ; New request to resolve an address + "REMAP" / ; Address re-mapped to another + "SENTCONNECT" / ; Sent a connect message along a circuit + "SENTRESOLVE" / ; Sent a resolve message along a circuit + "SUCCEEDED" / ; Received a reply; stream established + "FAILED" / ; Stream failed and not retriable + "CLOSED" / ; Stream closed + "DETACHED" / ; Detached from circuit; still retriable + "CONTROLLER_WAIT" ; Waiting for controller to use ATTACHSTREAM + ; (new in 0.4.5.1-alpha) + "XOFF_SENT" ; XOFF has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XOFF_RECV" ; XOFF has been received for this stream + ; (new in 0.4.7.5-alpha) + "XON_SENT" ; XON has been sent for this stream + ; (new in 0.4.7.5-alpha) + "XON_RECV" ; XON has been received for this stream + ; (new in 0.4.7.5-alpha) + + Target = TargetAddress ":" Port + Port = an integer from 0 to 65535 inclusive + TargetAddress = Address / "(Tor_internal)" + + EscapedUsername = QuotedString + EscapedPassword = QuotedString + + ClientProtocol = + "SOCKS4" / + "SOCKS5" / + "TRANS" / + "NATD" / + "DNS" / + "HTTPCONNECT" / + "UNKNOWN" + + NymEpoch = a nonnegative integer + SessionGroup = an integer + + IsoFields = a comma-separated list of IsoField values + + IsoField = + "CLIENTADDR" / + "CLIENTPORT" / + "DESTADDR" / + "DESTPORT" / + the name of a field that is valid for STREAM events +``` + +The circuit ID designates which circuit this stream is attached to. If +the stream is unattached, the circuit ID "0" is given. The target +indicates the address which the stream is meant to resolve or connect to; +it can be "(Tor_internal)" for a virtual stream created by the Tor program +to talk to itself. + +```text + Reason = "MISC" / "RESOLVEFAILED" / "CONNECTREFUSED" / + "EXITPOLICY" / "DESTROY" / "DONE" / "TIMEOUT" / + "NOROUTE" / "HIBERNATING" / "INTERNAL"/ "RESOURCELIMIT" / + "CONNRESET" / "TORPROTOCOL" / "NOTDIRECTORY" / "END" / + "PRIVATE_ADDR" + + The "REASON" field is provided only for FAILED, CLOSED, and DETACHED + events, and only if extended events are enabled (see 3.19). Clients MUST + accept reasons not listed above. Reasons are as given in tor-spec.txt, + except for: + + END (We received a RELAY_END message from the other side of this + stream.) + PRIVATE_ADDR (The client tried to connect to a private address like + 127.0.0.1 or 10.0.0.1 over Tor.) + [XXXX document more. -NM] + + The "REMOTE_REASON" field is provided only when we receive a RELAY_END + message, and only if extended events are enabled. It contains the actual + reason given by the remote OR for closing the stream. Clients MUST accept + 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 + the new address as a response. + + The "SOURCE_ADDR" field is included with NEW and NEWRESOLVE events if + extended events are enabled. It indicates the address and port + that requested the connection, and can be (e.g.) used to look up the + requesting program. + + Purpose = "DIR_FETCH" / "DIR_UPLOAD" / "DNS_REQUEST" / + "USER" / "DIRPORT_TEST" + + The "PURPOSE" field is provided only for NEW and NEWRESOLVE events, and + only if extended events are enabled (see 3.19). Clients MUST accept + purposes not listed above. The purposes above are defined as: + + "DIR_FETCH" -- This stream is generated internally to Tor for + fetching directory information. + "DIR_UPLOAD" -- An internal stream for uploading information to + a directory authority. + "DIRPORT_TEST" -- A stream we're using to test our own directory + port to make sure it's reachable. + "DNS_REQUEST" -- A user-initiated DNS request. + "USER" -- This stream is handling user traffic, OR it's internal + to Tor, but it doesn't match one of the purposes above. + + The "SOCKS_USERNAME" and "SOCKS_PASSWORD" fields indicate the credentials + that were used by a SOCKS client to connect to Tor's SOCKS port and + initiate this stream. (Streams for SOCKS clients connected with different + usernames and/or passwords are isolated on separate circuits if the + IsolateSOCKSAuth flag is active; see Proposal 171.) + + The "CLIENT_PROTOCOL" field indicates the protocol that was used by a client + to initiate this stream. (Streams for clients connected with different + protocols are isolated on separate circuits if the IsolateClientProtocol + flag is active.) Controllers MUST tolerate unrecognized client protocols. + + The "NYM_EPOCH" field indicates the nym epoch that was active when a client + initiated this stream. The epoch increments when the NEWNYM signal is + received. (Streams with different nym epochs are isolated on separate + circuits.) + + The "SESSION_GROUP" field indicates the session group of the listener port + that a client used to initiate this stream. By default, the session group is + different for each listener port, but this can be overridden for a listener + via the "SessionGroup" option in torrc. (Streams with different session + groups are isolated on separate circuits.) + + The "ISO_FIELDS" field indicates the set of STREAM event fields for which + stream isolation is enabled for the listener port that a client used to + initiate this stream. The special values "CLIENTADDR", "CLIENTPORT", + "DESTADDR", and "DESTPORT", if their correspondingly named fields are not + present, refer to the Address and Port components of the "SOURCE_ADDR" and + Target fields. +``` + +<a id="control-spec.txt-4.1.3"></a> + +### OR Connection status changed { #ORCONN } + +The syntax is: + +```text + "650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] [ SP "ID=" ConnID ] CRLF + + ORStatus = "NEW" / "LAUNCHED" / "CONNECTED" / "FAILED" / "CLOSED" + + ; 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, OR + ; Connection is as follows: + "650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON=" + Reason ] [ SP "NCIRCS=" NumCircuits ] CRLF +``` + +NEW is for incoming connections, and LAUNCHED is for outgoing +connections. CONNECTED means the TLS handshake has finished (in +either direction). FAILED means a connection is being closed that +hasn't finished its handshake, and CLOSED is for connections that +have handshaked. + +A LongName or ServerID is specified unless it's a NEW connection, in +which case we don't know what server it is yet, so we use Address:Port. + +If extended events are enabled (see 3.19), optional reason and +circuit counting information is provided for CLOSED and FAILED +events. + +```text + Reason = "MISC" / "DONE" / "CONNECTREFUSED" / + "IDENTITY" / "CONNECTRESET" / "TIMEOUT" / "NOROUTE" / + "IOERROR" / "RESOURCELIMIT" / "PT_MISSING" + + 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 + starting the client-side handshake. + CONNECTED -- The OR connection has been connected and the handshake is + done. + FAILED -- Our attempt to open the OR connection failed. + 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. + IDENTITY -- We connected to the OR, but found that its identity was + not what we expected. + CONNECTRESET -- We got an ECONNRESET or similar IO error from the + connection with the OR. + TIMEOUT -- We got an ETIMEOUT or similar IO error from the connection + with the OR, or we're closing the connection for being idle for too + long. + NOROUTE -- We got an ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or + similar error while connecting to the OR. + IOERROR -- We got some other IO error on our connection to the OR. + RESOURCELIMIT -- We don't have enough operating system resources (file + descriptors, buffers, etc) to connect to the OR. + PT_MISSING -- No pluggable transport was available. + MISC -- The OR connection closed for some other reason. + + [First added ID parameter in 0.2.5.2-alpha] +``` + +<a id="control-spec.txt-4.1.4"></a> + +### Bandwidth used in the last second { #BW } + +The syntax is: + +```text + "650" SP "BW" SP BytesRead SP BytesWritten *(SP Type "=" Num) CRLF + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + Type = "DIR" / "OR" / "EXIT" / "APP" / ... + Num = 1*DIGIT +``` + +BytesRead and BytesWritten are the totals. \[In a future Tor version, +we may also include a breakdown of the connection types that used +bandwidth this second (not implemented yet).\] + +<a id="control-spec.txt-4.1.5"></a> + +### Log messages { #LOG } + +The syntax is: + +"650" SP Severity SP ReplyText CRLF + +or + +"650+" Severity CRLF Data 650 SP "OK" CRLF + +Severity = "DEBUG" / "INFO" / "NOTICE" / "WARN"/ "ERR" + +Some low-level logs may be sent from signal handlers, so their destination +logs must be signal-safe. These low-level logs include backtraces, +logging function errors, and errors in code called by logging functions. +Signal-safe logs are never sent as control port log events. + +Control port message trace debug logs are never sent as control port log +events, to avoid modifying control output when debugging. + +<a id="control-spec.txt-4.1.6"></a> + +### New descriptors available { #NEWDESC } + +This event is generated when new router descriptors (not microdescs or +extrainfos or anything else) are received. + +Syntax: + +```text + "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 + ; is as follows: + "650" SP "NEWDESC" 1*(SP ServerID) CRLF +``` + +<a id="control-spec.txt-4.1.7"></a> + +### New Address mapping { #ADDRMAP } + +These events are generated when a new address mapping is entered in +Tor's address map cache, or when the answer for a RESOLVE command is +found. Entries can be created by a successful or failed DNS lookup, +a successful or failed connection attempt, a RESOLVE command, +a MAPADDRESS command, the AutomapHostsOnResolve feature, or the +TrackHostExits feature. + +Syntax: + +```text + "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry + [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] [SP "CACHED=" Cached] + [SP "STREAMID=" StreamId] CRLF + + NewAddress = Address / "<error>" + Expiry = DQUOTE ISOTime DQUOTE / "NEVER" + + ErrorCode = "yes" / "internal" / "Unable to launch resolve request" + UTCExpiry = DQUOTE IsoTime DQUOTE + + Cached = DQUOTE "YES" DQUOTE / DQUOTE "NO" DQUOTE + StreamId = DQUOTE StreamId DQUOTE +``` + +Error and UTCExpiry are only provided if extended events are enabled. +The values for Error are mostly useless. Future values will be +chosen to match 1\*(ALNUM / "\_"); the "Unable to launch resolve request" +value is a bug in Tor before 0.2.4.7-alpha. + +Expiry is expressed as the local time (rather than UTC). This is a bug, +left in for backward compatibility; new code should look at UTCExpiry +instead. (If Expiry is "NEVER", UTCExpiry is omitted.) + +Cached indicates whether the mapping will be stored until it expires, or if +it is just a notification in response to a RESOLVE command. + +StreamId is the global stream identifier of the stream or circuit from which +the address was resolved. + +<a id="control-spec.txt-4.1.8"></a> + +### Descriptors uploaded to us in our role as authoritative dirserver { #AUTHDIR_NEWDESCS} + +\[NOTE: This feature was removed in Tor 0.3.2.1-alpha.\] + +Tor generates this event when it's a directory authority, and +somebody has just uploaded a server descriptor. + +Syntax: + +```text + "650" "+" "AUTHDIR_NEWDESCS" CRLF Action CRLF Message CRLF + Descriptor CRLF "." CRLF "650" SP "OK" CRLF + Action = "ACCEPTED" / "DROPPED" / "REJECTED" + Message = Text +``` + +The Descriptor field is the text of the server descriptor; the Action +field is "ACCEPTED" if we're accepting the descriptor as the new +best valid descriptor for its router, "REJECTED" if we aren't taking +the descriptor and we're complaining to the uploading relay about +it, and "DROPPED" if we decide to drop the descriptor without +complaining. The Message field is a human-readable string +explaining why we chose the Action. (It doesn't contain newlines.) + +<a id="control-spec.txt-4.1.9"></a> + +### Our descriptor changed { #DESCCHANGED } + +Syntax: + +"650" SP "DESCCHANGED" CRLF + +\[First added in 0.1.2.2-alpha.\] + +<a id="control-spec.txt-4.1.10"></a> + +### Status events { #STATUS } + +Status events (STATUS_GENERAL, STATUS_CLIENT, and STATUS_SERVER) are sent +based on occurrences in the Tor process pertaining to the general state of +the program. Generally, they correspond to log messages of severity Notice +or higher. They differ from log messages in that their format is a +specified interface. + +Syntax: + +```text + "650" SP StatusType SP StatusSeverity SP StatusAction + [SP StatusArguments] CRLF + + StatusType = "STATUS_GENERAL" / "STATUS_CLIENT" / "STATUS_SERVER" + StatusSeverity = "NOTICE" / "WARN" / "ERR" + StatusAction = 1*ALPHA + StatusArguments = StatusArgument *(SP StatusArgument) + StatusArgument = StatusKeyword '=' StatusValue + StatusKeyword = 1*(ALNUM / "_") + StatusValue = 1*(ALNUM / '_') / QuotedString + + StatusAction is a string, and StatusArguments is a series of + keyword=value pairs on the same line. Values may be space-terminated + strings, or quoted strings. + + These events are always produced with EXTENDED_EVENTS and + VERBOSE_NAMES; see the explanations in the USEFEATURE section + for details. + + Controllers MUST tolerate unrecognized actions, MUST tolerate + unrecognized arguments, MUST tolerate missing arguments, and MUST + tolerate arguments that arrive in any order. + + Each event description below is accompanied by a recommendation for + controllers. These recommendations are suggestions only; no controller + is required to implement them. +``` + +Compatibility note: versions of Tor before 0.2.0.22-rc incorrectly +generated "STATUS_SERVER" as "STATUS_SEVER". To be compatible with those +versions, tools should accept both. + +Actions for STATUS_GENERAL events can be as follows: + +```text + CLOCK_JUMPED + "TIME=NUM" + Tor spent enough time without CPU cycles that it has closed all + its circuits and will establish them anew. This typically + happens when a laptop goes to sleep and then wakes up again. It + also happens when the system is swapping so heavily that Tor is + starving. The "time" argument specifies the number of seconds Tor + thinks it was unconscious for (or alternatively, the number of + seconds it went back in time). + + This status event is sent as NOTICE severity normally, but WARN + severity if Tor is acting as a server currently. + + {Recommendation for controller: ignore it, since we don't really + know what the user should do anyway. Hm.} + + DANGEROUS_VERSION + "CURRENT=version" + "REASON=NEW/OBSOLETE/UNRECOMMENDED" + "RECOMMENDED=\"version, version, ...\"" + Tor has found that directory servers don't recommend its version of + the Tor software. RECOMMENDED is a comma-and-space-separated string + of Tor versions that are recommended. REASON is NEW if this version + of Tor is newer than any recommended version, OBSOLETE if + this version of Tor is older than any recommended version, and + UNRECOMMENDED if some recommended versions of Tor are newer and + some are older than this version. (The "OBSOLETE" reason was called + "OLD" from Tor 0.1.2.3-alpha up to and including 0.2.0.12-alpha.) + + {Controllers may want to suggest that the user upgrade OLD or + UNRECOMMENDED versions. NEW versions may be known-insecure, or may + simply be development versions.} + + TOO_MANY_CONNECTIONS + "CURRENT=NUM" + Tor has reached its ulimit -n or whatever the native limit is on file + descriptors or sockets. CURRENT is the number of sockets Tor + currently has open. The user should really do something about + this. The "current" argument shows the number of connections currently + open. + + {Controllers may recommend that the user increase the limit, or + increase it for them. Recommendations should be phrased in an + OS-appropriate way and automated when possible.} + + BUG + "REASON=STRING" + Tor has encountered a situation that its developers never expected, + and the developers would like to learn that it happened. Perhaps + the controller can explain this to the user and encourage her to + file a bug report? + + {Controllers should log bugs, but shouldn't annoy the user in case a + bug appears frequently.} + + CLOCK_SKEW + SKEW="+" / "-" SECONDS + MIN_SKEW="+" / "-" SECONDS. + SOURCE="DIRSERV:" IP ":" Port / + "NETWORKSTATUS:" IP ":" Port / + "OR:" IP ":" Port / + "CONSENSUS" + If "SKEW" is present, it's an estimate of how far we are from the + time declared in the source. (In other words, if we're an hour in + the past, the value is -3600.) "MIN_SKEW" is present, it's a lower + bound. If the source is a DIRSERV, we got the current time from a + connection to a dirserver. If the source is a NETWORKSTATUS, we + decided we're skewed because we got a v2 networkstatus from far in + the future. If the source is OR, the skew comes from a NETINFO + cell from a connection to another relay. If the source is + CONSENSUS, we decided we're skewed because we got a networkstatus + consensus from the future. + + {Tor should send this message to controllers when it thinks the + skew is so high that it will interfere with proper Tor operation. + Controllers shouldn't blindly adjust the clock, since the more + accurate source of skew info (DIRSERV) is currently + unauthenticated.} + + BAD_LIBEVENT + "METHOD=" libevent method + "VERSION=" libevent version + "BADNESS=" "BROKEN" / "BUGGY" / "SLOW" + "RECOVERED=" "NO" / "YES" + Tor knows about bugs in using the configured event method in this + version of libevent. "BROKEN" libevents won't work at all; + "BUGGY" libevents might work okay; "SLOW" libevents will work + fine, but not quickly. If "RECOVERED" is YES, Tor managed to + switch to a more reliable (but probably slower!) libevent method. + + {Controllers may want to warn the user if this event occurs, though + generally it's the fault of whoever built the Tor binary and there's + not much the user can do besides upgrade libevent or upgrade the + binary.} + + DIR_ALL_UNREACHABLE + Tor believes that none of the known directory servers are + reachable -- this is most likely because the local network is + down or otherwise not working, and might help to explain for the + user why Tor appears to be broken. + + {Controllers may want to warn the user if this event occurs; further + action is generally not possible.} + + Actions for STATUS_CLIENT events can be as follows: + + BOOTSTRAP + "PROGRESS=" num + "TAG=" Keyword + "SUMMARY=" String + ["WARNING=" String] + ["REASON=" Keyword] + ["COUNT=" num] + ["RECOMMENDATION=" Keyword] + ["HOST=" QuotedString] + ["HOSTADDR=" QuotedString] + + Tor has made some progress at establishing a connection to the + Tor network, fetching directory information, or making its first + circuit; or it has encountered a problem while bootstrapping. This + status event is especially useful for users with slow connections + or with connectivity problems. + + "Progress" gives a number between 0 and 100 for how far through + the bootstrapping process we are. "Summary" is a string that can + be displayed to the user to describe the *next* task that Tor + will tackle, i.e., the task it is working on after sending the + status event. "Tag" is a string that controllers can use to + recognize bootstrap phases, if they want to do something smarter + than just blindly displaying the summary string; see Section 5 + for the current tags that Tor issues. + + The StatusSeverity describes whether this is a normal bootstrap + phase (severity notice) or an indication of a bootstrapping + problem (severity warn). + + For bootstrap problems, we include the same progress, tag, and + summary values as we would for a normal bootstrap event, but we + also include "warning", "reason", "count", and "recommendation" + key/value combos. The "count" number tells how many bootstrap + problems there have been so far at this phase. The "reason" + string lists one of the reasons allowed in the ORCONN event. The + "warning" argument string with any hints Tor has to offer about + why it's having troubles bootstrapping. + + The "reason" values are long-term-stable controller-facing tags to + identify particular issues in a bootstrapping step. The warning + strings, on the other hand, are human-readable. Controllers + SHOULD NOT rely on the format of any warning string. Currently + the possible values for "recommendation" are either "ignore" or + "warn" -- if ignore, the controller can accumulate the string in + a pile of problems to show the user if the user asks; if warn, + the controller should alert the user that Tor is pretty sure + there's a bootstrapping problem. + + The "host" value is the identity digest (in hex) of the node we're + trying to connect to; the "hostaddr" is an address:port combination, + where 'address' is an ipv4 or ipv6 address. + + Currently Tor uses recommendation=ignore for the first + nine bootstrap problem reports for a given phase, and then + uses recommendation=warn for subsequent problems at that + phase. Hopefully this is a good balance between tolerating + occasional errors and reporting serious problems quickly. + + ENOUGH_DIR_INFO + Tor now knows enough network-status documents and enough server + descriptors that it's going to start trying to build circuits now. + [Newer versions of Tor (0.2.6.2-alpha and later): + If the consensus contains Exits (the typical case), Tor will build + both exit and internal circuits. If not, Tor will only build internal + circuits.] + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to tell them so.} + + NOT_ENOUGH_DIR_INFO + We discarded expired statuses and server descriptors to fall + below the desired threshold of directory information. We won't + try to build any circuits until ENOUGH_DIR_INFO occurs again. + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to tell them so.} + + CIRCUIT_ESTABLISHED + Tor is able to establish circuits for client use. This event will + only be sent if we just built a circuit that changed our mind -- + that is, prior to this event we didn't know whether we could + establish circuits. + + {Suggested use: controllers can notify their users that Tor is + ready for use as a client once they see this status event. [Perhaps + controllers should also have a timeout if too much time passes and + this event hasn't arrived, to give tips on how to troubleshoot. + On the other hand, hopefully Tor will send further status events + if it can identify the problem.]} + + CIRCUIT_NOT_ESTABLISHED + "REASON=" "EXTERNAL_ADDRESS" / "DIR_ALL_UNREACHABLE" / "CLOCK_JUMPED" + We are no longer confident that we can build circuits. The "reason" + keyword provides an explanation: which other status event type caused + our lack of confidence. + + {Controllers may want to use this event to decide when to indicate + progress to their users, but should not interrupt the user's browsing + to do so.} + [Note: only REASON=CLOCK_JUMPED is implemented currently.] + + CONSENSUS_ARRIVED + Tor has received and validated a new consensus networkstatus. + (This event can be delayed a little while after the consensus + is received, if Tor needs to fetch certificates.) + + DANGEROUS_PORT + "PORT=" port + "RESULT=" "REJECT" / "WARN" + A stream was initiated to a port that's commonly used for + vulnerable-plaintext protocols. If the Result is "reject", we + refused the connection; whereas if it's "warn", we allowed it. + + {Controllers should warn their users when this occurs, unless they + happen to know that the application using Tor is in fact doing so + correctly (e.g., because it is part of a distributed bundle). They + might also want some sort of interface to let the user configure + their RejectPlaintextPorts and WarnPlaintextPorts config options.} + + DANGEROUS_SOCKS + "PROTOCOL=" "SOCKS4" / "SOCKS5" + "ADDRESS=" IP:port + A connection was made to Tor's SOCKS port using one of the SOCKS + approaches that doesn't support hostnames -- only raw IP addresses. + If the client application got this address from gethostbyname(), + it may be leaking target addresses via DNS. + + {Controllers should warn their users when this occurs, unless they + happen to know that the application using Tor is in fact doing so + correctly (e.g., because it is part of a distributed bundle).} + + SOCKS_UNKNOWN_PROTOCOL + "DATA=string" + A connection was made to Tor's SOCKS port that tried to use it + for something other than the SOCKS protocol. Perhaps the user is + using Tor as an HTTP proxy? The DATA is the first few characters + sent to Tor on the SOCKS port. + + {Controllers may want to warn their users when this occurs: it + indicates a misconfigured application.} + + SOCKS_BAD_HOSTNAME + "HOSTNAME=QuotedString" + Some application gave us a funny-looking hostname. Perhaps + it is broken? In any case it won't work with Tor and the user + should know. + + {Controllers may want to warn their users when this occurs: it + usually indicates a misconfigured application.} + + Actions for STATUS_SERVER can be as follows: + + EXTERNAL_ADDRESS + "ADDRESS=IP" + "HOSTNAME=NAME" + "METHOD=CONFIGURED/CONFIGURED_ORPORT/DIRSERV/RESOLVED/ + INTERFACE/GETHOSTNAME" + Our best idea for our externally visible IP has changed to 'IP'. If + 'HOSTNAME' is present, we got the new IP by resolving 'NAME'. If the + method is 'CONFIGURED', the IP was given verbatim as the Address + configuration option. If the method is 'CONFIGURED_ORPORT', the IP was + given verbatim in the ORPort configuration option. If the method is + 'RESOLVED', we resolved the Address configuration option to get the IP. + If the method is 'GETHOSTNAME', we resolved our hostname to get the IP. + If the method is 'INTERFACE', we got the address of one of our network + interfaces to get the IP. If the method is 'DIRSERV', a directory + server told us a guess for what our IP might be. + + {Controllers may want to record this info and display it to the user.} + + CHECKING_REACHABILITY + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We're going to start testing the reachability of our external OR port + or directory port. + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + REACHABILITY_SUCCEEDED + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We successfully verified the reachability of our external OR port or + directory port (depending on which of ORADDRESS or DIRADDRESS is + given.) + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + GOOD_SERVER_DESCRIPTOR + We successfully uploaded our server descriptor to at least one + of the directory authorities, with no complaints. + + {Originally, the goal of this event was to declare "every authority + has accepted the descriptor, so there will be no complaints + about it." But since some authorities might be offline, it's + harder to get certainty than we had thought. As such, this event + is equivalent to ACCEPTED_SERVER_DESCRIPTOR below. Controllers + should just look at ACCEPTED_SERVER_DESCRIPTOR and should ignore + this event for now.} + + SERVER_DESCRIPTOR_STATUS + "STATUS=" "LISTED" / "UNLISTED" + We just got a new networkstatus consensus, and whether we're in + it or not in it has changed. Specifically, status is "listed" + if we're listed in it but previous to this point we didn't know + we were listed in a consensus; and status is "unlisted" if we + thought we should have been listed in it (e.g. we were listed in + the last one), but we're not. + + {Moving from listed to unlisted is not necessarily cause for + alarm. The relay might have failed a few reachability tests, + or the Internet might have had some routing problems. So this + feature is mainly to let relay operators know when their relay + has successfully been listed in the consensus.} + + [Not implemented yet. We should do this in 0.2.2.x. -RD] + + NAMESERVER_STATUS + "NS=addr" + "STATUS=" "UP" / "DOWN" + "ERR=" message + One of our nameservers has changed status. + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + NAMESERVER_ALL_DOWN + All of our nameservers have gone down. + + {This is a problem; if it happens often without the nameservers + coming up again, the user needs to configure more or better + nameservers.} + + DNS_HIJACKED + Our DNS provider is providing an address when it should be saying + "NOTFOUND"; Tor will treat the address as a synonym for "NOTFOUND". + + {This is an annoyance; controllers may want to tell admins that their + DNS provider is not to be trusted.} + + DNS_USELESS + Our DNS provider is giving a hijacked address instead of well-known + websites; Tor will not try to be an exit node. + + {Controllers could warn the admin if the relay is running as an + exit node: the admin needs to configure a good DNS server. + Alternatively, this happens a lot in some restrictive environments + (hotels, universities, coffeeshops) when the user hasn't registered.} + + BAD_SERVER_DESCRIPTOR + "DIRAUTH=addr:port" + "REASON=string" + A directory authority rejected our descriptor. Possible reasons + include malformed descriptors, incorrect keys, highly skewed clocks, + and so on. + + {Controllers should warn the admin, and try to cope if they can.} + + ACCEPTED_SERVER_DESCRIPTOR + "DIRAUTH=addr:port" + A single directory authority accepted our descriptor. + // actually notice + + {This event could affect the controller's idea of server status, but + the controller should not interrupt the user to tell them so.} + + REACHABILITY_FAILED + "ORADDRESS=IP:port" + "DIRADDRESS=IP:port" + We failed to connect to our external OR port or directory port + successfully. + + {This event could affect the controller's idea of server status. The + controller should warn the admin and suggest reasonable steps to take.} + + HIBERNATION_STATUS + "STATUS=" "AWAKE" | "SOFT" | "HARD" + Our bandwidth based accounting status has changed, and we are now + relaying traffic/rejecting new connections/hibernating. + + {This event could affect the controller's idea of server status. The + controller MAY inform the admin, though presumably the accounting was + explicitly enabled for a reason.} + + [This event was added in tor 0.2.9.0-alpha.] +``` + +<a id="control-spec.txt-4.1.11"></a> + +### Our set of guard nodes has changed { #GUARD } + +Syntax: + +```text + "650" SP "GUARD" SP Type SP Name SP Status ... CRLF + Type = "ENTRY" + Name = ServerSpec + (Identifies the guard affected) + Status = "NEW" | "UP" | "DOWN" | "BAD" | "GOOD" | "DROPPED" +``` + +The ENTRY type indicates a guard used for connections to the Tor +network. + +The Status values are: + +```text + "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 + no longer consider it to be a member of our guard list. + "UP" -- The guard now seems to be reachable. + "DOWN" -- The guard now seems to be unreachable. + "BAD" -- Because of flags set in the consensus and/or values in the + configuration, this node is now unusable as a guard. + "BAD_L2" -- This layer2 guard has expired or got removed from the + consensus. This node is removed from the layer2 guard set. + "GOOD" -- Because of flags set in the consensus and/or values in the + configuration, this node is now usable as a guard. + + Controllers must accept unrecognized types and unrecognized statuses. +``` + +<a id="control-spec.txt-4.1.12"></a> + +### Network status has changed { #NS } + +Syntax: + +"650" "+" "NS" CRLF 1\*NetworkStatus "." CRLF "650" SP "OK" CRLF + +The event is used whenever our local view of a relay status changes. +This happens when we get a new v3 consensus (in which case the entries +we see are a duplicate of what we see in the NEWCONSENSUS event, +below), but it also happens when we decide to mark a relay as up or +down in our local status, for example based on connection attempts. + +\[First added in 0.1.2.3-alpha\] + +<a id="control-spec.txt-4.1.13"></a> + +### Bandwidth used on an application stream { #STREAM_BW } + +The syntax is: + +```text + "650" SP "STREAM_BW" SP StreamID SP BytesWritten SP BytesRead SP + Time CRLF + BytesWritten = 1*DIGIT + BytesRead = 1*DIGIT + Time = ISOTime2Frac +``` + +BytesWritten and BytesRead are the number of bytes written and read +by the application since the last STREAM_BW event on this stream. + +Note that from Tor's perspective, *reading* a byte on a stream means +that the application *wrote* the byte. That's why the order of "written" +vs "read" is opposite for stream_bw events compared to bw events. + +The Time field is provided only in versions 0.3.2.1-alpha and later. It +records when Tor created the bandwidth event. + +These events are generated about once per second per stream; no events +are generated for streams that have not written or read. These events +apply only to streams entering Tor (such as on a SOCKSPort, TransPort, +or so on). They are not generated for exiting streams. + +<a id="control-spec.txt-4.1.14"></a> + +### Per-country client stats { #CLIENTS_SEEN } + +The syntax is: + +```text + "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary SP + IPVersions CRLF +``` + +We just generated a new summary of which countries we've seen clients +from recently. The controller could display this for the user, e.g. +in their "relay" configuration window, to give them a sense that they +are actually being useful. + +Currently only bridge relays will receive this event, but once we figure +out how to sufficiently aggregate and sanitize the client counts on +main relays, we might start sending these events in other cases too. + +TimeStarted is a quoted string indicating when the reported summary +counts from (in UTCS). + +The CountrySummary keyword has as its argument a comma-separated, +possibly empty set of "countrycode=count" pairs. For example (without +linebreak), +650-CLIENTS_SEEN TimeStarted="2008-12-25 23:50:43" +CountrySummary=us=16,de=8,uk=8 + +The IPVersions keyword has as its argument a comma-separated set of +"protocol-family=count" pairs. For example, +IPVersions=v4=16,v6=40 + +Note that these values are rounded, not exact. The rounding +algorithm is specified in the description of "geoip-client-origins" +in dir-spec.txt. + +<a id="control-spec.txt-4.1.15"></a> + +### New consensus networkstatus has arrived { #NEWCONSENSUS } + +The syntax is: + +```text + "650" "+" "NEWCONSENSUS" CRLF 1*NetworkStatus "." CRLF "650" SP + "OK" CRLF +``` + +A new consensus networkstatus has arrived. We include NS-style lines for +every relay in the consensus. NEWCONSENSUS is a separate event from the +NS event, because the list here represents every usable relay: so any +relay *not* mentioned in this list is implicitly no longer recommended. + +\[First added in 0.2.1.13-alpha\] + +<a id="control-spec.txt-4.1.16"></a> + +### New circuit buildtime has been set { #BUILDTIMEOUT_SET } + +The syntax is: + +```text + "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 + "CLOSE_MS=" CloseTimeout SP "CLOSE_RATE=" CloseRate + CRLF + Type = "COMPUTED" / "RESET" / "SUSPENDED" / "DISCARD" / "RESUME" + Total = Integer count of timeouts stored + Timeout = Integer timeout in milliseconds + Xm = Estimated integer Pareto parameter Xm in milliseconds + Alpha = Estimated floating point Paredo parameter alpha + Quantile = Floating point CDF quantile cutoff point for this timeout + TimeoutRate = Floating point ratio of circuits that timeout + CloseTimeout = How long to keep measurement circs in milliseconds + CloseRate = Floating point ratio of measurement circuits that are closed +``` + +A new circuit build timeout time has been set. If Type is "COMPUTED", +Tor has computed the value based on historical data. If Type is "RESET", +initialization or drastic network changes have caused Tor to reset +the timeout back to the default, to relearn again. If Type is +"SUSPENDED", Tor has detected a loss of network connectivity and has +temporarily changed the timeout value to the default until the network +recovers. If type is "DISCARD", Tor has decided to discard timeout +values that likely happened while the network was down. If type is +"RESUME", Tor has decided to resume timeout calculation. + +The Total value is the count of circuit build times Tor used in +computing this value. It is capped internally at the maximum number +of build times Tor stores (NCIRCUITS_TO_OBSERVE). + +The Timeout itself is provided in milliseconds. Internally, Tor rounds +this value to the nearest second before using it. + +\[First added in 0.2.2.7-alpha\] + +<a id="control-spec.txt-4.1.17"></a> + +### Signal received { #SIGNAL } + +The syntax is: + +"650" SP "SIGNAL" SP Signal CRLF + +Signal = "RELOAD" / "DUMP" / "DEBUG" / "NEWNYM" / "CLEARDNSCACHE" + +A signal has been received and actions taken by Tor. The meaning of each +signal, and the mapping to Unix signals, is as defined in section 3.7. +Future versions of Tor MAY generate signals other than those listed here; +controllers MUST be able to accept them. + +If Tor chose to ignore a signal (such as NEWNYM), this event will not be +sent. Note that some options (like ReloadTorrcOnSIGHUP) may affect the +semantics of the signals here. + +Note that the HALT (SIGTERM) and SHUTDOWN (SIGINT) signals do not currently +generate any event. + +\[First added in 0.2.3.1-alpha\] + +<a id="control-spec.txt-4.1.18"></a> + +### Configuration changed { #CONF_CHANGED } + +The syntax is: + +StartReplyLine \*(MidReplyLine) EndReplyLine + +```text + StartReplyLine = "650-CONF_CHANGED" CRLF + MidReplyLine = "650-" KEYWORD ["=" VALUE] CRLF + EndReplyLine = "650 OK" +``` + +Tor configuration options have changed (such as via a SETCONF or RELOAD +signal). KEYWORD and VALUE specify the configuration option that was changed. +Undefined configuration options contain only the KEYWORD. + +<a id="control-spec.txt-4.1.19"></a> + +### Circuit status changed slightly { #CIRC_MINOR } + +The syntax is: + +```text + "650" SP "CIRC_MINOR" SP CircuitID SP CircEvent [SP Path] + [SP "BUILD_FLAGS=" BuildFlags] [SP "PURPOSE=" Purpose] + [SP "HS_STATE=" HSState] [SP "REND_QUERY=" HSAddress] + [SP "TIME_CREATED=" TimeCreated] + [SP "OLD_PURPOSE=" Purpose [SP "OLD_HS_STATE=" HSState]] CRLF + + CircEvent = + "PURPOSE_CHANGED" / ; circuit purpose or HS-related state changed + "CANNIBALIZED" ; circuit cannibalized + + Clients MUST accept circuit events not listed above. +``` + +The "OLD_PURPOSE" field is provided for both PURPOSE_CHANGED and +CANNIBALIZED events. The "OLD_HS_STATE" field is provided whenever +the "OLD_PURPOSE" field is provided and is a hidden-service-related +purpose. + +Other fields are as specified in section 4.1.1 above. + +\[First added in 0.2.3.11-alpha\] + +<a id="control-spec.txt-4.1.20"></a> + +### Pluggable transport launched { #TRANSPORT_LAUNCHED } + +The syntax is: + +```text + "650" SP "TRANSPORT_LAUNCHED" SP Type SP Name SP TransportAddress SP Port + Type = "server" | "client" + Name = The name of the pluggable transport + TransportAddress = An IPv4 or IPv6 address on which the pluggable + transport is listening for connections + Port = The TCP port on which it is listening for connections. + + A pluggable transport called 'Name' of type 'Type' was launched + successfully and is now listening for connections on 'Address':'Port'. +``` + +<a id="control-spec.txt-4.1.21"></a> + +### Bandwidth used on an OR or DIR or EXIT connection { #CONN_BW } + +The syntax is: + +```text + "650" SP "CONN_BW" SP "ID=" ConnID SP "TYPE=" ConnType + SP "READ=" BytesRead SP "WRITTEN=" BytesWritten CRLF + + ConnType = "OR" / ; Carrying traffic within the tor network. This can + either be our own (client) traffic or traffic we're + relaying within the network. + "DIR" / ; Fetching tor descriptor data, or transmitting + descriptors we're mirroring. + "EXIT" ; Carrying traffic between the tor network and an + external destination. + + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + + Controllers MUST tolerate unrecognized connection types. +``` + +BytesWritten and BytesRead are the number of bytes written and read +by Tor since the last CONN_BW event on this connection. + +These events are generated about once per second per connection; no +events are generated for connections that have not read or written. +These events are only generated if TestingTorNetwork is set. + +\[First added in 0.2.5.2-alpha\] + +<a id="control-spec.txt-4.1.22"></a> + +### Bandwidth used by all streams attached to a circuit { #CIRC_BW } + +The syntax is: + +```text + "650" SP "CIRC_BW" SP "ID=" CircuitID SP "READ=" BytesRead SP + "WRITTEN=" BytesWritten SP "TIME=" Time SP + "DELIVERED_READ=" DeliveredBytesRead SP + "OVERHEAD_READ=" OverheadBytesRead SP + "DELIVERED_WRITTEN=" DeliveredBytesWritten SP + "OVERHEAD_WRITTEN=" OverheadBytesWritten SP + "SS=" SlowStartState SP + "CWND=" CWNDCells SP + "RTT=" RTTMilliseconds SP + "MIN_RTT=" RTTMilliseconds CRLF + BytesRead = 1*DIGIT + BytesWritten = 1*DIGIT + OverheadBytesRead = 1*DIGIT + OverheadBytesWritten = 1*DIGIT + DeliveredBytesRead = 1*DIGIT + DeliveredBytesWritten = 1*DIGIT + SlowStartState = 0 or 1 + CWNDCells = 1*DIGIT + RTTMilliseconds= 1*DIGIT + Time = ISOTime2Frac +``` + +BytesRead and BytesWritten are the number of bytes read and written +on this circuit since the last CIRC_BW event. These bytes have not +necessarily been validated by Tor, and can include invalid cells, +dropped cells, and ignored cells (such as padding cells). These +values include the relay headers, but not circuit headers. + +Circuit data that has been validated and processed by Tor is further +broken down into two categories: delivered relay message bodies, +and overhead. +DeliveredBytesRead and DeliveredBytesWritten are the total +length of the relay message bodies +transmitted since the last CIRC_BW event, not counting relay +cell headers or circuit headers. OverheadBytesRead and +OverheadBytesWritten are the extra unused bytes at the end of each +cell in order for it to be the fixed CELL_LEN bytes long. + +The sum of DeliveredBytesRead and OverheadBytesRead MUST be less than +BytesRead, and the same is true for their written counterparts. This +sum represents the total relay cell bytes on the circuit that +have been validated by Tor, not counting relay headers and cell headers. +Subtracting this sum (plus relay cell headers) from the BytesRead +(or BytesWritten) value gives the byte count that Tor has decided to +reject due to protocol errors, or has otherwise decided to ignore. + +The Time field is provided only in versions 0.3.2.1-alpha and later. It +records when Tor created the bandwidth event. + +The SS, CWND, RTT, and MIN_RTT fields are present only if the circuit +has negotiated congestion control to an onion service or Exit hop (any +intermediate leaky pipe congestion control hops are not examined here). +SS provides an indication if the circuit is in slow start (1), or not (0). +CWND is the size of the congestion window in terms of number of cells. +RTT is the N_EWMA smoothed current RTT value, and MIN_RTT is the minimum +RTT value of the circuit. The SS and CWND fields apply only to the +upstream direction of the circuit. The slow start state and CWND values +of the other endpoint may be different. + +These events are generated about once per second per circuit; no events +are generated for circuits that had no attached stream writing or +reading. + +\[First added in 0.2.5.2-alpha\] + +\[DELIVERED_READ, OVERHEAD_READ, DELIVERED_WRITTEN, and OVERHEAD_WRITTEN +were added in Tor 0.3.4.0-alpha\] + +\[SS, CWND, RTT, and MIN_RTT were added in Tor 0.4.7.5-alpha\] + +<a id="control-spec.txt-4.1.23"></a> + +### Per-circuit cell stats { #CELL_STATS } + +The syntax is: + +```text + "650" SP "CELL_STATS" + [ SP "ID=" CircuitID ] + [ SP "InboundQueue=" QueueID SP "InboundConn=" ConnID ] + [ SP "InboundAdded=" CellsByType ] + [ SP "InboundRemoved=" CellsByType SP + "InboundTime=" MsecByType ] + [ SP "OutboundQueue=" QueueID SP "OutboundConn=" ConnID ] + [ SP "OutboundAdded=" CellsByType ] + [ SP "OutboundRemoved=" CellsByType SP + "OutboundTime=" MsecByType ] CRLF + CellsByType, MsecByType = CellType ":" 1*DIGIT + 0*( "," CellType ":" 1*DIGIT ) + 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 + OutboundTime=create_fast:0,relay_early:0 + 650 CELL_STATS InboundQueue=19403 InboundConn=32 + InboundAdded=relay:1,created_fast:1 + InboundRemoved=relay:1,created_fast:1 + InboundTime=relay:0,created_fast:0 + OutboundQueue=6710 OutboundConn=18 + OutboundAdded=create:1,relay_early:1 + OutboundRemoved=create:1,relay_early:1 + OutboundTime=create:0,relay_early:0 +``` + +ID is the locally unique circuit identifier that is only included if the +circuit originates at this node. + +Inbound and outbound refer to the direction of relay cell flow through the +circuit which is either to origin (inbound) or from origin (outbound). + +InboundQueue and OutboundQueue are identifiers of the inbound and +outbound circuit queues of this circuit. These identifiers are only +unique per OR connection. OutboundQueue is chosen by this node and +matches InboundQueue of the next node in the circuit. + +InboundConn and OutboundConn are locally unique IDs of inbound and +outbound OR connection. OutboundConn does not necessarily match +InboundConn of the next node in the circuit. + +InboundQueue and InboundConn are not present if the circuit originates +at this node. OutboundQueue and OutboundConn are not present if the +circuit (currently) ends at this node. + +InboundAdded and OutboundAdded are total number of cells by cell type +added to inbound and outbound queues. Only present if at least one cell +was added to a queue. + +InboundRemoved and OutboundRemoved are total number of cells by +cell type processed from inbound and outbound queues. InboundTime and +OutboundTime are total waiting times in milliseconds of all processed +cells by cell type. Only present if at least one cell was removed from +a queue. + +These events are generated about once per second per circuit; no +events are generated for circuits that have not added or processed any +cell. These events are only generated if TestingTorNetwork is set. + +\[First added in 0.2.5.2-alpha\] + +<a id="control-spec.txt-4.1.24"></a> + +### Token buckets refilled { #TB_EMPTY } + +The syntax is: + +```text + "650" SP "TB_EMPTY" SP BucketName [ SP "ID=" ConnID ] SP + "READ=" ReadBucketEmpty SP "WRITTEN=" WriteBucketEmpty SP + "LAST=" LastRefill CRLF + + BucketName = "GLOBAL" / "RELAY" / "ORCONN" + ReadBucketEmpty = 1*DIGIT + WriteBucketEmpty = 1*DIGIT + 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 +``` + +This event is generated when refilling a previously empty token +bucket. BucketNames "GLOBAL" and "RELAY" keywords are used for the +global or relay token buckets, BucketName "ORCONN" is used for the +token buckets of an OR connection. Controllers MUST tolerate +unrecognized bucket names. + +ConnID is only included if the BucketName is "ORCONN". + +If both global and relay buckets and/or the buckets of one or more OR +connections run out of tokens at the same time, multiple separate +events are generated. + +ReadBucketEmpty (WriteBucketEmpty) is the time in millis that the read +(write) bucket was empty since the last refill. LastRefill is the +time in millis since the last refill. + +If a bucket went negative and if refilling tokens didn't make it go +positive again, there will be multiple consecutive TB_EMPTY events for +each refill interval during which the bucket contained zero tokens or +less. In such a case, ReadBucketEmpty or WriteBucketEmpty are capped +at LastRefill in order not to report empty times more than once. + +These events are only generated if TestingTorNetwork is set. + +\[First added in 0.2.5.2-alpha\] + +<a id="control-spec.txt-4.1.25"></a> + +### HiddenService descriptors { #HS_DESC } + +The syntax is: + +```text + "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir + [SP DescriptorID] [SP "REASON=" Reason] [SP "REPLICA=" Replica] + [SP "HSDIR_INDEX=" HSDirIndex] + + Action = "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" / + "FAILED" / "CREATED" + HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN" + AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN" + HsDir = LongName / Fingerprint / "UNKNOWN" + DescriptorID = 32*Base32Character / 43*Base64Character + Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" / + "UNEXPECTED" / "QUERY_NO_HSDIR" / "QUERY_RATE_LIMITED" + Replica = 1*DIGIT + HSDirIndex = 64*HEXDIG + + These events will be triggered when required HiddenService descriptor is + not found in the cache and a fetch or upload with the network is performed. + + If the fetch was triggered with only a DescriptorID (using the HSFETCH + command for instance), the HSAddress only appears in the Action=RECEIVED + since there is no way to know the HSAddress from the DescriptorID thus + the value will be "UNKNOWN". + + If we already had the v0 descriptor, the newly fetched v2 descriptor + will be ignored and a "HS_DESC" event with "IGNORE" action will be + generated. + + For HsDir, LongName is always preferred. If HsDir cannot be found in node + list at the time event is sent, Fingerprint will be used instead. + + If Action is "FAILED", Tor SHOULD send Reason field as well. Possible + values of Reason are: + - "BAD_DESC" - descriptor was retrieved, but found to be unparsable. + - "QUERY_REJECTED" - query was rejected by HS directory. + - "UPLOAD_REJECTED" - descriptor was rejected by HS directory. + - "NOT_FOUND" - HS descriptor with given identifier was not found. + - "UNEXPECTED" - nature of failure is unknown. + - "QUERY_NO_HSDIR" - No suitable HSDir were found for the query. + - "QUERY_RATE_LIMITED" - query for this service is rate-limited + + For "QUERY_NO_HSDIR" or "QUERY_RATE_LIMITED", the HsDir will be set to + "UNKNOWN" which was introduced in tor 0.3.1.0-alpha and 0.4.1.0-alpha + respectively. + + If Action is "CREATED", Tor SHOULD send Replica field as well. The Replica + field contains the replica number of the generated descriptor. The Replica + number is specified in rend-spec.txt section 1.3 and determines the + descriptor ID of the descriptor. + + For hidden service v3, the following applies: + + The "HSDIR_INDEX=" is an optional field that is only for version 3 + which contains the computed index of the HsDir the descriptor was + uploaded to or fetched from. + + The "DescriptorID" key is the descriptor blinded key used for the index + value at the "HsDir". + + The "REPLICA=" field is not used for the "CREATED" event because v3 + doesn't use the replica number in the descriptor ID computation. + + Because client authentication is not yet implemented, the "AuthType" + field is always "NO_AUTH". + + [HS v3 support added 0.3.3.1-alpha] +``` + +<a id="control-spec.txt-4.1.26"></a> + +### HiddenService descriptors content { #HS_DESC_CONTENT } + +The syntax is: + +```text + "650" "+" "HS_DESC_CONTENT" SP HSAddress SP DescId SP HsDir CRLF + Descriptor CRLF "." CRLF "650" SP "OK" CRLF + + HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN" + DescId = 32*Base32Character / 32*Base64Character + HsDir = LongName / "UNKNOWN" + Descriptor = The text of the descriptor formatted as specified in + rend-spec.txt section 1.3 (v2) or rend-spec-v3.txt + section 2.4 (v3) or empty string on failure. +``` + +This event is triggered when a successfully fetched HS descriptor is +received. The text of that descriptor is then replied. If the HS_DESC +event is enabled, it is replied just after the RECEIVED action. + +If a fetch fails, the Descriptor is an empty string and HSAddress is set +to "UNKNOWN". The HS_DESC event should be used to get more information on +the failed request. + +If the fetch fails for the QUERY_NO_HSDIR or QUERY_RATE_LIMITED reason from +the HS_DESC event, the HsDir is set to "UNKNOWN". This was introduced in +0.3.1.0-alpha and 0.4.1.0-alpha respectively. + +It's expected to receive a reply relatively fast as in it's the time it +takes to fetch something over the Tor network. This can be between a +couple of seconds up to 60 seconds (not a hard limit). But, in any cases, +this event will reply either the descriptor's content or an empty one. + +\[HS_DESC_CONTENT was added in Tor 0.2.7.1-alpha\] +\[HS v3 support added 0.3.3.1-alpha\] + +<a id="control-spec.txt-4.1.27"></a> + +### Network liveness has changed { #NETWORK_LIVENESS } + +Syntax: + +```text + "650" SP "NETWORK_LIVENESS" SP Status CRLF + Status = "UP" / ; The network now seems to be reachable. + "DOWN" / ; The network now seems to be unreachable. + + Controllers MUST tolerate unrecognized status types. + + [NETWORK_LIVENESS was added in Tor 0.2.7.2-alpha] +``` + +<a id="control-spec.txt-4.1.28"></a> + +### Pluggable Transport Logs { #PT_LOG } + +Syntax: + +"650" SP "PT_LOG" SP PT=Program SP Message + +```text + Program = The program path as defined in the *TransportPlugin + configuration option. Tor accepts relative and full path. + Message = The log message that the PT sends back to the tor parent + process minus the "LOG" string prefix. Formatted as + specified in pt-spec.txt section "3.3.4. Pluggable + Transport Log Message". + + This event is triggered when tor receives a log message from the PT. + + Example: + + PT (obfs4): LOG SEVERITY=debug MESSAGE="Connected to bridge A" + + the resulting control port event would be: + + Tor: 650 PT_LOG PT=/usr/bin/obs4proxy SEVERITY=debug MESSAGE="Connected to bridge A" + + [PT_LOG was added in Tor 0.4.0.1-alpha] +``` + +<a id="control-spec.txt-4.1.29"></a> + +### Pluggable Transport Status { #PT_STATUS } + +Syntax: + +"650" SP "PT_STATUS" SP PT=Program SP TRANSPORT=Transport SP Message + +```text + Program = The program path as defined in the *TransportPlugin + configuration option. Tor accepts relative and full path. + Transport = This value indicates a hint on what the PT is such as the + name or the protocol used for instance. + Message = The status message that the PT sends back to the tor parent + process minus the "STATUS" string prefix. Formatted as + specified in pt-spec.txt section "3.3.5 Pluggable + Transport Status Message". + + This event is triggered when tor receives a log message from the PT. + + Example: + + PT (obfs4): STATUS TRANSPORT=obfs4 CONNECT=Success + + the resulting control port event would be: + + Tor: 650 PT_STATUS PT=/usr/bin/obs4proxy TRANSPORT=obfs4 CONNECT=Success + + [PT_STATUS was added in Tor 0.4.0.1-alpha] +``` |