Versions Compared

Old Version 14

changes.mady.by.user Fiona Sargeant

Saved on

compared with

New Version 15

changes.mady.by.user Fiona Sargeant

Saved on

Key

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

Overview

PhixFlow uses a Java keystore for data that needs to be secure. When PhixFlow is installed, the keystore is created and the following are added:

  • a pepper key used to encrypt local user password
  • username and password for the PhixFlow database

The instructions for this are in the Installing PhixFlow topic: see Configure a Keystore and KeysAliases.

We recommend that you also store other credentials in the keystore, such as those provided:

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

You will need to provide PhixFlow users with the keys so that they can configure secure

  • datasources
  • email accounts.


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

Table of Contents
indent12px
stylenone



Note

This documentation assumes that each PhixFlow instance has it's own unique keystore.

If you run multiple instances on the same server using a single keystore, the stored information and their aliases should be unique. Ideally the alias should indicate the instance to which it relates.

Keytool Syntax

The keytool command syntax is:

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

where

  • <keytool> depends on OS or command tool:
    • in the Windows command prompt    "%JAVA_HOME%\bin\keytool.exe"
    • in Windows PowerShell    &"$env:JAVA_HOME\bin\keytool.exe"
    • in Linux    $JAVA_HOME/bin/keytool 
  • <file> is the full path to the keystore file. The keystore file name must match the name in phixflow-instance.xml. The default name is secure.jks, for example:
    • Windows   C:\secure\secure.jks
    • Linux   /opt/secure/secure.jks
  • <type>Either PKCS12 (recommended) or JCEKS.
  • <key> is a key/alias for something you want to store. Use this to retrieve the encrypted data.

After you enter a <key>, the keytool 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, usually a username or a password.

Tip

When you run a <keytool> command, the keytool prompts you to enter:

  • the keystore password.
  • a "password". This is the information you want to store associated with the alias provided in the command. This may be a username, a password or a pepper key.

Adding Data to the Keystore

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

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


For a username and password, you need to run the command twice. For example:

  • a keystore is called secure.jks
  • its password is keypass
  • The datasource instance details you want to store are:
    • username sqluser, wth the key db1
    • password x34!2axf with the key db1pass

Windows example:

Expand
titleClick to expand Windows example


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



Expand
titleClick here to expand Linux example


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


Understanding How PhixFlow Uses A Keystore

This section PhixFlow has a secret service wrapper that it uses to communicate with the keystore. The configuration file webapp/WEB-INF/classes/phixflow-secret.xml tells Phixflow where to find the keystore file and its password. PhixFlow periodically checks the keystore based on the retryDelay. This defaults to 10 seconds, set in milliseconds. This means PhixFlow can use updated information in the keystore without requiring a Tomcat restart.

Example: Accessing the PhixFlow Database

This example 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:

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

 How PhixFlow authenticates to its database using a keystore


Details used in the diagram
Keystore file namehidden.jks
Keystore passwordstorepw
Environment variable nameKEY_PASS
Environment variable value
(the keystore password)		storepw
PhixFlow database credentialsUsernamePassword
Actual

phixFlow

P*59word
Alias

phixflow-database-user

phixflow-database-password


Note

The default keystore filename set in webapp/WEB-INF/classes/phixflow-secret.xml. This configuration file manages PhixFlow authenticating to its own database.

Configuring Keystore Reading

The configuration file webapp/WEB-INF/classes/phixflow-secret.xml 

manages PhixFlow authenticating to its own database

. As well as having the keystore filename, you can use the options in this to configure how often PhixFlow re-reads data from the keystore.

There are two ways to use the keystore

PhixFlow is configured to periodically check the keystore directly based on the retryDelay set in phixflow-secret.xml 

Alternatively, you can configure PhixFlow to only read the keystore when it starts

Expand
titleChecks periodically
Code Block<!-- To directly use keyStoreService and not the caching service, comment the CachingSecretService bean elements and change the bean id of KeystoreSecretService to secretService There should be a bean defined with id secretService always, as that's is referred in phixflow-datasource

.

xml --> <bean id="secretService" class="com.accipia.centerview.service.secret.CachingSecretService"> <property name="cachingPeriod"> <value>10000</value> </property> <property name="secretService" ref="keyStoreSecretService"> </property> </bean> <bean id="keyStoreSecretService" class="com.accipia.centerview.service.secret.KeystoreSecretService"> <property name="retries"><!-- keystore type (PKCS12 or JCEKS) --> <value>3</value> </property> <property name="retryDelay"> <value>10000</value> </property> Expand
titleOnly checks on startup

Using the keyStoreService

Code Block<!-- To directly use keyStoreService and not the caching service, comment the CachingSecretService bean elements and change the bean id of KeystoreSecretService to secretService There should be a bean defined with id secretService always, as that's is referred in phixflow-datasource.xml --> <bean id="secretService" class="com.accipia.centerview.service.secret.CachingSecretService"> <property name="cachingPeriod"> <value>10000</value> </property> <property name="secretService" ref="keyStoreSecretService"> </property> </bean> <bean id="secretService" class="com.accipia.centerview.service.secret.KeystoreSecretService"> # <property name="retries"><!-- keystore type (PKCS12 or JCEKS) --> # <value>3</value> # </property> # <property name="retryDelay"> # <value>10000</value> # </property>