commit aaf2434acfcb586a2a7bdd99ee2bbe0756f6f97d Author: David Goulet <dgoulet@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@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