From 7325b930f28721ced4139deff5dd70a54d532432 Mon Sep 17 00:00:00 2001 From: Joel Martin Date: Thu, 24 Jun 2010 10:50:36 -0500 Subject: [PATCH] Add proxy functionality description. --- docs/proxy_description.txt | 67 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/proxy_description.txt diff --git a/docs/proxy_description.txt b/docs/proxy_description.txt new file mode 100644 index 00000000..218078a3 --- /dev/null +++ b/docs/proxy_description.txt @@ -0,0 +1,67 @@ +Description of the WebSockets to TCP Proxy + + +At the most basic level, the proxy just translates WebSockets traffic +to normal socket traffic. The proxy accepts the WebSockets header, +parses it, and then begins forwarding traffic between the client and +the target in both directions. At a minimum the proxy needs to base64 +encode traffic destined for the client and decode it coming from the +client. Also, WebSockets traffic starts with '\0' (0) and ends with +'\xff' (255) so that needs to be added/stripped by the proxy. There +is a little bit of buffering you need to do in case the data from the +client isn't a full WebSockets frame (i.e. doesn't end in 255). + + +Other proxy features (that aren't necessary for the basic operation): + + +SSL (the wss:// WebSockets URI): + +This is detected automatically by the proxy by sniffing the first byte +of the client's connection and then wrapping the socket if the data +starts with '\x16' (indicating SSL). + + +Sequence Numbering: + +When the client doesn't have native WebSockets support in the browser +(currently only Chrome and Safari 5), a flash emulator fallback is +used. Unfortunately, when this is used, frame ordering is not 100%, +so the GET URI in the initial handshake has "seq_num=1". This tells +the proxy to add sequence numbers to every WebSockets frame so that +the browser can reorder them. + + +UTF-8 encoding: + +In addition to the base64 encoding of the data, the proxy also +supports UTF-8 encoding of the data (the native WebSockets encoding). +However, in order to not burden the browser too much, the encoding +doesn't use the full UTF-8 value space, but only uses the first 256 +values. This actually makes UTF-8 encoding slightly less space +efficient than base64. Also, flash cannot handle byte arrays with 0's +in them properly, so the values are actually 1-256 (rather than 0-255) +and the browser does modulus 256 on the data. For these two reasons, +base64 is the default and is indicated in the GET string by +"base64=1". + + +Flash security policy: + +The proxy detects flash security policy requests (again by sniffing +the first packet) and answers with an appropriate flash security +policy response (and then closes the port). This means no separate +flash security policy server is needed for supporting the flash +WebSockets fallback emulator. + + +Daemonizing: + +The proxy also supports daemonizing (when the -f option is not +specified). + + +Record: + +Finally, there is a debug feature that allows recording of the traffic +sent and received from the client to a file (the --record option).