torproject/torspec
1
0
Fork 0
mirror of https://github.com/torproject/torspec.git synced 2025-02-14 05:28:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge remote branch 'origin/maint-0.2.2'

Browse Source
This commit is contained in:
Nick Mathewson 2010-12-01 12:45:38 -05:00
commit cbdd7b4e5e
1 changed files with 88 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
control-spec.txt
View File

@ -96,32 +96,35 @@
; followed by the ASCII Linefeed character (decimal value 10)."
CRLF = CR LF
; Identifiers for servers.
ServerID = Nickname / Fingerprint
Nickname = 1*19 NicknameChar
NicknameChar = "a"-"z" / "A"-"Z" / "0" - "9"
Fingerprint = "$" 40*HEXDIG
; A "=" indicates that the given nickname is canonical; a "~" indicates
; that the given nickname is not canonical. If no nickname is given at
; all, Tor does not even have a guess for what this router calls itself.
LongName = Fingerprint [ ( "=" / "~" ) Nickname ]
; How a controller tells Tor about a particular OR. There are four
; possible formats:
; $Digest -- The router whose identity key hashes to the given digest.
; $Fingerprint -- The router whose identity key hashes to the fingerprint.
; This is the preferred way to refer to an OR.
; $Digest~Name -- The router whose identity key hashes to the given
; digest, but only if the router has the given nickname.
; $Digest=Name -- The router whose identity key hashes to the given
; digest, but only if the router is Named and has the given
; $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.
; Name -- The Named router with the given nickname, or, if no such
; 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 ]
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
@ -477,25 +480,36 @@
StreamID SP StreamStatus SP CircID SP Target CRLF
"orconn-status"
A series of lines as for an OR connection status event. Each is of the
form:
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.
Each is of the form:
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
Status-with-time = ("unlisted") SP ISOTime
Status = ("up" / "never-connected" / "down" /
"unusable" / "unlisted" )
ServerID2 = Nickname / 40*HEXDIG
[From 0.1.1.4-alpha to 0.1.1.10-alpha, this was called "helper-nodes".
Tor still supports calling it that for now, but support will be
removed in 0.1.3.x.]
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. Current Tors never generate 'down'.]
@ -770,46 +784,47 @@
3.19. 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:
"USEFEATURE" *(SP FeatureName) CRLF
FeatureName = 1*(ALPHA / DIGIT / "_" / "-")
Sometimes extensions to the controller protocol break compatibility with
older controllers. In this case, whenever possible, the extensions are
first included in Tor disabled by default, and only enabled on a given
controller connection when the "USEFEATURE" command is given. Once a
"USEFEATURE" command is given, it applies to all subsequent interactions on
the same connection; to disable an enabled feature, a new controller
connection must be opened.
This is a forward-compatibility mechanism; each feature will eventually
become a regular part of the control protocol in some future version of Tor.
Tor will ignore a request to use any feature that is already on by default.
Tor will give a "552" error if any requested feature is not recognized.
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
Same as passing 'EXTENDED' to SETEVENTS; this is the preferred way to
request the extended event syntax.
This feature was first used in 0.1.2.3-alpha. It is always-on in
Tor 0.2.2.1-alpha and later.
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
Instead of ServerID as specified above, the controller should
identify ORs by LongName in events and GETINFO results. This format is
strictly more informative: rather than including Nickname for
known Named routers and Fingerprint for unknown or unNamed routers, the
LongName format includes a Fingerprint, an indication of Named status,
and a Nickname (if one is known).
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 will not be always-enabled until at least two stable
releases after 0.1.2.2-alpha, the release where it was first
available. It is always-on in Tor 0.2.2.1-alpha and later.
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.
3.20. RESOLVE
@ -1000,7 +1015,11 @@
"FAILED" / ; circuit closed (was not built)
"CLOSED" ; circuit closed (was built)
Path = ServerID *("," ServerID)
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)
Reason = "NONE" / "TORPROTOCOL" / "INTERNAL" / "REQUESTED" /
"HIBERNATING" / "RESOURCELIMIT" / "CONNECTFAILED" /
@ -1089,19 +1108,26 @@
4.1.3. OR Connection status changed
The syntax is:
"650" SP "ORCONN" SP (ServerID / Target) SP ORStatus [ SP "REASON="
"650" SP "ORCONN" SP (LongName / Target) SP ORStatus [ SP "REASON="
Reason ] [ SP "NCIRCS=" NumCircuits ] 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 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.
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
@ -1138,7 +1164,11 @@
4.1.6. New descriptors available
Syntax:
"650" SP "NEWDESC" 1*(SP ServerID) CRLF
"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
4.1.7. New Address mapping