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 thedeployment.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: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:
-
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.
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:[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.-
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.