Configure keystores and encryption

Overview

The default encryption in Semarchy xDI offers a basic level of safety for sensitive data such as passwords, but it is preferable to specify your own encryption methods and keys when working in a production environment.

You can define encryption keys and methods in a Java keystore file. This keystore can be used by the runtime and by xDI Analytics.

Create a keystore

If you do not already have one, create a Java keystore with an encryption key. You can use software such as the keytool command that comes with Java, or the GUI-based tool KeyStore Explorer.

Whichever tool you choose, follow these general steps:

Create a keystore file.
1. Give your keystore a password.
Generate a secret key.
1. Choose the encryption algorithm and strength.
2. Choose an alias for your secret key.
3. Give your secret key a password.
Save the keystore to a safe location.

Note the key alias, key password, and keystore password for the next step.

There are different types of keystore files, each with their own advantages. If you are not sure which to use, JCEKS or PKCS12 are both good choices.

Define a keystore for the runtime

Open the runtime configuration file, engineParameters.xml. Go to the section labeled Keystores, and uncomment or add the <keystores> node.

Example 1. Keystores node

<keystores>
    <keystore path="path_to_keystore_file" password="keystore_password" type="JKS">
        <key name="key_functional_name" alias="key_alias_in_keystore" password="key_password"/>
    </keystore>
    <keystore path="path_to_keystore_file" password="keystore_password" type="JCEKS">
        <key name="key_functional_name_2" alias="key_alias_in_keystore" password="key_password" blockCipherModeOperation="PCBC/PKCS5Padding"/>
    </keystore>
</keystores>

Define at least one <keystore> node with at least one <key> node inside. Fill out the parameters as follows:

Table 1. Keystore node attributes
Attribute	Required?	Description
`path`	Yes	Path to the Java keystore file, including the file name. Can be an absolute path, or relative to the main runtime directory.
`password`	Yes	Password of the keystore file.
`type`	No	Java keystore type. If undefined, the keystore type is set to the JVM default. This is usually `JKS`.

Table 2. Key node attributes
Attribute	Required?	Description
`name`	Yes	User-defined name to refer to this key in other parts of the runtime configuration, or in the command line.
`alias`	Yes	Alias of the key as defined inside the keystore.
`password`	Yes	Password of the key entry in the keystore.
`blockCipherModeOperation`	No	Which block cipher mode to use for encryption and decryption.

Examples

Example 2. Single keystore with one key, defaults, absolute path

<keystores>
    <keystore path="D:\Users\semarchy\security\mykeystore.jks" password="mypassword1!">
        <key name="prod" alias="sem-encryption-key" password="key_password"/>
    </keystore>
</keystores>

Example 3. Single keystore with two keys, relative path

<keystores>
    <keystore path="properties/sec/keystore.pk12" password="mypassword1!" type="PKCS12">
        <key name="prod" alias="sem-encryption-key-1" password="key_password_1"/>
        <key name="dev" alias="sem-encryption-key-2" password="key_password_2" blockCipherModeOperation="PCBC/PKCS5Padding"/>
    </keystore>
</keystores>

Configure password encryption

In the configuration file, go to the section labeled Password Ciphering. There are two <parameter> nodes that can be uncommented or added:

The node with the name="globalPasswordCipheringKeyName" parameter controls all password encryption.
The node with the name="deliveryPasswordCipheringKeyName" parameter controls password encryption for deliveries only, and overrides the former setting if both are set.

Example 4. Ciphering parameter nodes

<!-- <parameter name="globalPasswordCipheringKeyName" value="key_functional_name"/> -->

<!-- <parameter name="deliveryPasswordCipheringKeyName" value="key_functional_name"/> -->

Change the value parameter so that it has the user-defined name of a key you defined in the Keystores section earlier.

Make sure that you have one of either node at most.

Examples

Example 5. One encryption parameter

<parameter name="globalPasswordCipheringKeyName" value="prod"/>

Example 6. Two encryption parameters

<parameter name="globalPasswordCipheringKeyName" value="dev"/>
<parameter name="deliveryPasswordCipheringKeyName" value="prod"/>