commit b9302fb0aa2d5b635002bc5bf50219d42b90d9d7
Author: Nick Mathewson <nickm(a)torproject.org>
Date: Mon Feb 23 10:18:51 2015 -0500
Document stupidity of our broken QuotedStrings.
---
control-spec.txt | 39 +++++++++++++++++++++++++++++++++------
1 file changed, 33 insertions(+), 6 deletions(-)
diff --git a/control-spec.txt b/control-spec.txt
index d8d3dcd..1c90967 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -108,6 +108,36 @@
accept LF. Tor, however, MUST NOT generate LF instead of CRLF.
Controllers SHOULD always send CRLF.
+2.1.1. 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 reflect 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:
+
+ 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 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.)
+
2.2. Commands from controller to Tor
Command = Keyword OptArguments CRLF / "+" Keyword OptArguments CRLF CmdData
@@ -1426,12 +1456,9 @@
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. Special characters sent by the SOCKS client are
- escaped, namely \\, \", \', \r, \n, \t, and byte values > 127 printed as
- octal values, such as \377 for character 255. (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.)
+ 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.)
The "REND_QUERY" field is provided only for hidden-service-related
circuits, and only in versions 0.2.3.11-alpha and later. Clients