[tor-commits] [torspec/master] Add #6411 changes to the spec.

[nickm at torproject.org]

commit f5ff36912003ae595fb125ad4c4450cc2468ddda
Author: Yawning Angel <yawning at 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