This is the final post about WebSocket server installation. We will add TLS to the websocket server, so you can establish secure websocket connection.
- Basic WebSocket Server Installation Guide for IBM Domino Server
- Setting up the websocket user
- Securing your WebSocket server with TLS
- Your first non-chat websocket app
- Adding server-side listener for persistence
October 3rd 2016 update
I have modified this post to take advantage of the proxy handler in the websocket server, in order to take advantage of using a single port for both websocket and http traffic.
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
You will need two tools to execute the guides:
OpenSSLOpenSSL 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
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).
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.crt 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.crt
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.crt -inkey csaba.key -out keystore.p12
- Instead of localhost, use your servername: example.com.
- Instead of csaba.key and csaba.crt use your own private key and certificate.
- When it asks for an export password, enter a good one. (I entered password2 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
Reconfiguring Domino backend:
Open your website document and reconfigure your internet ports:
Open your website default sttings in the Internet Site tab and edit the security settings and disable Redirect TCP to SSL:
Restart your server.
Testing the secure connection
Check your startup log in the console. It should look like this. There should not be any error in your console log:
Open the chat.nsf in your browser, notice that the https and wss connections do not have any special ports, they both connect through port 443.
Also notice 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 using a single 443 port for both ws and https traffic.