Implementation notes

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

    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:

     16:660537E3E1CD49996044A3BF558097A981F539FEA2F9DA662B4626C1C2
        ++++++++++++++++**^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           salt                       hashed value
                       indicator

You can generate the salt of a password by calling

           'tor --hash-password <password>'

or by using the example code in the Python and Java controller libraries. To authenticate under this scheme, the controller sends Tor the original secret that was used to generate the password, either as a quoted string or encoded in hexadecimal.

Don't let the buffer get too big

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.

Backward compatibility with v0 control protocol

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.

Tor config options for use by controllers

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

    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.)

Phases from the Bootstrap status event

 [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.

Overview of Bootstrap reporting

Bootstrap phases can be viewed as belonging to one of three stages:

Initial connection to a Tor relay or bridge
Obtaining directory information
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.

Phases in Bootstrap Stage 1

Phase 0: tag=starting summary="Starting"

Tor starts out in this phase.

  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.

  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.

  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.

  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.

  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.

  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.

Phases in Bootstrap Stage 2

  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.

  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.

  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.

 [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.

 [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.]

Phases in Bootstrap Stage 3

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

  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.

 [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.

 [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]

Bootstrap phases reported by older versions of Tor

These phases were reported by Tor older than 0.4.0.x. For newer versions of Tor, see Section 5.5.

 [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"

Phase 20: tag=requesting_status summary="Asking for networkstatus consensus"

Phase 25: tag=loading_status summary="Loading networkstatus consensus"

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"

  Phase 45
  tag=requesting_descriptors summary="Asking for relay descriptors
                                      [ for internal paths]"

 [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]"

 [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.

 [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.

 [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.

 [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.

 [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.]

Tor Specifications