Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Generating an encryption certificate
To encrypt the traffic using the WebSocket 'wss://' URI scheme you
need to generate a certificate for the proxy to load. By default the
proxy loads a certificate file name
self.pem but the
option can override the file name. You can generate a self-signed
certificate using openssl. When asked for the common name, use the
hostname of the server where the proxy will be running:
openssl req -new -x509 -days 365 -nodes -out self.pem -keyout self.pem
Accepting a self-signed certificate in the browser
Most browser WebSocket implementations now require self-signed certificates to be accepted by the browser. Unfortunately browsers will not pop up a message for accepting certificates for encrypted WebSocket connections (WSS) like they do for normal encrypted HTTP connections (HTTPS).
Certificate problems will manifest in different ways in different browsers:
In Safari (desktop or iOS) the browser will often just refuse to connect and the connection to websockify is terminated.
In firefox, the browser will refuse to connect and websockify will close the connection and print a message similar to:
handler exception: [Errno 1] _ssl.c:392: error:14094418:SSL routines:SSL3_READ_BYTES:tlsv1 alert unknown ca
In Chrome 19 and newer, the browser will refuse to connect and websockify will close the connection and print a message similar to:
handler exception: [Errno 336265225] _ssl.c:351: error:140B0009:SSL routines:SSL_CTX_use_PrivateKey_file:PEM lib
This means that the certificate used by the websockify for the encrypted connection is not properly signed for the domain it is running on (and firefox only shows the certificate error dialog for normal HTTPS URLs not for WebSocket connections).
If you are using a self-signed certificate, you can force the browser to recognize the certificate by browsing directly to the WebSocket port using a regular HTTPS URL. The certificate warning message should be shown.
For example, in firefox, click "I Understand the Risks", then click "Add Exception...", then select "Permanently store this exception", and finally click "Confirm Security Exception". The certificate should now be permanently accepted by firefox for both HTTPS and WebSocket WSS connections. The method should be similar in Safari for accepting a self-signed certificate.
Self-signed certificates with iOS (iPod/iPhone/iPad/)
In order to use a self-signed certificate with iOS, there are two additional requirements:
- The certificate subject "common name" must match the hostname.
- The certificate must be imported manually.
There are two known ways of importing the certificate:
- Provide a link to the cert on a web page.
- Attach the cert to an email. Open up the email from the iOS device, touch the attachment and the wizard to import it will show up.
After doing this, you will have a "Profile" installed, and encrypted websockets should work.
See issue 124 for more discussion of encrypted connection issues.