TomEE: SSL/TLS Secured Websockets

In a previous article, WebSocket and Lock it! we showed how to use basic authentication on websocket calls to an application deployed on TomEE.

In this article, we explain how to add SSL/TLS security to the connection between the client and the application server. To demonstrate this, we’ve created a new wss-secured-websocket project. This work is valid both for Secure Websocket (WSS) and HTTPS.

Adding transport layer security is important in order to protect the data exchange. Payloads and headers are sent in clear text when using simple HTTP. This is critical when considering the authentication header. As you can see here, basic authentication sends the username and password encoded in base64, which is a simple encoding algorithm that is easily decoded:

To prevent a third party from decoding the authentication header and stealing the credentials, the use of SSL/TLS.

SSL/TLS

Secure Socket Layer (SSL) and Transport Layer Security (TLS) refers to the handshake that takes place between a client and a server. The handshake doesn’t actually do any encryption itself, it just agrees on a shared secret and the type of encryption that is going to be used. TLS is just a new name for SSL v4 – essentially, we are talking about the same protocol. Apart from WSS and HTTPS, the SSL/TLS protocol is also used by other services, like SMTPS (Secure, Simple Mail Transfer Protocol) and FTPS (Secure, File Transfer Protocol).

The security of the connection is ensured by the data encryption. For that, the server needs an SSL/TLS certificate binding the identity to a key pair: the public and private encryption keys. The certificates are not dependent on the protocols and can be used with SSL and TLS.

On production servers, you will need a certificate created by a Certificate Authority (CA), someone that will verify that you are a good guy. The CAs have their own certificates in order to:

Issue a trusted public key, placed in web browsers like Firefox or Chrome or in the trusted certificates of the JRE at $JAVA_HOME/jre/lib/security/cacerts.

Issue Certificate Signing Requests (CSR) used by your server in the encryption process.

In the demo project, you have the instructions to create a CA and CSR certificates and the files created in the process, for demonstration purposes. In the end, you will have a keystore with the certificate chain and the private key stored, in the case of the demo, under the alias tomcat.

If you place the public key of the generated CA certificate in the browser trusted store, the encrypted communication will also be validated as originated in a trusted party, showing a green message in the address bar.

During development, it self-signedor developers to use a self-signed certificate for their servers. Instructions to generate a keystore with a self signed certificate are also available on the project. This places a single-element certificate chain for localhost and a private key under the alias tomcat, the one we use in the demo project.

Configure SSL/TLS on TomEE

To get started, we need to set up basic authentication configuration from the secured-websocket project previous article. In the previous article we showed, among other things how to:

Set the src/main/webapp/WEB-INF/web.xml for basic authentication in the app.

Set the src/main/conf/tomcat-users.xml with the server side user credentials.

How to send the authorization header with the credentials in all client requests.

The WebSocketResourceJEE7Test will be executed. You can also run it on your IDE.

Apart from the configurations, we did before, now we have a keystore.jks file and we need to configure the server.xml from TomEE. All this can be found in the wss-secured-websocket/src/main/conf folder of the project.

To activate SSL/TLS we need to activate the related connector in the server.xml.

Bruno is a well versed Java and Open Source technology developer and a Senior Software Engineer at Tomitribe. With over 10 years as an enterprise level engineer, he has lead QA and development teams, garnered skills in design and development process. brunobat_