commit f5ff36912003ae595fb125ad4c4450cc2468ddda Author: Yawning Angel yawning@torproject.org Date: Sat Apr 25 08:03:05 2015 +0000

Add #6411 changes to the spec. --- control-spec.txt | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+)

diff --git a/control-spec.txt b/control-spec.txt index c961a2d..276490a 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -843,6 +843,17 @@

[New in Tor 0.2.7.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.] + Examples: C: GETINFO version desc/name/moria1 S: 250+desc/name/moria= @@ -1282,6 +1293,113 @@

[HSFETCH was added in Tor 0.2.7.1-alpha]

+3.27. ADD_ONION + + The syntax is: + "ADD_ONION" SP KeyType ":" KeyBlob + [SP "Flags=" Flag *("," Flag)] + 1*(SP "Port=" VirtPort ["," Target]) 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 + + KeyBlob = + "BEST" / ; The server should generate a key using the "best" + supported algorithm (KeyType == "NEW") + "RSA1024" / ; The server should generate a 1024 bit RSA key + (KeyType == "NEW") + 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. + + 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). + + The server reply format is: + "250-ServiceID=" ServiceID CRLF + ["250-PrivateKey=" KeyType ":" KeyBlob 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). + + 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.) + + Examples: + C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80 + S: 250-ServiceID=exampleonion1234 + 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=testonion1234567 + S: 250-PrivateKey=RSA1024:[Blob Redacted] + S: 250 OK + + [ADD_ONION was added in Tor 0.2.7.1-alpha.] + +3.28. DEL_ONION + + The syntax is: + "DEL_ONION" SP ServiceID CRLF + + 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.] + 4. Replies

Reply codes follow the same 3-character format as used by SMTP, with the