How to use TLS and SHA-2 certificates in Domino Web Service Consumer


As many others, we have got bitten by the lack of TLS and SHA-2 support in IBM Domino.

Our application relies heavily on consuming web services that require authentication using certificates. And everything worked fine until last week. Then, one of the providers started requesting SHA-2 certificates for authentication and the other started requesting TLS instead of SSS v3.

Our current solution uses Java web consumers, similar to this:

ServiceBinding stub = new ServiceLocator().getWebService(portAddress);

Certificates are kept in the server's keyring.

How can we use SHA-2 certificates and TLS with Domino web consumers?

I tried importing the certificates in Java truststore / keystore and using code like this:

System.setProperty("", "/path/to/keystore");
System.setProperty("", "pwd);
System.setProperty("", "/path/to/truststore");
System.setProperty("", "pwd");

but it didn't seem to work. I am still debugging the code in order to find the exact cause.

But what to do with TLS? Is is possible to use Apache / Nginx as some kind of proxy for web service authentication?

Or is our only option to write web service consumers as standalone Java applications and call them from Notes?



We were able to solve both SHA-2 and TLS issues by using an Apache reverse proxy. We first tried with forward proxy, but it didn't work.

In the working solution, our Domino web service consumer first contacts the Apache reverse proxy using SSL, but without any authentication. Then Apache contacts the web service provider using the certificate that Domino used previously.

After Apache and web service provider finished handshake and authentication, it is free for the web service consumer in Domino to do its stuff.

As it turns out, it was rather easy to set up. You'll need an Apache server (obviously), we installed our in a CentOS virtual machine.

The configuration you need to do is quite simple and looks like this:

<VirtualHost *:8443>
    # Turn off forward proxy
    ProxyRequests Off

    # Communication with Domino is using SSL, so we need SSL support
    SSLEngine On
    SSLCertificateFile /etc/pki/tls/certs/localhost.crt
    SSLCertificateKeyFile /etc/pki/tls/private/localhost.key

    # This is necessary for authentication to work.
    SSLProxyEngine On
    # This is Domino certificate including private key saved as unecrypted pem file.
    SSLProxyMachineCertificateFile /etc/httpd/certs/domino-cert.pem
    # This is list of CA certificates necessary to authenticate the provider.
    SSLProxyCACertificateFile /etc/httpd/certs/provider-cert.pem

    # Redirection rules are in this case very simple - redirect everything that comes
    # to the proxy to the web service provider address.
    ProxyPass /
    ProxyPassReverse /

    # Allow only connections from Intranet.
    <Proxy *>
        Order deny,allow
        Deny from all
        Allow from

Just a few things to mention here:

  • You should be able to use certificate and key installed by default with Apache, as they are only used to secure communication between the Domino and the proxy.
  • Domino key and certificate must be in unencrypted pem format. Use openssl to convert if necessary. If you should get error message about missing or encrypted private key, open your pem certificate and confirm that it includes RSA in lines -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----. openssl sometimes generates certificate without the RSA and then Apache won't be able to use it.

That concludes the Apache configuration. The only thing that remains is to modify the web service consumer - find in your code the line where you set endpoint address, something like and change it to

And that's it. We now have working solution for using Domino web services together with TLS and SHA-2 certificates. And we can calmly wait for IBM to implement support for this in Domino.