KB Article #180329
How to update the sample certificates for AIS 2.1.0, AIS 2.2.1 and AIS 2.3.0 .
Problem
On the 9th of August, the Tomcat server certificate delivered with AIS infrastructure will expire.
On the 28th 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:
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
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) Import PassPortCA.crt in <export_registry_path>/registry/truststore/truststore.jks using passportca alias
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, import PassPortCA.crt in Product_Install_folder/InterPlay/war/WEB-INF/truststore.jks using the certificateEntry property defined in properties as alias (the default value is passportssofilter)
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
Related articles:
https://support.axway.com/kb/180293/language/en
https://support.axway.com/kb/180303/language/en