Add or Change SSL/TLS certificate in Lotus Domino

Add or Change SSL/TLS certificate in Lotus Domino
Security Linux

Add or Change SSL/TLS certificate in Lotus Domino

SSL/TLS certificates don’t last forever, most of them need to be renewed on a yearly cycle and occasionally you will want to change the type of the SSL certificate mid-cycle.

Lotus Notes SSL/TLS

For work with ssl/tls certificates in the lotus notes are used with the kyrtool program.

You can download kyrtool from this IBM website . Or direct from our web site .

To install, uncompress the zip file in your Notes/Domino program directory, or you can use any directory. In order to run on Windows, launch kyrtool.exe. To run on Linux, launch /opt/ibm/domino/bin/tools/startup kyrtool as shown below. The exact path to the startup command on Linux will vary based on your Notes/Domino installation path. If the tool is not being run from the same directory as your notes.ini file, the =/path/to/notes.ini parameter is required as shown below.

Prerequisites

  • we need to use a user other than root to work with the kyrtool program (in our case we use a notes user)

  • we unzip kyrtool to /home/notes/kyrtool directory

  • we use 64-bit linux kernel system, so our working directory will be /home/notes/kyrtool/linux64

  • file /home/notes/kyrtool/linux64/kyrtool has executable permissions, e.g. chmod 755 /home/notes/kyrtool/linux64/kyrtool

  • full path to lotus domino startup program is /opt/ibm/domino/bin/tools/startup (depend on your Lotus Domino install directory)

  • full path to notes.ini file is /mnt/notes/data/notes.ini (depend on your Lotus Domino install directory)

  • we have a full SSL certificate chain with your domain SSL/TLS certificate, key to your domain SSL/TLS certificate and intermediate certificate(s) in pem format (clear text)

  • our domain name is secar.cz, SSL/TLS certificate is wildcard certificate *.secar.cz

  • when configuring parameters as e.g. filenae, we must use a full path, never a relative location

SSL/TLS certificates

Assume, we have a 3 files:

  • our_domain.key - this is a key to our SSL/TLS domain certificate in PEM format

  • our_domain.crt - this is SSL/TLS certificate in PEM format (clear text using base64 coding)

  • ca_intermediate.crt - this is intermediate certificate from our certiciate authority (e.g. Symantec, Thawte, Geotrust) in PEM format

  • ca_root_certificate.crt - this is a root ssl/tls certificate of our certicate authority

We create a single file our_domain.pem, which includes a key to certificate, a certificate for our domain, and all intermediate certificates whith root ca certificate in the correct order:

~] su - notes
~] cd /home/notes/kyrtool/linux64 
~] cat our_domain.key our_domain.crt ca_intermediate.crt ca_root_certificate.crt > our_domain.pem

Our directory with all in one file our_domain.pem:

~] ls -alFh
drwxr-xr-x. 2 notes notes 4,0K 13. pro 13.47 ./
drwxrwxr-x. 6 notes notes 4,0K 13. pro 12.46 ../
-rw-rw-r--. 1 notes notes 1,7K 13. pro 13.21 ca_intermediate.crt
-rw-rw-r--. 1 notes notes 1,3K 13. pro 13.46 ca_root_certificate.crt
-rwxr-xr-x. 1 notes notes  52K  3. lis  2014 kyrtool*
-rw-rw-r--. 1 notes notes 2,2K 13. pro 13.20 our_domain.crt
-rw-rw-r--. 1 notes notes 1,7K 13. pro 13.12 our_domain.key
-rw-rw-r--. 1 notes notes 6,8K 13. pro 13.47 our_domain.pem

Our all in one file our_domain.pem has this example structure:

~] cat our_domain.pem
—–BEGIN RSA PRIVATE KEY—– 
(Your Private Key: our_domain.key) 
—–END RSA PRIVATE KEY—– 
—–BEGIN CERTIFICATE—– 
(Your Primary SSL certificate: our_domain.crt) 
—–END CERTIFICATE—– 
—–BEGIN CERTIFICATE—– 
(Your Intermediate certificate: ca_intermediate.crt) 
—–END CERTIFICATE—– 
—–BEGIN CERTIFICATE—– 
(Your Root certificate: ca_root_certificate.crt) 
—–END CERTIFICATE—–

KYRTOOL

We can show a help to kyrtool program:

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini -h


        KyrTool v1.0

kyrtool [=/path/to/notes.ini] command [subcommand] [flags]

Commands:
        create           Create a new keyring file
        delete           Delete a root in a keyring file
        import           Import into a keyring file
        show             Show information about a keyring file
        verify <path>    Verify the content of a PEM import file

Use 'kyrtool [command] -h' to view help for each command.

The keyring password is stored in the STH file and will be
automatically read when using an existing keyring file.

Help to create kyrtool subcommand is:

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini create -h


        KyrTool v1.0

kyrtool create [flags]

Creates a new Domino SSL keyring file

'Create' flags:
        -h               Display this help message and exit
        -k <path>        Path to keyfile (Mandatory)
        -p <password>    Keyring password (Mandatory)
        -v               Verbose mode; repeating increases verbosity level

Create sth and kyr files

We create a lotus domino keyring (sth and kyr file) with name dominoB.(kyr|sth) and password 12345

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini create -k /home/notes/kyrtool/linux64/dominoB.kyr -p 12345

Keyfile /home/notes/kyrtool/linux64/dominoB.kyr created successfully

Check your directory:

~] ls -alFh
-rw-rw-r--. 1 notes notes 1,7K 13. pro 13.21 ca_intermediate.crt
-rw-rw-r--. 1 notes notes 1,3K 13. pro 13.46 ca_root_certificate.crt
-rw-rw-r--. 1 notes notes  29K 13. pro 13.49 dominoB.kyr
-rw-------. 1 notes notes  129 13. pro 13.49 dominoB.sth
-rwxr-xr-x. 1 notes notes  52K  3. lis  2014 kyrtool*
-rw-rw-r--. 1 notes notes 2,2K 13. pro 13.20 our_domain.crt
-rw-rw-r--. 1 notes notes 1,7K 13. pro 13.12 our_domain.key
-rw-rw-r--. 1 notes notes 6,8K 13. pro 13.47 our_domain.pem

Verity our all in one certificates and key file our_domain.pem

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini verify /home/notes/kyrtool/linux64/our_domain.pem 


        KyrTool v1.0

Successfully read 2048 bit RSA private key
INFO: Successfully read 3 certificates
INFO: Private key matches leaf certificate
INFO: IssuerName of cert 0 matches the SubjectName of cert 1
INFO: IssuerName of cert 1 matches the SubjectName of cert 2
INFO: Final certificate in chain is self-signed

Import our key and certificates chain to lotus domino keyring

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini import all -k /home/notes/kyrtool/linux64/dominoB.kyr -i /home/notes/kyrtool/linux64/our_domain.pem 

Using keyring path '/home/notes/kyrtool/linux64/dominoB.kyr'
Successfully read 2048 bit RSA private key
SECIssUpdateKeyringPrivateKey succeeded
SECIssUpdateKeyringLeafCert succeeded

Verify that we have all the necessary certificates in the lotusu domino keyring

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini show certs -k /home/notes/kyrtool/linux64/dominoB.kyr

Using keyring path '/home/notes/kyrtool/linux64/dominoB.kyr'


Certificate #0

Subject:        CN=*.secar.cz
Issuer:         CN=RapidSSL TLS RSA CA G1/OU=www.digicert.com/O=DigiCert Inc/C=US
Not Before:     21.08.2018 02:00:00
Not After:      23.02.2020 13:00:00
Key length:     2048 bits
Signature Alg:  sha256WithRSAEncryption

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Certificate #1

Subject:        CN=RapidSSL TLS RSA CA G1/OU=www.digicert.com/O=DigiCert Inc/C=US
Issuer:         CN=DigiCert Global Root G2/OU=www.digicert.com/O=DigiCert Inc/C=US
Not Before:     02.11.2017 13:24:33
Not After:      02.11.2027 13:24:33
Key length:     2048 bits
Signature Alg:  sha256WithRSAEncryption

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Certificate #2

Subject:        CN=DigiCert Global Root G2/OU=www.digicert.com/O=DigiCert Inc/C=US
Issuer:         CN=DigiCert Global Root G2/OU=www.digicert.com/O=DigiCert Inc/C=US
Not Before:     01.08.2013 14:00:00
Not After:      15.01.2038 13:00:00
Key length:     2048 bits
Signature Alg:  sha256WithRSAEncryption

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Verify that private key matches our ssl/tls wildcard certificate 

~] /opt/ibm/domino/bin/tools/startup kyrtool =/mnt/notes/data/notes.ini show keys -k /home/notes/kyrtool/linux64/dominoB.kyr

Using keyring path '/home/notes/kyrtool/linux64/dominoB.kyr'

Key length: 2048 bits

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

Key length: 2048 bits

-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

You have to your public certificate (public key) and private key.

Install new keyring or replace old keyring with new one

Our new lotus domino keyring has two files: dominoB.kyr and dominoB.sth. Copy new keyring or replace old keyring with new one in your lotus domino data directory. Our lotus domino data directory is /mnt/notes/data/.

~] cp dominoB.kyr /mnt/notes/data/dominoB.kyr
~] cp dominoB.sth /mnt/notes/data/dominoB.sth

Set the appropriate permissions on the SSL key ring files to ensure the Domino server can access the files. In our Production Environment our lotus domino server run as notes user

~] chown notes:notes /mnt/notes/data/dominoB.kyr
~] chown notes:notes /mnt/notes/data/dominoB.sth

Check, that you have a right lotus domino keyring in Domino administrator.

Screen capture of SSL settings in Server document Screen capture of SSL settings in Server document

Restart the HTTP task by issuing the command "tell http restart" on the Domino server console. If other tasks need to use the keyring, restart those tasks.

Check you have a right install ssl/tls certificate

SUBSCRIBE FOR NEW ARTICLES

@
comments powered by Disqus