From 9a53e606a00233e433e2fa9ddad3b5ad49432fe2 Mon Sep 17 00:00:00 2001 From: David Goulet Date: Tue, 7 Nov 2017 14:48:35 -0500 Subject: prop284: dos2unix the proposal Signed-off-by: David Goulet --- proposals/284-hsv3-control-port.txt | 336 ++++++++++++++++++------------------ 1 file changed, 168 insertions(+), 168 deletions(-) (limited to 'proposals/284-hsv3-control-port.txt') diff --git a/proposals/284-hsv3-control-port.txt b/proposals/284-hsv3-control-port.txt index 0bee081..f2d03f6 100644 --- a/proposals/284-hsv3-control-port.txt +++ b/proposals/284-hsv3-control-port.txt @@ -1,168 +1,168 @@ -Filename: 284-hsv3-control-port.txt -Title: Hidden Service v3 Control Port -Author: David Goulet -Created: 02-November-2017 -Status: Open - -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 - - No change. This command can support v3 hidden service without changes. - -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. - - New "KeyBlob" value to support the new "ED25519-V3", if specified, will - generate a new ed25519 private key. - - Because client authentication is not yet implemented, the "ClientAuth" - field is ignored as well as "Flags=BasicAuth". - -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 / 32*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 32 base64 characters which is - the descriptor blinded key used for the index value at the "HsDir". - - 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" +Filename: 284-hsv3-control-port.txt +Title: Hidden Service v3 Control Port +Author: David Goulet +Created: 02-November-2017 +Status: Open + +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 + + No change. This command can support v3 hidden service without changes. + +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. + + New "KeyBlob" value to support the new "ED25519-V3", if specified, will + generate a new ed25519 private key. + + Because client authentication is not yet implemented, the "ClientAuth" + field is ignored as well as "Flags=BasicAuth". + +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 / 32*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 32 base64 characters which is + the descriptor blinded key used for the index value at the "HsDir". + + 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" -- cgit v1.2.3-54-g00ecf