[tor-dev] Proposal 351: Making SOCKS5 authentication extensions extensible

[Nick Mathewson]

(You can see this proposal rendered at
https://spec.torproject.org/proposals/351-socks-auth-extensions.html )

```
Filename: 351-socks-auth-extensions.md
Title: Making SOCKS5 authentication extensions extensible
Author: Nick Mathewson
Created: 9 September 2024
Status: Open
```

## Introduction

Currently, Tor implementations use
the SOCKS5 username and password fields
to pass parameters for stream isolation.
(See the `IsolateSocksAuth` flag in the C tor manual,
and the "Stream isolation" section
([forthcoming](https://gitlab.torproject.org/tpo/core/torspec/-/merge_requests/279))
in our [socks extensions](../socks-extensions.md) spec.)

> Tor implementations also support SOCKS4 and SOCKS4a,
> but they are not affected by this proposal.
>
> The C Tor implementation also supports other proxy types besides SOCKS.
> They are not affected by this proposal
> because they either have other means to extend their protocols
> (as with HTTP headers in HTTP CONNECT)
> or no means to pass extension information
> (as for DNS proxies, iptables transparent proxies, etc).

Until now, the rules for interpreting these fields have been simple:
all values are permitted,
and streams with unequal values may not share a circuit.

But in order to integrate SOCKS connections into Arti's RPC protocol,
we additionally want the ability to send RPC "Object IDs"[^ObjectId]
in these fields.
To do this, we will need some way to tell
when we have received an object ID,
when we have received an isolation parameter,
and to avoid confusing them with one another.

> Note that some confusion will necessarily remain possible:
> Since current Tor clients are allowed to send any value
> as SOCKS username and password,
> any value we specify here will be one which a client in principle
> _might_ have sent under the old protocol.

Additionally,
since we are adding complexity to the interpretation of these fields,
it's possible we'll want to change this complexity in the future.
To do this, we'll want a versioning scheme to premit changes.

## Proposal

> If accepted, the following can be incorporated into
> our [socks extensions](../socks-extensions.md) spec.)

We support a series of extensions in SOCKS5 Username/Passwords.
Currently,
these extensions can encode a stream isolation parameter
(used to indicate that streams may share a circuit)
and an RPC object ID
(used to associate the stream with an entity in an RPC session).

These extensions are in use whenever the SOCKS5 Username
begins with the 8-byte "magic" sequence `[3c 74 6f 72 53 30 58 3e]`.
(This is the ASCII encoding of `<torS0X>`).

If the SOCKS5 Username/Password fields are present
but the Username does not begin with this byte sequence,
it indicates _legacy isolation_.
New client implementations SHOULD NOT use legacy isolation.
A SocksPort may be configured to reject legacy isolation.

When these extensions are in use,
the next byte of the username after the "magic" sequence
indicate a version number.
Any implementation receiving an unrecognized or missing version
MUST reject the socks request.

When the version number is `[30]` (the ascii encoding of `0`),
we interpret the rest of the Username field and the Password field
as follows:

The remainder of the Username field encodes an RPC Object ID.
(If the remainder of the Username field is empty, there is no RPC object.)

The Password field is stream isolation parameter.
If it is empty, the stream isolation parameter is an empty string.

### Stream isolation

> This replaces the corresponding part of
> the "Stream isolation" section
> ([forthcoming](https://gitlab.torproject.org/tpo/core/torspec/-/merge_requests/279))
> in our [socks extensions](../socks-extensions.md) spec.

Two streams are considered to have the same SOCKS authentication values
if and only if one of the following is true:

- They are both SOCKS4 or SOCKS4a, with the same user "ID" string.
- They are both SOCKS5, with no authentication.
- They are both SOCKS5 with USERNAME/PASSWORD authentication,
  using legacy isolation parameters,
  and they have identical usernames
  and identical passwords.
- They are both SOCKS5 using the extensions above,
  with the same stream isolation parameter.

### A further extension for integration with Arti SOCKS

> We should add the following to a specification,
> though it is not clear whether it goes in the Arti RPC spec
> or in the socks extensions spec.

In some cases,
the RPC Object ID may denote an object
that already includes information about its intended stream isolation.
In such cases, the stream isolation MUST be blank.
Implementations MUST reject non-blank stream isolation in such cases.

In some cases, the RPC object ID may denote an object
that already includes information
about its intended destination address and port.
In such cases, the destination address MUST be `0.0.0.0` or `::`
(encoded either as an IPv4 address, an IPv6 address, or a hostname)
and the destination port MUST be 0.
Implementations MUST reject other addresses in such cases.

-----

> (Here the specifications end.
> The rest of this proposal is discussion.)

## Design considerations

Our use of SOCKS5 Username/Passwords here
(as opposed to some other, new authentication type)
is based on the observation
that many existing SOCKS5 implementations support Username/Password,
but comparatively few support arbitrary plug-in authentication.

The magic "`<torS0X>`" prefix is chosen to be 8 characters long
so that existing client implementations that generate random strings
will not often generate it by mistake.

The version number is chosen to be an ASCII `0` rather than a raw 0 byte,
for compatibility with existing SOCKS5 client implementations
that do not support non-ASCII username/password values.



## C Tor migration

When this proposal is accepted,
we *should* configure C tor to implement it as follows:

- To reject any SOCKS5 Username starting with `<torS0X>`
  unless it is exactly `<torS0X>0`.

This behavior is sufficient to give correct isolation behavior,
to reject any connection including an RPC object ID,
and to reject any as-yet-unspecified isolation mechanisms.






[^ObjectId]: An ObjectId is used in the Arti RPC protocol
   to associate a SOCKS request with some existing Client object,
   or with a preexisting DataStream.