commit ba30c1df4a11248c0a6c9b458530a7985ae41fac Author: Donncha O'Cearbhaill donncha@donncha.is Date: Sun Mar 22 18:49:38 2015 +0000

Add control spec entry for HSPOST, and update HS_DESC events. (#3523) --- control-spec.txt | 47 ++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 40 insertions(+), 7 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt index 276490a..8a55e94 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1400,6 +1400,36 @@

[DEL_ONION was added in Tor 0.2.7.1-alpha.]

+3.29. HSPOST + + The syntax is: + "+HSPOST" *[SP "SERVER=" Server] CRLF Descriptor CRLF "." CRLF + + Server = LongName + Descriptor = The text of the descriptor formatted as specified + in rend-spec.txt section 1.3. + + 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 + like a normal HS descriptor upload and will upload to the set of responsible + HS directories. + + If any value is unrecognized, a 552 error is returned and the command is + stopped. If there is an error in parsing the descriptor, the server + must send a "554 Invalid descriptor" reply. + + On success, Tor replies "250 OK" then Tor MUST eventually follow + this with a HS_DESC event with the result for each upload location. + + Examples are: + C: +HSPOST SERVER=9695DFC35FFEB861329B9F1AB04C46397020CE31 + [DESCRIPTOR] + . + S: 250 OK + + [HSPOST 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 @@ -2690,18 +2720,20 @@

The syntax is:

- "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir [SP DescriptorID] - [SP "REASON=" Reason] + "650" SP "HS_DESC" SP Action SP HSAddress SP AuthType SP HsDir + [SP DescriptorID] [SP "REASON=" Reason]

- Action = "REQUESTED" / "RECEIVED" / "IGNORE" / "FAILED" - HSAddress = 16*Base32Character / "UNKNOWN" + Action = "REQUESTED" / "UPLOAD" / "RECEIVED" / "UPLOADED" / "IGNORE" / + "FAILED" + HSAddress = 16*Base32Character AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN" HsDir = LongName / Fingerprint DescriptorID = 32*Base32Character - Reason = "BAD_DESC" / "QUERY_REJECTED" / "NOT_FOUND" / "UNEXPECTED" + Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" / + "UNEXPECTED"

These events will be triggerred when required HiddenService descriptor is - not found in the cache and a fetch from network is performed. + not found in the cache and a fetch or upload with the 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 @@ -2714,10 +2746,11 @@ For HsDir, LongName is always prefered. If HsDir cannot be found in node list at the time event is sent, Fingerprint will be used instead.

- If Action is "FAILED", Tor SHOULD send Reason field as well. Possible + If Action is "FAILED", Tor SHOULD send Reason field as well. Possible values of Reason are: - "BAD_DESC" - descriptor was retrieved, but found to be unparsable. - "QUERY_REJECTED" - query was rejected by HS directory. + - "UPLOAD_REJECTED" - descriptor was rejected by HS directory. - "NOT_FOUND" - HS descriptor with given identifier was not found. - "UNEXPECTED" - nature of failure is unknown.