MTG Secrets Protection Business Processes

MTG Secrets Protection Manager is a standalone command line interface (CLI) tool that can be used to manage hardware security module (HSM) master keys and application-specific data encryption keys (DEKs). The HSM master keys are used to protect a software (in-memory) DEK, which in turn can be used to encrypt and decrypt application-specific data or secrets.

There are multiple reasons to encrypt the application-specific data or secrets using a DEK instead of using the HSM master keys directly:

performance (an HSM can quickly become the bottleneck in a distributed application)
disaster recovery (using a DEK allows for a back-up mechanism between different HSM types without the need to export/import HSM keys)
extended HSM support (enables support for HSMs that do not support symmetric keys e.g., the no longer available MTG smartHSM)

Usage with MTG applications

The following MTG applications require a protected DEK to be configured in order to be able to function:

KMS-Server

Therefore, it is mandatory to run the MTG Secrets Protection Manager init command at least once when installing these applications. Running the init command will do the following (see command-init ) :

Generate a new DEK (in-memory);
Generate one or more master keys to protect the DEK (one master key for each configured HSM).
Protect the DEK with each master key using the configured master key;
Finally, a secrets-protection.properties file will be generated that contains the protected DEK properties (see secrets protection properties).

Any of the aforementioned MTG applications can then use the content of the secrets-protection.properties file, to automatically connect to an HSM where a master key exists, unprotect the DEK and use it to encrypt application-specific data or secrets.

The first master key (with index 0, i.e. secrets-protection.master-keys[0]) will be used by the MTG applications to unprotect the protected DEK.
Any extra master keys (with index > 0) are intended to be used either for failover or as offline backup.

Multiple applications may share the same content of the secrets-protection.properties file and therefore the same DEK.

The MTG Secrets Protection Manager forces you to generate a backup to at least 1 HSM. A small-form-factor HSM (e.g. a USB HSM) is recommended for use as a backup HSM. If one is not available, a keystore file (bcfks) can be used instead by specifying KEYSTORE as the HSM type.

Getting started with MTG Secrets Protection

How to use

Install the MTG Secrets Protection Manager package
Configure the MTG Secrets Protection Manager application.properties in the configuration directory. Make sure at least two master keys are configured to facilitate the creation of a backup.
You may want to explore some of the available templates as a reference.
If using the MTG Secrets Protection Manager for the first time, run the init command. It will use the configured application.properties file and generate a secrets-protection.properties file. For each configured KEYSTORE master key, a keystore (.bcfks) file will also be generated.
Securely store:
- the generated secrets-protection.properties file
- any generated .bcfks files.
- any small-form-factor HSMs (e.g. USB HSMs).
Copy the content of the secrets-protection.properties file into the application.properties file of each MTG application that requires a protected DEK to function.

Each MTG application that uses the content of the secrets-protection.properties file must have access to the same HSM or keystore file used to protect the DEK.

A master key is normally generated and kept safe inside a hardware security module (HSM). If there is no HSM available, a keystore file (bcfks) can be used instead by specifying the HSM type as KEYSTORE. This is both less secure and less convenient, as the keystore file will have to be manually distributed on each system that requires access to it.

Running MTG Secrets Protection Manager

The tool comes a one executable jar file, which can be run as follows:

java -jar  mtg-spm.jar <config-options> [command] <options> <params>

The required Java version is 17.

In addition, there are templates for the application.properties and the logback.xml files.

The application.properties file (and, optionally, the secrets-protection.properties file) can be placed in the same directory where the tool is started. Otherwise the full path to the file must be set via the command-line option --spring.config.location

If the logback.xml file shall be used, the full path must be set via the commandline option --logging.config

The location of any external HSM .jar files may be specified by setting the LOADER_PATH environment variable. It may contain a comma-separated list of directories, archives, or directories within archives. Not for KEYSTORE!

A full start script would be:

#!/bin/bash

export LOADER_PATH=<Pfad-zu-externen-HSM-jars>

CONFIG_OPTIONS=
#comment the line below, if the `add` command ist used
CONFIG_OPTIONS=$CONFIG_OPTIONS --spring.config.location=/etc/mtg/secrets-protection-manager/application.properties
#uncomment the line below, if the `add` command ist used
#CONFIG_OPTIONS=$CONFIG_OPTIONS --spring.config.location=/etc/mtg/secrets-protection-manager/application.properties,/etc/mtg/secrets-protection-manager/secrets-protection.properties
CONFIG_OPTIONS=$CONFIG_OPTIONS --logging.config=/etc/mtg/secrets-protection-manager/logback.xml

JAVA_BIN = java

######### HSM Specific ENV ############

#UTIMACO PKCS11
#export CS_PKCS11_R3_CFG=<path>/cs_pkcs11_R3.cfg

#NCIPHER PKCS11
#export CKNFAST_LOADSHARING=true

#external JARs (e.g. Utimcato CXI)
#export LOADER_PATH=<path-to-external-HSM-jars>

### Run
$JAVA_BIN -jar mtg-spm.jar $CONFIG_OPTIONS $@

Commands

A help subcommand is available for each command.

The following commands are available:

status

The status command performs basic validation of the configured properties and prints a status report.

Run the status command as follows:

java -jar  mtg-spm.jar <config-options> status

Either the content of the application.properties file or the content of the secrets-protection.properties file or both are checked, depending on the configuration.

The following steps are performed by the tool for this command:

(optionally) read the application.properties file (containing the master keys configuration)
(optionally) read the secrets-protection.properties file (containing the protected DEKs configuration)
check if all configured master keys exist (on the HSM or on the file system as a keystore file)
check if all configured protected DEK entries can be unprotected
check if all unprotected DEKs match

init

The init command generates a DEK (in-memory), one or more master keys (one master key for each configured HSM) and protects the DEK using each master key. It should normally be run only once during the initial application setup.

Run the init command as follows:

java -jar  mtg-spm.jar <config-options> init --out=<outputDirectory>

The command expects the following mandatory argument:

-o, --out=<outputDirectory>

The output directory to write the 'secrets-protection.properties' file to.

If there is already a 'secrets-protection.properties' at the <outputDirectory> the MTG Secrets Protection Manager stops with an error.

The following steps are performed by the tool for this command:

Read the application.properties file (containing the master keys configuration);
At least two master keys must be configured (the first master key is meant to be used in the application, any additional master keys are meant to be used either for failover or as offline backup);
Generate a new software (in-memory) DEK using random bytes from the first configured master key;
Generate one or more master keys (on the HSM or on the file system as a keystore file);
Protect the DEK with each master key using the configured master key. See protection strategy;
Generate the secrets-protection.properties file.The content of this file should be copied inside each MTG application’s application.properties file so that the application can use it to unprotect the DEK.

add

The add command is used to add another master key to an existing DEK. The add command can be used to create another master key or to restore a master key after it has been lost.

Execute the add command as follows:

java -jar mtg-spm.jar <config-options> add --out=<outputDirectory>

The command expects the following mandatory argument:

-o, --out=<outputDirectory>

When calling the command, this parameter must be used to specify the output directory to write to after successfully creating the protected DEK in the secrets-protection.properties.

If there is already a file secrets-protection.properties in the output directory, the execution of the MTG Secrets Protection Manager will end with an error. A new output directory must be specified. The already existing secrets-protection.properties must be configured with when running the add command.

In the application.properties only entries of a new HSM / keystore may exist, on which a new master key is to be created. Otherwise the MTG Secrets Protection Manager exits with an error, no secrets-protection.properties file is generated and there may be new keys in the HSM.

Prerequisite to run the add command:

application.proterties contains only new HSM entries.
existing secrets-protection.properties is located in the /etc/opt/mtg-spm/ directory.

The following steps are associated with the add command:

Person changes to the directory: /opt/mtg-spm.
Person calls the script ./mtg-spm-tool.sh -o <new output directory>.
Program reads the file application.properties (with the configuration of the master keys).

There must be at least one new

Master Key must be configured.
Program reads the secrets-protection.properties file (containing the configuration of the already protected DEKs).

At least one protected

DEK must be configured.

Program decrypts the protected DEK to get the plaintext DEK.

If multiple protected DEKs are configured, they are processed in the order of their definition (i.e. the one with index [0] is used first). If the operation fails, the second one is used and so on.

Program generates one or more master keys (on the HSM or as a keystore file).
Program generates a DEK which is encrypted with the master key.
Program generates the new ``secrets-protection.properties'' file containing both the original and the newly added protected DEK entries.
Person checks the new secrets-protection.properties file.
Person changes all application.properties of the MTG applications to the new entry.

If multiple protected master keys have been created, only the first one with index 0 is to be added to the application.properties of the applications.

destroy

The destroy command can be used to destroy a pre-existing master key.

Run the destroy command as follows:

java -jar  mtg-spm.jar  <config-options> destroy

If there is a secrets-protection.properties at the <config-options> directory the MTG Secrets Protection Manager stops with an error; Exactly zero protected DEK must be configured;

The following steps are performed by the tool:

Read the application.properties file (containing the master keys configuration). At least one master key must be configured;
Ask for user confirmation before proceeding;
Destroy each configured master key (on the HSM or on the file system as a keystore file).

The master key will be gone after running the destroy command. Unless a backup is available its protected DEK (and any secrets encrypted using it) will also be lost.