Skip to content

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

To encrypt passwords on the WSO2 Identity Server:

  1. Add the following [secrets] configurations to the bottom of the deployment.toml file in the <IS_HOME>/repository/conf/ directory. Give an alias for the password type followed by the actual password. The following example lists the most common passwords in configuration files.

    [secrets]
admin_password = "[password_1]"
keystore_password = "[password_2]"
key_password = "[password_3]"
truststrore_password = "[password_4]"
log4j2_password = "[password_5]"

  2. Open a terminal, navigate to the <IS_HOME>/bin/ directory, and execute the following command to enable the cipher tool using the -Dconfigure flag.

    • On Linux: ./ciphertool.sh -Dconfigure
    • On Windows: ciphertool.bat -Dconfigure

  3. Open the deployment.toml file again and see that the alias 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.

  1. Shut down the WSO2 Identity Server.

  2. On a command prompt, navigate to the <IS_HOME>/bin/ directory where the cipher tool scripts reside.

  3. Run the cipher tool by executing the command corresponding to your operating system:

    • Linux: ./ciphertool.sh -Dchange
    • Windows: ciphertool.bat -Dchange

  4. You will be prompted for the primary keystore password. Enter the password. For the default keystore, it is wso2carbon.

  5. 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.

  6. 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.

  1. 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 -storepass password -keypass password

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

  2. 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.p12"
type = "PKCS12"
alias = "new_alias"
password = "$secret{keystore_password}"
key_password = "$secret{keystore_password}"

  3. Navigate to the <IS_HOME>/bin/ directory on the command prompt, where the cipher tool scripts reside.

  4. 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

  5. Go back to the deployment.toml file and see that the passwords are re-encrypted with the new encryption key.

Related topics