Overview

PhixFlow uses a Java keystore and associated secret service for data that needs to be secure. When PhixFlow is installed, the keystore is created and the username and password for the PhixFlow database are added. The instructions for this are in Configure a Keystore for Database Credentials.

Additional details that we recommend you store in the keystore are:

a pepper key used to encrypt local user passwords
where external authorisation is required, usernames and passwords for:
- email accounts
- datasource instances

You can then use an alias or key to retrieve the data from the keystore.

Sections on this page

Adding Data to the Keystore

To add data to the keystore, use the Java keytool -importpass line command. From a command prompt:

Enter the -importpass command, specifying an alias/key.
When the keytool prompts, enter the keystore's password.
When the keytool prompts again for a "password", enter the data, usually a user name or password.

For example:

The keystore is called secret.jks... what's our default called ...
The keystore password is secretpass
The datasource instance details you want to store are:
- username sqluser, wth the key db1
- password x34!2axf with the key db1pass

Windows example:

Click to expand Windows example

"%JAVA_HOME%\bin\keytool" -importpass -alias db1 -keystore C:\secure\secret.jks -storetype PKCS12
secretpass
sqluser
"%JAVA_HOME%\bin\keytool" -importpass -alias db1pass -keystore C:\secure\secret.jks -storetype PKCS12
secretpass
x34!2axf

Click here to expand Linux example

$JAVA_HOME/bin/keytool -importpass -alias db1 -keystore /opt/secure/secret.jks -storetype PKCS12
secretpass
sqluser
$JAVA_HOME/bin/keytool -importpass -alias db1pass -keystore /opt/secure/secret.jks -storetype PKCS12
secretpass
x34!2axf

Pepperkye

If you have local users you also need to set up a Pepperkey

Wikipedia article on Pepper Encrytption

Datasource instances or email

todo

Keytool Syntax

For reference, here is the keytool command syntax.

<keytool> -importpass -alias <key> -keystore <file> -storetype <type>

Where:	Is
`<keytool>`	Windows command prompt	`"%JAVA_HOME%\bin\keytool.exe"`
	Windows PowerShell	`&"$env:JAVA_HOME\bin\keytool.exe"`
	Linux	`$JAVA_HOME/bin/keytool`
`<key>`	The alias/key for a username or password. After you enter an alias, the keytool prompts you to enter the corresponding data, usually a username or password.
<file>	The full path to the keystore file, for example: Windows `C:\secure\name.jks` Linux `/opt/secure/name.jks`
<keytype>	PKCS12 (recommended) 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.

Understanding How PhixFlow Uses A Keystore

This section illustrates how PhixFlow uses a keystore to access its own database.

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`

Adding Data to a Keystore