Securing your WebSocket server with TLS

Datetime:2016-08-22 22:30:06          Topic: WebSocket           Share

This is the final post about WebSocket server installation. We will add TLS to the websocket server, so you can establish secure websocket connection.

Series Content

  1. Basic WebSocket Server Installation Guide for IBM Domino Server
  2. Setting up the websocket user
  3. Securing your WebSocket server with TLS
  4. Your first non-chat websocket app
  5. Adding server-side listener for persistence

Adding SHA-2 certificates to Domino

There are multiple great guides how to upgrade your Domino server using SHA-2 certificates. If you use a development server self-signed certificates are probably the easiest way to go. Please follow the directions of this guide:

Self-signed certificate guide

I have to admit, I have not succeeded to get WebSocket working on my server with self-signed certificates, however, now you can easily get free normal certificates from LetsEncrypt

Follow this guide, if you want to add SHA-2 certificates to your production server:

CA certificate guide

Tools needed

You will need two tools to execute the guides:


32-bit OpenSSL for Windows 64-bit OpenSSL for Windows



(Direct Dropbox link, so you don’t have to go through the painful IBM download process.)

Important note for 4k private keys

If you created a 4k (4096) key using the command below:

openssl genrsa -out server.key 4096

You will also need to patch your java policy files in



Read the guide here .

For your convenience, here is a download link to the files that you need to replace (instead of going through the awful IBM download process.)

unrestricted policy files

Adding SHA-2 certificate to the WebSocket server

Getting the private keys and certificates

a. OpenSSL

If you followed the guide above you will have access to the private key that you created with OpenSSL

You will need this private key in the next step. You will also need the certificates thet you received from CA or your self-signed certificate (ie. server.pem).

b. kyrtool

If you used the old-fashioned way of creating your server keys using certserv.nsf , then you need to get your keyring.kyr and keyring.sth files. You need to open a Command prompt window and navigate to the folder where you extracted the kyrtool.exe file. In my case I used the 64-bit kyrtool.exe and put it in my Domino server folder. I issue this command

kyrtool.exe show keys -k c:\domino\data\keyring.kyr

to get my private server key. You will see something like this

You can also access your certificates with this command:

kyrtool.exe show keys -k c:\domino\data\keyring.kyr

Save these into two files: csaba.key and csaba.pem  with these commands:

kyrtool.exe show keys -k c:\domino\data\keyring.kyr > c:\temp\csaba.key

kyrtool.exe show certs -k c:\domino\data\keyring.kyr > c:\temp\csaba.pem

Now you have your private keys and certs.

Creating keystore  for websocket

Open a new command prompt in  the OpenSSL/bin folder and type this command

openssl pkcs12 -export -name localhost -in csaba.pem -inkey csaba.key -out keystore.p12

  • Instead of localhost, use your servername:
  • Instead of csaba.key and csaba.pem use your own private key and certificate.
  • When it asks for an export password, enter a good one. (I entered password 2 for this example).

Navigate to your Domino\jvm\bin folder, where you find yet another tool called keytool.exe.  Copy your keystore.p12 file in this folder and issue this command:

keytool.exe -importkeystore -destkeystore websocket.jks -srckeystore keystore.p12 -srcstoretype pkcs12 -alias localhost

  • Instead of -alias localhost use your own server address.
  • when the command asks Destination keystore password, enter a new password, then repeat it. (I entered password3 for the example’s sake.)
  • Then, you will be asked for the source keystore password. Enter the password that you created in the previous step. (In my case, it’s password2 ).

Congratulations! You have just created your secure key (websocket.jks) for your websocket server.

Copy the websocket.jks file to your favorite folder. (I copied it to c:\Domino).

Modifying the WebSocket configuration document

Now the we have a proper secure key, we need to modify the websocket.nsf config document in order to use encrypted secure WebSocket connection. Open the websocket.nsf in your IBM Domino Admin application and edit the config document

Add these lines to the current config:





Also edit the first line to


Your config file should look like this:

Restart your server.

Testing the secure connection

Check your startup log in the console. It should look like this. There should a single error message but besides that, it should startup like this:

Open the chat.nsf in your browser:

You can see that the ws:// changed to wss:// which means that we have successfully established a secure encrypted websocket connection.

Well done, now you have a fully functional secure WebSocket server installed on your Domino server.

About List