Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

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

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


Where:Is

<keytool>

Windows command prompt"%JAVA_HOME%\bin\keytool.exe"
Windows PowerShell &"$env:JAVA_HOME\bin\keytool.exe"
Linux  $JAVA_HOME/bin/keytool 

<keyAlias> 

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:

  • Windows - C:\secure\name.jks
  • Linux - /opt/secure/name.jks
<keytype>either PKCS12 or JCEKS.

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.

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:

"%JAVA_HOME%\bin\keytool" -importpass -alias databasealias -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias pdbdev -keystore /opt/secure/hidden.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.

1.3.  The keytool prompts you to 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 the alias for the password. For example, run the command:

Windows:

"%JAVA_HOME%\bin\keytool" -importpass -alias 123xyz -keystore C:\secure\hidden.jks -storetype PKCS12

Linux:

$JAVA_HOME/bin/keytool -importpass -alias 123xyz -keystore C:\secure\hidden.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.

Step 3  Configure phixflow-datasource.xml

Edit phixflow-datasource.xml to add the aliases for the PhixFlow database username and password. For example:

<property name="username">
	<value>pdbdev</value>
</property>
<property name="password">
	<value>123xyz</value>
</property>

Step 4  Set the Environment Variable

We recommend that you use an environment variable for the keystore password, as it provides additional security.

Optionally, create an environment variable: <variable-name> <keystore-password>, where:

  • <variable-name>:
    • in Windows, is any name you choose, for example KEY_PASS
    • in Linux, is the EnvironmentFile directive in the systemd service definition.
      Ensure that only root can read/write EnvironmentFile.
  • <keystore-password> is the password for the keystore. For example storepw.

If you do not set an environment variable, you must include the keystore password in phixflow-secret.xml.

Never add the keystore password to the profile for the Tomcat user.

For information about how to set environment variables in Linux, see:

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>




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.

Figure 1: How PhixFlow authenticates to its database

  • No labels