Overview

To keep the database username and password secure, PhixFlow is configured to use a keystore file. The database account credentials are encrypted and stored here, along with aliases. You can then use the aliases to retrieve each secret username and password from the keystore.

To configure the keystore, you will use the Java keytool -importpass command at the command line.

Keytool Syntax

For reference, here is the full syntax and the values you will need to use. The steps below provide example commands.

<keytool> -importpass -alias <keyAlias> -keystore <pathToKeystoreFile> -storetype <keytype>

Sections on this page

Where:	Is
`<keytool>`	Windows command prompt	`"%JAVA_HOME%\bin\keytool.exe"`
	Windows PowerShell	`&"$env:JAVA_HOME\bin\keytool.exe"`
	Linux	`$JAVA_HOME/bin/keytool`
`<keyAlias>`	The alias for a username or password. The phixflow-secret.xml configuration file refers to the `<keyAlias>` so that PhixFlow knows which encrypted secret to retrieve from the keystore. After you enter an alias, the keytool prompts you to enter the corresponding username or password. This is the actual value that the database requires to permit access.
<pathToKeystoreFile>	The full path to the keystore file, for example: Windows - `C:\secure\name.jks` Linux - `/opt/secure/name.jks`
<keytype>	Either PKCS12 or JCEKS.

The keytool does not differentiate between the secrets it stores so it always prompts for a password. Sometimes you will need to enter a username and others a password. The following instructions explain which you need to enter.

How to Set up a Keystore

Step 1 Create the keystore and the alias for the database username

1.1 Run the -importpass command. In <keyAlias> specify the alias username for the PhixFlow database, for example phixflow-database-user.

Windows:

"%JAVA_HOME%\bin\keytool" -importpass -alias phixflow-database-user -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias phixflow-database-user -keystore /opt/secure/hidden.jks -storetype PKCS12

1.2 When prompted, enter the password you want to use for the keystore file, then re-enter to confirm it.

1.3 When prompted for the password or secret to be stored, enter the actual username for the PhixFlow database, for example phixflow.

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

2.1. Repeat the -importpass command. In <keyAlias> specify the alias password for the PhixFlow database, for example phixflow-database-password.

Windows:

"%JAVA_HOME%\bin\keytool" -importpass -alias phixflow-database-password -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias phixflow-database-password -keystore C:\secure\hidden.jks -storetype PKCS12

2.2 When prompted, enter the password for the keystore file. This is the same password you set in step 1.2. This time the password opens the keystore.

2.3 When prompted for the password or secret to be stored, enter the actual password for the PhixFlow database.

Step 3 Configure phixflow-datasource.xml

Edit phixflow-datasource.xml to add the aliases for the PhixFlow database username and password. For example:

<property name="username">
	<value>phixflow-database-user</value>
</property>
<property name="password">
	<value>phixflow-database-password</value>
</property>

Step 4 Set the Environment Variable

We recommend that you use an environment variable for the keystore password, as it provides additional security.
If you do not set an environment variable, you must include the keystore password in phixflow-secret.xml.

Create an environment variable with the form <variable-name>: <keystore-password>

In Windows In Linux

<variable-name>

In Windows: In the environment variable, specify any variable name you choose.

Use the EnvironmentFile directive in the systemd service definition.
Ensure that only root can read/write EnvironmentFile.

For information about how to set environment variables in Linux, see:

<keystore-password>

Specify the password for the keystore.

Never add the keystore password to the profile for the Tomcat user.

Step 5 Configure phixflow-secret.xml

Copy phixflow-secret.xml.example to phixflow-secret.xml and edit it to set the values as follows:

Required?	Property	Value	Example
Required	`keystoreType`	The type of the keystore, either PKCS12 or JCEKS	`<!-- keystore type (PKCS12 or JCEKS) --><property name="keystoreType"> <value>PKCS12</value> </property>`
Required	`keystoreFile`	The path to the keystore.	`<!-- keystore filepath --><property name="keystoreFile"> <value>/opt/secure/hidden.jks</value> </property>`
Either (recommended)	`keystorePassEnvironmentVariable`	The name of the environment variable. Use `<!--` and `-->` to comment out the `keystorePass` property.	`<!-- keystore password --><property name="keystorePassEnvironmentVariable"> <value>KEY_PASS</value></property>`
Or	`keystorePass`	The password for the keystore. Use `<!--` and `-->` to comment out the `keystorePassEnvironmentVariable` property.	`<!-- keystore password --><property name="keystorePass"> <value>storepw</value> </property>`

On startup, PhixFlow checks that there is one password mechanism, either keystorePassEnvironmentVariable or keystorePass. Do not specify both as this will prevent PhixFlow from running.

Understanding How PhixFlow Uses A Keystore

When PhixFlow is running, it provides the account credentials to its database as follows:

phixflow-datasource.xml stores alias credentials for the database. It requests actual credentials from phixflow-secret.xml.
phixflow-secret.xml asks the keystore for the actual credentials.
1. The keystore password is configured as an environment variable This file stores the location of the keystore file and optionally its password (2a in the diagram below).
2. Alternatively, phixflow-secret.xml stores the location of the keystore file and optionally its password (2b in the diagram below)
The keystore file returns the actual account credentials to phixflow-secret
which, in turn, passes the actual credentials to phixflow-datasource.xml.
phixflow-datasource.xml then uses the actual credentials to log into the database, so that PhixFlow can update it.

This is shown in the diagram below.

How PhixFlow authenticates to its database using a keystore

Details used in the diagram
Keystore file name	`hidden.jks`
Keystore password	`storepw`
Environment variable name	`KEY_PASS`
Environment variable value (the keystore password)	`storepw`
PhixFlow database credentials	Username	Password
Actual	`phixFlow`	`P*59word`
Alias	phixflow-database-user	`phixflow-database-password`

Configure a Keystore for Database Credentials