Versions Compared

Old Version 8

changes.mady.by.user Fiona Sargeant (Unlicensed)

Saved on

compared with

New Version Current

changes.mady.by.user Thomas Swindells

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

...

...

...

...

...

Overview

...

In version 11 the use of a keystore is optional, these instructions can be skipped if desired. In version 10 use of the keystore is required.

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.

...

Keytool Syntax

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

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

...

<keyAlias> 

...

The full path to the keystore file, for example:

  • Windows - C:\secure\name.jks
  • Linux - /opt/secure/name.jks

...

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

  1. Run the -importpass command
    In <keyAlias> specify the alias for the PhixFlow database username.
  2. When prompted, enter a password for the keystore file and confirm it. 
  3. When prompted, enter the username for the PhixFlow database.
Tip

The command's prompts are not very clear. The second prompt may ask for a password, but you need to enter the username.

Example commands

Windows:

...

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


Panel
borderColor#7da054
titleColorwhite
titleBGColor#7da054
borderStylesolid
titleSections on this page

Table of Contents
indent12px
stylenone



Tip

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

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

    Tip

    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. 
Code Block
titleWindows Command Line Example
keytool -importpass -alias pepperkey -keystore C:\secure\keystore.jks -storetype PKCS12


Code Block
titleWindows Powershell Example
keytool -importpass -alias pepperkey -keystore C:\secure\keystore.jks -storetype PKCS12


Code Block
titleLinux 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. 

Code Block
titleWindows Command Line
keytool -importpass -alias phixflow-database-user -keystore C:\secure\keystore.jks -storetype PKCS12


Code Block
titleWindows Powershell Example
keytool -importpass -alias phixflow-database-user -keystore C:\secure\

...

keystore.jks -storetype PKCS12


Code Block
titleLinux

...

Example
keytool -importpass -alias

...

phixflow-database-user -keystore /opt/secure/

...

keystore.jks -storetype PKCS12

1.2.  The keytool prompts you to set a password for the keystore file and confirm it. Enter the password, eg. storepw and re-enter to confirm.

...

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.

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

2.1.  Repeat the commands, using <keyAlias> to add the alias for the password. For example, run the command:

Windows:

...

2.2  When prompted, enter the keystore password.

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

Code Block
titleWindows Command Line Example
keytool -importpass -alias

...

phixflow-database-password -keystore C:\secure\

...

keystore.jks -storetype PKCS12


Code Block

Linux:

...

titleWindows Powershell Example
keytool -importpass -alias

...

phixflow-database-password -keystore C:\secure\

...

keystore.jks -storetype PKCS12

...

2.2  The keytool prompts you to enter the password for the keystore, for example, storepw.

2.3  When the keytool prompts you to enter the actual password to be stored, enter the password for the PhixFlow database, for example, P*56word.

...


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

Configure Phixflow
The configuration process differs between version 10 and version 11. 
Please follow the relevant instructions below.
 Expand
titleVersion 11
The following settings need to be configured in local.properties or as environment variables.
 Insert excerpt
Server Configuration Properties
Server Configuration Properties
nameKeystore
nopaneltrue

 Expand
titleVersion 10
Step 1  Configure phixflow-datasource.xml
Edit phixflow-datasource.xml to add the aliases for the PhixFlow database username and password. For example:
 Code Block
<property name="username">
	
...
<value>phixflow-database-user</value>
</property>
<property name="password">
	
...
<value>phixflow-database-password</value>
</property>
Step 
...
2  Set the Environment Variable
 Note
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 WindowsIn 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 
...
If you do not set an environment variable, you must include the keystore password in phixflow-secret.xml.
 Warning
Never add the keystore password to the profile for the Tomcat user.
...
 information about how to set environment variables in Linux, see:
<keystore-password>
...
Specify the password for the keystore.

 Warning
Never add the keystore password to the profile for the Tomcat user.
Step 3  Configure phixflow-secret.xml
Copy phixflow-secret.xml.example to phixflow-secret.xml and edit it to set the values as follows:
Required?PropertyValueExample
RequiredkeystoreTypeThe type of the keystore, either PKCS12 or JCEKS
<!-- keystore type (PKCS12 or JCEKS) --> 
<property name="keystoreType">
   <value>PKCS12</value>
</property>
RequiredkeystoreFile
The path to the keystore.
<!-- keystore filepath  --> 
<property name="keystoreFile">
   <value>/opt/secure/
...
keystore.jks</value> 
</property>
Either 
(recommended)		keystorePassEnvironmentVariable
The name of the environment variable.
Use <!-- and --> to comment out the keystorePass property.

 Info
When specifying the value for the password in an environment variable, the value entered should adhere the policy of the environment variables for your operating system. 

<!-- keystore password -->
<property name="keystorePassEnvironmentVariable"
...
><value>KEY_PASS</value>
</property>
OrkeystorePass
The password for the keystore.
Use <!-- and --> to comment out the keystorePassEnvironmentVariable property.
 Info
When specifying the value for the password in the phixflow-secret.xml, special characters will need to be escaped.

<!-- keystore password -->
<property name="keystorePass">
   <value>storepw</value>
</property>
Understanding How PhixFlow Uses A Keystore
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.
When PhixFlow is running, it provides the account credentials to its database as follows:
  1. phixflow-datasource.xml stores alias credentials for the database. It requests actual credentials from phixflow-secret.xml.
  2. phixflow-secret.xml asks the keystore for the actual credentials.
    • This file stores the location of the keystore file and optionally its password (2a in the diagram below).
    • Alternatively, the keystore password is configured as an environment variable (2b in the diagram below)
  3. The keystore file returns the actual account credentials to phixflow-secret,
  4. which, in turn, passes the actual credentials to phixflow-datasource.xml.
  5. 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.
Image Removed
...

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


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
 Code Block
titleLinux
linenumberstrue
keytool -importkeystore \
 -srckeystore keystoreOld.jks -srcstoretype PKCS12 \
 -destkeystore keystore.jks -deststoretype PKCS12

 Code Block
titleWindows
linenumberstrue
keytool -importkeystore \
 -srckeystore keystoreOld.jks -srcstoretype PKCS12 \
 -destkeystore keystore.jks -deststoretype PKCS12