Task:
Create new CSR for TLS 1.2 or higher (SSL) certificates for installation on Domino only, or a mixed bag of Domino and Apache or other open-source servers.
The Domino Administration certificate app assumes that the keyring and key are for a single domain name and not a UCC or wildcard one. One way to circumvent the issue is to use GSKit or OpenSSL to do all the work of creating and filling the keyring file. These steps are compliant for modern browsers. The kyrtool Domino tool can import the new multiple-domain certs.
Options:
Option A: OpenSSL and IKeyman
Use when you need to install on multiple server types for easier conversion between formats, and the certificates are not in CRT or PEM formats.
Option B: For Domino only
Use the kyrtool command line using CRT or PEM files with the kyrtool to create the kyr file.
Option C: Domino Kyrtool Renewal
Use for Domino renewals with kyrtool (mydomain.kyr) using the crt files from the Apache or Tomcat servers. No OpenSSL steps required.
HINTS:
- Beginning in 9.0.1 FP3, there was a new Kyrtool (32 bit on MS Windows, 64 bit on Linux) that came out. If you are running any of the current releases, this kyrtool supports 4096 bit keyring kyr files.
- For third-party renewals, where a new "key" file, and "kyr" are not applicable, for Domino only, use the Renewal option. This is the option Mindwatering uses for our internal Mindwatering muliti-domain UCC certificates. When the crt, and crt bundles are downloaded for the 2 year renewals.
- Steps verified all options in 2017, and 2019. Verified B and C options in 2019 and 2020.
Option A: Open SSL and IBM/HCL IKeyMan
OpenSSL installation:
- If you are running OpenSSL on MS Windows, it requires the 2008 Visual C++ Redistributables for 64-bit machines. Install it first.
- Run OpenSSL using the Run as Administrator.
Certification Instructions:
1. Using OpenSSL, create the new keyring and private key.
# openssl req -new -nodes -newkey rsa:4096 -sha256 -keyout myserver.mindwatering.net.key -out myserver.mindwatering.net.csr
Warning:
Watch what you enter, not all fields are required. For the common name, enter the FULL (FQDN) domain name. If you are purchasing a "wildcard" ID, include a *. prefix, e.g. [ *.mindwatering.net ]. Moreover, it should follow this model:
Country: US
State: North Carolina
City: Wake Forest
Org Name: Mindwatering Inc
Org Unit:
Common Name: www.mindwatering.net
Email Address:
There will be two additional "optional" fields.
Password:
Optional Company Name:
2. Output the CSR so that you can paste it into the SSL reseller's SSL signing tool.
# cat myserver.mindwatering.net.csr
a. For a commercial trusted certificate, follow the reseller's process for obtaining the signed certificate. Basically, you should be able to take this CSR and paste or upload it, and get back a "bundle" for install.
b. For a self-certified CSR, do the following steps before proceeding to step 3.
# openssl x509 -req -days 3650 -sha256 -in server.csr -signkey myserver.mindwatering.net.key -out myserver.mindwatering.net.pem
3 - Alternate Domino.
To install them on Domino servers:
a. Merge the private key and the certificate (crt) files; order matters mydomain-up-to-root:
Comodo example:
$ cat myserver.mindwatering.net.key mydomain_com.crt COMODORSADomainValidationSecureServerCA.crt COMODORSAAddTrustCA.crt AddTrustExternalCARoot.crt > mydomain.com.txt
b. Import into a new keyring file.
Continue to Option B instructions below.
3 - Apache Install.
To install them on the Apache servers:
a. Use SSH FTP (e.g. FileZilla) to copy the resulting CRT files and the private key file to the servers.
e.g. myserver.mindwatering.net.key and myserver.mindwatering.net.crt and ca_bundle.crt
b. Copy them to the certs and private ssl certs folders.
Notes:
The location depends on distro but you can usually find the locations in /etc/httpd.conf or /etc/ssl.conf. The private key file goes in the private subfolder, and the crt files go in the certs subfolder.
Change the names to match what is expected in the Apache's conf file(s).
c. Change them to be owned by root and change the permissions to so readable and writable only by root.
# chown root:root myserver.mindwatering.net.key
# chmod 400 myserver.mindwatering.net.key
. . .
# chown root:root myserver.mindwatering.net.crt
# chown root:root ca_bundle.crt
# chmod 400 myserver.mindwatering.net.crt
# chmod 400 ca_bundle.crt
4. For the Domino servers, we have to get the certificates and private key into the keyring.kyr format and create the hash sth file.
a. Convert the CRT and private KEY files to the PK12 format (for IKEYMAN).
# openssl pkcs12 -export -inkey myserver.mindwatering.key -in myserver.mindwatering.net.crt -name myserverkeyring -out myserver.mindwatering.net.p12
Note: You will be prompted for a keyring password. Make a note of it.
b. Convert the file from PKS / P12 format to a CMS KYB File.
Notes:
You have to use a NEW version of gsk7ikm. In this case, we used IHS 9's installation to get it's copy of gsk7ikm in the gsk7 subfolder. Make sure you update the JAVA_Home variable in the PC's environmental settings. Also, you'll have to update the certificates for unrestricted policy files (see SWG21395327). Download the "older" unrestricted.zip file; then extract to give you another version of local_policy.jar and US_export_policy.jar. After this, finally run gsk7ikm.exe.
In 9.0.1 FP3, there is a new kyrtool that supports a new keyring.kyr (search for KYRTool_9x_ClientServer)
1. File --> Open --> Navigate to the p12 file and click Open, enter the password.
2. Add the root and intermediate certificates.
- a. Under Key database content, switch from Personal Certficates to Signer Certificates.
- b. Click Add... button on the right. Select the root certificate and add it. Repeat again for the intermediate level certificate.
3. File --> Save As --> In the dialog, choose CMS and name the file (e.g. mindwateringnet.kyb ), enter a password (and note password if different), select the checkbox stash password to file, click OK.
c. Convert the new KYB file to the Domino KYR format.
Notes: You have to now use the OLD version of gsk5 version of ikeyman, as the current version does not include the KYR option. You also could not use the old one to convert from P12, because it doesn't understand the new P12 SSL/TLS files. You may have to update your Java_Home variable again depending if you are using the same PC or not. Download the old version at: ftp://ftp.software.ibm.com/software/lotus/tools/Domino/gsk5-ikeyman.zip
1. File --> Open --> Navigate to the KYB file and click Open, enter the password.
2. File --> Save As --> In the dialog, choose Keyring File and name the file (e.g. mindwateringnet.kyr ), enter a password (and note it), click OK.
5. Copy the KYR and STH files to the Domino server and update the Internet Site document and verify that the new keyring works.
Option B: HCL Domino KyrTool (Domino 9.0.1 FP3 or later).
Install KyrTool:
- For Linux, install the KyrTool that is 64-bit Domino server.
- For MS Windows, install the 32-bit one, as the Notes Client is 32-bit.
- Install the kyrtool tool into the Notes or Domino program (executable) folder.
Steps to Create Keyring and add Certificate
1. Create the keyring file.
LInux:
$ su notes
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini create -k /local/notesdata/mydomain.kyr -p keyringpassword
MS Windows:
c:\notes\kyrtool.exe =c:\notes\notes.ini create -k c:\notes\data\mydomain.kyr -p keyringpassword
2. Generate the server keys, and perform the certificate request. (I used OpenSSL for this part. See the steps above.)
Linux:
$ openssl genrsa -out myserver.key 4096
$ openssl req -new -sha256 -key myserver.key -out myserver.csr
> Send the resulting myserver.csr to your SSL provider. Download their "root", "secondary", and your server's certificate PEM files.
3. Add the key and the certs to the keyring. Install the Level 1 (top) cert first, then install the Level 2 (secondary level), and finally the server certificate.
cat myserver.key 1234serverdomain.crt lv1andlv2bundle.crt root.crt/opt/ > bundlecrt.txt
Linux:
$ su notes
$ cd /local/notesdata
Test first:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini verify /local/notesdata/certs.pem
Import:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini import all -k /local/notesdata/mydomain.kyr -i /local/notesdata/certs.pem
Note:
if you get an ELF message, "libnotes.so: wrong ELF class: ELFCLASS32", then you copied to the server the wrong version of kyrtool (e.g. 64-bit for Domino 32-bit). This occurs when you have an older Traveler server before traveler became 64-bit, so the Domino server is still 32-bit.
If you get an error "libnotes.so: cannot open shared object file", you are running it directly. Use the startup tool, or create a soft link. (See the Domino 10 setup on Ubuntu 18 document in this technical repository)
MS Windows:
c:\ kyrtool =c:\notes\notes.ini import all -k c:\notes\data\mydomain.kyr -i c:\notes\data\certs.pem
Optional (but suggested): Verify the certificates:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini show certs -k /local/notesdata/mydomain.kyr
4. Move the mydomain.kyr and the mydomain.sth to the server (if you didn't do this on the server).
5. Update the server's Internet Web Site, SMTP settings, other other protocols to use the new mydomain.kyr.
Option C: HCL Domino Kyrtool Renewal
Task: Add the new crt files into the existing kyr file.
Note:
We are assuming that you chose the Tomcat or Apache download from the third-party renewal site, and have received a crt for the server and typically a bundled intermediate and top-level certs file. If you have a server cert that is a text pem file (not base-64 encoded), then that is equivalent to the crt file format.
1. Transfer the server crt, and the bundled crt file, into a new folder called ssl.
2. Open a terminal on the server using the domino server id (e.g. notes). Combine the crt files (1234serverdomain.crt --> lv1andlv2bundle.crt to a new file bundlecrt.txt).
$ cd /home/notes/ssl/
$ cat 1234serverdomain.crt lv1andlv2bundle.crt > bundlecrt.txt
3. Verify the file and import the new cert files:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini verify /home/notes/ssl/bundlecrt.txt
Since we are doing a renewal, the message and ERROR that no key is found, is expected, and can be ignored.
No private key found in the input file
ERROR: No private key found in /home/notes/ssl/bundlecrt.txt
INFO: Successfully read 4 certificates
INFO: IssuerName of cert0 matches the Subject of cert 1
INFO: IssuerName of cert1 matches the Subject of cert 2
INFO: IssuerName of cert2 matches the Subject of cert 3
INFO: Final certificate in chain is self-signed.
Perform the import:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini import certs -k /local/notesdata/mydomain.kyr -i /home/notes/ssl/bundlecrt.txt
Verify the import:
$ /opt/ibm/domino/bin/tools/startup kyrtool =/local/notesdata/notes.ini show certs -k /local/notesdata/mydomain.kyr
The server certificate will be listed first, verify that the expiration date is valid. (e.g. issued today and starts today, through 2 to 3 years out, whatever is the renewal period.)
Clean up. remove the certs from the working folder and secure in a suitable repository.
4. Update the server to use the new certificate.
Open the command console to the Domino server. Tell http to refresh config, and verify security is okay.
> tell http quit
(wait)
> load http
> tell http sh security
Verify that SSL/TLS is enabled and pointing at the keyring just updated.
If the server is also running Traveler or Sametime, verify those services came back up with the load http.
5. Open a web browser and check the certificate.
Note:
If you need the key, you can display it with:
$ kyrtool show keys -k <path to keyring file>
previous page
|