diff --git a/README.md b/README.md index 7beb1682..c1286b4d 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,11 @@ There a few reasons why a proxy is required: host and port where the proxy is running and the password that the vnc server is using (if any). Hit the Connect button. +* If you are using python 2.3 or 2.4 and you want wsproxy to support + 'wss://' (TLS) then see the + [wsproxy README](http://github.com/kanaka/noVNC/blob/master/utils/README.md) + for instructions on building the ssl module. + ### Integration diff --git a/docs/browsers.md b/docs/browsers.md index 75a044ca..ad52fd31 100644 --- a/docs/browsers.md +++ b/docs/browsers.md @@ -116,9 +116,9 @@ accepting the certificate. Then return to noVNC and connect normally. -* Note 3: Browsers using WebKit build 66396 or later - (Chrome/Chromium after build 57838) have a Canvas rendering bug. The - WebKit bug is #46319. The noVNC bug is #28. diff --git a/docs/proxy_description.txt b/docs/proxy_description.txt deleted file mode 100644 index 83dfb1ce..00000000 --- a/docs/proxy_description.txt +++ /dev/null @@ -1,53 +0,0 @@ -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. - - -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). diff --git a/utils/README.md b/utils/README.md new file mode 100644 index 00000000..ac3e86d9 --- /dev/null +++ b/utils/README.md @@ -0,0 +1,93 @@ +## 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: + + + + + + + + + + + + + + + + + + + + + + + + + +
ImplementationBasic ProxyingDaemonizingSSL/wssFlash Policy ServerSession Recording
pythonyesyesyes 1yesyes
Cyesyesyesyesno
+ +* 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 +