MTG KMS BYOK Tool Business Processes

MTG KMS BYOK Tool Use Cases

Taken together, there are three Use Cases that the tool provides:

Byok: Generation of a byok file for importing a wrapped MTG KMS key into Azure Key Vault, using the commandline tools provided (Azure CLI).
Import: Importing an MTG KMS key into Azure Key Vault in one go.
Rekey: Renewal of specified keys in the MTG KMS.

In all cases the MTG KMS keys must be already created or registered at the MTG KMS System and all Azure Key Vault credentials, URL’s and keys must be available.

Byok

In this use case, the import process is divided in two separate tasks:

First, the user starts the MTG KMS BYOK Tool with the command byok. This will get a specified key from the MTG KMS, wrapped using a provided Azure KEK. The wrapped key will then be written into a .byok file. This subtask can be done independently of the import. The following resources are needed for the subtask:

Credentials or keystore for a KMS-Client to get access to the MTG KMS
Key-ID and public key of the Azure Key Vault KEK
One or more UUID(s) of the MTG KMS key(s)

The structure of the generated .byok file is described here.

The second subtask then is the import of the wrapped key(s) into the Azure Key Vault, using the Azure CLI tool.

Import

This task is responsible for importing private keys from the MTG KMS into an Azure Key Vault. It reads all the necessary information from the application.properties file.

When started, the task first gets the newest version of the configured MTG KMS keys and checks, if these exist in the Azure Key Vault. If not, it’s getting the MTG KMS key which is wrapped using the provided Azure KEK. Then it is importing the wrapped key into the key vault.

Rekey

This task is responsible for create new key pairs at MTG KMS and to replace existing ones at Azure Key Vault. In order to decide when a new key pair should be created, the MTG KMS BYOK Tool uses policies, which define the period, after which a renewal should be made. The task gets all the necessary information from the application.properties file.

When started, the task first gets the newest version of the configured MTG KMS keys and checks, if the activation date is older than the defined by the policy. If so, a new version of the key pair will be created. This new version could be imported later into the Azure Key Vault using either Byok or Import.

In order to start the MTG KMS BYOK Tool with Rekey in a daily, weekly or monthly manner a crontab trigger can be used.

Getting started with MTG KMS BYOK Tool

How to use

Install the MTG KMS BYOK Tool package
Configure the MTG KMS BYOK Tool application.properties in the configuration directory.

When using Command byok no application.properties file is needed, all parameters are set via command line.

Running MTG KMS BYOK Tool

The tool comes a one executable jar file, which can be started:

java -jar mtg-kms-byok-tool.jar <config-options> [command] <options> <params>

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

The application.properties file can be placed in the same directory where the tool is started. If not the full path to the file must be set via the commandline option --spring.config.location

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

A full start script would be:

#!/bin/bash

CONFIG_OPTIONS=
#comment the line below, if the `byok` command ist used
CONFIG_OPTIONS="$CONFIG_OPTIONS --spring.config.location=/etc/opt/mtg-kms-byok/application.properties"
CONFIG_OPTIONS="$CONFIG_OPTIONS --logging.config=/etc/opt/mtg-kms-byok/logback.xml"

JAVA_BIN=java

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

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

#NCIPHER PKCS11
#export CKNFAST_OVERRIDE_SECURITY_ASSURANCES="explicitness;tokenkeys" CKNFAST_LOADSHARING=true

#external JARs (e.g. Utimcato CXI)
#export LOADER_PATH=<PATH>

### Run
$JAVA_BIN -jar mtg-kms-byok-tool.jar $CONFIG_OPTIONS $@

Key Restrictions

The following restrictions apply to the keys to be imported:

Only private keys can be imported.
Only RSA and EC are supported algorithms
For EC keys the following Nist curves are supported
- P-256
- P-384
- P-521

Command Line Options

Usage: mtg-kms-byok-tool [-hVv] [COMMAND]
  -h, --help      Show this help message and exit.
  -v, --verbose   Specify multiple -v options to increase verbosity.
                  For example, `-v -v -v` or `-vvv`
  -V, --version   Print version information and exit.
Commands:
  byok      Generates the BYOK file(s) for importing private key(s) into an
              Azure Key Vault.
  import    Imports the keys, specified in the application.properties into the
              configured Azure Key Vault.
  rekey     Does a renewal of the keys, specified in the application.properties
              using the configured policies.
  validate  Validates the application.properties.
  help      Displays help information about the specified command

The output of the tool can be controlled by the verbose options. All logs will be sent to standard out by default.

If additional logging is needed or the output should be written to a file, a logback configuration file must be provided (see BYOK Tool Configuration)

Command `byok`

Usage: mtg-kms-byok-tool byok [-v] -i=<azureKekId> -k=<azureKekFile>
                              [--keystore-file=<keyStoreFile>]
                              [--keystore-pw=<keyStorePassword>]
                              [-o=<outputPath>] -p=<password> -s=<serverUrl>
                              [--truststore-file=<trustStoreFile>]
                              [--truststore-pw=<trustStorePassword>]
                              -u=<username> KEY-ID...
Generates the BYOK file(s) for importing private key(s) into an Azure Key Vault.
      KEY-ID...   *One* or more (seperated by blank) KMS key uuids. The id must be the uuid of the
                    private key of the MTG KMS key pair
                  For each key, a single byok file is created.
  -i, --azure-kek-id=<azureKekId>
                  The key id of the azure kek (From the Azure Key Vault and app registration details in the Azure portal).
  -k, --azure-kek, --azure-kek-file=<azureKekFile>
                  The file with the azure kek (From the Azure Key Vault and app registration details in the Azure portal).
                  Can be a PEM or raw PKCS#1 DER.
      --keystore-file=<keyStoreFile>
                  The keystore for accessing the KMS server via TLS and
                    authenticating via a client certificate
      --keystore-pw=<keyStorePassword>
                  The keystore password
  -o, --output-path=<outputPath>
                  The output path for the BYOK file(s).
                  For each key, a single byok file is created inside the
                    specified directory.
  -p, --password=<password>
                  The password for accessing the KMS server
  -s, --server-url=<serverUrl>
                  The URL for accessing the KMS server
                  If the access to the server is via HTTPS, a truststore mus be
                    specified
      --truststore-file=<trustStoreFile>
                  The truststore for accessing the KMS server via TLS
      --truststore-pw=<trustStorePassword>
                  The truststore password
  -u, --username=<username>
                  The username for accessing the KMS server
  -v, --verbose   Specify multiple -v options to increase verbosity.
                  For example, `-v -v -v` or `-vvv`

Process finished with exit code 0

The values for the Azure kek come from the Azure Key Vault and app registration details in the Azure portal.

Which parts of the KMS client must be configured (username/password or keystore) depends on the configuration in the MTG KMS.

The application.properties file can be placed in the same directory where the tool is started. If not, the full path to the file must be set via the commandline option --spring.config.location.
See BYOK Tool Configuration for the content of this file. This applies to all commands shown below.

Command `import`

Usage: mtg-kms-byok-tool import [-v]
imports the keys, specified in the application.properties
into the configured Azure Key Vault.
  -v, --verbose   Specify multiple -v options to increase verbosity.
                  For example, `-v -v -v` or `-vvv`

The configuration, what to import and where is configured in the application.properties file.

Command `rekey`

Usage: mtg-kms-byok-tool rekey [-v] [--force] [KEY-ID...]
Does a renewal of the keys, specified in the application.properties using the
configured policies.
      --force       Forces a renewal
  -v, --verbose     Specify multiple -v options to increase verbosity.
                    For example, `-v -v -v` or `-vvv`....

If --force is set, the policy period will be ignored and all keys will be renewed.

The configuration, what to rekey is configured the application.properties file.

Command `validate`

Usage: mtg-kms-byok-tool validate [-v]
Validates the application.properties.
  -v, --verbose   Specify multiple -v options to increase verbosity.
                  For example, `-v -v -v` or `-vvv`

This command can be used to check, if the content of the application.properties file is correct.

It checks the configured Azure Key Vaults, the access to the MTG KMS and the tenant / key configuration.