Versions Compared

Old Version 26

changes.mady.by.user Fiona Sargeant

Saved on

compared with

New Version 27

changes.mady.by.user Fiona Sargeant

Saved on

Key

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

Overview

PhixFlow expects to use a keystore for:

  • the database username and password
  • a pepper key that is added to add user passwords when encrypting them
  • the database username and password.

The pepper key 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 commandsIn the following examples, we have used a file type of PKCS12. You can also use JCEKS.

For details about the command syntax and how the keystore works, see Adding Data to a Keystore.


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

Table of Contents
indent12px
stylenone


Code Block
<keytool> -importpass -alias <keyAlias> -keystore <pathToKeystoreFile> -storetype <keytype>
Where:Is<keytool>
Windows command prompt

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 pepperkey

  1. Run the -importpass command, specifying pepperkey; see examples.
  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.
  3. When prompted for the password or secret to be stored, enter the string you want to use as a pepper key. 
Expand
titleExpand Windows Example

Command Line:

Code Block
"%JAVA_HOME%\bin\keytool
.exe"Windows PowerShell 
" -importpass -alias pepperkey -keystore C:\secure\hidden.jks -storetype PKCS12

Powershell:

Code Block
&"$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 - 
 -importpass -alias pepperkey -keystore C:\secure\
name
hidden.jks -storetype PKCS12



Expand
titleExpand Linux Example


Code Block
$JAVA_HOME/bin/keytool -importpass -alias pepperkey -keystore /opt/secure/
name
hidden.jks
<keytype>Either PKCS12 or JCEKS.
Tip

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.

 -storetype PKCS12



Tip

If you enter a different alias than pepperkey, remember to update phixflow-instance.xml so that it has the same alias.

Add Database Credentials

Step 1 

Create the keystore and the alias for the

Add the database username

1.1 Run the -importpass command. In <keyAlias> specify , 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 or secret to be stored, enter the actual username for the PhixFlow database, for example phixflow. 

Expand
titleExpand Windows Example

Command Line:

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

Powershell:

Code Block
&"$env:JAVA_HOME\bin\keytool.exe" -importpass -alias phixflow-database-user -keystore C:\secure\hidden.jks -storetype PKCS12



Expand
titleExpand Linux
:
Example


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


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

2.1.2 When prompted, enter the password you want to use for the keystore file, then re-enter to confirm it.1.3 When   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 or secret to be stored, enter the actual usernamepassword 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 .


Expand
titleExpand Windows Example


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


Code Block
&"
%JAVA
$env:JAVA_
HOME%
HOME\bin\keytool.exe" -importpass -alias phixflow-database-password -keystore C:\secure\hidden.jks -storetype PKCS12



Expand
titleExpand Linux
:
Example


Code Block
$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:
 Code Block
<property name="username">
	<value>phixflow-database-user</value>
</property>
<property name="password">
	<value>phixflow-database-password</value>
</property>
Step 4  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 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 5  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/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>
OrkeystorePass
The password for the keystore.
Use <!-- and --> to comment out the keystorePassEnvironmentVariable property.
<!-- keystore password -->
<property name="keystorePass">
   <value>storepw</value>
</property>

 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.
See
Adding Data to a Keystore Which includes understanding