Configure a Keystore and Aliases

Owned by Fiona Sargeant (Unlicensed)
Last updated: Aug 14, 2024 by Zoe Baldwin
3 min read

Overview

The use of a keystore is optional and these instructions can be skipped, if desired.

PhixFlow can use a keystore for:

  • a pepper string, which PhixFlow will add to local user passwords when encrypting them
  • the database username and password.

The pepper string and database account credentials are encrypted and stored here, along with their aliases. You can then use an alias to retrieve each secret from the keystore.

To configure the keystore, use the Java keytool -importpass command at the command line. In the following examples, we have used

  • a file type of PKCS12. You can also use JCEKS.
  • a keystore name of keystore.jks. If you use a different name for the keystore, you must update its name in the phixflow-secret.xml configuration file.
See also
Sections on this page

When you run the keytool -importpass command, it always prompts for a "password". This is because the keytool does not distinguish between the secrets that it stores. At the prompt, enter the actual value you want to store securely.

Create the keystore and add the pepper string and its alias

If you are creating the keystore on Windows, you must use the backslash \ in the path. PhixFlow will not be able to read the pepper key value if you use the forward slash /.

If you have follow the recommended instructions for installing Java (Install Java) the keytool program will be in your path. If you have take a different approach, you can find the keytool program under JAVA_INSTALLATION_HOME/bin.
  1. Run the -importpass command, specifying the alias: pepperkey 
    The alias is case-sensitive and must match phixflow-instance.xml: <prop key="pepperkey">pepperkey</prop>
    If you use a different alias, update phixflow-instance.xml to use the same alias.

  2. When prompted, enter the password you want to set for the keystore file, then re-enter to confirm it.
    Keep a secure record of this password.

    If you are following these instructions to upgrade PhixFlow, and your keystore already exists, in step 2 enter the password for your keystore.
    See also: Adding Data to a Keystore

  3. When prompted for the password, enter the string you want to use to pepper user passwords. 
    We recommend this string has the same characteristics as a password. For example it should be a random string containing at least 6 letters, numbers and special characters. 
    Keep a secure record of the pepper key. 
Windows Command Line Example
keytool -importpass -alias pepperkey -keystore C:\secure\keystore.jks -storetype PKCS12
Windows Powershell Example
keytool -importpass -alias pepperkey -keystore C:\secure\keystore.jks -storetype PKCS12
Linux Example
keytool -importpass -alias pepperkey -keystore /opt/secure/keystore.jks -storetype PKCS12

Populate the Keystore

Step 1  Add the database username

1.1 Run the -importpass command, specifying the alias username for the PhixFlow database, for example phixflow-database-user.

1.2 When prompted, enter the keystore password.

1.3 When prompted for the password, enter the actual username for the PhixFlow database, for example phixflow. 

Windows Command Line
keytool -importpass -alias phixflow-database-user -keystore C:\secure\keystore.jks -storetype PKCS12
Windows Powershell Example
keytool -importpass -alias phixflow-database-user -keystore C:\secure\keystore.jks -storetype PKCS12
Linux Example
keytool -importpass -alias phixflow-database-user -keystore /opt/secure/keystore.jks -storetype PKCS12

Step 2  Add the database password and alias to the keystore file

2.1.  Run the -importpass command specifying the alias password for the PhixFlow database, for example phixflow-database-password.

2.2  When prompted, enter the keystore password.

2.3 When prompted for the password, enter the actual password for the PhixFlow database.

Windows Command Line Example
keytool -importpass -alias phixflow-database-password -keystore C:\secure\keystore.jks -storetype PKCS12
Windows Powershell Example
keytool -importpass -alias phixflow-database-password -keystore C:\secure\keystore.jks -storetype PKCS12

Linux Example
keytool -importpass -alias phixflow-database-password -keystore /opt/secure/keystore.jks -storetype PKCS12

Configure Phixflow

The following settings need to be configured in local.properties or as environment variables.

Keystore Configuration

The keystore must be configured and populated during installation before PhixFlow is first started. Using a keystore is optional.

Property

Requires Configuration

Default Value

Explanation

keystore.file

Optional

/opt/secure/keystore.jks

Location of the keystore file. Only used if the keystore password is provided, otherwise use of the keystore is disabled.

phixflow-keystore-password

Optional

<none>

Default key name containing the keystore password

keystore.passwordKey

Rarely

phixflow-keystore-password

Name of the key containing the keystore password.

pepper.key.name

Rarely

pepperKey

Name of the key containing the pepper key which is used for encrypting passwords.

api.key.name

Rarely

phixflow-api-key

Name of the key containing the API key which is used for signing API credentials.

Changing the Keystore Password

It is not possible to change the password directly on the keystore file as this corrupts its values. Instead we recommend creating a new keystore file and importing the original values into it.

The process to create a new keystore is:

  1. Tomcat needs to be stopped.
  2. Rename your original keystore file e.g. keystoreOld.jks.
  3. Use the importkeystore command to import the existing keystore into a a new keystore, at which point you will be prompted for the password for the original keystore and then a new password for the new keystore.
    1. Give the new keystore the original keystore's name e.g. keystore.jks. 
  4. Depending on your configuration, you will need to update local.properties, phixFlow-secret.xml or the environment variable, with the new keystore password.

Examples

Linux
keytool -importkeystore \
 -srckeystore keystoreOld.jks -srcstoretype PKCS12 \
 -destkeystore keystore.jks -deststoretype PKCS12
Windows
keytool -importkeystore \
 -srckeystore keystoreOld.jks -srcstoretype PKCS12 \
 -destkeystore keystore.jks -deststoretype PKCS12