[tor-dev] Pluggable Transports 2.0 Specification, Draft 3

[Brandon Wiley]

Below is a link to the third draft of the Pluggable Transport 2.0
Specification. If you have feedback on this draft, please send me your
comments by October 31. Thank you!

Changes in this version:

- Expanded acknowledgements section - thanks Yawning!
- Removed TransportConn and TransportListener in favor of net.Conn and
net.Listener
- Modified SOCKS authentication method to use IANA-assigned designator
- Added error response codes for per-connection arguments
- Many typos fixed - thanks David Fifield!
- Clarified some definitions - thanks teor!


Link:
https://operatorfoundation.org/PluggableTransportSpecification-v2-Draft3.pdf

[Brandon Wiley]

nickm requested that I provide the following information about the PT 2.0
specification draft:

The only section that requires changes to tor is Section 3.3.4, on client
per-connection arguments.

Implementing the requirements from this section are discussed in the
following trac ticket: https://trac.torproject.org/projects/tor/ticket/21816

Here is the entirety of the proposal text that requires changes to tor, for
your convenience:

1.

If there are connection settings present, the authentication type 0x09
(IANA assigned, “JSON Parameter Block”) is used, followed by the
serialized per-connection parameter data. The serialization process for
the parameters is defined as follows:
-

● They keys and values are inserted into a map
-

● This map is serialized JSON to a UTF-8 string.


-

● The UTF-8 string is converted to a sequence of bytes. (This is trivial
for a UTF-8 string.)
-

● The number of bytes is counted.
-

● The byte count is encoded as a 4-byte sequence in network byte
order (big-endian).

-

● The encoded count is prepended to the byte sequence.

The following error codes are defined for the response when connection
settings are present:


-

● X’10’ - Connection settings size too large
-

● X’11’ - Timeout reading connection settings
-

● X’12’ - Error parsing connection settings
-

● X’13’ - Connection settings have invalid or missing keys or values

While the byte count is encoded as a 4-byte sequence, which is
capable of expressing
connection setting sizes up to 4GB, it is not required that the
implementation support the maximum possible size. If a size larger than
is supported by the implementation is specified, the X’10’ error code can
be used. Additionally, an implementation-dependent timeout should
included for receiving the connection settings. If this timeout is
exceeded, the X’11’ error code can be used. Error code X’12’ is returned
if the connection parameters are not properly encoded JSON. Error code
X’13’ is used if the connection settings are not correct for the specific
transport being used.

Example

\x00\x00\x00\x39{"shared-secret": "rahasia", "secrets-file": "/tmp/blob"}

Post by Brandon Wiley
Below is a link to the third draft of the Pluggable Transport 2.0
Specification. If you have feedback on this draft, please send me your
comments by October 31. Thank you!
- Expanded acknowledgements section - thanks Yawning!
- Removed TransportConn and TransportListener in favor of net.Conn and
net.Listener
- Modified SOCKS authentication method to use IANA-assigned designator
- Added error response codes for per-connection arguments
- Many typos fixed - thanks David Fifield!
- Clarified some definitions - thanks teor!
Link: https://operatorfoundation.org/PluggableTransportSpecificatio
n-v2-Draft3.pdf