Merge branch 'websocket-doc' of flashproxy

Title: WebSocket pluggable transport

Author: David Fifield

Overview

  This proposal describes the "websocket" pluggable transport for Tor.

  It uses the WebSocket protocol now implemented by many web browsers.

  It is mostly a straightforward description of proxying WebSocket to

  plain TCP, with special consideration for a base64 encoding for agents

  that don't support binary WebSocket frames.

Motivation

  The WebSocket protocol is used by the "flash proxy" system that uses

  web browsers as temporary proxies; browsers may connect to a relay

  that supports this pluggable transport. Additionally, if WebSocket has

  a lot of non-Tor use, it becomes a good target for tunneling, perhaps

  in conjunction with a lower layer of obfuscation. WebSocket commonly

  works over HTTP ports that are likely to get through a firewall.

WebSocket overview

  WebSocket is a protocol (rather, several mostly compatible protocols)

  aimed at exposing socket-like functionality to JavaScript in web

  browsers. It is partially aimed at supplanting techniques such as HTTP

  long polling for client–server communication. WebSocket provides

  bidirectional communication between a client and server, sufficient to

  tunnel Tor traffic. A WebSocket session begins with an HTTP Upgrade

  handshake. The socket carries data broken into variable-length

  "messages" which are further broken into "frames." There are

  distinguished frame opcodes that serve to send either data or control

  information. Frames sent by the client (but not the server) are XORed

  with a repeating 32-bit mask that is randomly generated per-frame.

  Broadly speaking, there are two versions of WebSocket: the older

  "hixie" protocol, and the newer "hybi" protocol which is now RFC 6455.

  There are subprotocols within these two versions that differ only in

  small ways: "hixie-75" and "hixie-76"; and "hybi-7", "hybi-10", and

  "hybi-17". The older "hybi" sockets were supported by Firefox 4 and

  Opera 11, but were later disabled because of problems with interaction

  with reverse HTTP proxies. Current versions of Firefox and Chrome

  support "hybi" sockets, while Safari only supports "hixie".

  The "hybi" sockets support text frames and binary frames. Text frames

  may only include UTF-8–encoded text; it is an error if payload doesn't

  decode. Binary frames may contain any binary data. However, not all

  web browsers support binary frames; they were first added to Firefox

  in version 11. The "hixie" sockets have only text frames.

Method name

  The method name of the transport is "websocket". For example, these

  are possible torrc configurations for a client and server,

  respectively:

UseBridges 1

ClientTransportPlugin websocket exec /usr/libexec/tor-websocket-proxy --client

Bridge websocket 198.51.100.1

ServerTransportPlugin websocket exec /usr/libexec/tor-websocket-proxy --server

The base64 subprotocol

  The most convenient way to tunnel data over WebSocket is with binary

  frames, but not all web browsers support binary frames. To work around

  this, the "base64" subprotocol encodes binary data as base64 within

  text frames. A client that knows it does not support binary frames

  requests the base64 subprotocol by including "base64" in the value of

  the Sec-WebSocket-Protocol header field. A server that also supports

  this subprotocol by sending the value "base64" (and only "base64") in

  the Sec-WebSocket-Protocol header field of its response. See under

  "Examples" for examples of handshakes like this.

  The base64 encoding is applied at the message level, not the frame

  level. This means, in particular, that any '=' padding occurs only at

  the end of a message, not at the end of each of its constituent

  frames. So, for example, the 5-byte message "Hello", whose base64

  encoding is "SGVsbG8=", may be sent as one text frame as follows:

    0x81 0x08 "SGVsbG8="

  or, for example, as two frames (one of 2 bytes and one of 6 bytes):

    0x01 0x02 "SG" 0x81 0x06 "VsbG8="

  When sent by a client, all frames including these must be masked. Here

  is an example of a masked base64-encoded message sent as a single

  frame (using the masking key 0x12345678):

    0x81 0x18 0x12 0x34 0x56 0x78 0x41 0x73 0x00 0x0b 0x70 0x73 0x6e 0x45

Examples

  Here are examples of WebSocket handshakes and the beginning of data

  transfer. The data is the beginning of a Tor connection (i.e., it

  begins with a TLS handshake). Data are shown using C string syntax.

  "> " at the beginning of a line indicates client-to-server

  communication; "< " is server-to-client. "[...]" indicates contents

  omitted for brevity. Newlines in the presentation are not significant.

  This section is non-normative.

  Using "hybi"/RFC 6455 WebSocket with binary frames:

> GET / HTTP/1.1\r\n

> Host: 192.0.2.1:80\r\n

> Origin: http://example.com\r\n

> Sec-WebSocket-Version: 13\r\n

> Sec-WebSocket-Key: mzo2xSF9N8VUxuefqO0RSw==\r\n

> Connection: Upgrade\r\n

> Upgrade: websocket\r\n

> \r\n

< HTTP/1.1 101 Switching Protocols\r\n

< Upgrade: websocket\r\n

< Connection: Upgrade\r\n

< Sec-WebSocket-Accept: fM0KjD7ixoxkl4PEXU6tNaTveSg=\r\n

< \r\n

> \x82\xfe\x01\x04\xc9\xd6\xdd\x29\xdf\xd5\xde\x29\x36\xd7[...]

< \x16\x03\x01\x00\x31\x02\x00\x00\x2d\x03[...]

  Using "hybi"/RFC 6455 WebSocket with the base64 subprotocol:

> GET / HTTP/1.1\r\n

> Host: 192.0.2.1:80\r\n

> Origin: http://example.com\r\n

> Sec-WebSocket-Version: 13\r\n

> Sec-WebSocket-Protocol: base64\r\n

> Sec-WebSocket-Key: k5Ybhw0XBDeBfmda1J9ooQ==\r\n

> Connection: Upgrade\r\n

> Upgrade: websocket\r\n

> \r\n

< HTTP/1.1 101 Switching Protocols\r\n

< Upgrade: websocket\r\n

< Connection: Upgrade\r\n

< Sec-WebSocket-Accept: LYWpflPUHdal8U1BLPXWR3iqUrI=\r\n

< Sec-WebSocket-Protocol: base64\r\n

< \r\n

> \x81\xfe\x01\x58\xbd\x94\x2a\x31\xfb\xf3\x67\x75\xfc\xc4[...]

< \x81\x7e\x04\xd0FgMBADECAA[...]

Considerations specific to pluggable transports

  Endpoints must implement WebSocket according to RFC 6455; for example,

  a server MUST close the connection if it receives an unmasked frame

  from a client, and a client MUST close the connection if it receives a

  masked frame from a server (RFC 6455 section 5.1). There are also

  additional requirements for WebSocket when used as a Tor pluggable

  transport.

  Clients MUST implement the RFC 6455 version of the protocol and use it

  for all connections. Servers MUST implement the RFC 6455 version of

  the protocol and MAY also implement earlier versions. That is, a

  server MAY check a client HTTP request to see if it matches an earlier

  version of the protocol, and MAY begin communicating using that

  protocol. Section 4.4 of RFC 6455 discusses supporting multiple

  versions of the protocol.

  Servers MUST support binary frames (opcode 2). Servers MAY also

  support text frames (opcode 1). Servers supporting text frames MUST

  implement the base64 subprotocol and accept it when requested by a

  client in the Sec-WebSocket-Protocol header field. Text frames MUST

  NOT be sent by either side if the base64 subprotocol has not been

  negotiated. Any endpoint receiving a text frame when base64 has not

  been negotiated, or a text message that cannot be decoded as base64,

  MUST close the connection.

  A client MUST NOT proceed after receiving any HTTP response status

  code other than 101. In particular, it MUST NOT follow redirections

  such as 301.

  Endpoints SHOULD respond to Ping frames with a single Pong frame, but

  nothing in this specification requires the sending of Ping frames.

  Message and frame boundaries are not meaningful. Received non-control

  messages are concatenated, in order, to reconstruct the original

  stream. Endpoints SHOULD limit the size of messages they send. All

  messages SHOULD be sent in a single frame.

  Endpoints MUST limit the size of messages and frames that they will

  buffer. When the sum of the length of already-buffered data and the

  length of the next frame exceeds the limit, the endpoint MUST close

  the connection and SHOULD do so with a status code of 1009 (see RFC

  6455 section 7.4.1). Endpoints MUST be capable of receiving messages

  containing up to 16384 bytes of binary data; this may require

  buffering up to 21848 bytes of UTF-8–encoded base64 text.

Questions/extensions

  WebSocket also has a TLS-wrapped version, identified by using the

  "wss" (as opposed to "ws") URL scheme. An advantage of this when

  tunneling through a browser is that the TLS handshake will be exactly

  that of a browser. However, this probably requires the certificates of

  relays' server transport plugins to be trusted by browsers.

References

  "Pluggable transports for circumvention"

  https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/180-pluggable-transport.txt

  RFC 6455, "The WebSocket Protocol" (a.k.a. hybi-17)

  https://tools.ietf.org/html/rfc6455

  "The WebSocket protocol (draft-ietf-hybi-thewebsocketprotocol-10)"

  (a.k.a. hybi-10)

  https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-10

  "The WebSocket protocol (draft-ietf-hybi-thewebsocketprotocol-7)"

  (a.k.a. hybi-7)

  https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-7

  "The WebSocket protocol (draft-ietf-hybi-thewebsocketprotocol-00)"

  (a.k.a. hybi-00, hixie-76)

  https://tools.ietf.org/html/draft-ietf-hybi-thewebsocketprotocol-00

  "The Web Socket protocol (draft-hixie-thewebsocketprotocol-75)"

  (a.k.a. hixie-75)

  https://tools.ietf.org/html/draft-hixie-thewebsocketprotocol-75

  Browser support matrix

  http://autobahn.ws/testsuite/reports/clients/index.html