Versions Compared

Old Version 1

changes.mady.by.user Fiona Sargeant

Saved on

compared with

New Version 2

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 and associated secret service for data that needs to be secure, this includes:

  • a pepper key used to encrypt local user passwords
  • username and passwords for the PhixFlow database
  • where external authorisation is required, usernames and passwords for: 

data, such as usernames and passwords are encrypted and stored here. You then use an alias or key to retrieve the data from the keystore.

To configure the keystore, you will 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 commands.


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

Table of Contents
indent12px
stylenone



SYNTAX TBC

Code Block
<keytool> -importpass -alias <keyAlias> -keystore <pathToKeystoreFile> -usernameKey <userkey> and -passwordKey <passkey> -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 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 - C:\secure\name.jks
  • Linux - /opt/secure/name.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.


The installer sets up a keystore during installation and configures the username and password for the database. 


If you have local users you also need to set up a Pepperkey

Wikipedia article on Pepper Encrytption


Adding Data to the Keystore


  1. Use the -importpass command to enter a key.
  2. When prompted, enter keystore's password.
  3. When prompted for a "password" enter the data, usually a user name or password. 

For example,

  • The keystore is called secret.jks... what's our default called ...
  • The keystore password  is secretpass
  • 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\hiddensecret.jks -storetype PKCS12
secretpass
sqluser
"%JAVA_HOME%\bin\keytool" -importpass -alias db1pass -keystore C:\secure\hiddensecret.jks -storetype PKCS12
secretpass
x34!2axf



Expand
titleClick here to expand Linux
:
example


Code Block
$JAVA_HOME/bin/keytool -importpass -alias
phixflow-database-password
db1 -keystore /opt/secure/
hidden
secret.jks -storetype PKCS12
secretpass
sqluser
$JAVA_HOME/bin/keytool -importpass -alias
phixflow-database-password
db1pass -keystore /opt/secure/
hidden
secret.jks -storetype PKCS12
secretpass
x34!2axf
  • 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.


    Understanding How PhixFlow Uses A Keystore

    This section 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