Steps to renew certificate using IBM Key Management Utility

byLiveStream -
2
Steps to renew certificate using IBM Key Management Utility

Steps to Renew Certificate Using IBM Key Management Utility: A Complete DevOps Guide

If you're running IBM HTTP Server (IHS) in production, renewing SSL certificates is a routine but critical task. The IBM Key Management Utility (iKeyman) is the primary tool for managing KDB key database files, but its workflow isn't always intuitive. In this guide, I'll walk you through the exact process I use to renew certificates in enterprise environments—including the gotchas that can break your service if you're not careful.

We'll cover everything from CSR generation to final verification, with special attention to maintaining configuration consistency (like that SSLServerCert directive in httpd.conf). By the end, you'll have a battle-tested procedure that works whether you're renewing a single server or propagating certificates across a cluster.

Prerequisites

Before you begin, ensure you have:

  • Access to the IBM HTTP Server: You'll need RDP/SSH access to the server where IHS is installed (typically Windows Server in enterprise setups).
  • IBM Key Management Utility: Installed as part of the IBM HTTP Server package. If missing, reinstall IHS or copy the utility from another server.
  • Backup permissions: Write access to D:\IBM\HTTPServer\KeyFile DB\ (or your custom path) to back up KDB files.
  • Certificate authority (CA) access: Credentials to submit CSRs to your internal CA or public CA (e.g., DigiCert, Sectigo).
  • Service restart rights: Permissions to restart the IBM HTTP Server service (or coordination with your operations team).
  • Notepad++/VS Code: For editing httpd.conf and comparing certificate details (optional but helpful).

Pro tip: If this is your first renewal, schedule a maintenance window. While the process is non-destructive, a misstep (like forgetting to back up the KDB file) can cause downtime.

Step 1: Back Up Existing Certificate Files

Always start with a backup. The KDB file (.kdb) contains your private keys, and losing it means starting from scratch. Here's what to back up:

D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\
  ├── absnet.kdb      # Key database file
  ├── absnet.rdb      # Certificate database file
  ├── absnet.sth      # Stash file (contains encrypted password)
  └── Password for KDB file.txt  # Critical—contains the KDB password

Create a backup directory and copy these files:

mkdir "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Backup_$(date +%Y%m%d)"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\*.kdb" "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Backup_$(date +%Y%m%d)\"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\*.rdb" "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Backup_$(date +%Y%m%d)\"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\*.sth" "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Backup_$(date +%Y%m%d)\"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Password for KDB file.txt" "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\Backup_$(date +%Y%m%d)\"

Why this matters: The .sth file is especially critical—it contains the encrypted password for the KDB file. If you lose it, you'll need to recreate the KDB from scratch, which means reconfiguring httpd.conf and potentially breaking existing client connections.

Step 2: Launch IBM Key Management Utility

Open the utility via one of these methods:

  • Start Menu: Start → IBM HTTP Server → Start Key Management Utility.
  • Command line: Navigate to D:\IBM\HTTPServer\bin\ and run ikeyman.bat.

Once open, you'll see the GUI. Here's what to do next:

  1. Click Key Database File → Open.
  2. Browse to your backup KDB file: D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\absnet.kdb.
  3. When prompted for a password, open Password for KDB file.txt and paste the contents.

Pro tip: If the utility freezes when opening the KDB file, it's often due to a corrupted .sth file. Restore from backup or recreate the stash file by re-entering the password and saving.

Step 3: Extract Certificate Details

Before generating a CSR, you need the Common Name (CN) and Key Label from the existing certificate. This ensures the new certificate matches the configuration in httpd.conf.

  1. In the "Key database content" dropdown, select Personal Certificates.
  2. Identify the active certificate (marked with an asterisk *).
  3. Click View/Edit.
  4. In the pop-up window, note the following (example values shown):
Common Name (CN): absn-qa.OUgc.net
Key Label: absent_SHA2_2015

Why this matters: The Key Label is referenced in httpd.conf (see the SSLServerCert directive). If you change it, you'll need to update the config file and restart IHS—something you want to avoid in production.

Step 4: Generate a Certificate Signing Request (CSR)

Now, generate a CSR using the same details as the existing certificate:

  1. In the "Key database content" dropdown, select Personal Certificate Requests.
  2. Click New.
  3. Fill in the form with the details from Step 3. Here's an example:
Field Value
Key Label absent_SHA2_2015 (must match existing)
Key Size 2048 (or 4096 if your CA supports it)
Common Name (CN) absn-qa.OUgc.net
Organization (O) Your company name (e.g., Global Corp Inc)
Organizational Unit (OU) Department (e.g., IT Operations)
Locality (L) City (e.g., New York)
State/Province (ST) State (e.g., NY)
Country (C) 2-letter code (e.g., US)
  1. Click OK.
  2. When prompted for a file name, save the CSR to: D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\certreq.arm.

Common pitfall: If you change the Key Label, the new certificate won't match the SSLServerCert directive in httpd.conf, causing IHS to fail on restart. Always double-check this field.

Step 5: Submit the CSR to Your CA

Now, submit the CSR to your certificate authority:

  1. Open the CSR file (certreq.arm) in a text editor and copy its contents.
  2. Log in to your CA's portal (e.g., DigiCert, Sectigo, or your internal CA).
  3. Paste the CSR and submit the request.
  4. Note the Request ID and share it with your Certificate Key Management team (if applicable).

Pro tip: If your CA provides a .p7b file (PKCS#7), it will include the root and intermediate certificates. If they provide separate files, you'll need to download them individually.

Step 6: Download and Prepare the New Certificate

Once the CA approves your request, download the following files and place them in the renewal directory:

D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\
  ├── certnew.cer      # Server certificate
  └── certnew.p7b      # Root/intermediate certificates (PKCS#7 bundle)

Verification step: Open certnew.cer in a text editor and confirm it contains a -----BEGIN CERTIFICATE----- block. If it's empty or corrupted, contact your CA.

Step 7: Import the New Certificate into the KDB File

Now, import the new certificate into the KDB file:

  1. Reopen the IBM Key Management Utility and load the backup KDB file (absnet.kdb).
  2. In the "Key database content" dropdown, select Personal Certificates.
  3. Click Receive.
  4. Browse to D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\certnew.cer and click OK.

The new certificate should now appear in the "Personal Certificates" list. Verify it by clicking View/Edit and checking:

  • The Issued To field matches your CN (absn-qa.OUgc.net).
  • The Valid From and Valid To dates are correct.
  • The Key Label matches the existing one (absent_SHA2_2015).

Step 8: Import Root and Intermediate Certificates

The server certificate won't work without its trust chain. Here's how to import the root/intermediate certificates:

  1. In the "Key database content" dropdown, select Signer Certificates.
  2. Click Add.
  3. Browse to D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\certnew.p7b and click OK.
  4. A window will pop up listing the certificates in the bundle. Select all of them (typically 2-3) and click OK.

Verification step: After importing, the "Signer Certificates" list should show the root and intermediate certificates. If any are missing, download them individually from your CA and repeat the process.

Step 9: Restart IBM HTTP Server

To apply the new certificate, restart the IBM HTTP Server service:

net stop "IBM HTTP Server"
net start "IBM HTTP Server"

Common pitfall: If the service fails to start, check the Windows Event Viewer for errors. Common issues include:

  • Missing root/intermediate certificates (Event ID 36885).
  • Mismatched Key Label in httpd.conf (Event ID 36888).
  • Corrupted KDB file (Event ID 36870).

Step 10: Verify the New Certificate

Test the new certificate using one of these methods:

Method 1: Browser Test

  1. Open a browser and navigate to https://absn-qa.OUgc.net.
  2. Click the padlock icon in the address bar and view the certificate details.
  3. Verify the Issued To and Valid To dates.

Method 2: OpenSSL Command

Run this command from a Linux machine or Windows with OpenSSL installed:

openssl s_client -connect absn-qa.OUgc.net:443 -showcerts

Check the output for:

  • The subject matches your CN.
  • The issuer matches your CA.
  • The certificate chain is complete (no "self-signed" warnings).

Method 3: IBM HTTP Server Logs

Check the IHS logs for SSL-related errors:

type "D:\IBM\HTTPServer\logs\error.log" | findstr "SSL"

Look for lines like:

[notice] SSL0220I: SSL Handshake Failed, Socket has been closed. [192.168.1.100:12345 -> 10.0.0.1:443]

If you see these, the certificate isn't properly installed.

Step 11: Propagate the Certificate to Other Servers

If you have multiple IHS servers in a cluster, you'll need to propagate the new certificate. There are two methods:

Method 1: Copy KDB Files

  1. On the server where you renewed the certificate, copy the updated files:
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\absnet.kdb" "D:\IBM\HTTPServer\KeyFile DB\"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\absnet.rdb" "D:\IBM\HTTPServer\KeyFile DB\"
copy "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\absnet.sth" "D:\IBM\HTTPServer\KeyFile DB\"
  1. On the target server, back up the existing files (as in Step 1).
  2. Replace the files with the ones from the renewal directory.
  3. Restart the IBM HTTP Server service.

Method 2: Export/Import (Recommended for Large Clusters)

This method avoids copying the entire KDB file and is less error-prone:

  1. On the source server, open the IBM Key Management Utility and load the KDB file.
  2. Select the new certificate under Personal Certificates.
  3. Click Export/Import → 
    Export Key
    .
  4. Choose PKCS12 format and save the file (e.g., absnet.p12).
  5. Copy the .p12 file to the target server.
  6. On the target server, open the IBM Key Management Utility and load the KDB file.
  7. Click Export/Import → Import Key and select the .p12 file.
  8. Restart the IBM HTTP Server service.

Why this matters: The export/import method ensures the private key is securely transferred without exposing the entire KDB file. It's also easier to automate for large clusters.

Common Pitfalls and Troubleshooting

Pitfall 1: Mismatched Key Label

Symptom: IBM HTTP Server fails to start with Event ID 36888 in the Windows Event Viewer.

Cause: The Key Label in the new certificate doesn't match the SSLServerCert directive in httpd.conf.

Fix: Either:

  • Regenerate the CSR with the correct Key Label, or
  • Update httpd.conf to match the new Key Label and restart IHS.

Pitfall 2: Missing Root/Intermediate Certificates

Symptom: Browsers show a "Not Trusted" warning, or OpenSSL returns verify error:num=20:unable to get local issuer certificate.

Cause: The root/intermediate certificates aren't imported into the KDB file.

Fix: Import the .p7b file (or individual certificates) into the "Signer Certificates" section of the KDB file.

Pitfall 3: Corrupted KDB File

Symptom: IBM Key Management Utility crashes when opening the KDB file, or IHS fails to start with Event ID 36870.

Cause: The KDB file is corrupted (e.g., due to a failed write operation).

Fix:

  1. Restore the KDB file from backup.
  2. If no backup exists, recreate the KDB file from scratch (this requires reconfiguring httpd.conf).

Pitfall 4: Incorrect File Permissions

Symptom: IHS fails to start with Event ID 36871 ("Unable to open key file").

Cause: The IHS service account doesn't have read access to the KDB files.

Fix:

icacls "D:\IBM\HTTPServer\KeyFile DB\*.kdb" /grant "NT AUTHORITY\SYSTEM:(R)"
icacls "D:\IBM\HTTPServer\KeyFile DB\*.rdb" /grant "NT AUTHORITY\SYSTEM:(R)"
icacls "D:\IBM\HTTPServer\KeyFile DB\*.sth" /grant "NT AUTHORITY\SYSTEM:(R)"

How to Verify the Entire Process

After completing the renewal, run these checks to ensure everything is working:

  1. Certificate Expiry Check:
    2. openssl x509 -enddate -noout -in "D:\IBM\HTTPServer\KeyFile DB\SSL_Cert_renewal\certnew.cer"

    This should return a date at least 1 year in the future.

  2. KDB File Integrity Check:

    3. Open the KDB file in the IBM Key Management Utility and verify:

    • The new certificate appears under "Personal Certificates" with the correct Key Label.
    • The root/intermediate certificates appear under "Signer Certificates".
  3. IHS Configuration Check:

    4. Open D:\IBM\HTTPServer\conf\httpd.conf and verify the SSLServerCert directive matches the Key Label:

    <VirtualHost *:443>
    SSLEnable
    SSLServerCert absent_SHA2_2015
    Keyfile "D:\IBM\HTTPServer\KeyFile DB\absnet.kdb"
</VirtualHost>
  4. End-to-End Test:

    5. Use a tool like SSL Labs to test the server. Look for:

    • No chain issues (all certificates in the trust chain are present).
    • No weak protocols or ciphers (e.g., SSLv3, TLS 1.0).
    • A grade of "A" or higher.

Key Takeaways

  • Backup everything: The KDB file, stash file, and password are irreplaceable. Always back up before making changes.
  • Keep the Key Label consistent: Changing it breaks the SSLServerCert directive in httpd.conf, causing IHS to fail on restart.
  • Verify the trust chain: Missing root/intermediate certificates cause browsers to show "Not Trusted" warnings.
  • Test thoroughly: Use OpenSSL, browser checks, and SSL Labs to verify the certificate is working correctly.
  • Automate where possible: For large clusters, use the export/import method to propagate certificates securely and consistently.

FAQ

1. Can I renew a certificate without generating a new CSR?

Answer: No. The CSR is required to prove ownership of the private key and generate a new certificate. However, you can reuse the existing private key (by keeping the same Key Label), which avoids reconfiguring httpd.conf.

2. What if my CA provides a .pfx file instead of a .cer?

Answer: You can import the .pfx file directly into the KDB file using the IBM Key Management Utility:

  1. Select Personal Certificates → Import.
  2. Choose the .pfx file and enter the password (if any).
  3. The certificate and private key will be imported automatically.

3. How do I renew a certificate for a wildcard domain (e.g., *.example.com)?

Answer: The process is identical, but ensure the Common Name (CN) in the CSR is set to the wildcard domain (e.g., *.example.com). Note that wildcard certificates only cover one level of subdomains (e.g., app.example.com but not dev.app.example.com).

4. What if the IBM Key Management Utility crashes when opening the KDB file?

Answer: This usually indicates a corrupted KDB or stash file. Try these steps:

  1. Restore the KDB file from backup.
  2. 🛒 Recommended gear on Amazon

    Disclosure: some links above are affiliate links — if you buy through them I may earn a small commission at no extra cost to you. Thanks for supporting the channel!

Tags:

2 Comments

Previous Post Next Post