From 3a26880e80617210b4729f96664ef9f0345b0b7c Mon Sep 17 00:00:00 2001 From: George Kadianakis Date: Mon, 6 May 2019 18:13:57 +0300 Subject: control-spec: Specify add/remove/view client auth commands (client-side). --- control-spec.txt | 48 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) (limited to 'control-spec.txt') diff --git a/control-spec.txt b/control-spec.txt index eb3089b..bc57639 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1811,7 +1811,53 @@ [HSPOST was added in Tor 0.2.7.1-alpha] -3.23. DROPOWNERSHIP +3.30. ADD_ONION_CLIENT_AUTH + + The syntax is: + "ADD_ONION_CLIENT_AUTH" SP HSAddress + SP "X25519Key=" PrivateKeyBlob + [SP "ClientName=" Nickname] CRLF + + HSAddress = 56*Base32Character + PrivateKeyBlob = base64 encoding of x25519 key + + Tells the server 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. + +3.31. REMOVE_ONION_CLIENT_AUTH + + The syntax is: + "REMOVE_ONION_CLIENT_AUTH" SP HSAddress + SP "X25519Key=" PrivateKeyBlob CRLF + + Tells the server to remove the client-side v3 client auth credentials for the + onion service with "HSAddress" and client with key "PrivateKeyBlob". + +3.32. VIEW_ONION_CLIENT_AUTH + + The syntax is: + "VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF + + Tells the server to list all the stored client-side v3 client auth + credentials for "HSAddress". + + The server reply format is: + "250-VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF + *("250-CLIENT X25519Key=" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Type=Permanent"] CRLF) + "250 OK" CRLF + + Where "PrivateKeyBlob" is the x25519 private key of this client. If the + client auth credentials are stored in the filesystem, "Type=Permanent" is + returned as part of the output. "Nickname" is an optional nickname for this + client, which can be set either through the ADD_ONION_CLIENT_AUTH command, or + it's the filename of this client if the credentials are stored in the + filesystem. + +3.33. DROPOWNERSHIP The syntax is: "DROPOWNERSHIP" CRLF -- cgit v1.2.3-54-g00ecf From 13928996f4928773605527b561cdb212c1d93766 Mon Sep 17 00:00:00 2001 From: George Kadianakis Date: Tue, 7 May 2019 18:15:09 +0300 Subject: control-spec: Add error codes to the commands. --- control-spec.txt | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'control-spec.txt') diff --git a/control-spec.txt b/control-spec.txt index bc57639..21e104e 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1826,6 +1826,11 @@ should be used for this client, and "Nickname" is an optional nickname for the client. + On success, "250 OK" is returned. Otherwise, the following error codes exist: + 251 - Client with with this "PrivateKeyBlob" already existed. + 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" + 551 - Client with with this "Nickname" already exists + 3.31. REMOVE_ONION_CLIENT_AUTH The syntax is: @@ -1835,6 +1840,10 @@ Tells the server to remove the client-side v3 client auth credentials for the onion service with "HSAddress" and client with key "PrivateKeyBlob". + On success "250 OK" is returned. Otherwise, the following error codes exist: + 512 - Syntax error in "HSAddress", or "PrivateKeyBlob". + 251 - Client with "PrivateKeyBlob" did not exist. + 3.32. VIEW_ONION_CLIENT_AUTH The syntax is: @@ -1857,6 +1866,9 @@ it's the filename of this client if the 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: -- cgit v1.2.3-54-g00ecf From ce38ad7e46da9840c7d211837c4bffb62d525ebf Mon Sep 17 00:00:00 2001 From: George Kadianakis Date: Tue, 7 May 2019 19:03:48 +0300 Subject: control-spec: Various improvements following mailing list feedback. - Rename all commands to be less arbitrary - "Tells the server" -> "Tells the connected Tor" - Make TYPE an actual type thing. We only support one for now, but that's OK. Controllers and Tor can take shortcuts if needed. - Specify where credentials get stored. - Support viewing all the credentials. - Support the ADD command adding permanent credentials. - Change X25519Key to X25519PrivKey. --- control-spec.txt | 62 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 26 deletions(-) (limited to 'control-spec.txt') diff --git a/control-spec.txt b/control-spec.txt index 21e104e..c2b8f1b 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1811,60 +1811,70 @@ [HSPOST was added in Tor 0.2.7.1-alpha] -3.30. ADD_ONION_CLIENT_AUTH +3.30. ONION_CLIENT_AUTH_ADD The syntax is: - "ADD_ONION_CLIENT_AUTH" SP HSAddress - SP "X25519Key=" PrivateKeyBlob - [SP "ClientName=" Nickname] CRLF + "ONION_CLIENT_AUTH_ADD" SP HSAddress + SP "X25519PrivKey=" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Type=" TYPE] CRLF HSAddress = 56*Base32Character PrivateKeyBlob = base64 encoding of x25519 key - Tells the server 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. + 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. + + TYPE is a comma-separated tuple of types for this new client. For now, the + currently supported types 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. On success, "250 OK" is returned. Otherwise, the following error codes exist: 251 - Client with with this "PrivateKeyBlob" already existed. 512 - Syntax error in "HSAddress", or "PrivateKeyBlob" or "Nickname" 551 - Client with with this "Nickname" already exists -3.31. REMOVE_ONION_CLIENT_AUTH +3.31. ONION_CLIENT_AUTH_REMOVE The syntax is: - "REMOVE_ONION_CLIENT_AUTH" SP HSAddress - SP "X25519Key=" PrivateKeyBlob CRLF + "ONION_CLIENT_AUTH_REMOVE" SP HSAddress + SP "X25519PrivKey=" PrivateKeyBlob CRLF - Tells the server to remove the client-side v3 client auth credentials for the - onion service with "HSAddress" and client with key "PrivateKeyBlob". + Tells the connected Tor to remove the client-side v3 client auth credentials + for the onion service with "HSAddress" and client with key "PrivateKeyBlob". On success "250 OK" is returned. Otherwise, the following error codes exist: 512 - Syntax error in "HSAddress", or "PrivateKeyBlob". 251 - Client with "PrivateKeyBlob" did not exist. -3.32. VIEW_ONION_CLIENT_AUTH +3.32. ONION_CLIENT_AUTH_VIEW The syntax is: - "VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF + "ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF - Tells the server to list all the stored client-side v3 client auth - credentials for "HSAddress". + 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-VIEW_ONION_CLIENT_AUTH" SP HSAddress CRLF - *("250-CLIENT X25519Key=" PrivateKeyBlob + "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF + *("250-CLIENT X25519PrivKey=" PrivateKeyBlob [SP "ClientName=" Nickname] - [SP "Type=Permanent"] CRLF) + [SP "Type=" TYPE] CRLF) "250 OK" CRLF - Where "PrivateKeyBlob" is the x25519 private key of this client. If the - client auth credentials are stored in the filesystem, "Type=Permanent" is - returned as part of the output. "Nickname" is an optional nickname for this - client, which can be set either through the ADD_ONION_CLIENT_AUTH command, or - it's the filename of this client if the credentials are stored in the - filesystem. + Where "PrivateKeyBlob" is the x25519 private key of this client. "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. + + TYPE is a comma-separated field of types for this client, the currently + supported types 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". -- cgit v1.2.3-54-g00ecf From dafda3944241e4ab6dfe0fee90d2e97979ac8f94 Mon Sep 17 00:00:00 2001 From: George Kadianakis Date: Mon, 3 Jun 2019 16:18:21 +0300 Subject: fixup! control-spec: Various improvements following mailing list feedback. --- control-spec.txt | 49 +++++++++++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 18 deletions(-) (limited to 'control-spec.txt') diff --git a/control-spec.txt b/control-spec.txt index c2b8f1b..01063b0 100644 --- a/control-spec.txt +++ b/control-spec.txt @@ -1815,11 +1815,12 @@ The syntax is: "ONION_CLIENT_AUTH_ADD" SP HSAddress - SP "X25519PrivKey=" PrivateKeyBlob + SP KeyType ":" PrivateKeyBlob [SP "ClientName=" Nickname] - [SP "Type=" TYPE] CRLF + [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 @@ -1827,29 +1828,39 @@ key that should be used for this client, and "Nickname" is an optional nickname for the client. - TYPE is a comma-separated tuple of types for this new client. For now, the - currently supported types are: + 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 with with this "PrivateKeyBlob" already existed. + 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 - SP "X25519PrivKey=" PrivateKeyBlob CRLF + + 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" and client with key "PrivateKeyBlob". + for the onion service with "HSAddress". On success "250 OK" is returned. Otherwise, the following error codes exist: - 512 - Syntax error in "HSAddress", or "PrivateKeyBlob". - 251 - Client with "PrivateKeyBlob" did not exist. + 512 - Syntax error in "HSAddress". + 251 - Client credentials for "HSAddress" did not exist. 3.32. ONION_CLIENT_AUTH_VIEW @@ -1862,18 +1873,20 @@ The server reply format is: "250-ONION_CLIENT_AUTH_VIEW" [SP HSAddress] CRLF - *("250-CLIENT X25519PrivKey=" PrivateKeyBlob - [SP "ClientName=" Nickname] - [SP "Type=" TYPE] CRLF) + *("250-CLIENT" SP KeyType ":" PrivateKeyBlob + [SP "ClientName=" Nickname] + [SP "Flags=" FLAGS] CRLF) "250 OK" CRLF - Where "PrivateKeyBlob" is the x25519 private key of this client. "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. + 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. - TYPE is a comma-separated field of types for this client, the currently - supported types are: + 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: -- cgit v1.2.3-54-g00ecf