]>
Commit | Line | Data |
---|---|---|
71ba9a7a | 1 | ## WebSockets Utilities: wswrapper and wsproxy |
e5d60a8b JM |
2 | |
3 | ||
71ba9a7a JM |
4 | ### wswrapper |
5 | ||
6 | wswrapper is an LD_PRELOAD library that converts a TCP listen socket | |
7 | of an existing program to a be a WebSockets socket. The `wswrap` | |
8 | script can be used to easily launch a program using wswrapper. Here is | |
9 | an example of using wswrapper with vncserver. wswrapper will convert | |
10 | the socket listening on port 5901 to be a WebSockets port: | |
11 | ||
12 | `cd noVNC/utils` | |
13 | ||
14 | `./wswrap 5901 vncserver -geometry 640x480 :1` | |
15 | ||
16 | ||
17 | ### wsproxy | |
e5d60a8b JM |
18 | |
19 | At the most basic level, wsproxy just translates WebSockets traffic | |
20 | to normal socket traffic. wsproxy accepts the WebSockets handshake, | |
21 | parses it, and then begins forwarding traffic between the client and | |
22 | the target in both directions. WebSockets payload data is UTF-8 | |
23 | encoded so in order to transport binary data it must use an encoding | |
24 | that can be encapsulated within UTF-8. wsproxy uses base64 to encode | |
25 | all traffic to and from the client. Also, WebSockets traffic starts | |
26 | with '\0' (0) and ends with '\xff' (255). Some buffering is done in | |
27 | case the data from the client is not a full WebSockets frame (i.e. | |
28 | does not end in 255). | |
29 | ||
30 | ||
71ba9a7a | 31 | #### Additional wsproxy features |
e5d60a8b JM |
32 | |
33 | These are not necessary for the basic operation. | |
34 | ||
35 | * Daemonizing: When the `-f` option is not specified, wsproxy runs | |
36 | in the background as a daemon process. | |
37 | ||
38 | * SSL (the wss:// WebSockets URI): This is detected automatically by | |
39 | wsproxy by sniffing the first byte sent from the client and then | |
40 | wrapping the socket if the data starts with '\x16' or '\x80' | |
41 | (indicating SSL). | |
42 | ||
43 | * Flash security policy: wsproxy detects flash security policy | |
44 | requests (again by sniffing the first packet) and answers with an | |
45 | appropriate flash security policy response (and then closes the | |
46 | port). This means no separate flash security policy server is needed | |
47 | for supporting the flash WebSockets fallback emulator. | |
48 | ||
49 | * Session recording: This feature that allows recording of the traffic | |
50 | sent and received from the client to a file using the `--record` | |
51 | option. | |
52 | ||
53 | ||
71ba9a7a | 54 | #### Implementations of wsproxy |
e5d60a8b | 55 | |
2574936f JM |
56 | There are three implementations of wsproxy: python, C, and Node |
57 | (node.js). wswrapper is only implemented in C. | |
e5d60a8b | 58 | |
2574936f JM |
59 | Here is the feature support matrix for the the wsproxy implementations |
60 | and wswrapper: | |
e5d60a8b JM |
61 | |
62 | ||
63 | <table> | |
64 | <tr> | |
90966d62 JM |
65 | <th>Feature\Program</th> |
66 | <th>wsproxy.py</th> | |
67 | <th>wsproxy</th> | |
68 | <th>wsproxy.js</th> | |
69 | <th>wswrap/wswrapper</th> | |
70 | </tr> | |
71 | <tr> | |
2574936f | 72 | <th>Language</th> |
e5d60a8b | 73 | <td>python</td> |
90966d62 JM |
74 | <td>C</td> |
75 | <td>Node (node.js)</td> | |
76 | <td>C</td> | |
77 | </tr> | |
78 | <tr> | |
79 | <th>Primary Function</th> | |
80 | <td>proxy</td> | |
2574936f | 81 | <td>proxy</td> |
90966d62 JM |
82 | <td>proxy</td> |
83 | <td>interposer</td> | |
84 | </tr> | |
85 | <tr> | |
86 | <th>Multi-process</th> | |
e5d60a8b | 87 | <td>yes</td> |
fd758dd3 | 88 | <td>yes</td> |
e5d60a8b | 89 | <td>yes</td> |
90966d62 JM |
90 | <td>indirectly</td> |
91 | </tr> | |
92 | <tr> | |
93 | <th>Daemonize</th> | |
e5d60a8b | 94 | <td>yes</td> |
e5d60a8b | 95 | <td>yes</td> |
90966d62 JM |
96 | <td>no</td> |
97 | <td>indirectly</td> | |
98 | </tr> | |
99 | <tr> | |
100 | <th>SSL/wss</th> | |
101 | <td>yes 1</td> | |
e5d60a8b | 102 | <td>yes</td> |
90966d62 JM |
103 | <td>no</td> |
104 | <td>no</td> | |
105 | </tr> | |
106 | <tr> | |
107 | <th>Flash Policy Server</th> | |
e5d60a8b | 108 | <td>yes</td> |
fd758dd3 JM |
109 | <td>yes</td> |
110 | <td>no</td> | |
90966d62 | 111 | <td>no</td> |
fd758dd3 | 112 | </tr> |
90966d62 JM |
113 | <tr> |
114 | <th>Web Server</th> | |
fd758dd3 | 115 | <td>yes</td> |
fd758dd3 JM |
116 | <td>no</td> |
117 | <td>no</td> | |
118 | <td>no</td> | |
e5d60a8b | 119 | </tr> |
90966d62 JM |
120 | <tr> |
121 | <th>Session Recording</th> | |
122 | <td>yes</td> | |
2574936f JM |
123 | <td>no</td> |
124 | <td>no</td> | |
125 | <td>no</td> | |
126 | </tr> | |
e5d60a8b JM |
127 | </table> |
128 | ||
129 | * Note 1: to use SSL/wss with python 2.5 or older, see the following | |
130 | section on *Building the Python ssl module*. | |
131 | ||
132 | ||
133 | ### Building the Python ssl module (for python 2.5 and older) | |
134 | ||
135 | * Install the build dependencies. On Ubuntu use this command: | |
136 | ||
6502293f | 137 | `sudo aptitude install python-dev bluetooth-dev` |
e5d60a8b JM |
138 | |
139 | * Download, build the ssl module and symlink to it: | |
140 | ||
6502293f | 141 | `cd noVNC/utils` |
3dc3135b | 142 | |
6502293f | 143 | `wget http://pypi.python.org/packages/source/s/ssl/ssl-1.15.tar.gz` |
3dc3135b | 144 | |
6502293f | 145 | `tar xvzf ssl-1.15.tar.gz` |
3dc3135b | 146 | |
6502293f | 147 | `cd ssl-1.15` |
3dc3135b | 148 | |
6502293f | 149 | `make` |
3dc3135b | 150 | |
6502293f | 151 | `cd ../` |
3dc3135b | 152 | |
6502293f | 153 | `ln -sf ssl-1.15/build/lib.linux-*/ssl ssl` |
e5d60a8b | 154 |