Using this information, you can prepare the appropriate JSON for the password to be encrypted. For example:

{"plainTextPassword":"secret","algorithm":"AES/CBC/PKCS5PADDING","algorithmKey":"AES"}

Keep this JSON available to use when you follow the steps below.

Step 1. Encrypt the password

When you encrypt the database password, you can supply some optional arguments, as shown in the table below.

To encrypt the database password, follow the steps below.

1. Go to <Confluence-installation-directory>/bin.

2. Run the following command to encrypt your database password. You can also use the optional parameters described above. 

   java -cp "./*" com.atlassian.secrets.cli.db.DbCipherTool -c com.atlassian.secrets.store.algorithm.AlgorithmSecretStore

3. When prompted for a password, enter the pre-prepared JSON object based on the information from Before you begin.
   Note: the JSON object must be entered as a single line.
   

   When this command runs successfully, you will see output similar to the output below:

   
   

   2023-10-13 00:30:49,016 main INFO [com.atlassian.secrets.DefaultSecretStoreProvider] Initiating secret store class: com.atlassian.secrets.store.algorithm.AlgorithmSecretStore
   2023-10-13 00:30:50,811 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Initiate AlgorithmCipher
   2023-10-13 00:30:50,891 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Encrypting data...
   2023-10-13 00:30:50,950 main DEBUG [store.algorithm.serialization.EnvironmentVarBasedConfiguration] Will try to read file path from environment variable under: com_atlassian_db_config_password_ciphers_algorithm_java_security_AlgorithmParameters
   2023-10-13 00:30:50,951 main DEBUG [store.algorithm.serialization.EnvironmentVarBasedConfiguration] Nothing found under environment variable.
   2023-10-13 00:30:51,093 main DEBUG [store.algorithm.serialization.UniqueFilePathGenerator] Will use generated name: java.security.AlgorithmParameters_1234567890
   2023-10-13 00:30:51,108 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Name of generated file with algorithm params used for encryption: java.security.AlgorithmParameters_1234567890
   2023-10-13 00:30:51,111 main DEBUG [store.algorithm.serialization.EnvironmentVarBasedConfiguration] Will try to read file path from environment variable under: com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_spec_SecretKeySpec
   2023-10-13 00:30:51,111 main DEBUG [store.algorithm.serialization.EnvironmentVarBasedConfiguration] Nothing found under environment variable.
   2023-10-13 00:30:51,220 main DEBUG [store.algorithm.serialization.UniqueFilePathGenerator] Will use generated name: javax.crypto.spec.SecretKeySpec_1234567890
   2023-10-13 00:30:51,245 main DEBUG [store.algorithm.serialization.SerializationFile] Saved file: javax.crypto.spec.SecretKeySpec_1234567890
   2023-10-13 00:30:51,353 main DEBUG [store.algorithm.serialization.UniqueFilePathGenerator] Will use generated name: javax.crypto.SealedObject_1234567890
   2023-10-13 00:30:51,357 main DEBUG [store.algorithm.serialization.SerializationFile] Saved file: javax.crypto.SealedObject_1234567890
   2023-10-13 00:30:51,369 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Encryption done.
   Success!
   For Jira, set the following properties in dbconfig.xml:
   
   <atlassian-password-cipher-provider>com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</atlassian-password-cipher-provider>
   <password>{"sealedObjectFilePath":"javax.crypto.SealedObject_1234567890","keyFilePath":"javax.crypto.spec.SecretKeySpec_1234567890"}</password>
   
   For Bitbucket, set the following properties in bitbucket.properties:
   
   jdbc.password.decrypter.classname=com.atlassian.secrets.store.algorithm.AlgorithmSecretStore
   jdbc.password={"sealedObjectFilePath":"javax.crypto.SealedObject_1234567890","keyFilePath":"javax.crypto.spec.SecretKeySpec_1234567890"}
   
   For Bamboo, set the following properties in bamboo.cfg.xml:
   
   <property name="jdbc.password.decrypter.classname">com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</property>
   <property name="hibernate.connection.password">{"sealedObjectFilePath":"javax.crypto.SealedObject_1234567890","keyFilePath":"javax.crypto.spec.SecretKeySpec_1234567890"}</property>
   
   For Confluence, set the following properties in confluence.cfg.xml:
   
   <property name="jdbc.password.decrypter.classname">com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</property>
   <property name="hibernate.connection.password">{"sealedObjectFilePath":"javax.crypto.SealedObject_1234567890","keyFilePath":"javax.crypto.spec.SecretKeySpec_1234567890"}</property>

When encrypting your password, the encryption tool generates three files and prints the output JSON object that you'll later add to the confluence.cfg.xml file. The next step discusses how to secure those files.

Step 2. Secure the generated files

Encrypting a password results in three generated files:

• javax.crypto.SealedObject_[timestamp]
  The file with the encrypted password.

• javax.crypto.spec.SecretKeySpec_[timestamp]
  The key used to encrypt your password. You will need this file to decrypt your password.

• java.security.AlgorithmParameters_[timestamp]
  The algorithm parameters used to encrypt your password. You will only need this file if you want to recreate the password.

If you're running Confluence in a cluster, the files must be available to all nodes via the same path. Confluence needs to access and read those files to decrypt your password, and to connect to the database. Change the permissions on the files generated by the tool so that they are read-only to the user running Confluence.

Step 3. Add the encrypted password to confluence.cfg.xml

To add the encrypted password:

1. Back up the <home-directory>/confluence.cfg.xml file. Move the backup to a safe place outside your instance.

2. In the confluence.cfg.xml file, add or modify the jdbc.password.decrypter.classname property to contain:

   com.atlassian.secrets.store.algorithm.AlgorithmSecretStore

3. In the confluence.cfg.xml file, add or modify the hibernate.connection.password property to contain the fully qualified path to the two files:

   {"sealedObjectFilePath":"/home/confluence/javax.crypto.SealedObject_1234567890","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_1234567890"}

4. Once updated, check that confluence.cfg.xml contains:

   <property name="jdbc.password.decrypter.classname">com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</property>
   <property name="hibernate.connection.password">{"sealedObjectFilePath":"/home/confluence/javax.crypto.SealedObject_1234567890","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_1234567890"}</property>

   Note: If you're running Confluence on Windows, avoid backslashes in the path to prevent JSON parsing errors. The paths should look like the following example:

   <property name="jdbc.password.decrypter.classname">com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</property>
   <property name="hibernate.connection.password">{"sealedObjectFilePath":"C:/confluence/javax.crypto.SealedObject_1234567890","keyFilePath":"C:/confluence/javax.crypto.spec.SecretKeySpec_1234567890"}</property>

5. Restart Confluence.

Step 4 (optional). Store paths as environment variables

You can choose to store paths to the generated files as environment variables. If the paths aren't present in the confluence.cfg.xml file, Confluence will automatically look for them in the specific environment variables. In this way, file paths will not be stored in the confluence.cfg.xml file, making it difficult to locate the files used for encryption.

To store the paths to the generated files as environment variables:

1. Store the two generated files as environment variables.

   • You don't need to add the file with algorithm parameters because AlgorithmCipher does not use it to decrypt the password.

   • You must set the following environment variables to the correct values in any of the scripts used for launching your Confluence instance. 

     com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_spec_SecretKeySpec
     com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_SealedObject

     For example:

     export com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_spec_SecretKeySpec=/home/confluence/javax.crypto.spec.SecretKeySpec_1234567890
     export com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_SealedObject=/home/confluence/javax.crypto.SealedObject_1234567890

2. Edit the output from the first step, Encrypt the password, and remove paths to the files.
   Your confluence.cfg.xml file should look like:

   <property name="jdbc.password.decrypter.classname">com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</property>
   <property name="hibernate.connection.password">{}</property>

3. Restart Confluence.

Decrypt the password

To decrypt the database password:

1. Extend the command used earlier with the -m decrypt parameter:

   java -cp "./*" com.atlassian.secrets.cli.db.DbCipherTool -c com.atlassian.secrets.store.algorithm.AlgorithmSecretStore -m decrypt

2. When asked for the password, provide the JSON object from your confluence.cfg.xml file.
   

   {"sealedObjectFilePath":"/home/confluence/javax.crypto.SealedObject_1234567890","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_1234567890"}

   After a successful decode, you will see a message similar to this:

   2023-10-13 05:01:14,203 main INFO [com.atlassian.secrets.DefaultSecretStoreProvider] Initiating secret store class: com.atlassian.secrets.store.algorithm.AlgorithmSecretStore
   2023-10-13 05:01:15,991 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Initiate AlgorithmCipher
   2023-10-13 05:01:16,068 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Decrypting data...
   2023-10-13 05:01:16,250 main DEBUG [secrets.store.algorithm.AlgorithmSecretStore] Decryption done.
   Success! Decrypted password using cipher provider: com.atlassian.secrets.store.algorithm.AlgorithmSecretStore decrypted password: secret

Recreate an encrypted password

If you lose an encrypted password and try to encrypt the plaintext password once again, the new encrypted password will look different. This is not an issue, as it will still represent the same plaintext password. However, in some cases, you might want to keep it consistent, for example by having the same encrypted password when a Confluence instance is migrated to another server.

To encrypt the password in the exact same way as you did before, you will need the key used to encrypt the original password and the algorithm parameters. Both of these were generated by the encryption tool and saved in the following files:

• Key - javax.crypto.spec.SecretKeySpec_[timestamp]
• Algorithm parameters - java.security.AlgorithmParameters_[timestamp]

Once you've located these files, you can point the encryption tool to their location by using two extra fields in the JSON object.

When asked for a password, provide the JSON object:

{"plainTextPassword":"secret","algorithm":"AES/CBC/PKCS5PADDING","algorithmKey":"AES","algorithmParametersFilePath":"/home/confluence/java.security.AlgorithmParameters_1234567890","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_1234567890"}

To encrypt the password, follow the steps in the first step, Encrypt the password, and use the JSON object with the key and algorithm parameters.

Troubleshooting

[c.a.c.config.database.DatabaseConfigHandler] Trying to get encrypted password from xml and decrypt it
[c.a.d.c.p.ciphers.algorithm.AlgorithmCipher] Runtime Exception thrown when decrypting:

[c.a.c.config.database.DatabaseConfigHandler] Trying to get encrypted password from xml and decrypt it
[c.a.c.config.database.DatabaseConfigHandler] Database password decryption success!
[c.a.config.bootstrap.DefaultAtlassianBootstrapManager] Could not successfully test your database:

[c.a.c.health.HealthChecks] Confluence couldn't connect to your database
[c.a.c.health.HealthChecks] Confluence failed to establish a connection to your database.