Advanced encryption

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

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

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 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"}

Step 1: Encrypting the password

  1. Go to <Jira-installation-directory>/bin.
  2. Run the following command to encrypt your password. You can also use optional parameters described below.

    java -cp "./*" com.atlassian.db.config.password.tools.CipherTool -c com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher
    See optional arguments
    • -- silent -s: limits logging to 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 it. We recommend that you omit this parameter so your password is not stored in the history.

      Enclose the JSON object in single quotes.


  3. After running the command, you'll be asked to provide the required arguments in a JSON object. Prepare it based on the information from Before you begin.

The encryption tool generated three files that were used to encrypt your password, and printed the output JSON object that you'll later add to the dbconfig.xml file.

Step 2: Securing the generated files

Move the files generated by the tool to a secure place, and change them to read-only. Jira needs to be able to access and read those files to decrypt your password and connect to the database.

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


Step 3: (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 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.

  1. Store the two of the generated files as environment variables. You don't need to add the file with algorithm parameters, because Jira will not be using it to decrypt the password. You must use the following environment variables:

    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_123456789
    export com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_SealedObject=/home/jira/javax.crypto.SealedObject_123456789
  2. Edit the output from Step 1: Encrypting the password and remove paths to the files. The final output should look similar to the following JSON object:

    <atlassian-password-cipher-provider>com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</atlassian-password-cipher-provider>
    <password>{}</password>

Step 4: Adding the encrypted password to dbconfig.xml

Add the output JSON object to the dbconfig.xml file, replacing your current password.

  1. Go to Jira home directory and back up the dbconfig.xml file. Move the backup to a safe place outside of your Jira server.
  2. Edit the dbconfig.xml file.
  3. Replace the <password> tag with the output JSON object. Depending on whether you used environment variables or not, adjust the JSON object to one of the following examples:

    • If you stored file paths as environment variables, remove the paths from the output. It should look like the following example:

      <atlassian-password-cipher-provider>com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</atlassian-password-cipher-provider>
      <password>{}</password>
    • If you didn't use environment variables and want to stick to file paths in the dbconfig.xml file, make sure you updated them after moving the files to a secure place. The output should look like the following example: 

      <atlassian-password-cipher-provider>com.atlassian.db.config.password.ciphers.algorithm.AlgorithmCipher</atlassian-password-cipher-provider>
      <password>{"sealedObjectFilePath":"/home/jira/javax.crypto.SealedObject_123456789","keyFilePath":"/home/jira/javax.crypto.spec.SecretKeySpec_123456789"}</password>
    • 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.db.config.password.ciphers.algorithm.AlgorithmCipher</atlassian-password-cipher-provider>
      <password>{"sealedObjectFilePath":'C:\\jira\\javax.crypto.SealedObject_123456789',"keyFilePath":'C:\\jira\\javax.crypto.spec.SecretKeySpec_123456789'}</password>
  4. Restart Jira.

Decrypting the password

To decrypt the password, extend the command 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 JSON object, provide the one from your dbconfig.xml file.

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

Recreating an encrypted password

When you lose the encrypted password and encrypt the plain text password once again, the new encrypted password will look differently. This is not an issue, as it will still represent the same plain text password. However, in some cases, you might want to keep the consistency, for example by having the same encrypted password for all Jira Data Center nodes.

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

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"}

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 plain text one.

The setup screen opens after restarting Jira...

The setup 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 Oct 26, 2023

Was this helpful?

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