diff options
Diffstat (limited to 'control-spec.txt')
| -rw-r--r-- | control-spec.txt | 131 |
1 files changed, 105 insertions, 26 deletions
diff --git a/control-spec.txt b/control-spec.txt index ab164ea..11f62ba 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -811,6 +811,7 @@ if unknown "dir/status-vote/current/consensus" [added in Tor 0.2.1.6-alpha] + "dir/status-vote/current/consensus-microdesc" [added in Tor 0.4.3.1-alpha] "dir/status/authority" "dir/status/fp/<F>" "dir/status/fp/<F1>+<F2>+<F3>" @@ -1604,17 +1605,18 @@ KeyType = "NEW" / ; The server should generate a key of algorithm KeyBlob "RSA1024" / ; The server should use the 1024 bit RSA key provided - in as KeyBlob + in as KeyBlob (v2). "ED25519-V3"; The server should use the ed25519 v3 key provided in as - KeyBlob + KeyBlob (v3). KeyBlob = "BEST" / ; The server should generate a key using the "best" - supported algorithm (KeyType == "NEW") + supported algorithm (KeyType == "NEW"). + [As of 0.4.2.3-alpha, ED25519-V3 is used] "RSA1024" / ; The server should generate a 1024 bit RSA key - (KeyType == "NEW") + (KeyType == "NEW") (v2). "ED25519-V3"; The server should generate an ed25519 private key - (KeyType == "NEW") + (KeyType == "NEW") (v3). String ; A serialized private key (without whitespace) Flag = @@ -1623,7 +1625,7 @@ "Detach" / ; Do not associate the newly created Onion Service to the current control connection. "BasicAuth" / ; Client authorization is required using the "basic" - method. + method (v2 only). "NonAnonymous" /; Add a non-anonymous Single Onion Service. Tor checks this flag matches its configured hidden service anonymity mode. @@ -1641,10 +1643,10 @@ optional HiddenServicePort "TARGET" argument). ClientName = An identifier 1 to 16 characters long, using only - characters in A-Za-z0-9+-_ (no spaces). + characters in A-Za-z0-9+-_ (no spaces) (v2 only). ClientBlob = Authorization data for the client, in an opaque format - specific to the authorization method. + specific to the authorization method (v2 only). The server reply format is: "250-ServiceID=" ServiceID CRLF @@ -1667,11 +1669,11 @@ way to recreate the generated keypair and the corresponding Onion Service at a later date). - If client authorization is enabled using the "BasicAuth" flag, the - service will not be accessible to clients without valid authorization - data (configured with the "HidServAuth" option). The list of authorized - clients is specified with one or more "ClientAuth" parameters. If - "ClientBlob" is not specified for a client, a new credential will be + If client authorization is enabled using the "BasicAuth" flag (which is v2 + only), the service will not be accessible to clients without valid + authorization data (configured with the "HidServAuth" option). The list of + authorized clients is specified with one or more "ClientAuth" parameters. + If "ClientBlob" is not specified for a client, a new credential will be randomly generated and returned. Tor instances can either be in anonymous hidden service mode, or @@ -1709,13 +1711,9 @@ PRF secret, and just pay the cost of recomputing the public key when importing an ED25519-V3 key.] - (The "NEW:BEST" option obeys the HiddenServiceVersion torrc option default - value. Since 0.3.5.1-alpha, it is 3. For Tor versions before 0.3.5.1-alpha, - default HiddenServiceVersion is 2.) - Examples: C: ADD_ONION NEW:BEST Flags=DiscardPK Port=80 - S: 250-ServiceID=exampleonion1234 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad S: 250 OK C: ADD_ONION RSA1024:[Blob Redacted] Port=80,192.168.1.1:8080 @@ -1723,11 +1721,11 @@ S: 250 OK C: ADD_ONION NEW:BEST Port=22 Port=80,8080 - S: 250-ServiceID=testonion1234567 - S: 250-PrivateKey=RSA1024:[Blob Redacted] + S: 250-ServiceID=sampleonion4t2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad + S: 250-PrivateKey=ED25519-V3:[Blob Redacted] S: 250 OK - C: ADD_ONION NEW:BEST Flags=DiscardPK,BasicAuth Port=22 + C: ADD_ONION NEW:RSA1024 Flags=DiscardPK,BasicAuth Port=22 ClientAuth=alice:[Blob Redacted] ClientAuth=bob S: 250-ServiceID=testonion1234567 S: 250-ClientAuth=bob:[Blob Redacted] @@ -1736,7 +1734,7 @@ Examples with Tor in anonymous onion service mode: C: ADD_ONION NEW:BEST Flags=DiscardPK Port=22 - S: 250-ServiceID=testonion1234567 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad S: 250 OK C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 @@ -1748,13 +1746,13 @@ S: 512 Tor is in non-anonymous hidden service mode C: ADD_ONION NEW:BEST Flags=DiscardPK,NonAnonymous Port=22 - S: 250-ServiceID=testonion1234567 + S: 250-ServiceID=exampleoniont2pqglbny66wpovyvao3ylc23eileodtevc4b75ikpad S: 250 OK [ADD_ONION was added in Tor 0.2.7.1-alpha.] - [ClientAuth was added in Tor 0.2.9.1-alpha.] - [NonAnonymous was added in Tor 0.2.9.3-alpha.] [MaxStreams and MaxStreamsCloseCircuit were added in Tor 0.2.7.2-alpha] + [ClientAuth was added in Tor 0.2.9.1-alpha. It is v2 only.] + [NonAnonymous was added in Tor 0.2.9.3-alpha.] [HS v3 support added 0.3.3.1-alpha] 3.28. DEL_ONION @@ -1819,7 +1817,88 @@ [HSPOST was added in Tor 0.2.7.1-alpha] -3.23. DROPOWNERSHIP +3.30. ONION_CLIENT_AUTH_ADD + + The syntax is: + "ONION_CLIENT_AUTH_ADD" SP HSAddress + SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" TYPE] CRLF + + HSAddress = 56*Base32Character + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key + + Tells the connected Tor to add client-side v3 client auth credentials for the + onion service with "HSAddress". The "PrivateKeyBlob" is the x25519 private + key that should be used for this client, and "Nickname" is an optional + nickname for the client. + + FLAGS is a comma-separated tuple of flags for this new client. For now, the + currently supported flags are: + "Permanent" - This client's credentials should be stored in the filesystem. + If this is not set, the client's credentials are epheremal + and stored in memory. + + If client auth credentials already existed for this service, replace them + with the new ones. + + If Tor has cached onion service descriptors that it has been unable to + decrypt in the past (due to lack of client auth credentials), attempt to + decrypt those descriptors as soon as this command succeeds. + + On success, "250 OK" is returned. Otherwise, the following error codes exist: + 251 - Client auth credentials for this onion service already existed and replaced. + 252 - Added client auth credentials and successfully decrypted a cached descriptor. + 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" + 551 - Client with with this "Nickname" already exists + 552 - Unrecognized KeyType + +3.31. ONION_CLIENT_AUTH_REMOVE + + The syntax is: + "ONION_CLIENT_AUTH_REMOVE" SP HSAddress + + KeyType = "x25519" is the only one supported right now + + Tells the connected Tor to remove the client-side v3 client auth credentials + for the onion service with "HSAddress". + + On success "250 OK" is returned. Otherwise, the following error codes exist: + 512 - Syntax error in "HSAddress". + 251 - Client credentials for "HSAddress" did not exist. + +3.32. ONION_CLIENT_AUTH_VIEW + + The syntax is: + "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + + Tells the connected Tor to list all the stored client-side v3 client auth + credentials for "HSAddress". If no "HSAddress" is provided, list all the + stored client-side v3 client auth credentials. + + The server reply format is: + "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + *("250-CLIENT" SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" FLAGS] CRLF) + "250 OK" CRLF + + KeyType = "x25519" is the only one supported right now + PrivateKeyBlob = base64 encoding of x25519 key + + "Nickname" is an optional nickname for this client, which can be set either + through the ONION_CLIENT_AUTH_ADD command, or it's the filename of this + client if the credentials are stored in the filesystem. + + FLAGS is a comma-separated field of flags for this client, the currently + supported flags are: + "Permanent" - This client's credentials are stored in the filesystem. + + On success "250 OK" is returned. Otherwise, the following error codes exist: + 512 - Syntax error in "HSAddress". + +3.33. DROPOWNERSHIP The syntax is: "DROPOWNERSHIP" CRLF |