control: Merge prop284 into control-spec.txt

The proposal 284 is now effectively Closed.

Closes #24847

Signed-off-by: David Goulet <dgoulet@torproject.org>

3 files changed, 59 insertions, 17 deletions

diff --git a/control-spec.txt b/control-spec.txt
index e961daa..e085519 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -918,6 +918,7 @@
       returned.
 
       [New in Tor 0.2.7.1-alpha]
+      [HS v3 support added 0.3.3.1-alpha]
 
     "hs/service/desc/id/<ADDR>"
       Prints the content of the hidden service descriptor corresponding to
@@ -930,6 +931,7 @@
       returned.
 
       [New in Tor 0.2.7.2-alpha]
+      [HS v3 support added 0.3.3.1-alpha]
 
     "onions/current"
     "onions/detached"
@@ -941,6 +943,7 @@
       The format of each line is:
          HSAddress
       [New in Tor 0.2.7.1-alpha.]
+      [HS v3 support added 0.3.3.1-alpha]
 
     "network-liveness"
       The string "up" or "down", indicating whether we currently believe the
@@ -1477,13 +1480,14 @@
     "HSFETCH" SP (HSAddress / "v" Version "-" DescId)
               *[SP "SERVER=" Server] CRLF
 
-    HSAddress = 16*Base32Character
-    Version = 2
-    DescId = 32*Base32Character
+    HSAddress = (16*Base32Character / 56*Base32Character)
+    Version = "2" / "3"
+    DescId = (32*Base32Character / 32*Base64Character)
     Server = LongName
 
   This command launches hidden service descriptor fetch(es) for the given
-  HSAddress or DescId.
+  HSAddress or DescId. For v3, "DescId" is the descriptor blinded key used as
+  an index to query the directory. It can only be used with "Version=3".
 
   If a DescId is specified, at least one Server MUST also be provided,
   otherwise a 512 error is returned. If no DescId and Server(s) are specified,
@@ -1511,6 +1515,7 @@
      S: 250 OK
 
   [HSFETCH was added in Tor 0.2.7.1-alpha]
+  [HS v3 support added 0.3.3.1-alpha]
 
 3.27. ADD_ONION
 
@@ -1523,14 +1528,18 @@
 
     KeyType =
      "NEW"     / ; The server should generate a key of algorithm KeyBlob
-     "RSA1024"   ; The server should use the 1024 bit RSA key provided
+     "RSA1024" / ; The server should use the 1024 bit RSA key provided
                    in as KeyBlob
+     "ED25519-V3"; The server should use the ed25519 v3 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")
+     "ED25519-V3"; The server should generate an ed25519 private key
+                   (KeyType == "NEW")
      String      ; A serialized private key (without whitespace)
 
     Flag =
@@ -1612,7 +1621,11 @@
 
   (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.)
+  RSAPrivateKey, with all newlines removed. For a "ED25519-V3" key is a Base64
+  encoded ed25519 private key.)
+
+  (The "NEW:BEST" option obeys the HiddenServiceVersion torrc option default
+  value. Currently it is 2.)
 
   Examples:
      C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80
@@ -1656,6 +1669,7 @@
   [ClientAuth was added in Tor 0.2.9.1-alpha.]
   [NonAnonymous was added in Tor 0.2.9.3-alpha.]
   [MaxStreams and MaxStreamsCloseCircuit were added in Tor 0.2.7.2-alpha]
+  [HS v3 support added 0.3.3.1-alpha]
 
 3.28. DEL_ONION
 
@@ -1682,16 +1696,22 @@
   number of arguments, or a 552 if it doesn't recognize the ServiceID.
 
   [DEL_ONION was added in Tor 0.2.7.1-alpha.]
+  [HS v3 support added 0.3.3.1-alpha]
 
 3.29. HSPOST
 
   The syntax is:
-    "+HSPOST" *[SP "SERVER=" Server] CRLF Descriptor CRLF "." CRLF
+    "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress]
+              CRLF Descriptor CRLF "." CRLF
 
     Server = LongName
+    HSAddress = 56*Base32Character
     Descriptor =  The text of the descriptor formatted as specified
     in rend-spec.txt section 1.3.
 
+  The "HSAddress" key is optional and only applies for v3 descriptors. A 513
+  error is returned if used with v2.
+
   This command launches a hidden service descriptor upload to the specified
   HSDirs. If one or more Server arguments are provided, an upload is triggered
   on each of them in parallel. If no Server options are provided, it behaves
@@ -1712,6 +1732,7 @@
      S: 250 OK
 
   [HSPOST was added in Tor 0.2.7.1-alpha]
+  [HS v3 support added 0.3.3.1-alpha]
 
 4. Replies
 
@@ -1882,7 +1903,7 @@
       EscapedUsername = QuotedString
       EscapedPassword = QuotedString
 
-      HSAddress = 16*Base32Character
+      HSAddress = 16*Base32Character / 56*Base32Character
       Base32Character = ALPHA / "2" / "3" / "4" / "5" / "6" / "7"
 
       TimeCreated = ISOTime2Frac
@@ -3036,16 +3057,18 @@
 
     "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir
              [SP DescriptorID] [SP "REASON=" Reason] [SP "REPLICA=" Replica]
+             [SP "HSDIR_INDEX=" HSDirIndex]
 
     Action =  "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" /
               "FAILED" / "CREATED"
-    HSAddress = 16*Base32Character / "UNKNOWN"
+    HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN"
     AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN"
     HsDir = LongName / Fingerprint / "UNKNOWN"
-    DescriptorID = 32*Base32Character
+    DescriptorID = 32*Base32Character / 43*Base64Character
     Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" /
              "UNEXPECTED" / "QUERY_NO_HSDIR"
     Replica = 1*DIGIT
+    HSDirIndex = 64*HEXDIG
 
     These events will be triggered when required HiddenService descriptor is
     not found in the cache and a fetch or upload with the network is performed.
@@ -3079,18 +3102,36 @@
     number is specified in rend-spec.txt section 1.3 and determines the
     descriptor ID of the descriptor.
 
+    For hidden service v3, the following applies:
+
+       The "HSDIR_INDEX=" is an optional field that is only for version 3
+       which contains the computed index of the HsDir the descriptor was
+       uploaded to or fetched from.
+
+       The "DescriptorID" key is the descriptor blinded key used for the index
+       value at the "HsDir".
+
+       The "REPLICA=" field is not used for the "CREATED" event because v3
+       doesn't use the replica number in the descriptor ID computation.
+
+       Because client authentication is not yet implemented, the "AuthType"
+       field is always "NO_AUTH".
+
+   [HS v3 support added 0.3.3.1-alpha]
+
 4.1.26. HiddenService descriptors content
 
   The syntax is:
 
     "650" "+" "HS_DESC_CONTENT" SP HSAddress SP DescId SP HsDir CRLF
-      Descriptor CRLF "." CRLF "650" SP "OK" CRLF
+               Descriptor CRLF "." CRLF "650" SP "OK" CRLF
 
-    HSAddress = 16*Base32Character / "UNKNOWN"
-    DescId = 32*Base32Character
+    HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN"
+    DescId = 32*Base32Character / 32*Base64Character
     HsDir = LongName / "UNKNOWN"
     Descriptor = The text of the descriptor formatted as specified in
-    rend-spec.txt section 1.3 or empty string on failure.
+                 rend-spec.txt section 1.3 (v2) or rend-spec-v3.txt
+                 section 2.4 (v3) or empty string on failure.
 
   This event is triggered when a successfully fetched HS descriptor is
   received. The text of that descriptor is then replied. If the HS_DESC
@@ -3109,6 +3150,7 @@
   this event will reply either the descriptor's content or an empty one.
 
   [HS_DESC_CONTENT was added in Tor 0.2.7.1-alpha]
+  [HS v3 support added 0.3.3.1-alpha]
 
 4.1.27. Network liveness has changed
 
diff --git a/proposals/000-index.txt b/proposals/000-index.txt
index 8506966..688e2f7 100644
--- a/proposals/000-index.txt
+++ b/proposals/000-index.txt
@@ -204,7 +204,7 @@ Proposals by number:
 281  Downloading microdescriptors in bulk [DRAFT]
 282  Remove "Named" and "Unnamed" handling from consensus voting [OPEN]
 283  Move IPv6 ORPorts from microdescriptors to the microdesc consensus [ACCEPTED]
-284  Hidden Service v3 Control Port [FINISHED]
+284  Hidden Service v3 Control Port [CLOSED]
 285  Directory documents should be standardized as UTF-8 [OPEN]
 286  Controller APIs for hibernation access on mobile [OPEN]
 287  Reduce circuit lifetime without overloading the network [OPEN]
@@ -288,7 +288,6 @@ Proposals by status:
    232  Pluggable Transport through SOCKS proxy [in 0.2.6]
    260  Rendezvous Single Onion Services [in 0.2.9.3-alpha]
    278  Directory Compression Scheme Negotiation [in 0.3.1.1-alpha]
-   284  Hidden Service v3 Control Port
  CLOSED:
    101  Voting on the Tor Directory System [in 0.2.0.x]
    102  Dropping "opt" from the directory format [in 0.2.0.x]
@@ -368,6 +367,7 @@ Proposals by status:
    271  Another algorithm for guard selection [in 0.3.0.1-alpha]
    272  Listed routers should be Valid, Running, and treated as such [in 0.2.9.3-alpha, 0.2.9.4-alpha]
    274  Rotate onion keys less frequently [in 0.3.1.1-alpha]
+   284  Hidden Service v3 Control Port
  SUPERSEDED:
    112  Bring Back Pathlen Coin Weight
    113  Simplifying directory authority administration
diff --git a/proposals/284-hsv3-control-port.txt b/proposals/284-hsv3-control-port.txt
index ee26853..1ff20bb 100644
--- a/proposals/284-hsv3-control-port.txt
+++ b/proposals/284-hsv3-control-port.txt
@@ -2,7 +2,7 @@ Filename: 284-hsv3-control-port.txt
 Title: Hidden Service v3 Control Port
 Author: David Goulet
 Created: 02-November-2017
-Status: Finished
+Status: Closed
 
 1. Summary