Master Key settings

Select Settings > Master Key Security to view and change the current Master Key method.

Figure 1: Master Key settings
Master Key settings
Figure 2: Changing the Master Key method
Changing the Master Key method to KMIP CTM

The eperi sEcure Platform uses the Master Key to encrypt eperi sEcure Platform's system keys. With the system keys sensitive data in the eperi sEcure Platform database (such as encryption keys and configuration data) is encrypted.

To change the Master Key method, select the desired method, provide required information, then click Submit.

Option in CLI tool Option in Admin Console Description
EPERI Eperi Encryption Choose this method to encrypt the system keys with eperi sEcure Platform's encryption feature.
RAM RAM Password Choose this method to encrypt the system keys with your own password. This password is kept only in memory and must be entered on each start of eperi sEcure Platform.
Important: If you intend to use this Master Key method, a modern OS is needed, for example CentOS/RHEL 8 or Ubuntu 18 LTS / 20.04 LTS. The eperi user needs permissions to use systemd-tty-ask-password-agent in order to prompt for the RAM password. Use setfacl to grant the eperi user the necessary permissions for this purpose: 
sudo setfacl -m u:eperi:wx /run/systemd/ask-password
CLEAR_TEXT Clear Text Choose this method to store the system keys unencrypted in the database. In this case, we recommend to protect the system keys with the vendor-specific database encryption. We also recommend to protect the file /opt/eperi/gateway/tomcat/webapps/ROOT/etc/database.conf with proper operating system access control mechanisms since the connection credentials for the eperi sEcure Platform database are stored in the clear inside this file.
HSMEPERI HSM Eperi Encryption Choose this method to protect the system keys with an HSM. The HSM credentials are encrypted with eperi sEcure Platform's encryption feature.

Additionally, it is required to enter the credentials of your HSM (see below).
HSMRAM HSM RAM Encryption Choose this method to protect the system keys with an HSM. The HSM credentials are encrypted with your own password which is kept in memory and must be entered after each start of eperi sEcure Platform. In case you have selected this option, you are prompted to enter the RAM Password twice.

Additionally, it is required to enter your HSM credentials (see below).
KMIP_CTM KMIP CTM Choose this method to protect the system keys with KMIP CTM. KMIP is a protocol that supports various key management activities, such as key generation, distribution, and deletion. It also provides interoperability between different key management systems and clients. CipherTrust Manager (CTM) is part of the Thales CipherTrust Data Security Platform.

With KMIP CTM, CipherTrust Manager stores and administers the master key, which is accessed via KMIP.
N/A Hardware Security Module Choose this method to protect the system keys with an HSM. Please make sure the eperi sEcure Platform server can connect to the HSM by following these steps first:
  • Your HSM device/hardware and the HSM client are correctly set up and configured. Please see the topic Connecting a Luna HSM to eperi sEcure Platform for instructions how to do this in case of a Luna HSM.
  • You have manually copied the respective "provider" JAR file to the folder /opt/eperi/gateway/tomcat/webapps/ROOT/WEB-INF/lib.
    • For a Luna HSM: LunaProvider.jar
    • For a Utimaco HSM: CryptoServerJCE.jar
When choosing this method, you additionally need to provide the following:
  • HSM credentials protection method: Select which method should be used to protect the HSM credentials and the database.conf:
    • eperi Encryption: The HSM credentials are encrypted with eperi sEcure Platform's encryption feature.
    • RAM Password: The HSM credentials are encrypted with your own password which is kept in memory and must be entered after each start of eperi sEcure Platform. In case you have selected this option, you are prompted to enter the RAM Password twice.
When using Luna HSMs, you need to provide the following:
  • HSM Partition: Enter the HSM Partition to be used.
  • Password for HSM Partition: Enter the Password for this HSM Partition.
  • Key Alias: Enter the Key Alias to be used.
When using Utimaco HSMs, you need to provide the following:
  • HSM Device: Enter the name of the HSM Device to be used (e.g. 3001@hostname).
  • Username: Enter a user name.
  • Password: Enter your password.
  • Key Alias: Enter the Key Alias to be used.
  • Key Group: Enter a Key Group to be used (optional).
  • Key Specifier: Enter a Key Specifier (optional).
In case you have selected RAM Password as Master Key method, choose and enter your RAM Password twice, then click Submit.
CAUTION: Please make sure you remember the RAM Password, because it is required to enter it again every time eperi sEcure Platform is restarted!

To change the Master Key method in a cluster setup, please follow the instructions in section Changing the Master Key method in a cluster setup.