Versions Compared

Old Version 4

changes.mady.by.user Fiona Sargeant

Saved on

compared with

New Version Current

changes.mady.by.user Fiona Sargeant

Saved on

Key

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

Insert excerpt
_Banners
_Banners
nameadministration
nopaneltrue

Overview

PhixFlow uses a Java keystore

and associated secret service

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

The instructions for this are

in 

in the Installing PhixFlow topic: see Configure a Keystore

for Database Credentials

and Aliases.

Additional details

We recommend that

we recommend

you also store other credentials in the keystore

are

, such as those provided:

You can then use an alias

or key to Table of Contentsindent12pxstylenone

to retrieve the data from the keystore.

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

You will need to provide PhixFlow users with the alias that they need to configure secure:

  • datasources
  • email accounts.

Note

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 
Anchor
syntax
syntax

Note

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:

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

The keytool command syntax to delete entries is:

Code Block
<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
  • <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 string.

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
/
  1. (key).
  2. When the keytool prompts, enter the keystore's password.
  3. When the keytool prompts again for a "password", enter
the data, usually
  1. 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:

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



Expand
titleClick here to expand Linux example


Code Block
$JAVA_HOME/bin/
keytool -importpass -alias db1 -keystore /opt/secure/
secret
secure.jks -storetype PKCS12
secretpass
keypass
sqluser
$JAVA_HOME/bin/
keytool -importpass -alias db1pass -keystore /opt/secure/
secret
secure.jks -storetype PKCS12
secretpass
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. 

Understanding How PhixFlow Uses A Keystore

This section 
keypass
x34!2axf

Pepperkye

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

Wikipedia article on Pepper Encrytption

Datasource instances or email

todo

Keytool Syntax

For reference, here is the keytool command syntax.

Code Block
<keytool> -importpass -alias <key> -keystore <file> -storetype <type>
Where:Is<keytool>
Windows command prompt"%JAVA_HOME%\bin\keytool.exe"Windows PowerShell &"$env:JAVA_HOME\bin\keytool.exe"Linux  $JAVA_HOME/bin/keytool 

<key> 

The alias/key for a username or password.

After you enter an alias, the keytool prompts you to enter the corresponding data, usually a username or password.

<file>

The full path to the keystore file, for example:

  • Windows  C:\secure\name.jks
  • Linux  /opt/secure/name.jks
<keytype>PKCS12 (recommended) or JCEKS.


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.

Tip

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:

  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.

Image Removed

Live Search
spaceKey@self
additionalnone
placeholderSearch all help pages
typepage

Panel
borderColor#00374F
titleColorwhite
titleBGColor#00374F
borderStylesolid
titleSections on this page

Table of Contents
maxLevel3
indent12px
stylenone



Image Added

 How PhixFlow authenticates to its database using a keystore

Is it better to just disable it in PhixFlow

(This sounds like a security back door though)


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

Possibly another page??

Local User Password Encrytption

PhixFlow users can be set up as

  • external - all user authentication and permissions are handled externally for example by a SAML single-sign-on service or Active Directory.
  • mixed - user authentication is handled externally but a assigned to user groups in PhixFlow, which handle permissions
  • local - both user authentication and permissions are handled locally

For local users only, you can configure an added layer of security. PhixFlow one-way encrypts user passwords and the answers to user security questions.

  • security answers: normalized Bcrypt - this changes all letters to lower case and removes spaces before encrytpting. It does not use the pepepr key, so security answers will work if the user account is imported to another instance
    • user passwords: pepper key Bcrypt
  • this requires an exact match, case/spaces etc

    • AND uses a pepper key from the keystore to get an additional string to add to the password. The pepper key is tied to the PhixFlow instance

    Note

    You can export/import user accounts from one instance to another. However their passwords will not work in the new instance because the pepperkey will be different. The user will need to have their password reset in the import instance.

    To check a passowrd or answer, PhixFlow identifies which method has been used to encrypt it, and uses the same method to encrypt the string supplied by the user. PhixFlow then compares the two encrypted versions and ensures these match.

    In version 8.3.0 PhixFlow switched to using Bcrypt as its method of encrypting data.

    phixflow-login.xml includes a list for the encoders. Phixflow will check for

    Bcrypt

    legacy (used prior to 8.3.0

    startup - used for the initital administrator login to a new installation

    How to move passwords to the new encoder

    For PhixFlow instances upgraded to 8.3.0

    Your local users will have passwords and security questions that require the legacy encoder. You can continue to run with this. However, to ensure your system is using the more secure Bcrypt and one-way encoding we recommend users change their passwords and their security answers as soon as possible.

    When a user changes their password/answers, it is automatically encrypted with the new Bcrypt encode.

    Making phixflow-login.xml more secure

    Consider the following change

    For new installations at 8.3.0 onwards, all passwords and answers will be using Bcrypt.

    For upgraded instaances, when all passwords and answers are using Bcrypt

    Update phixflow-login.xml to comment out the legacy line. 

    Warning

    commenting out the legacy line will prevent any remaining passwords or answers from working. There is no way to check this in advance. If answers are still encrypted using the legacy encoder, then they will only find out if they need to reset their password.

    Consider the following change when you have an administrator login set up for your installation

    Update phixflow-login.xml to comment out the startup line. This will automatically disable the startup user. If you subseqently have problems that mean you cannot log into the sytem, you can re-enable the startup user from outside PhixFlow. 


    Note

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