Versions Compared

Old Version 1

changes.mady.by.user Fiona Sargeant (Unlicensed)

Saved on

compared with

New Version Current

changes.mady.by.user Fiona Sargeant (Unlicensed)

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

, this includes

. When PhixFlow is installed, the keystore is created and the following are added:

  • a pepper
key
  • string used to encrypt local user
passwords
  • password
  • username and
passwords data, such as usernames and passwords are encrypted and stored here. You then use an alias or key to
  • password for the PhixFlow database
  • where external authorisation is required, usernames and passwords for: 

    • SYNTAX TBC

    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:

    You can then use an alias 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

    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
    <keyAlias>
    <key> -keystore
    <pathToKeystoreFile>
    <file> -
    usernameKey <userkey> and -passwordKey <passkey> -
    storetype
    <keytype>Where
    <type>

    The keytool command syntax to delete entries is:

    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
    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 -
        • Windows   C:\secure\
      name
        • secure.jks
      Linux -
        • Linux   /opt/secure/
      name
        • secure.jks
      <keytype>Either PKCS12
      • <type>Either PKCS12 (recommended) or JCEKS.
      TipThe
      • <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

      differentiate

      distinguish between the secrets that 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

    • Use the -importpass command to enter a key.
      • When prompted, enter

      . 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 (key).
      2. When the keytool prompts, enter the keystore's password.
      3. When
      prompted
      1. 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\
      hidden
      secure.jks -storetype PKCS12
      secretpass
      keypass
sqluser
      "%JAVA_HOME%\bin\
      keytool
      "
       -importpass -alias db1pass -keystore C:\secure\
      hidden
      secure.jks -storetype PKCS12
      secretpass
      keypass
x34!2axf



      Expand
      Linux:
      titleClick here to expand Linux example


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

      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

      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

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