How to import a wildcard SSL certificate into a Domino Key Ring

Some customers are using wildcard SSL certificates in their environments and want to use them for accessing the Domino environments via Traveler and WebMail.

What you’ll need:

To use those wildcard certificates you have to go through the following steps ( I did this on my Windows machine ):

First you have to to export the wildcard certificate from the PFX file:

c:\openssl\bin\openssl pkcs12 – in <path-to-pfx> -out <path-to-pem> -nodes -chain


This generates the following file:


You can open this file for example with NotePad++ and you will see the following content with all intermediates, root certificates and also the private key:


In my case you now have the private key, the certificate, the intermediate and the root certificate in the PEM file. To go on I created a new text file and copied the content from the PEM file over – with the following order:

  • Private Key
  • Certificate
  • Intermediate
  • Root






To check if everything is fine you can check with the KyrTool by entering the following command:

C:\HCL\Notes>kyrtool.exe verify c:\wildcard\wildcard.txt


If you don´t receive any error >> Congrats !!

Now you´re ready to create a KYR file, import the content of the text file ( in this case it was “wildcard.txt” ), move the KYR and STH file to your Domino Server, customize the setting in the Server Document/Website, restart your HTTP server and grab a beer.

The way how to generate the KYR file, … is documented here ( starting at 5. )



Extracting Private Key from PFX file and generating a KYR file

Today I had to create a new certificate at customer site because of a Shitrix attack and had to extract the private key from the PFX file.

It´s quite easy running the following command:

openssl pkcs12 -in path:/myfile.pfx -nocerts -out path:/private-key.pem -nodes

Enter Import Password: password

With this command you extract the private key AND the certificate which you can use for creating the KYR file needed for your Domino environment. You can find your private key and the certificate in the file “path:/private-key.pem” and can copy the text between and encluding —BEGIN PRIVATE KEY— and —END CERTIFICATE—.


Request is empty and command SendMail is expected to have a body.

Today I had the issue on a customer site that no iOS device was able to send mail after upgrading Traveler to on Domino 9.0.1 FP10IF3, implementing a new wildcard certificate and reconfiguring the HTTP server to redirect HTTP calls to HTTPs.

After some investigation I checked the console log and discovered multiple error messages:

[12DC:000C-0FEC] 10.12.2019 08:39:06 Traveler: WARNING username´s Request is empty and command SendMail is expected to have a body.

After rechecking the server document of the Notes Traveler server I checked the entry for the external URL >> So the company did not use SSL certificates for the communication of mobile devices with their Traveler !!! Therefore no NOTES.INI entry called “NTS_EXTERNAL_URL=https://….” was set.

A small correction of the entry in the server document, setting the NOTES.INI entry via “set configuration NTS_EXTERNAL_URL= UPDATE” and a restart of the Traveler service was only half the way.

If you have this configuration of configured profiles on iOS devices WITHOUT SSL ( hopefully no one is using this anymore ) you have to remove and recreate the profile because you can´t modify the account to use SSL !

Generating a keyring file with a third party CA SHA-2 cert using OpenSSL and KYRTool on a Windows workstation

Official Step-By-Step guide

1. Before you begin, note the following information about running KYRTool & OpenSSL

If you have a command line parameter with spaces in it, such as the path to a file, the space can cause the command line to be read incorrectly, resulting in errors. This can affect running commands for both OpenSSL and KYRTool
To include a space in a parameter, the parameter must be delimited with quotation marks. For example, if Notes were installed in the Program Files directory, then the command line for creating a keyring might look like this:

kyrtool =”c:\Program Files\IBM\Notes\notes.ini” create -k “c:\Program Files\IBM\Notes\data\keyring.kyr” -p password

1a. KYRTool

Download link:

Place the KYRTool in the Notes program directory, as it relies on .DLLs installed by Notes.
If you have the Notes/Domino program directory in your system’s PATH environment variable, this can be installed to any directory.

1b. OpenSSL

Download links for the Windows versions of OpenSSL are available at

The light version of OpenSSL is sufficient for the tasks required for creating a SHA-2 certificate. v1.0.1j is the latest recommended release as of December 2014. Either the 32-bit or 64-bit version can be used if you are on Windows 7.
OpenSSL may need updates to Windows Visual C++ libraries. If the libraries are not up to date, a prompt will display during the OpenSSL install noting that updated Visual C++ libraries are needed. Links for downloading these libraries are also on the download page for OpenSSL.
A configuration file “openssl.cfg” will be extracted by the installer to the bin directory. In order for OpenSSL to read this configuration file, you must set an environment variable by running the following command from a DOS prompt

SET OPENSSL_CONF=\openssl.cfg
e.g. SET OPENSSL_CONF=c:\OpenSSL-Win64\bin\openssl.cfg

You run OpenSSL from the “openssl.exe” file, which is found in the \bin directory of the OpenSSL install. Open a command prompt window in this directory to run it. If you double click on openssl.exe, it will open in a DOS command window. If you launch OpenSSL this way, you enter only the name of the OpenSSL function in the command window. For example, instead of typing “openssl genrsa…” you would enter “genrsa…”

2. Generate an RSA keypair using OpenSSL
[~]$ openssl genrsa -out server.key 4096

Generating RSA private key, 4096 bit long modulus
e is 65537 (0x10001)

The resulting keypair should not be password protected. This isn’t a good security practice, so only perform these steps for production systems on a restricted access system believed to be secure. The resulting keypair should look like the following:
[C:\] type server.key

[Many lines removed]

3. Generate a Certificate Signing Request (CSR) using OpenSSL

NOTE: If a config file for OpenSSL is not defined by an environment variable, a user may not be able to create a csr with the “openssl req” command, and will receive the following message when running the command. “Unable to load config info from /usr/local/ssl/openssl.cnf”. See Step 1b above to resolve this.

This step prompts you for information that should be in your final certificate, bundles that up along with the public half of the RSA keypair that was just generated, and signs the whole thing with the private half of the keypair. In this example, everything was left blank except for the DNS name of the SSL test server. Note the “-sha256”, as the default algorithm for current versions of OpenSSL is SHA-1.

[~]$ openssl req -new -sha256 -key server.key -out server.csr

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
Country Name (2 letter code) [XX]:.
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:.
Organization Name (eg, company) [Default Company Ltd]:.
Organizational Unit Name (eg, section) []:.
Common Name (eg, your name or your server’s hostname) []
Email Address []:

Please enter the following ‘extra’ attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

[C:\] type server.csr

[Many lines removed]

4. Acquire an SSL/TLS certificate from a third party CA

This process varies from CA to CA, but you generally copy the certificate request block from above into a web form and pick what signing algorithm you would like the CA to use. Feel free to select one of the SHA-2 algorithms (SHA-256, SHA-384, and SHA-512) — the resulting keyring file will work just fine on any 9.0.x server, even those without the hotfix for TLS and SHA-2.

You will receive a certificate just like the one created in the self-signed steps. This can be displayed by using the “type” command from a command prompt or by opening the file in Notepad.

[C:\] type server.pem
[Many lines removed]

You may also receive some of the CA’s intermediate root certificates. Also note that the file received may be a .crt instead of .pem. The .crt file will act the same as a .pem when you display it.

5. Create a new keyring file

At this point in the example, the Administrator switched from the Linux box where OpenSSL was run to a Windows box to use kyrtool.exe.

[C:\] kyrtool =c:\lotus\notes\notes.ini create -k c:\lotus\notes\data\keyring.kyr -p password
Keyfile c:\lotus\notes\data\keyring.kyr created successfully

2 [C:\Lotus\Notes\Data] dir keyring*
Volume in drive C is C_Drive
Volume Serial Number is 306D-00D5

Directory of C:\Lotus\Notes\Data

10/08/2014 02:15 PM 29,161 keyring.kyr
10/08/2014 02:15 PM 129 keyring.sth
2 File(s) 29,290 bytes
0 Dir(s) 400,743,673,856 bytes free

6. Import the RSA keypair and self-signed certificate into the new keyring file

6a. Concatenate server.key and server.pem into a single file:

This step varies from the self-signed case. You will have more than one certificate in your “.pem” file, and will want to place them in order with your server’s SSL “leaf” certificate first and the root certificate last. Verify step 6b will check to ensure that the ordering is correct. If it returns any warnings or errors, edit the PEM file and verify it again.

Note the following:

Certificate Authorities will frequently return a signed certificate in a .crt file. If they also provide the root certificates when returning the CSR file, then you can concatenate all of the .crt files to the private key by using the “type” command from a DOS prompt.

The files should be concatenated with the server key first, the server’s cert next, the intermediate cert next, and the root cert last. Concatenation can be done from a DOS prompt using the TYPE command. The type command takes a list of files, and appends them together into an output file designated with a greater-than symbol. For example, type server.key server.crt intermediate.crt root.crt > server.txt In this example “server.txt” is the file provided to the kyrtool for import into a Domino keyring. You can display this output file in Notepad.

If the root and intermediate certs are not provided with the signed certificate, export the intermediate and root certificates by opening the server certificate with Windows Crypto Extensions. This will display the server in a three-tabbed user interface. On the third tab, select each of the signing certificates, select display, and then export that certificate using the “save to file” command on the second tab. Save each cert file using Base 64 format.

6b. Verify the Input file:

This is an example of a complete and correctly ordered PEM file:

[C:\] kyrtool =c:\lotus\notes\notes.ini verify c:\lotus\notes\data\ssl\server.txt

KyrTool v1.0

Successfully read 2048 bit RSA private key
INFO: Successfully read 4 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: IssuerName of cert 2 matches the SubjectName of cert 3
INFO: Final certificate in chain is self-signed

If you receive any ERROR: lines, you should resolve those errors before moving on to step 6c.

6c. Import the keypair and self-signed certificate:

[C:\] kyrtool =c:\lotus\notes\notes.ini import all -k c:\lotus\notes\data\keyring.kyr -i c:\lotus\notes\data\ssl\server.txt

Using keyring path ‘c:\lotus\notes\data\keyring.kyr’
Successfully read 4096 bit RSA private key
SECIssUpdateKeyringPrivateKey succeeded
SECIssUpdateKeyringLeafCert succeeded

7. Examine the resulting keyring file

[C:\] kyrtool =c:\lotus\notes\notes.ini show keys -k c:\lotus\notes\data\keyring.kyr
[C:\] kyrtool =c:\lotus\notes\notes.ini show certs -k c:\lotus\notes\data\keyring.kyr

8. Copy over your new keyring file and start the Domino server

Back up your old .kyr and .sth files, shut down the server, copy over your new keyring and stash files, restart the server, and check out the results!

Ask the Experts session: Ask us anything about SSL and Certificates

Join Paul Johnson and other members of the IBM Domino team for an Ask the Experts session titled “Ask us anything about SSL and Certificates.” We’ll begin the session with a short demo or presentation but the main focus of the session is Q&A. So bring your questions!

Topic: Ask the Experts session: Ask Us Anything About SSL and Certificates
Date: Tuesday, December 16, 2014
Time: 11:00 AM EST for 60 minutes
Webcast URL:
Webcast Password:  webcast

For a list of world-wide phone numbers, the phone passcode, and an iCalendar (.ics) file for this session, click here:

Note: Audiocast will not be available for this session. An audio replay of the session will be posted to Technote 7044211 soon after the event.