``` Filename: 284-hsv3-control-port.txt Title: Hidden Service v3 Control Port Author: David Goulet Created: 02-November-2017 Status: Closed 1. Summary This document extends the hidden service control port events and commands to version 3 (rend-spec-v3.txt). No command nor events are newly added in this document, it only desribes how the current commands and events are extended to support v3. 2. Format The formatting of this document follows section 2 of control-spec.txt. It is split in two sections, the Commands and the Events for hidden service version 3. We define the alphabet of a Base64 encoded value to be: Base64Character = "A"-"Z" / "a"-"z" / "0"-"9" / "+" / "/" For a command or event, if nothing is mentionned, the behavior doesn't change from the control port specification. 3. Specification: 3.1. Commands As specified in the control specification, all commands are case-insensitive but the keywords are case-sensitive. 3.1.1. GETINFO Hidden service commands are: "hs/client/desc/id/" The can be a v3 address without the ".onion" part. The rest is as is. "hs/service/desc/id/" The can be a v3 address without the ".onion" part. The rest is as is. "onions/{current,detached}" No change. This command can support v3 hidden service without changes returning v3 address(es). 3.1.2. HSFETCH The syntax of this command supports both an HSAddress or a versionned descriptor ID. However, for descriptor ID, version 3 doesn't have the same concept as v2 so, for v3 the descriptor ID is the blinded key of a descriptor which is used as an index to query the HSDir: The syntax becomes: "HSFETCH" SP (HSAddress / "v" Version "-" DescId) *[SP "SERVER=" Server] CRLF HSAddress = (16*Base32Character / 56*Base32Character) Version = "2" / "3" DescId = (32*Base32Character / 32*Base64Character) Server = LongName The "HSAddress" key is extended to accept 56 base32 characters which is the format of a version 3 onion address. The "DescId" of the form 32*Base64Character is the descriptor blinded key used as an index to query the directory. It can only be used with "Version=3". 3.1.5. HSPOST To support version 3, the command needs an extra parameter that is the onion address of the given descriptor. With v2, the address could have been deduced from the given descriptor but with v3, this is not possible. In order to fire up the HS_DESC event correctly, we need the address so the request can be linked on the control port. Furthermore, the given descriptor will be validated with the given address and an error will be returned if they are not matching. The syntax becomes: "+HSPOST" *[SP "SERVER=" Server] [SP "HSADDRESS=" HSAddress] CRLF Descriptor CRLF "." CRLF HSAddress = 56*Base32Character The "HSAddress" key is optional and only applies for v3 descriptors. A 513 error is returned if used with v2. 3.1.3. ADD_ONION For this command to support version 3, new values are added but the syntax is unchanged: "ADD_ONION" SP KeyType ":" KeyBlob [SP "Flags=" Flag *("," Flag)] 1*(SP "Port=" VirtPort ["," Target]) *(SP "ClientAuth=" ClientName [":" ClientBlob]) CRLF New "KeyType" value to "ED25519-V3" which identifies the key type to be a v3 ed25519 key. With the KeyType == "ED25519-V3", the "KeyBlob" should be a base64 encoded ed25519 private key. The "NEW:BEST" option will still return a version 2 address as long as the HiddenServiceVersion torrc option default is 2. To ask for a new v3 key, this should be used: "NEW:ED25519-V3". Because client authentication is not yet implemented, the "ClientAuth" field is ignored as well as "Flags=BasicAuth". A 513 error is returned if "ClientAuth" is used with an ED25519-V3 key type. 3.1.4. DEL_ONION The syntax of this command is: "DEL_ONION" SP ServiceID CRLF ServiceID = The Onion Service address without the trailing ".onion" suffix The "ServiceID" can simply be a v3 address. Nothing else changes. 3.2. Events 3.2.1. HS_DESC For this event to support vesrion 3, one optional field and new values are added: "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 / 56*Base32Character / "UNKNOWN" AuthType = "NO_AUTH" / "BASIC_AUTH" / "STEALTH_AUTH" / "UNKNOWN" HsDir = LongName / Fingerprint / "UNKNOWN" DescriptorID = 32*Base32Character / 43*Base64Character Reason = "BAD_DESC" / "QUERY_REJECTED" / "UPLOAD_REJECTED" / "NOT_FOUND" / "UNEXPECTED" / "QUERY_NO_HSDIR" Replica = 1*DIGIT HSDirIndex = 64*HEXDIG 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 "HSAddress" key is extended to accept 56 base32 characters which is the format of a version 3 onion address. The "DescriptorID" key is extended to accept 43 base64 characters which 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". 3.2.2. HS_DESC_CONTENT For this event to support version 3, new values are added but the syntax is unchanged: "650" "+" "HS_DESC_CONTENT" SP HSAddress SP DescId SP HsDir CRLF Descriptor CRLF "." CRLF "650" SP "OK" CRLF 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-v3.txt section 2.4 or empty string on failure. The "HSAddress" key is extended to accept 56 base32 characters which is the format of a version 3 onion address. The "DescriptorID" key is extended to accept 32 base64 characters which is the descriptor blinded key used for the index value at the "HsDir". 3.2.3 CIRC and CIRC_MINOR These circuit events have an optional field named "REND_QUERY" which takes an "HSAddress". This field is extended to support v3 address: HSAddress = 16*Base32Character / 56*Base32Character / "UNKNOWN" ```