mirror of
https://github.com/torproject/torspec.git
synced 2024-11-23 17:59:42 +00:00
110 lines
3.9 KiB
Plaintext
110 lines
3.9 KiB
Plaintext
Filename: 304-socks5-extending-hs-error-codes.txt
|
|
Title: Extending SOCKS5 Onion Service Error Codes
|
|
Author: David Goulet, George Kadianakis
|
|
Created: 22-May-2019
|
|
Status: Closed
|
|
|
|
Note: We are extending SOCKS5 here but in terms, when Tor Browser supports
|
|
HTTPCONNECT, we should not do that anymore.
|
|
|
|
0. Abstract
|
|
|
|
We propose extending the SOCKS5 protocol to allow returning more meaningful
|
|
response failure onion service codes back to the client.
|
|
|
|
This is inspired by proposal 229 [PROP229] minus the new authentication
|
|
method.
|
|
|
|
1. Introduction
|
|
|
|
The motivation behind this proposal is because we need a synchronous way to
|
|
return a reason on why the SOCKS5 connection failed.
|
|
|
|
The alternative is to use a control port event but then the caller needs to
|
|
match the SOCKS failure to the control event. And tor provides no guarantee
|
|
that a control event will be emitted before the SOCKS failure or vice
|
|
versa.
|
|
|
|
With this proposal, the client can get the reason on why the onion service
|
|
connection failed with the SOCKS5 returned error code.
|
|
|
|
2. Proposal
|
|
|
|
2.1. New SocksPort Flag
|
|
|
|
In order to have backward compatibility with third party applications that
|
|
do not support the new proposed SOCKS5 error code, we propose a new
|
|
SocksPort flag that needs to be set in the tor configuration file in order
|
|
for those code to be sent back.
|
|
|
|
The new SocksPort flag is:
|
|
|
|
"ExtendedErrors" -- Tor will report new SOCKS5 error code detailed below
|
|
in section 2.2 (once merged, they will end up in
|
|
socks-extension.txt).
|
|
|
|
It is possible that more codes will be added in the future so an
|
|
application using this flag should possibly expect unknown codes to be
|
|
returned.
|
|
|
|
2.2. Onion Service Extended SOCKS5 Error Code
|
|
|
|
We introduce the following additional SOCKS5 reply codes to be sent in the
|
|
REP field of a SOCKS5 message iff the "ExtendedErrors" on the SocksPort is
|
|
set (see section 2.1 above).
|
|
|
|
The SOCKS5 specification [RFC1928] defines a range of code that are
|
|
"unassigned" so we'll be using those on the far end of the range in order
|
|
to inform the client of onion service failures:
|
|
|
|
Where:
|
|
|
|
* 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.
|
|
|
|
3. Compatibility
|
|
|
|
No new field or extension has been added. Only new code values from the
|
|
unassigned range are being used. We expect these to not be a problem for
|
|
backward compatibility.
|
|
|
|
These codes are only sent back if the new proposed SocksPort flag,
|
|
"ExtendedErrors", is set and making it easier for backward and foward
|
|
compatibility.
|
|
|
|
References:
|
|
|
|
[PROP229] https://gitweb.torproject.org/torspec.git/tree/proposals/229-further-socks5-extensions.txt
|
|
|
|
[RFC1928] https://www.ietf.org/rfc/rfc1928.txt
|