FAQ: Secure WebSockets

Overview

• How to set up a server
• Trust a self signed certificate
• Debugging SSL/TLS Connections
• WSS on Android
• Handshake error on Android
• Allow specific cipher suites/protocols
• SSLHandshakeException with Let's Encrypt certificate

How to set up a server

Take a look at this example on how to use SSL for your websocket server.

Trust a self signed certificate

If you do not have a valid certificate in place then you will have to create a self signed one. Browsers will simply refuse the connection in case of a bad certificate and will not ask the user to accept it. So the first step will be to make a browser to accept your self signed certificate. ( https://bugzilla.mozilla.org/show_bug.cgi?id=594502 ).
If the websocket server url is wss://localhost:8000 visit the url https://localhost:8000 with your browser. The browser will recognize the handshake and allow you to accept the certificate. This technique is also demonstrated in this video.

Debugging SSL/TLS Connections

If you are having a problem with a certificate please take a look at this.

WSS on Android

If you want to use wss on the android platfrom you should take a look at this.

There is some additional info for generating certificates here: #1410.

Allow specific cipher suites/protocols

This lib allows you to use specific cipher suites/protocols for your connection. Specific endpoints may allow some ciphers and/or some ciphers are buggy.

Please take a look at the SSLServerCustomWebsocketFactoryExample for an example!

Handshake error on Android

SSL on Android is always a bit buggy. If you have the following issue, this may help you!

javax.net.ssl.SSLHandshakeException: Handshake failed
    at com.android.org.conscrypt.OpenSSLSocketImpl.startHandshake(OpenSSLSocketImpl.java:429)
    at com.android.org.conscrypt.OpenSSLSocketImpl.waitForHandshake(OpenSSLSocketImpl.java:682)
    at com.android.org.conscrypt.OpenSSLSocketImpl.getInputStream(OpenSSLSocketImpl.java:644)
    at org.java_websocket.client.WebSocketClient.run(WebSocketClient.java:260)
    at java.lang.Thread.run(Thread.java:761)
Caused by: javax.net.ssl.SSLProtocolException: SSL handshake aborted: ssl=0xaa19cb80: Failure in SSL library, usually a protocol error
error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER (external/boringssl/src/ssl/tls_record.c:192 0xa706d196:0x00000000)
    at com.android.org.conscrypt.NativeCrypto.SSL_do_handshake(Native Method)
    at com.android.org.conscrypt.OpenSSLSocketImpl.startHandshake(OpenSSLSocketImpl.java:357)
	... 4 more

This issue is known and it is recommended to remove the protocol SSLv3 for your websocket! (See SSLServerCustomWebsocketFactoryExample)

SSLHandshakeException with Let's Encrypt certificate

Java requires the full certificate chain for a Let's Encrypt certificate.

This chain is missing, if you get an exception like this while you try to connect to the server:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

The server just has to include the chain certificate and the issue should be solved (see also #706)