Keytool Syntax

The keytool command syntax is:

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

where

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 the keytool prompts again for a "password", enter the data, usually a user name or password. 

For a username and password, you need to run the command twice. For example:

• a keystore is called secure.jks
• 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:

"%JAVA_HOME%\bin\keytool" -importpass -alias db1 -keystore C:\secure\secure.jks -storetype PKCS12
keypass
sqluser
"%JAVA_HOME%\bin\keytool" -importpass -alias db1pass -keystore C:\secure\secure.jks -storetype PKCS12
keypass
x34!2axf

$JAVA_HOME/bin/keytool -importpass -alias db1 -keystore /opt/secure/secure.jks -storetype PKCS12
keypass
sqluser
$JAVA_HOME/bin/keytool -importpass -alias db1pass -keystore /opt/secure/secure.jks -storetype PKCS12
keypass
x34!2axf

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

Local User Password Encryption

If you have local users you also need to set up a pepper key; see Wikipedia article on Pepper 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, PhixFlow one-way encrypts:

and adds a pepper key string from the keystore. The pepper key is specific to the PhixFlow instance.

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

Configuring Keystore Reading

The configuration file webapp/WEB-INF/classes/phixflow-secret.xml manages PhixFlow authenticating to its own database. As well as having the keystore filename, you can use the options in this to configure how often PhixFlow re-reads data from the keystore.

There are two ways to use the keystore

PhixFlow is configured to periodically check the keystore directly based on the retryDelay set in phixflow-secret.xml 

Alternatively, you can configure PhixFlow to only read the keystore when it starts

<!--
To directly use keyStoreService and not the caching service,
 comment the CachingSecretService bean elements and change the bean id of KeystoreSecretService to secretService
 There should be a bean defined with id secretService always, as that's is referred in phixflow-datasource.xml
-->
	<bean id="secretService" class="com.accipia.centerview.

service.

secret.

CachingSecretService">
		
		<property name="

cachingPeriod">

			<value>10000</value>
		</property>
		<property name="

secretService" ref="

keyStoreSecretService">

In version 8.3.0 PhixFlow switched to using Bcrypt as its method of encrypting data. All passwords and security answers that were set up in earlier versions will continue to be encrypted with the legacy encoder.

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

The encoding is configured in the phixflow-login.xml, in the passwordEncoder bean.

		</property>
		
	</bean>
	<bean id="keyStoreSecretService" class="com.accipia.centerview.

service.

secret.

KeystoreSecretService">
		<property name="

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. 

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. 

Is it better to just disable it in PhixFlow

(This sounds like a security back door though)

phixflow-instance.xml knows about the pepperkey. if you want to call it something else in the keystore, remember to update it here too. - shared statement with install instructions

Configuration in phixflow-secret.xml

phixflow-secret.xml manages PhixFlow authenticating to its own database. The username and password are stored securley in the keystore. phixflow-secret.xml holds the keys (also called aliases) 

Other configuration

<!-- number of retries to read keystore file --> 
<property name="retries"> 
    <value>3</value> 
</property> 
<!-- delay before we retry to read keystore file --> 
<property name="retryDelay"> 
   <value>10000</value> 
</property> To use new CachingSecretService need to have declaration of new bean definition in phixflow-secret.xml.example

retries"><!-- keystore type (PKCS12 or JCEKS) -->
			<value>3</value>
		</property>
		<property name="retryDelay">
			<value>10000</value>
		</property>

<!--
To directly use keyStoreService and not the caching service,
 comment the CachingSecretService bean elements and change the bean id of KeystoreSecretService to secretService
 There should be a bean defined with id secretService always, as that's is referred in phixflow-datasource.xml
-->
	<bean id="secretService" class="com.accipia.centerview.service.secret.CachingSecretService">
		
		<property name="cachingPeriod">
			<value>10000</value>
		</property>
		<property name="secretService" ref="keyStoreSecretService">
		</property>
		
	</bean>
	<bean id="secretService" class="com.accipia.centerview.service.secret.KeystoreSecretService">
#		<property name="retries"><!-- keystore type (PKCS12 or JCEKS) -->
#			<value>3</value>
#		</property>
#		<property name="retryDelay">
#			<value>10000</value>
#		</property>