Configure a key management service

A key management service (KMS) handles the encryption and decryption of secrets stored in xDM.

You can have multiple KMS instances, but only one is designated as the current KMS. The current KMS is used to encrypt new or updated secrets before they are stored. The others, referred to as outdated KMS, may persist from previous configurations and are used to decrypt secrets previously encrypted, which are then re-encrypted using the current KMS.

Supported KMS

xDM supports the following types of KMS:

  • Local KMS: encrypts secrets using the AES-GCM encryption method with a 256-bit AES encryption key, sourced from a configuration property or a key store file.

  • AWS KMS: delegates encryption to AWS Key Management Service using an AWS customer managed key.

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

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

xDM includes a default KMS for encrypting secrets, labeled Insecure. This KMS offers encryption during installation using a built-in default key. It is strongly recommended to replace it promptly with another KMS—​such as local KMS—​to enhance security in your environment.

KMS configuration

KMS are configured using the startup configuration properties.

KMS aliases

Each KMS is identified by an alias, which is a lowercase string containing only alphanumerical characters. Other characters, such as spaces, dots, dashes, underscores, and similar symbols, are not supported in the alias. Additionally, the alias cannot be one of the reserved names—​that is current and insecure.

The alias is part of the KMS configuration properties name (e.g., the property xdm.secrets.internal.KMS.awscorporate.type defines the type of awscorporate KMS).

Current KMS

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

Property Mandatory Description

xdm.secrets.internal.kms.current

No

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. If more than one KMS is defined, specifying this property is required.

Common properties

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

Property Mandatory Description

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

Yes

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

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

No

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

No

Boolean (true or false) value indicating if using internal secrets is allowed or not globally. For more information, see Limit secrets usage.

xdm.secrets.internal.allowed.<secret_usage>

No

Boolean (true or false) value indicating whether using internal secrets is allowed for a given <secret_usage>. For more information, see Limit secrets usage.

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 Mandatory Description

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

No

Key in a Base64-encoded form. 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 Mandatory Description

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

No

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

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

No

The password to unlock the keystore file containing the key.

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

No

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

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

No

The password of the key inside the keystore.

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

No

Keystore type. Defaults to pkcs12.
Key generation using Keytool

You can generate an AES-256 key in a key store using the command line tool keytool, 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, xDM uses 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 Mandatory Description

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

No

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

To enable master key rotation, choose between automatic or manual key rotation. For more information, see the official AWS documentation). With manual rotation, the key ARN changes over time. Configure the xdm.secrets.internal.kms.<kms_alias>.keyid property with an alias in AWS KMS, and make sure you update this alias' target when rotating the key.

AWS region and credentials configuration

xDM uses the AWS default credential provider chain and default region provider chain, relying on the system or environment for the AWS region and credentials. However, you can specify them for a KMS using the following properties.

Property Mandatory Description

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

No

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

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

No

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

No

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

No

Access AWS KMS by explicitly providing temporary credentials.

Azure KMS

When using the AZURE KMS type, 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 Mandatory Description

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

Yes

Azure Key Vault base URL.

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

Yes

Azure Key Vault key name. The key must be an RSA key.

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

Yes

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

No

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

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

Property Mandatory 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

No

Use these properties to build the credentials using a client ID 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

No

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 Mandatory Description

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

Yes

The ID of the project in the Google Cloud Platform.

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

Yes

The name of the KeyRing to use for encryption.

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

Yes

The location of the key ring.

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

Yes

The resource name of the CryptoKey to use for encryption.
Key rotation

To enable master key rotation, make sure to configure the key name without a version. You can rotate your key following the Google Cloud Key Management instructions.

Google Cloud credentials configuration

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 Mandatory Description

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

No

Path to the key file created in the 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

No

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

No

Provides the scope to send when calling accessSecretVersion. The default value is https://www.googleapis.com/auth/cloud-platform.
Google Cloud credentials are checked in the following order: first in the credential file, then in the credential value, and finally in the environment variable.