Introduction

Enabling SSL for Maximo with the IBM HTTP Server (IHS) ensures that communication between the web browser and the Maximo server is secure. Without SSL enabled communication between the web browser and the server may be observed by malicious actors, who may intercept login credentials, which is especially concerning if Active Directory authentication is used, or other sensitive information. It also allows malicious actors to perform Man in the Middle attacks, where communication between the web browser and Maximo may be altered in transit without either party aware of the manipulation.

In this post we will review terms related to enabling SSL and then describe the process to obtain and deploy an SSL certificate for the IBM HTTP Server.

Terms

Before we begin, let's review some common terms related to SSL certificates.

Private Key

The private key is created by you and it is critical that is kept secure. The private key is used to generate a public key that will be included with your Certificate Signing Request (CSR) to verify ownership when the certificate is issued. Many key management utilities, including the IBM iKeyman utility discussed later, will automatically generate and securely store the private key as part of the CSR creation process.

Certificate Signing Request (CSR)

A Certificate Signing Request (CSR) contains the information needed to validate ownership of a host and additional organizational information such as the city, state and country of the requesting organization and potentially contact information. The validation information is provided either through the use of CN (Common Name), which is a single host name that may include the wildcard character "*" or through a SAN (Subject Alternative Name), which is a list of one or more host names the certificate is being requested for. The Certificate Authority (CA), will request ownership verification of the requested host names, typically by placing a specially formed file or value on the web server or by adding a shared secret value to a TXT DNS entry.

Certificate Authority (CA)

A Certificate Authority (CA) is a trusted third party company or organization that verifies ownership of a host and issues digitally signed certificates generated from the CSR. There are many CA organizations and your organization may even have its own internally trusted CA. Each CA has varying claims to security, costs, and ease of use. Below are some of the more popular CA organizations, in case you not already selected one. These are provided in alphabetical order and we are not promoting or recommending any particular CA.

• Comodo - https://www.comodo.com/
• Digicert - https://www.digicert.com/
• GeoTrust - https://www.geotrust.com/
• GoDaddy - https://www.godaddy.com/
• Let's Encrypt - https://letsencrypt.org/
• Network Solutions - https://www.networksolutions.com/security/ssl-certificates
• Setigo - https://sectigo.com/
• Thawte - https://www.thawte.com/

Certificate

The certificate provides the basis for encrypting traffic between the web browser and your server. It is generated from the CSR, which was signed by your private key that ensures ownership and is signed by a trusted CA, which validated the claims of ownership for the hosts provided in the CSR. This enables the browser to verify that the host that it is communicating with is genuine and not being impersonated and to establish encrypted communication with the server to avoid snooping.

Key Database Utilities

The IHS stores certificates in a key database in a Certificate Management System (CMS) format, which is the native store type for the IBM Global Security Kit (GSK) that is used by the IBM HTTP Server. The iKeyman and gskcmd utilities interact with the CMS key database to create, update and remove certificates.

For more information on the CMS format there is a Stack Overflow discussion here https://stackoverflow.com/questions/19237736/understanding-ibm-cms-keystore#:~:text=A%20CMS%20keystore%20consists%20of,crl%20respectively

iKeyman

The iKeyman utility provides a graphical interface for managing CMS .kdb files used by the IHS. It requires that you have a graphical user environment and cannot be used from the command line.

Documentation for the iKeyman utility can be found here: https://www.ibm.com/docs/en/ibm-http-server/9.0.5?topic=environment-managing-keys-ikeyman-graphical-interface-distributed-systems.

gskcmd / gskcmd.bat (Windows)

The gskcmd is the command line utility for managing CMS .kdb files used by the IHS. The gskcmd is extremely useful for scripting certificate maintenance or for environments that do not have a Graphical User Interface (GUI), such as some Linux installations. Note that on Windows the gskcmd has the .bat extension, for simplicity we are going to refer to it simply as gskcmd.

Documentation for the gskcmd utility can be found here: https://www.ibm.com/docs/en/ibm-http-server/9.0.5?topic=environment-managing-keys-from-command-line-distributed-systems.

Troubleshooting

As you work through the process of requesting and deploying your certificate there are many potential challenges that can arise and identifying the problem can be difficult since SSL is by its very nature opaque.

Fortunately there are sites such as https://www.ssllabs.com/ssltest/ that provide online tools that can examine and validate your SSL configuration.

Another useful online resource is https://www.sslchecker.com/certdecoder, which allows you to view the contents of your CSR and Certificate to validate that the contents of your .crt or .csr file is what you are expecting.

Note that when using these tools, never provide your private key. Keeping your private key, private, is critical to the security of your certificate.

Process Overview

There five steps to perform to enable SSL for Maximo with the IHS.

• Create a key database
• Create a CSR and submit to a cert authority
• Import the certificate issued by the cert authority
• Import signer certificates to construct the certificate chain
• Configure the IHS to use the key database

In the following sections we will cover in detail each of the steps necessary to enable SSL for Maximo with the IHS.

Let's Encrypt

Before we begin, we mentioned the Let's Encrypt CA and while we do not endorse any particular CA, Let's Encrypt provides free SSL certificates with a fully automated verification and issuing process. These certificates are only valid for three months at a time and must be renewed frequently. Fortunately, Let's Encrypt provides a utility called CertBot (https://certbot.eff.org/), that automates this renewal process. Unfortunately, the certificates are issued as .crt files in PEM format, which must then be converted to a .p12 or .pfx file and then imported into the key database.

To address this, we have published a Bash script for Linux and a PowerShell script for Windows that automates the renewal, .p12 and .pfx file creation and importing to the key database.

These scripts are available on GitHub here: https://github.com/sharptree/letsencrypt-ihs

Let's Encrypt provides great way to secure Maximo instances, but may not be appropriate for all environments. It requires that your Maximo instance be exposed to the Internet so Let's Encrypt can validate the host name, and many corporate IT departments have policy restrictions that do not allow for Let's Encrypt certificates. Even if Let's Encrypt is not used, the scripts provide a good reference for automating whatever process you have in place and are worth reviewing.

You will still need to configure the IHS for SSL, which is covered near the end of this post, but from there the provided scripts will automate the process of creating the key database, requesting and validating the certificate and then import it to the .kdb key database.

Key Database Actions

The following are common actions for managing certificates with the IHS. For each of the examples, the value ihs_root refers to the installation directory of the IHS, for example /opt/IBM/HTTPServer on Linux or C:\IBM\HTTPServer on Windows.

IHS and GSK use the term key database and we will use that terminology as well, but key store is also commonly used and is an interchangeable term.

Create

The first thing we must do is create a key database, which is fortunately a simple procedure.

iKeyman

Start the iKeyman utility and click the Create new key database file button or click the Key Database File menu and then select New....

Typically the key database is saved to the ihs_root/conf directory as shown in the image below. In our example we are naming our new key database maximo.kdb.

Finally, enter and confirm a password for the key database and make sure to check the Stash password to a file checkbox.

gskcmd

The command line version is quite simple, with the command below, where the [password] value should be replaced with your password.

Copy
ihs_root/bin/gskcmd -keydb -create -db filename -pw [password] -stash

Stash File

The stash file stores the key database password in an encrypted format, in a file with the same name as the key database, but with a .sth extension. This allows the IHS to start without requiring manual entry of the keystore password. In practical terms this is required to start the server as a Linux or Windows service.

Create CSR

Next we are going to create a CSR that will be submitted to the CA so a certificate can be issued.

iKeyman

Start the iKeyman utility and select the Open key database file button or click the Key Database File menu and then select Open....

Select the key database and click the OK button. In this case we are using the key database from our previous example, maximo.kdb.

Enter the password for the key database.

From the drop down menu in the middle of the screen, which defaults to Personal Certificates, select the Personal Certificate Requests option.

Click the New... button to start creating a new CSR.

Enter the requested information for the CSR. These first parts are technical in that they impact the security of the certificate and define how the certificate is identified within the key database.

• Key Label - Indicates the label attached to the certificate or certificate request, this is later used to identify and manage the certificate.
• Key Size - Indicates a key size of 2048, 1024, or 512. The default key size is 1024, but if possible you should select 2048. The larger key size, the more secure the certificate and as with all cryptography the harder it is to crack.
• Signature Algorithm - Defaults to SHA1WithRSA, but you should select at least SHA256WithRSA. The SHA size as indicated by the number 256 in SHA256WithRSA, indicates the bit size for computing the hash and again, bigger is generally better. The hashing function, provides a unique fingerprint for your certificate, smaller bit sizes and insecure hashing functions like MD5 can be coerced to produce non-unique values, which would allow someone to impersonate your Maximo instance.
• Common Name - The fully qualified host name for the certificate. This is the public name that users access your server with, for example maximo.acme.com

If you want a certificate to be used by more than one host name, the additional host names can be provided as part of the DNS Name value under Subject Alternative Names at the bottom. This maps to the certificate's Subject Alternative Name (SAN) and allows a certificate to represent more than one host.

• DNS Name - One or more fully qualified host name values, comma separated.

The Organization details are informational and are visible to the user when they view the certificate. This allows the user to see who requested the certificate and verify if it matches what they expect. If they are using maximo.acme.com and the certificate was requested by Totally not Acme it can be an indication that something isn't right and they may not be able to trust the certificate.

• Organization - The company or organization name. This is for informational purposes so a user can see who owns the certificate.
• Organizational Unit - The company or organization name again, or department name, also for informational purposes.
• Locality - The city where the organization is based
• State/Province - The state or province, without abbreviation, where the organization is based.
• Zip Code - The Zip or Postal code for the organization.
• Country or region - The country or territory where the organization is based.

Finally enter the path for the output file, which is the CSR that will be sent to the CA to issue the certificate.

The iKeyman utility defaults to .arm extension, although it is more common to use .csr. The output is a text file, so the extension does not have a technical impact, but for clarity we prefer the .csr extension.

The following is the output CSR from the screen capture above.

Copy
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIC8TCCAdkCAQAwejELMAkGA1UEBhMCVVMxEzARBgNVBAgTCldhc2hpbmd0b24xEDAOBgNVBAcT
B1NlYXR0bGUxEjAQBgNVBAoTCVNoYXJwdHJlZTESMBAGA1UECxMJU2hhcnB0cmVlMRwwGgYDVQQD
ExNtYXhpbW8uc2hhcnB0cmVlLmlvMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6dRR
mNoRgwF+Cda3DaDUJpCB4riwdPvgsIrDUkIso0ptfJdHr3Q7dIKZpzXNt9n4taBchCDcOP1lbQmi
otgdB4+AmBKfQQ2+KnToAvDFKP4hdias8lq/g3YHKfXgWroIfWUfYdJ9yv/8sxUrPDzNvPqLW+v9
eDXecy9CbfHMajKTBTlBCxiKSdw8dCEBPkFoB8x3mXWFy62d+xTGcDHwql8vX7tEDvlYXYFZrhJH
aDuHGFiTqNCiIIQybGo+o34dDZUEzswf/0Fb1CfUAvgc0GDwOAxcjMY1keGr8htYuLmSBvdfFvvy
Vutms8U94Hh2thKGdRzJgoPBcGHEmrAGwQIDAQABoDIwMAYJKoZIhvcNAQkOMSMwITAfBgNVHREE
GDAWghRtYXhpbW8uc2hhcnB0cmVlLmRldjANBgkqhkiG9w0BAQsFAAOCAQEAZXFmdYrxSha/5qgc
u8qn1kwFTk7wNPsdWRXNTkwXx8bZvvjk2ofVIV3kAC1xUOGcHKs2c4QOQYiUN3B6Y3h8TX49sC7B
U6mkMgJ1yuKtQiNuJl5sFKXlOIh5X1Hhu9p1teEsVe+9laqZmEf0i+j6RCerjFqyejdfA3GILRc3
lnZHgRkuoJ5pGoV6QyJDsPGiqQsw7llqC4X8BkxQOJkT3UPkvu4NQork3PYrW6dLGnGFVW1G8t65
SrOiDdci0qEDwz4OUfkXnLJ6dCTybbllAeSm2ZISjzVy9PR7cFkhkZM3qyBov7kwhk7NXr+5WgK7
EktKccLQwau1CJ+AXAnpOw==
-----END NEW CERTIFICATE REQUEST-----

Once complete, the iKeyman utility displays a message instructing you to send the resulting CSR to your CA. You can also see that the Personal Certificate Request has been added to the key database content section with the entered label of maximo.

gskcmd

The follow creates a request with a primary host name of maximo.sharptree.io and includes the SAN value for maximo.sharptree.dev. The resulting CSR is written to the ihs_root/conf/maximo.csr file, which can then be provided to the CA.

In this example we used the -stashed flag to indicate that the stashed password file will be used, using the -pw [password] option allows you to specify the keystore password instead.

The values for the -dn flag correspond to the entry values listed for the iKeyman utility.

The [path to kdb] value should be replaced with the path to your .kdb file and the [path to maximo.csr] value should be replaced with the output path for the .csr.

Copy
ihs_root/bin/gskcmd  -certreq -create -db [path to kdb] -stashed -label maximo -sig_alg SHA256WithRSA -dn "cn=maximo.sharptree.io,O=Sharptree,OU=Sharptree,L=Seattle,st=Washington,c=US" -san_dnsname maximo.sharptree.dev -size 2048 -file [path to maximo.csr]

Note that the private key for this request was automatically created and stored to the key database.

Receive

Now we are going to receive the issued certificate from the CA and import it into our key database.

iKeyman

After creating a CSR and having received the certificate from the CA, with the key database open and the Personal Certificates option selected, which is the default, click the Receive button.

Enter the path to the received certificate file, which is typically a .crt or .cer file in PEM format, then click the OK button to import the certificate. The certificate will be matched with the initial CSR and the private key used to generate the CSR will be associated with the issued certificate.

Save the key database and ensure that the Stash password to a file option is checked so IHS can start as a service.

gskcmd

After creating a CSR and having received the certificate from the CA, execute the following command where [path to the cert] should be replaced with the path to the received .cer or .crt file and the [path to kdb] value should be replaced with the path to your .kdb.

In this example we used the -stashed flag to indicate that the stashed password file could be used, using the -pw [password] option allows you to specify the keystore password instead.

The -default option indicates that the certificate will be the default for the key database. In most cases for Maximo where IHS is only serving a single instance, this option should be selected.

Copy
ihs_root/bin/gskcmd -cert -receive -file [path to the cert] -db [path to kdb] -stashed -format ascii -label maximo -default yes

Importing External Certificate and Key

If you created the certificate request externally, either through the command line or through a CA's website, you will need to create a PKCS12 file, typically a .p12 extension in Linux or .pfx extension in Windows, before importing it using the iKeyman or gskapicmd utilities. The PKCS12 file combines the certificate provided by the CA and the key that was used to generate the CSR.

For more information on PKCS12, the Wikipedia article has details and links to the formal specifications here:https://en.wikipedia.org/wiki/PKCS_12

OpenSSL (Linux)

OpenSSL makes it very easy to create a .p12 file. Run the following command where [certificatename].crt is the file name for the certificate provide by the CA, the [keyname].crt is the private key used to generate the CSR, and [certificatename].p12 is the resulting .p12 file name. You will then be prompted to provide the private key password and the output .p12 password.

Copy
openssl pkcs12 -export -out [certificatename].p12 -inkey [keyname].crt -in [certificatename].crt

CertUtil (Windows)

Although OpenSSL is technically available for Windows, it is not native and finding the correct version to install can be difficult. Fortunately, Windows ships with certutil, which can be used to manipulate certificates and create p12 files. Compared to OpenSSL, certutil is frustratingly limited and opaque, but it works and is available, so sometimes the best tool is the one that you have.

Before we begin, copy the certificate issued by the CA and the private key used to sign the CSR to the same directory. Make sure the certificate has a .cer extension and if not change the extension to .cer. Next, rename the private key to have the same name as the certificate file with the same name as the certificate and .key extension. This step is critical as the certutil utility does not provide a way to specify the private key (come on Microsoft 🙄).

To create the .pfx file, open a Command Prompt as the Administrator user and navigate to the directory where you copied the certificate and key files. Run the following command where the [firstpassword] is the password for your private key and the [secondpassword] is the password for the resulting .pfx. If you do not provide a second password then you will be prompted to provide one. The [certificatename] parameter is the name of the resulting `.pfx' file.

Copy
certutil -f -p "[firstpassword],[secondpassword]" -MergePFX [certificatename].cer [certificatename].pfx

Documentation for certutil can be found here: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/certutil.

iKeyman

With the key database open, click the Import button.

From the Key file type drop down, select the PKCS12 value.

Use the Browse button to select the .p12 or .pfx file that was created in the previous steps, then click the OK button.

When prompted, enter the password that was used to create the .p12 or .pfx file.

Select and optionally rename the certificate to import, in the screen capture below we have renamed the certificate to import to maximo.sharptree.io, then click OK to import the certificate.

The certificate is now imported and visible in the list of Personal Certificates

Save the key database and ensure that the Stash password to a file option is checked so IHS can start as a service.

gskcmd

To import the certificate you will need to first get the label of the certificate in the .p12 or .pfx file that was previously created. To fetch the label execute the following command where [path to p12/pfx] is replaced with the path to your .p12 or .pfx file and [password] is replaced with the .p12 or .pfx password.

A list of certificates and their labels will be displayed, although in this case there should only be one certificate, PKCS does support storing multiple certificates.

Copy
ihs_root/bin/gskcmd -cert -list -db [path to p12/pfx] -type pkcs12 -pw [password]

Execute the following command where [certificate label to import] is replaced with the certificate label obtained in the previous step, [p12/pfx password] is replaced with the password for the .p12 or .pfx key database, [path to p12/pfx] is replaced with the path to your .p12 or .pfx file, [path to kdb] is replaced with the path to the .kdb file, [kdb password] is replaced with the password for the .kdb file and [certificate label] is replaced with the desired label for the certificate in the .kdb.

Copy
ihs_root/bin/gskcmd -cert -import -label [certificate label to import] -pw [p12/pfx password] -db [path to p12/pfx] -type pkcs12 -target [path to kdb] -target_pw [kdb password] -new_label [certificate label]

Importing Signer Certificates

In addition to the certificate signed by the CA you must also import the CA's intermediate and root certificates, enabling a full chain of trust to be established from the certificate back to the CA root certificate. The CA will often include their root and intermediate certificates along with the issued certificate, but these are also published on the CA's website. Since the .pem format can accommodate multiple certificates, the chain of trust is often provided in a full chain file that includes the root certificate and all its intermediate certificates. In the following example we are going to import Let's Encrypt's X1 root and R3 intermediate certificates, which are provided in a file we have named fullchain.pem.

iKeyman

With the key database open, select the Signer Certificates from the drop down in the middle of the screen.

Click the Add... button to start the import process.

Use the Browse button to select the CA root, intermediate, or chain certificate file, then click the OK button. In our example we are using a file named fullchain.pem that contains the X1 root and R3 intermediate certificates for Let's Encrypt.

Select the certificate or certificates to import, then click the OK button.

Optionally the certificate labels can be renamed. This does not impact anything functionally, but may make it easier to identify certificates from the list of install certs later. Click the OK button to continue.

The CA certificates are now imported and displayed in the list.

Save the key database and ensure that the Stash password to a file option is checked so IHS can start as a service.

gskcmd

Execute the following command where [ca certificate label] is replaced with the CA certificate label or your choosing, [path to kdb] is replaced with the path to the .kdb file, [kdb password] is replaced with the password for the .kdb file and [path to ca.pem] is replaced with the path to CA root or intermediate certificate.

Copy
ihs_root/bin/gskcmd -cert -add -label [ca certificate label] -db [path to kdb] -pw [kdb password] -file [path to ca.pem]

Note that the gskcmd cannot import multiple certificates at once. If you have a full chain certificate then simply split it into separate files where each certificate is started with -----BEGIN CERTIFICATE----- and terminated with -----END CERTIFICATE-----.

Configure the IBM HTTP Server

After creating the .kdb and importing the required certificates we can finally enable SSL for the IHS. By default when the IHS is installed with Maximo, the SSL module is not enabled and other directives in the httpd.conf configuration file will need to be added.

For the following steps open the ihs_root/conf/httpd.conf file in a text editor.

Enable Module

Locate and uncomment the # LoadModule ibm_ssl_module modules/mod_ibm_ssl.so by removing the # character.

Add SSL Port

Locate and uncomment the # Listen 0.0.0.0:443 by removing the # character.

Note that this directive configures the server to listen on port 443 on all available interfaces. Port 443 is the default SSL port, but another port may be selected if desired and a specific IP address can be configured if multiple interfaces are available.

Add a VirtualHost for SSL

At a minimum, add the following directive, which defines a VirtualHost for all host names on port 443 and defines that for requests on port 443 that SSL is enabled.

Copy
<VirtualHost *:443>
 SSLEnable
</VirtualHost>

The VirtualHost configuration can be quite complicated and contains many options. Full documentation for the VirtualHost directive can be found the Apache website here: https://httpd.apache.org/docs/2.4/vhosts/

Configure the KeyFile

Next specify the path to the key database that was created earlier. The following examples are for Windows and Linux respectively, but the path for your installation may differ.

Windows

Copy
KeyFile C:\IBM\HTTPServer\conf\maximo.kdb

Linux

Copy
KeyFile /opt/IBM/HTTPServer/conf/maximo.kdb

Restart

Finally, save the httpd.conf file and restart the IBM HTTP Server service for the changes to take effect.

Conclusion

In this post we reviewed the basic SSL concepts and terms, reviewed the iKeyman and gskcmd utilities for working with the IHS key database and finally reviewed the steps required to enable SSL with the IHS.

If you have any questions or comments please reach out to us at [email protected]