Add or Change SSL/TLS certificate in Lotus Domino
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 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
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.
