To add extra security to your Crowd instance, you can encrypt the database password that is stored in the crowd.cfg.xml file used by Crowd to access your database.

Before you begin

Prepare the JSON object

You need to provide all arguments required to encrypt your password in a JSON object. Prepare it beforehand using the following information and example.

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

Encrypting the password

Complete the following steps to encrypt the password.

Step 1: Encrypt the password

1. Go to <Crowd-installation-directory>.

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

3. After running the command, you'll be asked to provide the required arguments in a JSON object. You can read more about them in the Before you begin section.

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 crowd.cfg.xml file.

Step 2: Secure the generated files

Move the files generated by the tool to a place that’s accessible in a multi-node configuration and that won’t be overwritten by an upgrade (e.g. ${crowd_home}/shared/keys/db), and change them to read-only. Crowd 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: Add the encrypted password to crowd.cfg.xml

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

1. Go to Crowd home directory and back up the crowd.cfg.xml file. Move the backup to a safe place outside of your Crowd server.

2. Edit the crowd.cfg.xml file.

3. Replace the "hibernate.connection.password" property with the output JSON object. Adjust the JSON object based on the following examples:

   • UNIX Make sure to update the paths included in the snippet. The output should look like on the following example: 

     <property name="jdbc.password.decrypter.classname">com.atlassian.db.config.password.ciphers.algorithm.AesOnlyAlgorithmCipher</property>
     <property name="hibernate.connection.password">{"sealedObjectFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.SealedObject_1666647204564","keyFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.spec.SecretKeySpec_1666647204521"}</property>

   • WINDOWS Make sure to update the paths included in the snippet. 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: 

     <property name="jdbc.password.decrypter.classname">com.atlassian.db.config.password.ciphers.algorithm.AesOnlyAlgorithmCipher</property>
     <property name="hibernate.connection.password">{"sealedObjectFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.SealedObject_1666647204564","keyFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.spec.SecretKeySpec_1666647204521"}</property>

4. Restart Crowd.

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.AesOnlyAlgorithmCipher -m decrypt

When asked for the JSON object, provide the one from your crowd.cfg.xml file.

SAMPLE JSON OBJECT WHEN USING FILE PATHS

{"sealedObjectFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.SealedObject_1666647204564","keyFilePath":"<Crowd-home-directory>/shared/keys/db/javax.crypto.spec.SecretKeySpec_1666647204521"}

Recreating an encrypted password

When you lose the encrypted password and encrypt the plain text password again, the new encrypted password will look differently. That’s not an issue, as it will still represent the same plain text password. However, in some cases, you might want to re-create an encrypted password.

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.

{"plainTextPassword":"yourPassword", "algorithm":"AES/CBC/PKCS5PADDING", "algorithmKey":"AES", "algorithmParametersFilePath":"java.security.AlgorithmParameters_1666647204502", "keyFilePath":"java.security.AlgorithmParameters_1666647204502"}

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