KB Article #180329

How to update the sample certificates for AIS 2.1.0, AIS 2.2.1 and AIS 2.3.0 .

Problem

(warning) On the 9^th of August, the Tomcat server certificate delivered with AIS infrastructure will expire.

(warning) On the 28^th of November 2019, the root Certificate Authority that issues and it’s trusted by all AIS sample certificate will expire.

Resolution

Although Axway is strongly advising against the usage of sample certificates (especially for production purposes) we’re going to present a procedure for changing these certificates for testing purposes.

If you are using your own custom certificates for SSO and SSL then you are not impacted by the expiration of these certificates.

For specific information regarding the usage/replacement of custom certificates please refer to InterPlay 2.3.0 Security Guide, Change the HTTPS server certificate section.

The purpose of this document is to treat the case when the actual Axway sample certificates are to be replaced by newer Axway certificates, with modified expiration date and increased security (SHA-256 signature with 2048-bit RSA key).

Products/versions impacted:

The following products and versions are impacted:

Interplay 2.1.0/2.2.1/2.3.0
Designer 2.1.0/2.2.1/2.3.0
AdministrationUI 2.1.0/2.2.1/2.3.0
DatastoreClient 2.1.0/2.2.1/2.3.0
Report 2.1.0/2.2.1/2.3.0
Rule Engine Server 2.2.1/2.3.0

AIS 2.4 is not impacted as it already embeds the new default certificates and does not require applying a manual procedure. However if you plan to use CAS SSO this will require applying SP 2 for 2.4 (work in progress).

Important:

There is a known issue on all versions (2.1.0/2.2.1/2.3.0) with regards to CAS SSO (new SSO), applying this procedure will not work for CAS SSO, you need to apply a fix.
Fixes for CAS SSO will be provided in the next SPs as follows:

For 2.1.0 - next SP (SP17) to be released on June 14th 2019
For 2.2.1 - next SP (SP15) to be released on June 28th 2019
For 2.3.0 - next SP (SP15) to be released on July 19th 2019

We consider that PassPort is used for authentication by the Axway products.

The PassPort Service Pack 20 is mandatory for this procedure as it activates the new root Certificate Authority.

This procedure must be implemented on each AIS product installation. So if you have separate installation for Interplay, Datastore, Designer, Report, etc… you need to upgrade each one separately with the same procedure.

Introduction

In order to decide on what procedure to use (1. Only sample certificates or 2. Sample certificates combined with custom ones), please run the following command before replacing each of the provided keystores.

keytool -v -list -keystore <keystore-file-name>

The password is not mandatory for this command to work.

Examine the output of the command and confirm that no custom certificates are present in that keystore. All of the old sample certificates are issued by root CA [ CN=PassPortCA, OU=R&D, O=Axway, L=Puteaux, C=FR] that expires on Thu Nov 28 12:35:37 EET 2019.

If you are already using only your own custom certificates then this KB does not apply and you are not impacted by the expiration dates of the sample certificates.

If you are using only the Axway sample certificates then please implement the actions described at point #1 below.

Otherwise, if you are using both Axway sample certificates and your own certificates then please implement the actions described at point #2 below.

1. Update certificates for installations that use only sample certificates

Download the new sample certificates attached to this KB (New_Sample_Certificates.zip)

Certs

keystore.jks → Tomcat private certificates
truststorePassPort.jks → trusted certificates used for selfregistration and communication
truststoreSSO.jks → trusted certificates used for Proxy SSO (default SSO implementation)

Registry

truststore
- truststore.jks→ trusted certificates used for PassPort client

ssofilter

ssofilter.jks → private certificates for CAS SSO
truststore.jks → trusted certificates for CAS SSO

Please use the method presented in Introduction to check the presence of custom certificates for each keystore that will be replaced. It’s always a good idea to backup the original files prior to replacing them.

1. Stop the Tomcat/Rule Engine Server

2. Replace the three keystore files from Product_install_folder/AIS/Tools/config/certs with the ones from the provided certs folder

NOTE:

For AIS 2.1.0, please do not replace manually the three keystore files from Product_install_folder/AIS/Tools/config/certs with the ones provided on the KB.
Instead of that, you need to run the Administration update-store command.

Administration update-store -p <New_Sample_Certificates/certs/keystore_jks> -s <password> -t ssl_keystore
Administration update-store -p <New_Sample_Certificates/certs/truststorePassPort_jks> -s <password> -t selfregistration_truststore
Administration update-store -p <New_Sample_Certificates/certs/truststoreSSO_jks> -s <password> -t sso_trustore

The Administration update-store command is successful if you see the following output.

Copying source store to ...
Writing new configuration

3. Perform the following steps using Repository Console (../AIS/Repository/startConsole.sh or startConsole.bat)

a) Export registry file

exportRegistry <export_registry_path>

b) unregisterPassport for all applications that use PassPort

Usually, we have admin, default, designer:

unregisterPassport admin
unregisterPassport default
unregisterPassport designer

c) Replace <export_registry_path>/registry/truststore/truststore.jks with the one from the provided registry/truststore folder

d) Import registry:

importRegistry <export_registry_path>

4. Delete truststore file

For 2.1.0:

Delete <Product_install_dir>/AISuite/Extra/PassportAM/registry/truststore directory

For 2.2.1 & 2.3.0:

Delete <Product_install_dir>/AIS/Extra/PassportAM/registry/truststore directory

5. If you are using (or plan to use) the CAS SSO feature, replace ssofilter.jks and truststore.jks files from Product_Install_folder/InterPlay/war/WEB-INF with the ones from the provided ssofilter folder.

The same applies for Designer, DatastoreClient, keeping in mind the updated install path

6. Start Tomcat/Rule Engine Server

7. Validate that you can connect to the different UI as before, If not please contact Axway Support

2. Update certificates for installations that use sample certificates combined with custom ones

Obtain/download the new PassPort Certificate Authority public sample certificate (attached to this KB) – PassPortCA.crt.

This PassPort Certificate Authority public certificate must be imported in every truststore that needs to trust sample PassPort certificates with the following command:

   keytool -importcert -v -alias <alias> -file <certificate_crt> -keystore <truststore_jks>

When asked for certificate trust, answer “yes”.

It may be necessary to delete an old certificate with the same alias, in this case you can use the following command.

   keytool -delete -v -alias <alias> -keystore <truststore_jks>

It’s always a good idea to backup the original files prior to updating them.

1. Stop the Tomcat/Rule Engine Server

2. Import PassPortCA.crt in Product_install_folder/AIS/Tools/config/certs truststorePassPort.jks and truststoreSSO.jks using passportca alias

NOTE:

Administration update-store -p <New_Sample_Certificates/certs/keystore_jks> -s <password> -t ssl_keystore
Administration update-store -p <New_Sample_Certificates/certs/truststorePassPort_jks> -s <password> -t selfregistration_truststore
Administration update-store -p <New_Sample_Certificates/certs/truststoreSSO_jks> -s <password> -t sso_trustore

The Administration update-store command is successful if you see the following output:

Copying source store to ...
Writing new configuration