[mirror_novnc.git] / utils / README.md

## wsproxy: WebSockets to TCP Proxy


### How it works

At the most basic level, wsproxy just translates WebSockets traffic
to normal socket traffic. wsproxy accepts the WebSockets handshake,
parses it, and then begins forwarding traffic between the client and
the target in both directions. WebSockets payload data is UTF-8
encoded so in order to transport binary data it must use an encoding
that can be encapsulated within UTF-8. wsproxy uses base64 to encode
all traffic to and from the client. Also, WebSockets traffic starts
with '\0' (0) and ends with '\xff' (255). Some buffering is done in
case the data from the client is not a full WebSockets frame (i.e.
does not end in 255).


### Additional features

These are not necessary for the basic operation.

* Daemonizing: When the `-f` option is not specified, wsproxy runs
  in the background as a daemon process.

* SSL (the wss:// WebSockets URI): This is detected automatically by
  wsproxy by sniffing the first byte sent from the client and then
  wrapping the socket if the data starts with '\x16' or '\x80'
  (indicating SSL).

* Flash security policy: wsproxy 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.

* Session recording: This feature that allows recording of the traffic
  sent and received from the client to a file using the `--record`
  option.


### Implementations

There are two implementations of wsproxy included: a python
implementation and a C implementation.

Here is the feature support matrix for the wsproxy implementations:


<table>
    <tr>
        <th>Implementation</th>
        <th>Basic Proxying</th>
        <th>Daemonizing</th>
        <th>SSL/wss</th>
        <th>Flash Policy Server</th>
        <th>Session Recording</th>
    </tr> <tr>
        <td>python</td>
        <td>yes</td>
        <td>yes</td>
        <td>yes 1</td>
        <td>yes</td>
        <td>yes</td>
    </tr> <tr>
        <td>C</td>
        <td>yes</td>
        <td>yes</td>
        <td>yes</td>
        <td>yes</td>
        <td>no</td>
    </tr>
</table>

* Note 1: to use SSL/wss with python 2.5 or older, see the following
  section on *Building the Python ssl module*.


### Building the Python ssl module (for python 2.5 and older)

* Install the build dependencies. On Ubuntu use this command:

    `sudo aptitude install python-dev bluetooth-dev`

* Download, build the ssl module and symlink to it:

    `cd noVNC/utils`
    `wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz`
    `tar xvzf ssl-1.15.tar.gz`
    `cd ssl-1.15`
    `make`
    `cd ../`
    `ln -sf ssl-1.15/build/lib.linux-*/ssl ssl`
Commit	Line	Data
e5d60a8b JM	1	## wsproxy: WebSockets to TCP Proxy
	2
	3
	4	### How it works
	5
	6	At the most basic level, wsproxy just translates WebSockets traffic
	7	to normal socket traffic. wsproxy accepts the WebSockets handshake,
	8	parses it, and then begins forwarding traffic between the client and
	9	the target in both directions. WebSockets payload data is UTF-8
	10	encoded so in order to transport binary data it must use an encoding
	11	that can be encapsulated within UTF-8. wsproxy uses base64 to encode
	12	all traffic to and from the client. Also, WebSockets traffic starts
	13	with '\0' (0) and ends with '\xff' (255). Some buffering is done in
	14	case the data from the client is not a full WebSockets frame (i.e.
	15	does not end in 255).
	16
	17
	18	### Additional features
	19
	20	These are not necessary for the basic operation.
	21
	22	* Daemonizing: When the `-f` option is not specified, wsproxy runs
	23	in the background as a daemon process.
	24
	25	* SSL (the wss:// WebSockets URI): This is detected automatically by
	26	wsproxy by sniffing the first byte sent from the client and then
	27	wrapping the socket if the data starts with '\x16' or '\x80'
	28	(indicating SSL).
	29
	30	* Flash security policy: wsproxy detects flash security policy
	31	requests (again by sniffing the first packet) and answers with an
	32	appropriate flash security policy response (and then closes the
	33	port). This means no separate flash security policy server is needed
	34	for supporting the flash WebSockets fallback emulator.
	35
	36	* Session recording: This feature that allows recording of the traffic
	37	sent and received from the client to a file using the `--record`
	38	option.
	39
	40
	41	### Implementations
	42
	43	There are two implementations of wsproxy included: a python
	44	implementation and a C implementation.
	45
	46	Here is the feature support matrix for the wsproxy implementations:
	47
	48
	49	<table>
	50	<tr>
	51	<th>Implementation</th>
	52	<th>Basic Proxying</th>
	53	<th>Daemonizing</th>
	54	<th>SSL/wss</th>
	55	<th>Flash Policy Server</th>
	56	<th>Session Recording</th>
	57	</tr> <tr>
	58	<td>python</td>
	59	<td>yes</td>
	60	<td>yes</td>
	61	<td>yes 1</td>
	62	<td>yes</td>
	63	<td>yes</td>
	64	</tr> <tr>
65	<td>C</td>
66	<td>yes</td>
67	<td>yes</td>
68	<td>yes</td>
69	<td>yes</td>
70	<td>no</td>
71	</tr>
72	</table>
73
74	* Note 1: to use SSL/wss with python 2.5 or older, see the following
75	section on Building the Python ssl module.
76
77
78	### Building the Python ssl module (for python 2.5 and older)
79
80	* Install the build dependencies. On Ubuntu use this command:
81
6502293f	82	`sudo aptitude install python-dev bluetooth-dev`
e5d60a8b JM	83
	84	* Download, build the ssl module and symlink to it:
	85
6502293f JM	86	`cd noVNC/utils`
	87	`wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz`
	88	`tar xvzf ssl-1.15.tar.gz`
	89	`cd ssl-1.15`
	90	`make`
	91	`cd ../`
	92	`ln -sf ssl-1.15/build/lib.linux-*/ssl ssl`
e5d60a8b	93