Merge branch 'socks_codes_update' into 'main'

Add onion service error codes to socks-extensions.

Closes #208 and #207

See merge request tpo/core/torspec!161

1 files changed, 57 insertions, 0 deletions

diff --git a/socks-extensions.txt b/socks-extensions.txt
index 0107856..c35069d 100644
--- a/socks-extensions.txt
+++ b/socks-extensions.txt
@@ -9,6 +9,7 @@ Table of Contents
     3. Other command extensions.
     4. HTTP-resistance
     5. Optimistic data
+    6. Extended error codes
 
 1. Overview
 
@@ -108,6 +109,62 @@ Table of Contents
   their connection has succeeded or failed _after_ they have sent the
   data.
 
+6. Extended error codes
+
+  We define a set of additional extension error codes that can be returned
+  by our SOCKS implementation in response to failed onion service
+  connections.
+
+  (In the C Tor implementation, these error codes can be disabled
+  via the ExtendedErrors flag.  In Arti, these error codes are enabled
+  whenever onion services are.)
+
+    * X'F0' Onion Service Descriptor Can Not be Found
+
+      The requested onion service descriptor can't be found on the hashring
+      and thus not reachable by the client.
+
+    * X'F1' Onion Service Descriptor Is Invalid
+
+      The requested onion service descriptor can't be parsed or signature
+      validation failed.
+
+    * X'F2' Onion Service Introduction Failed
+
+      Client failed to introduce to the service meaning the descriptor was
+      found but the service is not anymore at the introduction points. The
+      service has likely changed its descriptor or is not running.
+
+    * X'F3' Onion Service Rendezvous Failed
+
+      Client failed to rendezvous with the service which means that the client
+      is unable to finalize the connection.
+
+    * X'F4' Onion Service Missing Client Authorization
+
+      Tor was able to download the requested onion service descriptor but is
+      unable to decrypt its content because it is missing client authorization
+      information for it.
+
+    * X'F5' Onion Service Wrong Client Authorization
+
+      Tor was able to download the requested onion service descriptor but is
+      unable to decrypt its content using the client authorization information
+      it has. This means the client access were revoked.
+
+    * X'F6' Onion Service Invalid Address
+
+      The given .onion address is invalid. In one of these cases this
+      error is returned: address checksum doesn't match, ed25519 public
+      key is invalid or the encoding is invalid.
+
+    * X'F7' Onion Service Introduction Timed Out
+
+      Similar to X'F2' code but in this case, all introduction attempts
+      have failed due to a time out.
+
+  (Note that not all of the above error codes are currently returned
+  by Arti as of August 2023.)
 
 
 References: