Documentation regarding configuring of Keystores does not mandate the addition of Primary and Internal Keystores causing errors during startup.

[VinulaUthsara]

Hi Team,

When configuring a distributed APIM setup of CP and GW we followed the below mentioned steps:

1. Change keystore password at "/repository/resources/security":

keytool -storepasswd -new <newpassword> -keystore wso2carbon.jks -storepass wso2carbon

2. Change key password

keytool -keypasswd -alias wso2carbon -keystore wso2carbon.jks

3. Update new password in deployment.toml
4. Start the server

We followed the above steps along with the documentation [1] and [2] to setup a distributed deployment locally and change the key password and keystore password. But we can observe issues where the APIM gives errors related to the keystores such as when only the keystore password and key password is changed in the keystore.tls configuration:

Caused by: java.io.IOException: Keystore was tampered with, or password was incorrect

and/or

Caused by: java.security.UnrecoverableKeyException: Password verification failed

We were able to resolve the above mentioned issues after adding the keystore.tls, keystore.primary and keystore.internal configurations to the deployment.toml files in our local testing as follows:

[keystore.tls]
file_name =  "wso2carbon.jks"
type =  "JKS"
password =  "<password1>"
alias =  "wso2carbon"
key_password =  "<password1>"

[keystore.primary]
file_name =  "wso2carbon.jks"
type =  "JKS"
password =  "<password1>"
alias =  "wso2carbon"
key_password =  "<password1>"

[keystore.internal]
file_name =  "wso2carbon.jks"
type =  "JKS"
password =  "<password1>"
alias =  "wso2carbon"
key_password =  "<password1>"

However, the above information/steps on adding all the configurations of keystore.tls, keystore.primary, keystore.internal with the newly changed key password and keystore password as mandatory (to avoid keystore related errors) is not mentioned in the documentation when a change is made to the keystore.

Information regarding this step in documentation [1] or [2] is not available. Due to this users will face this issue and not be aware that the above mentioned configurations cause these errors.

Therefore, it is better to improve the documentation with this information.

Affected Product Version: APIM 4.2.0

Suggested Labels: Type/Docs, Docs/Has Impact, Documentation, Type/Improvement

[1] https://apim.docs.wso2.com/en/4.2.0/install-and-setup/setup/distributed-deployment/deploying-wso2-api-m-in-a-distributed-setup/ [2] https://apim.docs.wso2.com/en/4.2.0/install-and-setup/setup/security/configuring-keystores/configuring-keystores-in-wso2-api-manager/#configuring-keystores-in-wso2-api-manager

Thanks.

[VinulaUthsara]

The documentation [1] has now been updated with the important note as in the following screenshot:

[1] https://apim.docs.wso2.com/en/latest/install-and-setup/setup/security/configuring-keystores/configuring-keystores-in-wso2-api-manager/

[VinulaUthsara]

Closing as completed