Overview
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.
To configure the keystore, you will use the following Java keytool 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> |
...
| Where: | Is | |
|---|---|---|
| Windows command prompt | |
| Windows PowerShell | | |
| Linux | | |
| The alias for a username or password. The keytool prompts you to enter the corresponding username or password. | |
| <pathToKeystoreFile> | The full path to the keystore file, for example:
| |
| <keytype> | either PKCS12 or JCEKS. | |
dfd
| Tip |
|---|
The command's prompts are not very clear. It sometimes asks for a password when you need to enter a username. |
How to Set up a Keystore
Step 1 Create the keystore and the alias for the database username
1.1 Run the -importpass command
...
. In <keyAlias> specify the alias for the PhixFlow database username
...
| 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
(pbdev in the following examples).
Windows:
| Code Block |
|---|
"%JAVA_HOME%\bin\keytool" -importpass -alias databasealiaspbdev -keystore C:\secure\hidden.jks -storetype PKCS12 |
...
| Code Block |
|---|
$JAVA_HOME/bin/keytool -importpass -alias pdbdev -keystore /opt/secure/hidden.jks -storetype PKCS12 |
1.2 . The keytool prompts you to set When prompted, enter a password for the keystore file and confirm it. Enter the password, eg. storepw and , then re-enter to confirm it.
1.3 . The keytool prompts you to When prompted, enter the actual username to be stored. Enter the username for the PhixFlow database, for example PhixFlow-DB-Dev..
Step 2 Add the database password and alias to the keystore file
2.1. Repeat the commands, using <keyAlias> to add Repeat the -importpass command. In <keyAlias> specify the alias for the PhixFlow database password. For example, run the command: (123xyz in the following examples).
Windows:
| Code Block |
|---|
"%JAVA_HOME%\bin\keytool" -importpass -alias 123xyz -keystore C:\secure\hidden.jks -storetype PKCS12 |
...
| Code Block |
|---|
$JAVA_HOME/bin/keytool -importpass -alias 123xyz -keystore C:\secure\hidden.jks -storetype PKCS12 |
2.2 The keytool prompts you to 2 When prompted, enter the password for the keystore , for example, storepwfile.
2.3 When the keytool prompts you to 3 When prompted enter the actual password to be stored, enter the password for the PhixFlow database, for example, P*56word.
Step 3 Configure phixflow-datasource.xml
...
| 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>: , where:<keystore-password>
| In Windows | In Linux | |
|---|---|---|
<variable-name> |
...
...
In Windows: In the environment variable, specify any variable name you choose |
...
. | Use the |
...
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 5 Configure phixflow-secret.xml
...
Understanding How PhixFlow Uses A Keystore
...
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.
- 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)
- 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.
...
Figure 1: How PhixFlow authenticates to its database
| 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 |
| 123xyz |