Configure a key management service

A key management service (KMS) encrypts and decrypts the secrets stored in Semarchy xDM.

Although you can have multiple KMS, only one of them is the current one. The current KMS is used to encrypt new or updated secrets before storage. The other ones (the outdated KMS) may remain from previous configurations to decrypt previously encrypted secrets before re-encrypting them with the current KMS.

Supported KMS

Semarchy xDM supports the following Key Management Services types:

  • LOCAL KMS: This KMS encrypts secrets with the AES-GCM encryption method, using an AES-256bits encryption key which is read from a configuration property or a key store file.

  • AWS KMS: This KMS delegates encryption to the AWS Key Management Service, using an AWS Customer Managed Key.

  • Azure KMS: This KMS delegates encryption to the Azure Key Vault service.

  • GCP KMS: This KMS delegates encryption to the Google Cloud Key Management service.

Semarchy xDM comes with a default KMS for encrypting secrets, labelled Insecure. This KMS provides encryption capabilities at installation time using a default built-in key. It is strongly recommended to quickly replace it with another KMS - even using LOCAL KMS - in your environment.

KMS configuration

KMS are configured using startup configuration properties.

KMS alias

Each KMS is identified by an Alias. This alias is a lowercase string containing alphanumerical characters. Other characters, such as spaces, dots, dashes, underscores, etc, are not supported in the alias. Besides, the alias cannot be one of the reserved aliases: current, insecure.

The alias is part of the KMS configuration properties name. For example the xdm.secrets.internal.KMS.awscorporate.type property defines the type of awscorporate KMS.

Current KMS

The current KMS is configured using the xdm.secrets.internal.kms.current property.

Property Description

xdm.secrets.internal.kms.current

The alias of the current KMS used to generate, encrypt and decrypt keys. The alias must be lowercase and alphanumerical, and cannot be one of the reserved aliases: current, insecure. This property is optional if only one KMS is defined.

Common properties

The following table lists the common properties used to configure each KMS.

xdm.secrets.internal.kms.<kms_alias>.type

Required. The KMS type. Possible values are LOCAL, AWS, AZURE, or GCP.

xdm.secrets.internal.kms.<kms_alias>.<property>

Each type of KMS has its own set of configuration properties, listed in the following sections for the local KMS, [_aws_kms], Azure KMS, Google Cloud KMS.

xdm.secrets.internal.allowed

Optional. Boolean (true/false) value indicating if using internal secrets is allowed or not globally. See Limit secrets usage for more information.

xdm.secrets.internal.allowed.<secret_usage>

Optional. Boolean (true/false) value indicating whether using internal secrets is allowed for a given <secret_usage>. See Limit secrets usage for more information.

Local KMS

When using the LOCAL Key Management Service, encryption used AES/GCM with an AES-256 bit key. This key is retrieved from a configuration property or a key store file.

Key in a property

To provide the key in a property, set the following property:

Property Description

xdm.secrets.internal.kms.<kms_alias>.key

Optional. Key in a Base64-encoded form. Note that this property is ignored for the KMS if any of the keystore properties is provided.

Key from a keystore file

To retrieve a key from a key store file, you must configure the following properties:

Property Description

xdm.secrets.internal.kms.<kms_alias>.keystore.file

Path to a keystore file containing the key. Required when using a keystore.

xdm.secrets.internal.kms.<kms_alias>.keystore.password

Optional. The password to unlock the keystore file containing the key.

xdm.secrets.internal.kms.<kms_alias>.keystore.key

Alias of the key inside the keystore. Required when using a keystore.

xdm.secrets.internal.kms.<kms_alias>.keystore.keypassword

Optional. The password of the key inside the keystore.

xdm.secrets.internal.kms.<kms_alias>.keystore.type

Optional. Keystore type. Defaults to pkcs12.

Key generation using Keytool

You can generate an AES-256 key in a key store using the command line keytool tool as shown below:

Example 1. Generating a key in a key store using keytool
keytool
    -genseckey
    -keystore <keystore-file>
    -storepass <keystore-password>
    -storetype pkcs12
    -alias <key_alias>
    -keyalg AES
    -keysize 256

To use the generated key as a KMS, you should set the following configuration:

Example 2. Using a key generated with keytool
xdm.secrets.internal.kms.<kms_alias>.keystore.file=<keystore-file>
xdm.secrets.internal.kms.<kms_alias>.keystore.password=<keystore-password>
xdm.secrets.internal.kms.<kms_alias>.keystore.type=pkcs12
xdm.secrets.internal.kms.<kms_alias>.keystore.key=<key_alias>
xdm.secrets.internal.kms.<kms_alias>.keystore.keypassword=<key_password>

AWS KMS

When using the AWS KMS Type, Semarchy xDM uses the AWS Key Management Service to generate and unwrap the encryption keys. This mechanism uses a Customer Managed Key managed in AWS KMS.

AWS configuration

Before configuring and using an AWS KMS, make sure to allow the following actions through key policies: Encrypt, kms:Decrypt, kms:ReEncrypt*, and kms:GenerateDataKey*.

Configuration properties

The following table lists the properties to configure an AWS KMS.

Property Description

xdm.secrets.internal.kms.<kms_alias>.keyid

The unique identifier for the customer master key (CMK).

Key rotation

To enable master key rotation, make sure to choose between automatic or manual key rotation (refer to the AWS documentation). With manual rotation, the key ARN changes over time. You should configure the xdm.secrets.internal.kms.<kms_alias>.keyid property with an alias in AWS KMS and make sure to update this alias' target when rotating the key.

AWS region and credentials configuration

Semarchy xDM uses the AWS Default Credential Provider Chain and Default Region Provider Chain and therefore relies on the system/environment for the AWS region and credentials. However, you use the following properties to specify them for a KMS.

xdm.secrets.internal.kms.<kms_alias>.region

Optional. AWS region to use. This property must be a valid input for AWS Region

xdm.secrets.internal.kms.<kms_alias>.credentials.profile

Optional. Alternate credential profile, similar to the one provided with the AWS_PROFILE environment variable.

xdm.secrets.internal.kms.<kms_alias>.credentials.basic.accesskey
xdm.secrets.internal.kms.<kms_alias>.credentials.basic.secretkey

Optional. Access AWS KMS using an AWS access key ID and secret access key.

xdm.secrets.internal.kms.<kms_alias>.credentials.session.accesskey
xdm.secrets.internal.kms.<kms_alias>.credentials.session.secretkey
xdm.secrets.internal.kms.<kms_alias>.credentials.session.token

Optional. Access AWS KMS by explicitly providing temporary credentials.

Azure KMS

When using the AZURE KMS Type, Semarchy xDM uses Azure Key Vault to wrap and unwrap the encryption keys.

Azure configuration

To operate properly, the credentials used to access Azure Key Vault should have the following key permissions on the vault: Get Key, Wrap Key, Unwrap Key.

Configuration properties

The following table lists the properties to configure an Azure KMS.

Property Description

xdm.secrets.internal.kms.<kms_alias>.vaulturl

Required. Azure Key Vault base URL.

xdm.secrets.internal.kms.<kms_alias>.keyname

Required. Azure Key Vault Key Name. The key must be an RSA key.

xdm.secrets.internal.kms.<kms_alias>.wrapalgorithm

Required. Algorithm to use to wrap the specified key content. Possible values include: RSA1_5, RSA_OAEP and RSA_OAEP_256

xdm.secrets.internal.kms.<kms_alias>.keyversion

Optional. Azure Key Vault Key Version. Leave this property empty to use the latest version of the key.

Key rotation

To enable Master Key Rotation, make sure to configure the KMS without specifying a key version in the xdm.secrets.internal.kms.<kms_alias>.keyversion property. New versions of the key in Azure Key Vault will automatically be used for encrypting new secrets or re-encrypting existing secrets.

Azure credentials configuration

Semarchy xDM uses the DefaultAzureCredentialBuilder and relies on the system/environment for the Azure Credentials. However, you can use the following properties to configure the credentials for a KMS.

Property Description

xdm.secrets.internal.kms.<kms_alias>.credentials.tenantid
xdm.secrets.internal.kms.<kms_alias>.credentials.clientid
xdm.secrets.internal.kms.<kms_alias>.credentials.clientsecret

Use these properties to build the credentials using a clientid and client secret. Having any of those properties defined makes the other ones required.

xdm.secrets.internal.kms.<kms_alias>.credentials.username
xdm.secrets.internal.kms.<kms_alias>.credentials.password

Use these properties to build the credentials using a username and password. Having any of those properties defined makes the other ones required.

Google Cloud KMS

When using the GCP KMS Type, Semarchy xDM uses Google Cloud Key Management to wrap and unwrap the encryption keys, using the encrypt and decrypt APIs.

Google Cloud KMS configuration

To operate properly, make sure to configure the credentials to access Google Cloud Key Management.

Configuration properties

The following table lists the properties to configure a Google Cloud KMS.

Property Description

xdm.secrets.internal.kms.<kms_alias>.projectid

Required. The ID of the project in the Google Cloud Platform.

xdm.secrets.internal.kms.<kms_alias>.keyringname

Required. The name of the KeyRing to use for encryption.

xdm.secrets.internal.kms.<kms_alias>.location

Required. The location of the key ring.

xdm.secrets.internal.kms.<kms_alias>.keyname

Required. The resource name of the CryptoKey to use for encryption.

Key rotation

To enable Master Key Rotation, make sure to configure the keyname without a version. You can rotate your key following the Google Cloud Key Management instructions.

Google Cloud credentials configuration

Semarchy xDM uses the GoogleCredentials to build the Google Credentials and so relies on the GOOGLE_APPLICATION_CREDENTIALS environment variable. However, you can use the following properties to configure the credentials for a KMS.

Property Description

xdm.secrets.internal.kms.<kms_alias>.credentials.file

Path to the key file created in Service Account. Required if neither the GOOGLE_APPLICATION_CREDENTIALS environment variable above nor the properties below are defined.

xdm.secrets.internal.kms.<kms_alias>.credentials.value

Raw content of the Service Account key file. Required if neither the GOOGLE_APPLICATION_CREDENTIALS environment variable nor the credential file are defined.

xdm.secrets.internal.kms.<kms_alias>.credentials.scope

Optional. Provides the scope to send when calling accessSecretVersion. The default value is https://www.googleapis.com/auth/cloud-platform.

Google Cloud credentials are first checked in the credential file, then credential value, then the environment variable.