AES encryption

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

This method provides more security as you don't have to store the encrypted password anywhere in the configuration file, which makes it difficult for unauthorised parties to find and decrypt it.

Encrypt the password

In this method, we'll use AlgorithmCipher, which lets you choose the algorithm used to encrypt the database password in the dbconfig.xml file.

Before you begin: Preparing the JSON object

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

FieldDescription
plainTextPasswordPassword in plaintext
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

 Using this information, 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: Encrypting the password

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

Argument

Description

-c,--class <arg>

Canonical class name of the cipher. Leave empty to use the default: com.atlassian.secrets.store.base64.Base64SecretStore

-h,--help

Output the help message, which displays these optional arguments

-m,--mode <arg>

Use encrypt (default) or decrypt on your provided password.

-p,--password <arg>

The plaintext password that you want to encrypt. If you omit this parameter, the console will ask you to type the password.

-s,--silent

Log minimum info.

To encrypt the database password, follow the steps below.

  1. Go to <Jira-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 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 is run you should 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 dbconfig.xml file. The next step discusses how to secure those files.

Step 2: Securing the generated files

The following files have been 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 need this file only if you wanted to recreate an encrypted password

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

Step 3: Adding the encrypted password to dbconfig.xml

To add the encrypted password:

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

  2. In the dbconfig.xml file, add or modify the <atlassian-password-cipher-provider> property to contain:

    com.atlassian.secrets.store.algorithm.AlgorithmSecretStore
  3. In the dbconfig.xml file, add or modify the <password> property to contain the fully qualified path to the two files:

    {"sealedObjectFilePath":"/home/jira/javax.crypto.SealedObject_1234567890","keyFilePath":"/home/jira/javax.crypto.spec.SecretKeySpec_1234567890"}
  4. Once updated, check that dbconfig.xml contains:

    <atlassian-password-cipher-provider>com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</atlassian-password-cipher-provider>
    <password>{"sealedObjectFilePath":"/home/jira/javax.crypto.SealedObject_1234567890","keyFilePath":"/home/jira/javax.crypto.spec.SecretKeySpec_1234567890"}</password>

    WINDOWS If you’re running Jira on Windows, you need to additionally escape the file paths and change double quotes (") surrounding the path to single quotes (') to avoid JSON parsing errors. The paths should look like the following example:

    <atlassian-password-cipher-provider>com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</atlassian-password-cipher-provider>
    <password>{"sealedObjectFilePath":'C:\\jira\\javax.crypto.SealedObject_1234567890',"keyFilePath":"'C:\\jira\\javax.crypto.spec.SecretKeySpec_1234567890'"}</password>
  5. Restart Jira.

Step 4: (Optional) Storing file paths as environment variables

tip/resting Created with Sketch.

This step is optional, but we recommend that you do it for extra security.

You can choose to store paths to the generated files as environment variables. If the paths aren't present in the dbconig.xml file, Jira will automatically look for them in the specific environment variables. In this way, file paths will not be stored in the dbconfig.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 Jira 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/jira/javax.crypto.spec.SecretKeySpec_1234567890
    export com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_SealedObject=/home/jira/javax.crypto.SealedObject_1234567890
  2. Edit the output from the first step, Encrypting the password, and remove paths to the files. Your confluence.cfg.xml file should look like:

    <atlassian-password-cipher-provider>com.atlassian.secrets.store.algorithm.AlgorithmSecretStore</atlassian-password-cipher-provider>
    <password>{}</password>
  3. Restart Jira.

Decrypting the password

To decrypt the sensitive data:

  1. Extend the command 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 JSON object, provide the one from your dbconfig.xml file.

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

On running the command, the secret will be decrypted and printed:

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

Recreating 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 Jira 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. Below you can find the description of these fields and a sample 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.

algorithmParametersFilePath

Path to a file that contains the algorithm parameters used to encrypt your original password, e.g. java.security.AlgorithmParameters_[timestamp] .

When asked for a password, provide the JSON object:

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

To encrypt the password, follow the steps in Step 1: Encrypting the password, and use the JSON object with they key and algorithm parameters.

Troubleshooting

Reverting the changes...

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

The health check screen opens after restarting Jira...

The health check screen means that Jira 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 <Jira_home_directory>/log/atlassian-jira.log, and check the lines after: Reading database configuration from.

You’ll probably see the following message:

[c.a.j.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 could have been deleted, or are no longer available if you changed the environment from staging to production. To verify that, try adding file paths to the JSON object in the dbconfig.xml file.
  • If you’re seeing some Bouncy Castle errors, you will need encrypt the password again.
‘Jira had problems starting up’ message is displayed after restarting Jira…

To investigate this problem, open <Jira_home_directory>/log/atlassian-Jira.log, and check the lines after: Reading database configuration from.

You’ll probably see the following messages:

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

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

This means that Jira decrypted the password successfully, but the password itself is incorrect. You can verify that by completing these steps:

  1. Open the dbconfig.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 dbconfig.xml file.
Last modified on Jul 12, 2024

Was this helpful?

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