PhixFlow Help
Configure a Keystore and Aliases
Overview
PhixFlow expects to use a keystore for:
- a pepper key, 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.
- Adding Data to a Keystore for the command syntax and how the keystore works
- Understanding Password Encryption for information about the pepper string and how to ensure user security information is migrated to use the most secure encryption
- Considerations for Pepper Keys for whether or not to use different pepper keys for different instances.
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 /
.
The following commands assume you have set the environment variable JAVA_HOME. If you do not, you can set it in your current session following the command examples:
- On windows in powershell:
$env:JAVA_HOME=
"C:\Program Files\Java\jre1.8.0_282"
- On linux in a bash shell:
export JAVA_HOME=
/usr/lib/jvm/adoptopenjdk-11-hotspot-amd64
Alternatively, replace JAVA_HOME in the commands below with the base installation directory of Java.
- 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. - 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. - When prompted for a password, enter the string you want to use 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.
Add Database Credentials
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 a password, 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. Run the -importpass
command again, 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.
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 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 |
|
Required | keystoreFile | The path to the keystore. |
|
Either (recommended) | keystorePassEnvironmentVariable | The name of the environment variable. Use |
|
Or | keystorePass | The password for the keystore. Use |
|
On startup, PhixFlow checks that there is one password mechanism, either keystorePassEnvironmentVariable
or
. Do not specify both as this will prevent PhixFlow from running.keystorePass
Please let us know if we could improve this page feedback@phixflow.com