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 |
---|---|
|
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: |
Common properties
The following table lists the common properties used to configure each KMS.
|
Required. The KMS type. Possible values are |
|
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. |
|
Optional. Boolean ( |
|
Optional. Boolean ( |
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 |
---|---|
|
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 |
---|---|
|
Path to a keystore file containing the key. Required when using a keystore. |
|
Optional. The password to unlock the keystore file containing the key. |
|
Alias of the key inside the keystore. Required when using a keystore. |
|
Optional. The password of the key inside the keystore. |
|
Optional. Keystore type. Defaults to |
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
To use the generated key as a KMS, you should set the following configuration: Example 2. Using a key generated with keytool
|
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 |
---|---|
|
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 |
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.
|
Optional. AWS region to use. This property must be a valid input for AWS Region |
|
Optional. Alternate credential profile, similar to the one provided with the AWS_PROFILE environment variable. |
|
Optional. Access AWS KMS using an AWS access key ID and secret access key. |
|
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 |
---|---|
|
Required. Azure Key Vault base URL. |
|
Required. Azure Key Vault Key Name. The key must be an RSA key. |
|
Required. Algorithm to use to wrap the specified key content. Possible values include: |
|
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 |
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 |
---|---|
|
Use these properties to build the credentials using a clientid and client secret. Having any of those properties defined makes the other ones required. |
|
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 |
---|---|
|
Required. The ID of the project in the Google Cloud Platform. |
|
Required. The name of the KeyRing to use for encryption. |
|
Required. The location of the key ring. |
|
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 |
---|---|
|
Path to the key file created in Service Account. Required if neither the |
|
Raw content of the Service Account key file. Required if neither the |
|
Optional. Provides the scope to send when calling accessSecretVersion. The default value is |
Google Cloud credentials are first checked in the credential file, then credential value, then the environment variable. |