Adding Data to a Keystore
- Fiona Sargeant (Unlicensed)
- Zoe Baldwin
- Chris Welford
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 string 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 Aliases.
We recommend that you also store other credentials in the keystore, such as those provided:
- to a database by an analysis model datasource instance
- by system notification email accounts.
You can then use an alias to retrieve the data from the keystore.
You will need to provide PhixFlow users with the alias that they need to configure secure:
- datasources
- email accounts.
This documentation assumes that each PhixFlow instance has it's own 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
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
.
The keytool command syntax to add entries is:
<keytool> -importpass -alias <key> -keystore <file> -storetype <type>
The keytool command syntax to delete entries is:
<keytool> -delete -alias <key> -keystore <file>
- <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
- Windows
- <type>Either PKCS12 (recommended) or JCEKS.
is a key/alias for something you want to store. Use this to retrieve the encrypted data.<key>
After you enter a
, 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.<key>
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 string.
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 string you want to store, usually a user name or password.
To add a username and password to the keystore, 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 keydb1
- password
x34!2axf
with the keydb1pass
- username
Windows example:
keytool -importpass -alias db1 -keystore C:\secure\secure.jks -storetype PKCS12 keypass sqluser keytool -importpass -alias db1pass -keystore C:\secure\secure.jks -storetype PKCS12 keypass x34!2axf
keytool -importpass -alias db1 -keystore /opt/secure/secure.jks -storetype PKCS12 keypass sqluser keytool -importpass -alias db1pass -keystore /opt/secure/secure.jks -storetype PKCS12 keypass x34!2axf
Changing Keystore Entries
It is not possible to change a username or password when it is in the keystore. Instead, you have to:
- delete the entry using the
keytool -delete
command; see Keystore Syntax, above. - add a different username or password using the
keytool -importpass
command, using the same alias.
For the commands, see Keystore Syntax, above.
If you change an alias, remember to update any configuration files that use the alias.
Keystores for Multiple Instances
If you are running more than one PhixFlow instance, you may have a keystore for each instance. In this case, you can use the same alias in each keystore. For example, each keystore can have a "pepperKey" or "databasePassword".
If you are using one keystore for multiple PhixFlow instances, then each instance must have a unique alias. It is good practice for the alias to clearly indicate the instance. For example if you have separate Production and Development instances you could use the aliases:
- ProdDatabasePassword, DevDatabasePassword
- ProdPepperKey, DevPepperKey.
Remember to update phixflow-instance.xml to refer to the pepper alias you set in the keystore.
Understanding How PhixFlow Uses A Keystore
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:
- 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.
- 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).
- 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 |
| P*59word |
Alias | phixflow-database-user | phixflow-database-password |
The default keystore filename set in webapp/WEB-INF/classes/phixflow-secret.xml
. This configuration file manages PhixFlow authenticating to its own database.