Encrypt Passwords with the Cipher Tool¶

The instructions on this page explain how plain text passwords in configuration files can be encrypted using the secure vault implementation that is built into the WSO2 Identity Server.

Before you begin

If you are using Windows, you need to have Ant installed in order to use the Cipher Tool.

Encrypt passwords¶

While you are able to encrypt passwords using symmetric or asymmetric encryption, it is recommended to use symmetric encryption due to its greater resilience towards emerging post-quantum threats. Asymmetric encryption methods like RSA are not recommended due to their vulnerability to quantum computing capabilities.

Important

Configure a separate keystore as the internal keystore to encrypt passwords. If the internal keystore is not specified, the primary keystore will be used instead.

Follow the steps below to encrypt passwords:

Add the following [secrets] configurations to the bottom of the deployment.toml file in the <IS_HOME>/repository/conf/ directory. Provide an alias for the password type followed by the actual password enclosed within square brackets [] as shown below.
```
[secrets]
admin_password = "[password_1]"
keystore_password = "[password_2]"
key_password = "[password_3]"
truststrore_password = "[password_4]"
log4j2_password = "[password_5]"
```
Open a terminal, navigate to the <IS_HOME>/bin/ directory, and execute the following command based on the encryption method and your operating system:
Symmetric encryptionAsymmetric encryption
Prerequisite

To support symmetric encryption, you should have a symmetric secret in an internal keystore of type PKCS12. Follow the instructions here to add one.
- For Linux: ./ciphertool.sh -Dconfigure -Dsymmetric
- For Windows: ciphertool.bat -Dconfigure -Dsymmetric
Warning

Asymmetric encryption methods like RSA are not recommended due to their vulnerability to post-quantum threats.
- For Linux: ./ciphertool.sh -Dconfigure
- For Windows: ciphertool.bat -Dconfigure

Open the deployment.toml again and see that the passwords are encrypted.

[secrets]
admin_password = "xxxxxxx"
keystore_password = "xxxxxxx"
key_password = "xxxxxxx"
truststrore_password = "xxxxxxx"
"log4j2_password" = "xxxxxxx"

Use encrypted passwords¶

Once you have encrypted passwords, you can use them in the relevant configuration files as follows:

In deployment.toml¶

You can include encrypted passwords in the deployment.toml file found in the <IS_HOME>/repository/conf directory by using the $secret{alias} format as shown below:

Note

You may pass passwords as environment variables and system properties instead of directly setting the values. See Set Passwords using Environment Variables/System Properties for instructions.

[super_admin]
username="admin"
password="$secret{admin_password}"

[keystore.tls]
password = "$secret{keystore_password}" 
alias = "$secret{keystore_password}" 
key_password = "$secret{key_password}"  

[truststore]                  
password = "$secret{keystore_password}"

In log4j2.properties¶

You may include encrypted passwords in the log4j2.properties file found in the <IS_HOME>/repository/conf directory. For example, you may set log4j.appender.LOGEVENT.password as shown below:

log4j.appender.LOGEVENT.password=secretAlias:log4j2_password

Change encrypted passwords¶

You may follow the steps below to change passwords that are already encrypted.

Shut down the WSO2 Identity Server.
On a command prompt, navigate to the <IS_HOME>/bin/ directory where the cipher tool scripts reside.
Run the cipher tool by executing the command corresponding to your encryption method and operating system:
Symmetric encryptionAsymmetric encryption
- For Linux: ./ciphertool.sh -Dconfigure -Dsymmetric
- For Windows: ciphertool.bat -Dconfigure -Dsymmetric
- For Linux: ./ciphertool.sh -Dconfigure
- For Windows: ciphertool.bat -Dconfigure
You will be prompted for the primary keystore password. Enter the password. For the default keystore, it is wso2carbon.
A numbered list of all encrypted password aliases will be displayed. Enter the number corresponding to the alias of the password you want to change.
The system will then prompt you (twice) to enter the new password. Enter your new password.

Rotating Encryption Secrets¶

Note

To support symmetric encryption, you must specify a PKCS12 type keystore as the internal keystore.

You can rotate encryption keys by switching between symmetric and asymmetric encryption or by changing the encryption keys within the same encryption mode. Follow the steps below.

Use the corresponding command to add the new key to an existing keystore with a new alias.

Symmetric encryptionAsymmetric encryption (JKS)Asymmetric encryption (PKCS12)

keytool -genseckey -alias new_alias -keyalg AES -keysize 256 -keystore internal.p12 -storetype PKCS12 -storepass password -keypass password

keytool -genkeypair -alias new_alias -keyalg RSA -keystore wso2carbon.jks -storepass password -keypass password

keytool -genkeypair -alias new_alias -keyalg RSA -keystore wso2carbon.p12 -storetype PKCS12 -storepass password -keypass password

Update the deployment.toml file found in the <IS_HOME>/repository/conf directory to reflect the new key or secret alias:

JKSPKCS12

[keystore.internal]
file_name = "internal.jks"
type = "JKS"
alias = "new_alias"
password = "$secret{keystore_password}"
key_password = "$secret{keystore_password}"

[keystore.internal]
file_name = "internal.p12"
type = "PKCS12"
alias = "new_alias"
password = "$secret{keystore_password}"
key_password = "$secret{keystore_password}"

Navigate to the <IS_HOME>/bin/ directory on the command prompt, where the cipher tool scripts reside.
Execute the cipher tool script to re-encrypt the passwords with the new key or secret. Use the -Drotate option and specify the old alias.
Symmetric encryptionAsymmetric encryption
- For Linux: ./ciphertool.sh -Drotate -Dold.alias=wso2carbon
- For Windows: ciphertool.bat -Drotate -Dold.alias=wso2carbon
- On Linux: ./ciphertool.sh -Drotate -Dold.alias=wso2carbon -Dsymmetric
- On Windows: ciphertool.bat -Drotate -Dold.alias=wso2carbon -Dsymmetric
Go back to the deployment.toml file and see that the passwords are re-encrypted with the new encryption key.