[tor-commits] [websocket/master] WebSocket transport doc.

dcf at torproject.org dcf at torproject.org
Thu Oct 3 16:36:10 UTC 2013


commit d168142144067342fa096b2157c7fb5b8ab40bdc
Author: David Fifield <david at bamsoftware.com>
Date:   Mon Apr 9 00:12:49 2012 -0700

    WebSocket transport doc.
---
 doc/websocket-transport.txt |  218 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 218 insertions(+)

diff --git a/doc/websocket-transport.txt b/doc/websocket-transport.txt
new file mode 100644
index 0000000..80d8b5e
--- /dev/null
+++ b/doc/websocket-transport.txt
@@ -0,0 +1,218 @@
+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 --managed
+Bridge websocket 198.51.100.1
+
+ServerTransportPlugin websocket exec /usr/libexec/tor-websocket-proxy --server --managed
+
+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 example 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 "sbG8="
+
+  When sent by a client, all frames including these must be masked. If
+  the masking key is 0x12345678, then the message may be sent as one
+  frame like this:
+
+    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: https://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: https://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.
+
+  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. Upon receiving such a message (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 1500 octets of binary data;
+  this may require buffering up to 2026 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





More information about the tor-commits mailing list