Advanced encryption

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

To add extra security to your Confluence site, you can encrypt the database password that is stored in the confluence.cfg.xml file.

In this method, we'll use AlgorithmCipher that allows you to choose the algorithm used to encrypt your password.

On this page:

Before you begin

Prepare the JSON object

You’ll need to provide all arguments required to encrypt your password in a JSON object. Prepare beforehand by using the information and examples below.

FieldDescription

plainTextPassword

Password in plain text.

algorithm

You can choose one of the following algorithms:

  • AES/CBC/PKCS5Padding

  • DES/CBC/PKCS5Padding

  • DESede/CBC/PKCS5Padding

algorithmKey

The algorithm key must correspond with the algorithm chosen above:

  • AES

  • DES

  • DESede

See a sample JSON object...
{"plainTextPassword":"yourPassword","algorithm":"AES/CBC/PKCS5PADDING","algorithmKey":"AES"}

Note that the JSON object must be entered as a single line.

Step 1. Encrypt the password

To encrypt the database password:

  1. Go to <install-directory>/bin.
  2. Run the following command to encrypt your password:
     

    java -cp "./*" com.atlassian.db.config.password.tools.CipherTool -c com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher
    Optional arguments...
    • -- silent -s: limits logging to a minimum

    • -- help -h: prints a help message with all parameters

    • -- mode -m: defines what to do with the password, either encrypt or decrypt. If omitted, 'encrypt' will be used.

    • -- password -p: JSON object with required arguments. If omitted, you'll be asked to enter a password. We recommend that you omit this parameter so that your password is not stored in the terminal history.

  3. After running the command, you'll be asked to provide the required arguments in a JSON object in a single line.

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

Move the files generated by the tool to a secure place. Change them to read-only and accessible only to the user running Confluence. If you're running Confluence in a cluster, the files should be available to all nodes via the same path. Confluence needs to be able to access and read those files to decrypt your password and connect to the database.

The following files are generated:

  • javax.crypto.SealedObject_[timestamp]
    File with the encrypted password.
  • javax.crypto.spec.SecretKeySpec_[timestamp]
    Key used to encrypt your password. You will need this file to decrypt your password.
  • java.security.AlgorithmParameters_[timestamp]
    Algorithm parameters used to encrypt your password. You will only need this file if you want to recreate the password.

Store paths as environment variables

This step is optional.

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 and the hibernate.connection.password is an empty JSON object ({}), AlgorithmCipher will look for them in the environment. This way, file paths are not stored in the 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
  2. Edit the output from the first step, Encrypt the password, and remove paths to the files. The decrypter class name and password should match the following:

    <jdbc.password.decrypter.classname>=com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher
    <hibernate.connection.password>={}

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

To add the encrypted password:

  1. Back up the <local-home>/confluence.cfg.xml file. Move the backup to a safe place, ideally outside your instance.
  2. In the confluence.cfg.xml file, replace the hibernate.connection.password property with the output JSON object. Depending on whether you’re using environment variables or not, adjust the JSON object to one of the following examples:

    If you’re storing file paths as environment variables, remove the paths from the output. The properties should look like the following:

    When using environment variables
    <property name="jdbc.password.decrypter.classname">com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</property>
    <property name="hibernate.connection.password">{}</property>

    If you’re not using environment variables and want to stick to file paths in the confluence.cfg.xml file, make sure you update their paths after moving them to a secure place. The properties should look like the following:

    When not using environment variables
    <property name="jdbc.password.decrypter.classname">com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</property>
    <property name="hibernate.connection.password">{"sealedObjectFilePath":"/home/confluence/javax.crypto.SealedObject_123456789","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_123456789"}</property>

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

    If using Windows
    <property name="jdbc.password.decrypter.classname">com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</property>
    <property name="hibernate.connection.password">{"sealedObjectFilePath":"C:/confluence/javax.crypto.SealedObject_123456789","keyFilePath":"C:/confluence/javax.crypto.spec.SecretKeySpec_123456789"}</property>
  3. Restart Confluence.

Decrypt the password

To decrypt an encrypted password, extend the command used earlier with the -m decrypt parameter:

java -cp "./*" com.atlassian.db.config.password.tools.CipherTool -c com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher -m decrypt

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

Sample JSON object when using environment variables
{}
Sample JSON object when using files
{"sealedObjectFilePath":"/home/confluence/javax.crypto.SealedObject_123456789","keyFilePath":"/home/confluence/javax.crypto.spec.SecretKeySpec_123456789"}

Recreate an encrypted password

If you lose an encrypted password and try to encrypt the plain text password once again, the new encrypted password will look different. This is not an issue, as it will still represent the same plain text 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.

FieldDescription
keyFilePath

Path to a file that contains the key used to encrypt your original password, e.g. javax.crypto.spec.SecretKeySpec_[timestamp].

If you stored the file path as environment variable, you can omit this parameter.

algorithmParametersFilePathPath to a file that contains the algorithm parameters used to encrypt your original password, e.g. java.security.AlgorithmParameters_[timestamp].
Sample JSON object with all fields...
{"plainTextPassword":"yourPassword", "algorithm":"AES/CBC/PKCS5PADDING","algorithmKey":"AES","algorithmParametersFilePath":"java.security.AlgorithmParameters_123456789","keyFilePath":"javax.crypto.spec.SecretKeySpec_123456789"}

Note that the JSON object must be entered as a single line.

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

Reverting the changes...

To revert the changes, remove the <atlassian-password-cipher-provider> tag from the confluence.cfg.xml file, and change the encrypted password to a plain text one.

Setup screen appears after restarting Confluence...

The setup screen means that Confluence couldn't connect to the database to access your configuration, most probably because of an error with decrypting your password.

To solve this problem, open <home-directory>/logs/atlassian-confluence.log, and check the lines after "Reading database configuration from".

You’ll probably see the following message:

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

If that’s the case, read the message, as it contains details about the error and a possible solution.

If the error is related to missing files, there might be a problem with your environment variables. They may have been deleted, or are no longer available if you changed the environment from staging to production. To verify, try adding file paths to the JSON object in the confluence.cfg.xml file.

If you’re seeing "Bouncy Castle" errors, you will need encrypt the password again.

‘Confluence had problems starting up’ message is displayed after restarting Confluence…

To investigate this problem, go to <home-directory>/logs/atlassian-confluence.log, and check the lines after: "Reading database configuration from".

You’ll probably see the following messages:

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

This means that Confluence decrypted the password successfully, but the password itself is incorrect.

To verify this:

  1. Open the confluence.cfg.xml file, and copy the encrypted password.
  2. Decrypt the password.
  3. Check if the decrypted password is the same as the one in your backup confluence.cfg.xml file.
Last modified on Aug 22, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.