Hi everyone, Attached is the proposal draft for the hidden service v3 contro port specification. The idea with this proposal is to _only_ extend the current commands and events to v3. Nothing new is added. We can think of more things to add after but for now, I wanted a baseline to start with that is only extending what exists. Any kind of feedbacks is welcome! :) Cheers! David -- Zu3IyL4LcdnKNkQIZqEqaTNUapUEJFdEcN02dPwo5FQ=
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/<ADDR>"
The <ADDR> can be a v3 address without the ".onion" part. The rest is
as is.
"hs/service/desc/id/<ADDR>"
The <ADDR> 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"
Attachment:
signature.asc
Description: PGP signature
_______________________________________________ tor-dev mailing list tor-dev@xxxxxxxxxxxxxxxxxxxx https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev