[tor-commits] [torspec/master] Add HSFETCH command and HS_DESC_CONTENT to control-spec

[nickm at torproject.org]

commit aaf2434acfcb586a2a7bdd99ee2bbe0756f6f97d
Author: David Goulet <dgoulet at ev0ke.net>
Date:   Thu Feb 12 14:02:05 2015 -0500

    Add HSFETCH command and HS_DESC_CONTENT to control-spec
    
    This adds the HSFETCH command as well as the HS_DESC_CONTENT event to the
    control specification.
    
    The HS_DESC event is also changed a bit to fit the HSFETCH command case.
    
    Ref.: #14847
    
    Signed-off-by: David Goulet <dgoulet at ev0ke.net>
---
 control-spec.txt |   76 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 75 insertions(+), 1 deletion(-)

diff --git a/control-spec.txt b/control-spec.txt
index a88153c..c88968a 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1229,6 +1229,47 @@
 
   [DROPGUARDS was added in Tor 0.2.5.2-alpha.]
 
+3.26. HSFETCH
+
+  The syntax is:
+    "HSFETCH" SP (HSAddress / "v" Version "-" DescId)
+              *[SP "SERVER=" Server] CRLF
+
+    HSAddress = 16*Base32Character
+    Version = 2
+    DescId = 32*Base32Character
+    Server = LongName
+
+  This command launches hidden service descriptor fetch(es) for the given
+  HSAddress or DescId.
+
+  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,
+  it behaves like a normal Tor client descriptor fetch. If one or more
+  Server are given, they are used instead triggering a fetch on each of them
+  in parallel.
+
+  The caching behavior when fetching a descriptor using this command is
+  identical to normal Tor client behavior.
+
+  Details on how to compute a descriptor id (DescId) can be found in
+  rend-spec.txt section 1.3.
+
+  If any values are unrecognized, a 513 error is returned and the command is
+  stopped. On success, Tor replies "250 OK" then Tor MUST eventually follow
+  this with both a HS_DESC and HS_DESC_CONTENT events with the results. If
+  SERVER is specified then events are emitted for each location.
+
+  Examples are:
+     C: HSFETCH v2-gezdgnbvgy3tqolbmjrwizlgm5ugs2tl
+        SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31
+     S: 250 OK
+
+     C: HSFETCH ajkhdsfuygaesfaa
+     S: 250 OK
+
+  [HSFETCH 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
@@ -2523,7 +2564,7 @@
     [SP "REASON=" Reason]
 
     Action =  "REQUESTED" / "RECEIVED" / "IGNORE" / "FAILED"
-    HSAddress = 16*Base32Character
+    HSAddress = 16*Base32Character / "UNKNOWN"
     AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN"
     HsDir = LongName / Fingerprint
     DescriptorID = 32*Base32Character
@@ -2532,6 +2573,11 @@
     These events will be triggerred when required HiddenService descriptor is
     not found in the cache and a fetch from network is performed.
 
+    If the fetch was triggered with only a DescriptorID (using the HSFETCH
+    command for instance), the HSAddress only appears in the Action=RECEIVED
+    since there is no way to know the HSAddress from the DescriptorID thus
+    the value will be "UNKNOWN".
+
     If we already had the v0 descriptor, the newly fected v2 descriptor will be
     ignored and a "HS_DESC" event with "IGNORE" action will be generated.
 
@@ -2545,6 +2591,34 @@
        - "NOT_FOUND" - HS descriptor with given identifier was not found.
        - "UNEXPECTED" - nature of failure is unknown.
 
+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
+
+    HSAddress = 16*Base32Character / "UNKNOWN"
+    DescId = 32*Base32Character
+    HsDir = LongName
+    Descriptor = The text of the descriptor formatted as specified in
+    rend-spec.txt section 1.3 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
+  event is enabled, it is replied just after the RECEIVED action.
+
+  If a fetch fails, the Descriptor is an empty string and HSAddress is set
+  to "UNKNOWN". The HS_DESC event should be used to get more information on
+  the failed request.
+
+  It's expected to receive a reply relatively fast as in it's the time it
+  takes to fetch something over the Tor network. This can be between a
+  couple of seconds up to 60 seconds (not a hard limit). But, in any cases,
+  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]
+
 5. Implementation notes
 
 5.1. Authentication