This upgrade includes instructions to add a pepper string and alias to the keystore. See:

• Adding Data to a Keystore for the keystore command syntax and how the keystore works
• Understanding Password Encryption for information about the pepper key and how to ensure user security information is migrated to use the most secure encryption
• Considerations for Pepper Strings for whether or not to use different pepper keys for different instances.

Run the PhixFlow upgrade script

Running the upgrade script makes essential security improvements to passwords.

After upgrading your database in Step 10 of Upgrading PhixFlow, make sure you have sufficient disc space, memory and time to run the PhixFlow upgrade script.  There is advice in the special upgrade instructions for 8.2.0.

Run the PhixFlow upgrade script from the installation directory .../phixflow-version-date/install. To see information about all the options, run the upgrade script with the -help option.

java -jar bin/upgrader.jar -help

The command returns:

[Boot] INFO:  loading properties from one-jar.properties
2021-02-09 10:52:19,475 [main] INFO  phixflow.upgrader.main.UpgraderMain - PhixFlow Upgrade starting
Option              Description
------              -----------
--skip-superceded   Skip upgrading the superceded_dtm column on stream data tables
                      (Oracle only; only use if advised by PhixFlow support)
--help              Print this message
--match-streams     Only streams matching this regexp are upgraded (Oracle only)
--pass              The database password
--test              Test the database connection properties
--upgrade           Upgrade the PhixFlow database schema
--url               The database url, e.g. jdbc:mysql://hostname/database
--user              The database username

To upgrade PhixFlow, run the upgrade script with the -upgrade option, for example.

java -jar bin/upgrader.jar -url="jdbc:mysql://localhost/phixflow" -user=<myuser> -pass=<mypass> -upgrade

After the upgrade script completes, continue with the following configuration steps.

Add a pepper string to the keystore 

PhixFlow now requires a pepper string to be added to the keystore. When a local user sets their password, the pepper string is added to it and the combined string is encrypted. This means user passwords are tied to a PhixFlow instance. 

1. Run the -importpass command, specifying the alias: pepperkey
The alias is case-sensitive. If you use a different alias, update phixflow-instance.xml to use the same alias.

2. When prompted, enter the keystore password.
3. When prompted for the password, enter the pepper string you want to add to user passwords. 
   We recommend this string has the same characteristics as a password. For example it should be a random string containing at least 6 letters, numbers and special characters. 
   Keep a secure record of the pepper sting. 

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

&"$env:JAVA_HOME\bin\keytool.exe" -importpass -alias pepperkey -keystore C:\secure\hidden.jks -storetype PKCS12

$JAVA_HOME/bin/keytool -importpass -alias pepperkey -keystore /opt/secure/hidden.jks -storetype PKCS12

Merge changes in configuration files

You must create new versions of the following configuration files in $webapp/WEB-INF/classes:

 - phixflow-instance.xml
 - phixflow-datasource.xml
 - phixflow-login.xml
 - phixflow-secret.xml

To do this we recommend you:

1. Rename your existing configuration file, for example by adding a .bak suffix.
2. Follow the Install the PhixFlow Webapp instructions for creating a new file from the.example file provided. 
3. Copy the individual values from your existing configuration file and paste them into the new file.
   Avoid copying entire XML blocks into your new configuration files, as you may overwrite a section of the configuration file that PhixFlow needs.

If you choose to merge the changes from the new .example file into your existing configuration file, the following notes indicate where there are changes.

phixflow-instance.xml

The new section for configuring the pepper alias is required.

<!-- The pepper key is instance specific so extra caution has to be taken when changing the pepper key value in keystore, changing the value in keystore will cause login issue for user's migrated to new password encryption -->

   <util:properties id="instanceProperties">
      <prop key="pepperkey">pepperkey</prop>
   </util:properties>

The default value is pepperkey. If you have multiple PhixFlow instances, each instance must have a pepper string and alias; see Considerations for Pepper Strings.

phixflow-datasource.xml

1. You can no longer specify the database username and password directly in phixflow-datasource.xml.
If you have not already done so, you must add the database username and password to the keystore.
Specify the keys for the username and password in the new bean <bean id="externalCredential" by replacing demo.

<bean id="externalCredential" class="com.accipia.centerview.util.ExternalCredentialProvider">

   <property name="secretService">
      <ref bean="secretService"/>
   </property>
   <property name="usernameKey">
      <value>demo</value>
   </property>
   <property name="passwordKey">
      <value>demo</value>
   </property>

</bean>

2. In <bean id="dataSource" 

• the class name has changed from class="com.accipia.centerview.util.PhixFlowDataSource">
  to class="org.apache.commons.dbcp2.PhixFlowDataSource">
• property name and ref bean have changed from secretService to credentialProvider and externalCredential respectively
• the following lines have been removed, because they are now in the <bean id="externalCredential":
  <property name="username">
   <value>demo</value>
</property>
<property name="password">
   <value>demo</value>
</property>

phixflow-login.xml

1. New <bean id="passwordEncoder" specifies the encryption method for passwords; see Understanding Password Encryption.

2. New <bean id="securityQuestionEncoder" specifies the encryption method for security question.

3. New <bean id="sameSiteCookieFilter". If you use SAML for login, uncomment this.

4. <bean id="exampleAuthenticationOnlySamlAttributeMap" has an additional property: <property name="globalLogout" value="false" />

5. <bean id="idpFileMetadataProvider" has additional property: <property name="requireLogoutResponseSigned" value="true" />

phixflow-secret.xml

1. The new <bean id="keyStoreSecretService" is required.
2. <bean id="secretService" has changed.

After restart, configure datasources and email accounts

After the upgrade is complete and PhixFlow has been restarted, review each datasource instance and email account. For those that require a username and password, we recommend these are stored securely; see the release note on Secure Credentials for Datasource and Email Account.

1. Save the username and password with their alias to the keystore; see Adding Data to a Keystore.
2. In the properties for the datasource instance or email account:
   1. Set Authorisation Type External.
   2. Add the aliases to the Username Key and Password Key fields.