Enable encrypted private key storage with a KMS

Canton can use a KMS to encrypt private keys at rest (envelope encryption):

1. Private keys are stored encrypted in the node’s database.

2. On startup, the KMS decrypts them for in-memory use.

This improves security with no runtime performance impact. See Protect private keys with envelope encryption and a Key Management Service for details.

Note

This assumes the KMS provider has already been configured. See Configure a KMS.

Enable envelope encryption

Envelope encryption is a common approach chosen by KMS vendors that uses a symmetric encryption key, called the wrapper key, to encrypt and decrypt the stored, private keys.

To enable encrypted private key storage with a KMS using envelope encryption, we must add the following configuration and restart the node.

canton.participants.participant1.crypto.private-key-store.encryption.type = kms

Both new and existing nodes (including Participants) can be configured to use this feature.

In both cases, keys are stored encrypted in the Canton node’s database.

Important

Restoring from a database backup requires access to the wrapper keys used during the encryption of the data in the backup. Deleting the wrapper keys renders the backup unusable.

Manually generate a wrapper key

By default, a new symmetric wrapper key is automatically generated by Canton after the node restarts. If you want to use a pre-generated wrapper key, you must first create a new wrapper key in the KMS and record its identifier, taking into account the following requirements.

AWS KMS wrapper key requirements

Important

Daml Enterprise license required

Supported values for identifying the wrapper key:

• Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

• Key ARN (Amazon Resource Name): arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab

• Key alias: alias/test-key

Note that if you are using an existing key, it must be a symmetric key using the correct scheme. In AWS KMS, this means:

• Key specification: SYMMETRIC_DEFAULT

• Key usage: ENCRYPT_DECRYPT

GCP KMS wrapper key requirements

Important

Daml Enterprise license required

Supported values for identifying the wrapper key:

• Key name: test-key

• Key Resource Name (RN): projects/gcp-kms-testing/locations/us-east1/keyRings/canton-test-keys/cryptoKeys/test-key/cryptoKeyVersions/1

Note that if you are using an existing key, it must be created with the following attributes:

• Key algorithm: GOOGLE_SYMMETRIC_ENCRYPTION

• Key purpose: ENCRYPT_DECRYPT

KMS Driver key requirements

The way keys are uniquely identified is left to the driver implementation. However, the following constraints must be observed:

• Keys must be 128-bit in length and usable with the AES-GCM crypto scheme.

Add new wrapper key to configuration

With the key created and its ID in hand, you must explicitly add the ID to the configuration using:

canton.participants.participant1.crypto.private-key-store.encryption.wrapper-key-id = alias/canton-kms-test-key

An example configuration that puts together both AWS KMS and envelope encryption with a manually generated wrapper key is shown below:

_shared_aws {
  # Configure an AWS KMS
  crypto {
    kms {
      type = aws
      region = us-east-1
      multi-region-key = false
      audit-logging = false
    }

    # Configure an encrypted store with KMS
    private-key-store {
      encryption.type = kms
      # In this example we are using the same wrapper key for all nodes. This is not recommended and you should
      # either let Canton generate those keys or choose a different one for each node.
      encryption.wrapper-key-id = alias/canton-kms-test-key
    }
  }
}

After subsequent restarts the operator does not need to specify the identifier for the wrapper key; Canton stores the wrapper key ID in the database.