Encrypting the Acoustic Exchange Toolkit configurations

Prerequisites

When you install the Exchange Toolkit, configuration settings, including passwords, are visible in properties files. To encrypt certain settings so that sensitive information is not visible, run the encryptconfig script.

The encryption is based on a password-based cryptography standard. By default, the encryption uses a password that is built into the toolkit code. You can further secure the configuration settings by defining a different password. You can define a different password for your environment by defining a custom encryption key.

Defining a custom encryption key is optional. However, you must decide whether to define a custom encryption key before you encrypt the properties settings. If you choose to create a custom encryption key, you must do so before you run the encryptconfig script.

The encryptConfig script is in the bin directory in the folder where you installed the Exchange Toolkit files. The script encrypts configuration values in jdbc.properties and config.properties. The script encrypts only values that include the terms: authkey, password, secret, refresh, or access. When you run the encryptConfig script, the script replaces the displayed values for these settings with a string of encrypted characters.

Note: Encrypting configurations with the encryptconfig script does not encrypt the proxy server settings if you encrypt the toolkit configuration settings. However, if the proxy.password property contains a value, the value is encrypted.

FileProperty
jdbc.propertiesjdbc.password: Password for the database user. Note: The password must correlate with the system user who is specified in jdbc.user.
config.propertiesubx.endpoint.authentication.key: The authentication key for registering an endpoint and accessing Exchange APIs.

Encrypting the value of a configuration property does not prevent you from changing the value. However, each time that you change the value, you must run encryptConfig again to encrypt the new value.

You can encrypt values in jdbc.properties and config.properties simultaneously or encrypt each file separately.

Step-by-step

1. Run encryptConfig.bat (Windows) or encryptConfig.sh (UNIX or Linux)

Depending on your operating system, run encryptConfig.bat (Windows) or encryptConfig.sh (UNIX or Linux).

  • To encrypt jdbc.properties and config.properties simultaneously, run the script as: <CU_HOME>/bin/encryptConfig.
    Example: <CU_HOME>\bin\encryptconfig.bat
  • To encrypt the files separately. Run encryptConfig with the -f parameter as: <CU_HOME>/bin/encryptconfig -f /conf/.
    Example: <CU_HOME>/bin/encryptConfig.sh -f <CU_HOME>/conf/config.properties
    The script encrypts values only in the property file that you specify with the -f option.
  1. Creating a custom Acoustic Exchange Toolkit encryption key
    To apply increased local control over the encryption of sensitive configuration values, you can create a custom encryption key. This task is optional, but does provide an added layer of security.

When you create a custom encryption key, you change the password that the encryption script uses to hide sensitive configuration values. If you decide to create a custom encryption key, you must perform this procedure before you run the encryptConfig script.

Define the value for the custom encryption key in a flat file. The file is considered the Encryption Key File and system administrators must restrict access to it. Enter the path to this file as a setting in the setenv file.

Note: If you change the value of the Encryption Key File, you must remove the current encryption, repeat this procedure to create a new custom encryption key, and run encryptConfig again. If you do not repeat all of the steps in this process, the toolkit scripts will fail.

Procedure

  1. In a text editor, create a strong password for the encryption script and save the file as a text file. The file that you create is the Encryption Key File. Save the file in a folder outside of the bin directory.
    Restrict access to the directory in which you save the file.

  2. In the bin directory of <CU_HOME>, edit the setenv file to specify the path to the Encryption Key File. Modify the ENCRYPTION_KEY_FILE setting, as follows.
    Windows (setenv.bat): set ENCRYPTION_KEY_FILE="-com.ibm.emm.integration.security.EncryptionKeyFile=<EncryptionKeyFile>"

UNIX or Linux (setenv.sh): ENCRYPTION_KEY_FILE=-com.ibm.emm.integration.security.EncryptionKeyFile=/
The new custom password is used to encrypt values in jdbc.properties and authentication.key in config.properties.

  1. Run the encryptConfig script to encrypt the configuration settings.

3. Removing encryption from Acoustic Exchange Toolkit configuration properties

Some situations require that you remove the encryption from encrypted properties. For example, to change the value for the Encryption Key File, you must remove encryption from all currently encrypted values before you can proceed.

Encrypted values can be found in jdbc.properties and config.properties. The encrypted values appear as random strings.

  1. In jdbc.properties and config.properties, locate the encrypted values. Replace each encrypted value with its correct unencrypted value.
  2. Save the file.
    On Windows, if you were using a custom encryption key and then stopped using the key, close all command prompts.

After you complete this task, the configuration values appear without encryption.