IBM Support

Renewing a certificate using iKeyman

Question & Answer


Question

How do you properly renew a certificate with the IBM Key Management (iKeyman) or gskcapicmd utilities?

Answer

The following steps are required for renewing an expiring (or expired) certificate.
A certificate is renewed with the Receive operation in iKeyman.  A receive operation is possible when iKeyman under the following two conditions:
  • The key store has an existing certificate with the same distinguished name and keys as the certificate to be received
  • The key store has a pending certificate signing request (CSR) with the same distinguished name and keys as the certificate to be received
Table of Contents

Renewing certificates issued by an external Certificate Authority (CA) from the GUI
Follow this procedure if you obtain your SSL certificate from a public certificate authority (CA) such as Comodo, Sectigo, Digicert, Verisign, or Symantec.  
You can also follow this procedure if your company operates a private, central certificate authority.
  1. Determine whether your CA supports renewing of a certificate without the submission of a new Certificate Signing Request (CSR). This type of renewal, sometimes called re-signing, is supported by IBM HTTP Server.
    A certificate renewed or re-signed this way uses the same private key size as the last time a CSR was submitted.
  2. If your CA requires a new Certificate Signing Request (CSR)
    1. Start the iKeyman graphical interface, Open the KeyFile (*.kdb) containing the certificate to be updated, and change to the Personal Certificates tab in the center of the GUI
    2. Select the label of the expiring certificate and then click Recreate Request.  Follow the prompts to save "certreq.arm" and note the selected directory
    3. Follow your CA's process to submit a renewal CSR
    4. You will receive a signed certificate in return, for example "cert.arm" (or *.cer, *.der, *.crt, or even *.txt)
  3. If your CA does not require a new CSR:
    1. Request a renewal (or re-signed) certificate from the CA's tooling directly.  This results in a new issued certificate, for example "cert.arm" but could have any filename including *.cer, *.der, *.crt, or even *.txt
    2. Start the iKeyman graphical interface, Open the KeyFile (*.kdb) containing the certificate to be updated, and change to the Personal Certificates tab in the center of the GU 
  4. Click Receive. Follow the prompts and select the "cert.arm" returned by your CA
  5. Close the iKeyman utility and restart the IHS for the changes to take effect.
Renewing certificates issued by an external Certificate Authority (CA) from the Command Line (UNIX/Linux)
The procedure to renew a certificate can be accomplished quickly on the command line.  This example uses the following variables:
export IHSROOT=/opt/IBM/HTTPServer
export KDB=$IHSROOT/conf/key.kdb
export CERTLABEL=wildcard2020
Setting these variables in your terminal will allow you to copy and paste the examples below.  If you don't know the certificate label that is expiring, you can run the following command to list certificates expiring within the next 60 days:
$IHSROOT/bin/gskcapicmd -cert -list -db $KDB -stashed -expiry 60
  1. Determine whether your CA supports renewing of a certificate without the submission of a new Certificate Signing Request (CSR). This type of renewal, sometimes called re-signing, is supported by IBM HTTP Server.
    A certificate renewed or re-signed this way will use the same private key size as the last time a CSR was submitted.
  2. Verify that the selected certificate label is the one that will soon expire by inspecting the output of the following command. If no dates are printed, the selected label is NOT expiring within the next 60 days.
    $IHSROOT/bin/gskcapicmd -cert -list -db $KDB -stashed -label $CERTLABEL -expiry 60
    -	wildcard2020
              Not Before : June 16, 2018 8:42:57 PM EDT
              Not After : June 18, 2020 8:42:57 PM EDT
    !	rootCA
  3. If your CA requires a new Certificate Signing Request (CSR), run the following command to generate a new CSR:
    $IHSROOT/bin/gskcapicmd -certreq -recreate -db $KDB -stashed -label $CERTLABEL -target certreq-renewal.arm
    • Follow your CA's process to submit the generated certreq-renewal.arm
    • You should receive a signed certificate in return, for example "cert.arm" (or *.cer, *.der, *.crt, or even *.txt)
  4. If your CA does not require a new CSR:

    Request a renewal (or re-signed) certificate from the CA's tooling directly.  The output should be a certificate, for example "cert.arm" but could have any filename including *.cer, *.der, *.crt, or even *.txt
  5. Receive the "cert.arm" returned by your certificate authority, confirm the expiration date is farther in the future, and validate the certificate chain.
    $IHSROOT/bin/gskcapicmd -cert -receive -db $KDB -stashed -file cert.arm
    
    $IHSROOT/bin/gskcapicmd -cert -list -db $KDB -stashed -label $CERTLABEL -expiry 5000
    -	wildcard2020
              Not Before : June 16, 2020 8:48:00 PM EDT
              Not After : June 17, 2022 8:48:00 PM EDT
    !	rootCA
    
    $IHSROOT/bin/gskcapicmd -cert -validate -db $KDB -stashed -label $CERTLABEL
    OK
    If the validation step prints anything other than OK, your CA may have provided you with new trusted issuers that must be added to your key store.  
    The error message will contain text including "Issuer=" which will be followed by the distinguished name of the missing CA. 
    $IHSROOT/bin/gskcapicmd -cert -validate -db $KDB -stashed -label $CERTLABEL
    CTGSK2146W An invalid certificate chain was found.
    Additional untranslated info: No certificate chain built
    Additional untranslated info: GSKKM_VALIDATIONFAIL_SUBJECT: [Class=]GSKVALMethod::PKIX[Issuer=]CN=ihsca3[#=]5745386367fb9c6d[Subject=]CN=localhost
    CTGSK2146W An invalid certificate chain was found.
    
    $IHSROOT/bin/gskcapicmd -cert -add -db $KDB -stashed -file root.crt -label rootCA
    $IHSROOT/bin/gskcapicmd -cert -validate -db $KDB -stashed -label $CERTLABEL
    OK
  6. Restart the IBM® HTTP Server for the changes to take effect.
Renewing certificates issued by an external Certificate Authority (CA) from the Command Line (Windows)
The procedure to renew a certificate can be accomplished quickly on the command prompt.  This example uses the following variables:
set IHSROOT="C:\Program Files\IBM\HTTPServer"
set KDB=%IHSROOT%\conf\key.kdb
set CERTLABEL=wildcard2020
Setting these variables in your command prompt will allow you to copy and paste the examples below.  If you don't know the certificate label that is expiring, you can run the following command to list certificates expiring within the next 60 days:
%IHSROOT%\bin\gskcapicmd.bat -cert -list -db %KDB% -stashed -expiry 60
  1. Determine whether your CA supports renewing of a certificate without the submission of a new Certificate Signing Request (CSR). This type of renewal, sometimes called re-signing, is supported by IBM HTTP Server.
    A certificate renewed or re-signed this way will use the same private key size as the last time a CSR was submitted.
  2. Verify that the selected certificate label is the one that will soon expire by inspecting the output of the following command. If no dates are printed, the selected label is NOT expiring within the next 60 days.
    %IHSROOT%\bin\gskcapicmd.bat -cert -list -db %KDB% -stashed -expiry 60
    -	wildcard2020
              Not Before : June 16, 2018 8:42:57 PM EDT
              Not After : June 18, 2020 8:42:57 PM EDT
    !	rootCA
  3. If your CA requires a new Certificate Signing Request (CSR), run the following command to generate a new CSR:
    %IHSROOT%\bin\gskcapicmd.bat -certreq -recreate -db %KDB% -stashed -label %CERTLABEL% -target certreq-renewal.arm
    • Follow your CA's process to submit the generated certreq-renewal.arm
    • You should receive a signed certificate in return, for example "cert.arm" (or *.cer, *.der, *.crt, or even *.txt)
  4. If your CA does not require a new CSR:

    Request a renewal (or re-signed) certificate from the CA's tooling directly.  The output should be a certificate, for example "cert.arm" but could have any filename including *.cer, *.der, *.crt, or even *.txt
  5. Receive the "cert.arm" returned by your certificate authority, confirm the expiration date is farther in the future, and validate the certificate chain.
    %IHSROOT%\bin\gskcapicmd.bat -cert -receive -db %KDB% -stashed -file cert.arm
    
    %IHSROOT%\bin\gskcapicmd.bat -cert -list -db %KDB% -stashed -label %CERTLABEL% -expiry 5000
    -	wildcard2020
              Not Before : June 16, 2020 8:48:00 PM EDT
              Not After : June 17, 2022 8:48:00 PM EDT
    !	rootCA
    
    %IHSROOT%\bin\gskcapicmd.bat -cert -validate -db %KDB% -stashed -label %CERTLABEL%
    OK
    If the validation step prints anything other than OK, your CA may have provided you with new trusted issuers that must be added to your key store.  
    The error message will contain text including "Issuer=" which will be followed by the distinguished name of the missing CA. 
    %IHSROOT%\bin\gskcapicmd.bat -cert -validate -db %KDB% -stashed -label %CERTLABEL%
    CTGSK2146W An invalid certificate chain was found.
    Additional untranslated info: No certificate chain built
    Additional untranslated info: GSKKM_VALIDATIONFAIL_SUBJECT: [Class=]GSKVALMethod::PKIX[Issuer=]CN=ihsca3[#=]5745386367fb9c6d[Subject=]CN=localhost
    CTGSK2146W An invalid certificate chain was found.
    
    %IHSROOT%\bin\gskcapicmd.bat -cert -add -db %KDB% -stashed -file root.crt -label rootCA
    %IHSROOT%\bin\gskcapicmd.bat -cert -validate -db %KDB% -stashed -label %CERTLABEL%
    OK
  6. Restart the IBM® HTTP Server for the changes to take effect.
Renewing "Self-Signed" certificates
These certificates are not renewed, but new self-signed certificates can be created at any time.
  1. Start the iKeyman graphical interface.
  2. Open the existing KeyFile (.kdb) that contains the self-signed certificate.
  3. Click the certificate in the Personal Certificates section of the KeyFile and then click the Delete button to the right of the screen.
    Note: This removes the certificate from the KeyFile.
    Click the New Self-Signed button to the right of the screen.
  4. Fill in the new self-signed certificate form and then click OK.
    Note: You will now see your new certificate listed in the Personal Certificates section of the KeyFile.
  5. Close the iKeyman utility and restart the IHS for the changes to take effect.

[{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEQTJ","label":"IBM HTTP Server"},"ARM Category":[{"code":"a8m50000000Cd21AAC","label":"IHS->SSL->Cert management"}],"ARM Case Number":"","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"All Version(s)","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"IBM HTTP Server","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"7.0","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

Document Information

Modified date:
29 September 2021

UID

swg21045925