IBM Support

Replacement of an expiring certificate on the IBM WebSphere DataPower SOA Appliance

Troubleshooting


Problem

What is the procedure for replacing an expiring certificate that is in use on the DataPower appliance with a newly obtained certificate?

Cause

Once you have obtained a new certificate from your certificate authority and are ready to replace the expiring one currently in use by your DataPower configuration with this new certificate, there is no single prescribed manner in which to perform the replacement operation. The following information presents some options for formulating an approach that best fits your environment.

Resolving The Problem

First, know your certificate material. It's not uncommon for newer certificates to be chained, so it is not a one for one replacement; the existing certificate on the DataPower appliance may need to be replaced by more than one certificate. Therefore, it is important to ensure you have the full certificate chain, as appropriate (i.e, the personal, intermediate and root certificates). Certificate authorities may send two certificates in the chain and expect the third one to be downloaded from their website.

Here's a screenshot of a sample chain. Notice that you can check the 'Certification Path' tab if there are any remaining certificates in the chain. Also note the chain of "Issued To" and "Issued By" identities.
ExampleCertificateChain.jpgExampleCertificateChain.jpg


As for the certificate configuration on DataPower, the appliance will reference the actual key and certificate files stored in the cert: directory by file name.  Navigation in the WebGUI to the SSL Proxy Profile -> Crypto Profile -> Crypto Key and Certificate objects will show the current files referenced by the configuration.




For example, your DataPower configuration may currently reference the existing files cert:///current-key.pem and cert:///current-cert.pem.



As long as the replacement file(s) are NOT named the same as these files (i.e. the new ones are named cert:///new-key.pem and cert:///new-cert.pem for example), it is safe to load the new file(s) into the cert: directory at any time ahead of the replacement operation.   Your existing configuration will not use the new files, so long as the Crypto Key and Certificate Objects still refer to the files associated with the expiring certificate (i.e. cert:///current-key.pem and cert:///current-cert.pem).



Having both expiring and replacement files in the cert: directory at once allows for the capability to modify the configuration to point to the new files or revert it back to the expiring files relatively easily or to configure a new SSL Proxy Profile object that references the new files. The new SSL Proxy Profile could be used to test independently of the currently running configuration using a new test service such as an XML Firewall.

You can navigate directly to the key and certificate objects using these paths: 
      ObjectsCrypto ConfigurationCrypto Certificate.
      ObjectsCrypto ConfigurationCrypto Key

Another view is from Control Panel -> Keys and Certificate Management.



Either way, note how the configuration ultimately references the files in the cert: directory and plan ahead for how you prefer to reference the new files. 

They may be swapped out within the existing Crypto Configuration objects (i.e. update the objects to reference the new file(s) or to revert to the expiring ones as needed).

Alternatively, a new separate set of Crypto Configuration objects that reference the new files may be created and replacement performed at the Crypto object level by updating the configuration to reference the new replacement Crypto Configuration objects.

Important Note: If the replacement certificate has the same file name of the expired certificate, you MUST disable/enable the certificate object in order to clear all cached references to the expired certificate.

For more information on certificates, refer to the product documentation specific to your firmware and appliance type. Navigate to the Administrator's Guide, under "Managing the Appliance" - "Working with keys and certificates" from the WebSphere DataPower Product Documentation Portal.

[{"Product":{"code":"SS9H2Y","label":"IBM DataPower Gateways"},"Business Unit":{"code":"BU004","label":"Hybrid Cloud"},"Component":"--","Platform":[{"code":"PF009","label":"Firmware"}],"Version":"7.5.2;7.5.1;7.5;7.1;7.0.0","Edition":"Edition Independent"}]

Document Information

Modified date:
15 June 2018

UID

swg21500046