Encrypted Connections

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 --cert=CERT 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.

WARNING: This is very insecure as that certificate can now be used to spoof any site the device visits. It should only be used for testing and the certificate should be removed from the device afterwards.

Other info

See issue 124 for more discussion of encrypted connection issues.