MTG Secrets Protection Manager Configuration

The MTG Secrets Protection Manager accepts three files as configuration:

  • an application.properties file (containing the master keys configuration)

  • (optionally) a secrets-protection.properties file (containing the protected DEKs configuration). This file is normally automatically generated and does not need to be manually edited, only copied in the configuration folder.

  • (optionally) a logback.xml for the logging configuration

application.properties

The application.properties file contains configuration pertaining to master keys.

Master keys configuration is required when running the init, add and destroy commands.
Master keys configuration is optional when running the status command.

The following properties are available:

Property Description

secrets-protection.master-keys[i].name

The master key name

secrets-protection.master-keys[i].domain

The master key domain

secrets-protection.master-keys[i].hsm.type

The master key HSM type.
One of [KEYSTORE, UTIMACO, LUNA_SA, PKCS11].

secrets-protection.master-keys[i].strategy

The strategy to use to protect the DEK.
See protection strategy.
One of [ENCRYPTION, KEY_PROTECTION].

secrets-protection.master-keys[i].hsm.address

The HSM address. Depending on the HSM type this field can refer to one of:

  • the network address for HSM type [UTIMACO, LUNA_SA].

  • the absolute filepath and file name of the to-be-created keystore file (.bcfks) for HSM type [KEYSTORE]. The location must be writable.

  • the absolute filepath and file name of the .so/.dll library for HSM type [PKCS11].

secrets-protection.master-keys[i].hsm.credentials[j].username

The HSM credentials username

secrets-protection.master-keys[i].hsm.credentials[j].password

The HSM credentials password

secrets-protection.master-keys[i].hsm.credentials[j].roles

The HSM credentials' role. A comma-separated list, e.g. KEYMANAGEMENT,KEYUSAGE.
One or more of [KEYMANAGEMENT, KEYUSAGE].

The HSM credentials that need to be configured depend on the HSM and its policies. For KEYSTORE and PKCS11 HSMs, there must be exactly one credential that has both the KEYMANAGEMENT,KEYUSAGE roles (as neither keystore files nor PKCS11 generally support the concept of such roles).

For the rest of the HSM types, any combination (from requiring one credential with both roles, to requiring multiple credentials per role) is possible, depending on the exact HSM policies.

Check out the various templates for the application.properties for sample configurations for different HSMs.

If you require assistance for the configuration of MTG Secrets Protection Manager, do not hesitate to contact our support.

  • one or more (depending on the HSM policies) KEYMANAGEMENT credentials are required when running the init, add, destroy commands.

  • one or more (depending on the HSM policies) KEYUSAGE credentials are required when running any command.

  • because only KEYUSAGE credentials are needed by the MTG application to unprotect the DEK, any credentials inside the application.properties file that do not contain the KEYUSAGE role will be filtered out and will not be available in the generated secrets-protection.properties file.


secrets-protection.properties

The secrets-protection.properties file contains configuration pertaining to protected DEKs. It is automatically generated by the MTG Secrets Protection Manager and should normally not be edited.

Protected DEKs configuration must not exist when running the init and destroy commands. Protected DEKs configuration is optional when running the status command.

The following properties are available:

Property Description

secrets-protection.protected-deks[k].ciphertext

The ciphertext of the protected DEK.
Used only with the ENCRYPTION protection strategy.

secrets-protection.protected-deks[k].iv

The initialization vector of the protected DEK.
Used only with the ENCRYPTION protection strategy.

secrets-protection.protected-deks[k].wrapped-key

The wrapped ciphertext of protected DEK.
Used only with the KEY_PROTECTION protection strategy.

secrets-protection.protected-deks[k].master-key.name

The master key name

secrets-protection.protected-deks[k].master-key.domain

The master key domain

secrets-protection.protected-deks[k].master-key.strategy

The strategy used to protect the DEK.
See protection strategy.
One of [ENCRYPTION, KEY_PROTECTION].

secrets-protection.protected-deks[k].master-key.hsm.type

The master key HSM type.
One of [KEYSTORE, UTIMACO, LUNA_SA, PKCS11].

secrets-protection.protected-deks[k].master-key.hsm.address

The HSM address.
Depending on the HSM type this field can refer to one of:

  • the network address for HSM type [UTIMACO, LUNA_SA].

  • the absolute filepath of the keystore file (.bcfks) for HSM type [KEYSTORE].

  • the absolute filepath of the .so/.dll library for HSM type [PKCS11].

secrets-protection.protected-deks[k].master-key.hsm.credentials[j].username

The HSM credentials username

secrets-protection.protected-deks[k].master-key.hsm.credentials[j].password

The HSM credentials password

secrets-protection.protected-deks[k].master-key.hsm.credentials[j].roles

The HSM credentials role. A comma-separated list, e.g. KEYMANAGEMENT,KEYUSAGE.+ One or more of [KEYMANAGEMENT, KEYUSAGE].

where i, j and k are the indices of the master key, HSM credential and protected DEK respectively.

Extra care should be taken when manually editing properties that use the [index] notation. Indices always start with [0] and may not be skipped (i.e. cannot go from [0] to [2]).

Protection strategy

The following protection strategies are available:

Encryption

The ENCRYPTION protection strategy performs the following steps:

  1. Generate an AES-256 key on the HSM;

  2. Encrypt the DEK using AES_GCM_NOPADDING with the master key.

This is the default protection strategy. Prefer using it on any HSM that supports symmetric encryption.

Key Protection

The KEY_PROTECTION protection strategy performs the following steps:

  1. Generates an BRAINPOOLP256R1 EC keypair on the HSM;

  2. Calculates a shared secret by performing Elliptic-curve Diffie–Hellman (ECDH) key agreement using the keypair’s private and public keys;

  3. Derives a key from the shared secret as specified in BSI TR-03111 (chapter 4.3.3 "Key Derivation Functions");

  4. Wraps the DEK using the derived key.

Only use this strategy with HSMs that do not support symmetric encryption (e.g. the no longer available MTG smartHSM).

Backup

Creating a backup

Before running the init command, one or more master keys are expected to be configured in the application.properties file. The first master key (with index 0, i.e. secrets-protection.master-keys[0]) will be the one 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.

Any HSM type can be used for a backup master key, but most appropriate is either a small-form-factor PKCS11 HSM (e.g. a USB HSM) or a KEYSTORE HSM.

After running the init command, the following steps must be performed, in order create a backup that will allow for a DEK restoration in the case of an HSM malfunction:

  • securely store a copy of the generated secrets-protection.properties file;

  • (optionally) securely store any generated keystore (.bcfks) files;

  • (optionally) unplug and securely store any small-form-factor HSMs (e.g. USB HSMs) intended to be used as backup.

Restoring a backup

In order to restore a backup, the following steps must be performed:

  1. Configure the previously securely stored 'secrets-protections.properties' file that contains the protected DEK you wish to restore;

  2. (optionally) Configure any previously securely stored keystore (.bcfks) files;

  3. (optionally) plug in any previously securely stored small-form-factor HSMs (e.g. USB HSMs);

  4. Configure the 'application.properties' file with the new master key that should be used to protect the restored DEK.

  5. Run the MTG Secrets Protection Manager add command;

  6. Configure the newly generated content of the secrets-protection.properties file in each MTG application.