Keystore setup

To generate or to verify the message signatures of TCH messages, the TCH connector requires access to private keys in either a keystore or truststore file.

The TCH connector requires access to a private key of the participant to generate the required message signatures for all of the messages that The Clearing House Real Time Payments sends to TCH. The message signatures of the messages received from TCH can optionally be verified. If message signature verification is configured, the connector needs the public key of TCH installed in either the keystore or in a separate truststore file.

The keystore and truststore files must be in JKS format, and the keystore must contain at least the personal certificate for message signature generation. This personal certificate holds the private key that the participant has generated and for which he has shared the public part of the certificate with TCH. Additionally, the connector provides a signature validation capability that requires it to have access to the public certificate that is provided by TCH. Public certificates should be installed in a separate truststore file, because they don't need the same password protection as personal certificates. Using a truststore is optional, as public certificates can also be placed in the keystore file.

All signature processing related files can be installed anywhere. The location of the keystore, truststore, and password files, as well as the name of the personal certificate alias (label), must be specified using the mqsichangeproperties command. The following example shows how to run this command.

mqsichangeproperties <integration node> -e <integration server> -o ComIbmJVMManager -n jvmSystemProperty -v "-Dcom.ibm.fxr.keystore=<keystore file> -Dcom.ibm.fxr.keypass=<keystore password file> -Dcom.ibm.fxr.privateAlias=<Alias(Label) of private(owner) certificate> -Dcom.ibm.fxr.truststore=<truststore file>

By default, the keystore password is obtained from an encrypted file. The file is created by using the encryption tool that is provided by Financial Transaction Manager in the following directory:ftm_base_install_directory/tools/encryption/encrypt.jar. The following example shows how to run the encryption tool.

java -jar encryption.jar keypass

This creates an encrypted password file called keypass.en3 within the same directory.

To access the keystore file, the TCHConnector needs to decrypt the keystore password at run time. For the connector to be able to decrypt the file, the FTM encrypt.jar file must be located in the Java™ class path for the IBM® App Connect Enterprise environment that the The Clearing House Real Time Payments TCH connector is deployed into.

The following table shows the IBM App Connect Enterprise Java environment variables that are used to specify the keystore and truststore access for the connector.

Table 1. TCH connector keystore and truststore environment
Variable	Description
com.ibm.fxr.keystore	The path and file name of the keystore file.
com.ibm.fxr.keypass	The path and file name of the file that contains the password that is used to access the keystore file. The file contains the encrypted password, which is the default, or the plain text password.
com.ibm.fxr.truststore	The path and file name of the truststore file.
com.ibm.fxr.trustpass	The path and file name of the file that contains the password that is used to access the truststore file. The file contains the encrypted password, which is the default, or the plain text password without any trailing blanks or line breaks. Access to the truststore doesn't require this password protection because the connector accesses only public certificates.
com.ibm.fxr.passfileenc	Specifies whether the password files are encrypted or not. The default is to use encrypted password files. To use a plain text file for passwords, set this variable to 'n' (no).
com.ibm.fxr.privateAlias	The alias (label) under which the owner certificate, with its private key, is loaded into the keystore. If a value is not provided for this variable, `fxrsiggencert` is expected to be used as the alias.
com.ibm.fxr.publicAlias	The alias (label) under which the signer certificate, with its public key, is loaded into the truststore or keystore. If a value is not provided for this variable, all of the public certificates are loaded and used dynamically according to the signature `X509IssuerSerial` listed in a received message.
com.ibm.fxr.logLevel	Specifies the level of details for recording the TCH connectors cryptographic related operations. Allowed values are: ALL, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SERVERE. The default logLevel is INFO and finer levels should be only set for test and failure analysis purposes, eg. -Dcom.ibm.fxr.logLevel=ALL
com.ibm.fxr.logFile	Specifies the LogFile path for recording the TCH connectors cryptographic related operations, eg. -Dcom.ibm.fxr.logFile=/tmp/tempLog. If not set the output for logging is placed in the IIB execution groups stdout file.

Migration hints

Certificates periodically need to be renewed. During a migration period, both the current and the new certificate might be valid to be used. When two owner certificates are installed during a migration period, specify which certificate should be used in the com.ibm.fxr.privateAlias variable. When more than one public certificate that were obtained from TCH is installed, don't specify the com.ibm.fxr.publicAlias variable. This lets the connector decide which certificate to use based on the signature serial that is received in the message from TCH.