AES encryption
In this method, you’ll use AlgorithmCipher that allows you to choose the algorithm used to encrypt the sensitive information in the bitbucket.properties file.
Before you begin: Prepare the JSON object
You’ll need to provide all arguments required to encrypt the sensitive data in a JSON object. Prepare beforehand by using the information and examples below.
| Field | Description |
|---|---|
plainTextPassword | Password in plain text. |
algorithm | You can choose one of the following algorithms:
|
algorithmKey | The algorithm key must correspond with the algorithm chosen above:
|
Step 1. Encrypt the sensitive data
Let's look at an example of encrypting your database password.
Go to
<Bitbucket-installation-directory>/tools/atlassian-password.Run the following command to encrypt your password:
java -cp "./*" com.atlassian.secrets.cli.db.DbCipherTool -c com.atlassian.secrets.store.algorithm.AlgorithmSecretStoreAfter running the command, you'll be asked to provide the required arguments in a JSON object in a single line. Prepare it based on the information from Before you begin.
When encrypting your data, the encryption tool generates three files and prints the output JSON object that you'll later add to the bitbucket.properties file. The next step discusses how to secure those files.
Step 2. Secure the generated files
Change the permissions on the files generated by the tool so that they are read-only to the user running Bitbucket. Note that if a multi-node cluster is in use, then the files should be available on the same path for all nodes. Bitbucket needs the encrypted property to configure cluster-wide settings such as the database password.
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 need this file only if you want to recreate an encrypted password.
Step 3. (Optional) Store file paths as environment variables
This step is optional and is only applicable if you're on a version below 8.11
This step is optional. You can store paths to the generated files as environment variables. If the paths aren't present in the bitbucket.properties file and the jdbc.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.
Store the two generated files as environment variables. You don't need to add the file with algorithm parameters, because
AlgorithmCipherdoes 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 Bitbucket instance:com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_spec_SecretKeySpec com_atlassian_db_config_password_ciphers_algorithm_javax_crypto_SealedObjectEdit 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.secrets.store.algorithm.AlgorithmSecretStore jdbc.password={}
Step 4. Add the encrypted data to bitbucket.properties
Go to the Bitbucket home directory and back up the bitbucket.properties file. Move the backup to a safe place, ideally outside your instance.
- Based on your Bitbucket version, do one of the following:
For versions on 8.11+, in the bitbucket.properties file, replace the application property with the output JSON object with
{ENC}prefixed to the value. The properties should look like the following:encrypted-property.cipher.classname=com.atlassian.secrets.store.algorithm.AlgorithmSecretStore jdbc.password={ENC}{"sealedObjectFilePath":"/home/bitbucket/javax.crypto.SealedObject_123456789","keyFilePath":"/home/bitbucket/javax.crypto.spec.SecretKeySpec_123456789"}For versions below 8.11, in the
bitbucket.propertiesfile, replace thejdbc.passwordproperty 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:
jdbc.password.decrypter.classname=com.atlassian.secrets.store.algorithm.AlgorithmSecretStore jdbc.password={}If you’re not using environment variables and want to stick to file paths in the bitbucket.properties file, make sure you update their paths after moving them to a secure place. The properties should look like the following: If you’re not using environment variables and want to stick to file paths in the
bitbucket.propertiesfile, make sure you update their paths after moving them to a secure place. The properties should look like the following:jdbc.password.decrypter.classname=com.atlassian.secrets.store.algorithm.AlgorithmSecretStore jdbc.password={"sealedObjectFilePath":"/home/bitbucket/javax.crypto.SealedObject_123456789","keyFilePath":"/home/bitbucket/javax.crypto.spec.SecretKeySpec_123456789"}
Restart Bitbucket.
Decrypt the sensitive data
To decrypt the sensitive data, 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 decryptWhen asked for a password, based on your Bitbucket version, do one of the following:
For versions on 8.11+, provide the JSON object from your
bitbucket.propertiesfile without the{ENC}prefix.{"sealedObjectFilePath":"/home/bitbucket/javax.crypto.SealedObject_123456789","keyFilePath":"/home/bitbucket/javax.crypto.spec.SecretKeySpec_123456789"}For versions below 8.11, provide the JSON object from your
bitbucket.propertiesfile.Sample JSON object when using file paths{"sealedObjectFilePath":"/home/bitbucket/javax.crypto.SealedObject_123456789","keyFilePath":"/home/bitbucket/javax.crypto.spec.SecretKeySpec_123456789"}
Recreate encrypted data
Let's look at an example of recreating encrypted database 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 Bitbucket 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.
| Field | Description |
|---|---|
keyFilePath | Path to a file that contains the key used to encrypt your original password, e.g. 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. |
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.