Security Hardening

Using an external KMS for managing participant keys

By default, Canton participants use cryptographic keys that are generated by the participant itself and stored in the regular database used by the participant. To improve key security, participants can be configured to use an external Key Management System (KMS) to generate and store keys. Please consult the official Canton documentation on KMS support for additional details and a list of supported KMS providers. Participants deployed as part of a validator node support the External Key Storage mode of KMS usage.

In the following, we describe how to configure a validator so that its participant keys are managed by an external KMS. This guide assumes that you are using the Helm-based deployment of the validator. KMS usage is not currently supported for Docker Compose-based deployments.

Migrating an existing validator to use an external KMS

It is not generally supported to migrate an existing validator from “non-KMS-based” to “KMS-based” operation, or to migrate from one KMS provider to another. The main reason for this is that a participant’s root namespace key cannot be rotated, and importing it from a potentially unsafe location into a KMS would diminish the security gain of using the KMS. Moreover, some KMS providers do not support importing existing keys at all and can only be used for managing keys generated by the KMS itself.

Our recommended approach for switching to use KMS is to:

  1. Set up a fresh validator from scratch with the desired KMS configuration. (Rest of this guide.)

  2. Transfer all relevant assets from the existing non-KMS validator to the new KMS-enabled validator.

  3. Retire the non-KMS validator.

Configuring a fresh validator to use an external KMS

Please refer to the Canton documentation on configuring KMS support for determining the right configuration options to match your desired KMS provider and setup. We provide minimal Helm configuration examples for Google Cloud (GCP) KMS and Amazon Web Services (AWS) KMS below.

Whatever KMS provider you choose, please note:

  • Values in the kms section of the participant Helm chart are implicitly mapped to the Canton participant crypto.kms config. This implies that all configuration keys supported by Canton are supported, not only the ones shown in the examples above. Key names in camelCase are automatically converted to kebab-case.

  • For setting extra environment variables and mounting files to configure authentication to the KMS, you can use the .additionalEnvVars, .extraVolumeMounts, and .extraVolumes fields of the Splice participant Helm chart (see the examples).

  • Make sure that your KMS configuration is always included in the values files you pass to helm install participant ... or helm upgrade participant ....

  • Only configuration changes to splice-participant are required to deploy a KMS-enabled validator.

  • You need to deploy a fresh participant in order for KMS to be used correctly, which implies that you will need to setup the remaining validator components afresh as well (see above).

Google Cloud KMS

The mock configuration below for GCP KMS is included in splice-node/examples/sv-helm/kms-participant-gcp-values.yaml:

# Participant using GCP KMS (mock values; please modify to match your setup)
# See https://docs.daml.com/canton/usermanual/kms/kms_gcp_setup.html

kms:
  type: gcp
  # Replace LOCATION_ID, PROJECT_ID, and KEY_RING_ID based on your GCP KMS setup
  locationId: LOCATION_ID
  projectId: PROJECT_ID
  keyRingId: KEY_RING_ID
  # All other Canton options are supported as well;
  # camelCase keys here are automatically converted to kebab-case

# Example for configuring authentication to the GCP KMS.
# Adds an env var on the participant pod that points to the location of the Google
# credentials file and mounts that file as a volume, reading its contents from a secret.
# In order for this to work as-is, you need to create the appropriate k8s secret
# and ensure that it holds the contents of a valid Google credentials file
# (under the `googleCredentials` key).
additionalEnvVars:
  - name: GOOGLE_APPLICATION_CREDENTIALS
    value: "/app/gcp-credentials.json"
extraVolumeMounts:
  - name: gcp-credentials
    mountPath: "/app/gcp-credentials.json"
    subPath: googleCredentials
extraVolumes:
  - name: gcp-credentials
    secret:
      secretName: gke-credentials

Please refer to the Canton documentation for a list of supported configuration options and their meaning, as well as for instructions on configuring authentication to the KMS. Note again that Splice participants support the External Key Storage mode of KMS usage, so that (per the relevant Canton docs) the authentication credentials you supply must correspond to a GCP service account with the following IAM permissions:

  • cloudkms.cryptoKeyVersions.create

  • cloudkms.cryptoKeyVersions.useToDecrypt

  • cloudkms.cryptoKeyVersions.useToSign

  • cloudkms.cryptoKeyVersions.get

  • cloudkms.cryptoKeyVersions.viewPublicKey

For example, you can grant the Cloud KMS Admin and Cloud KMS Crypto Operator roles to the validator KMS service account.

Amazon Web Services KMS

The mock configuration below for AWS KMS is included in splice-node/examples/sv-helm/kms-participant-aws-values.yaml:

# Participant using AWS KMS (mock values; please modify to match your setup)
# See https://docs.daml.com/canton/usermanual/kms/kms_aws_setup.html
kms:
  type: aws
  # Replace REGION based on your AWS KMS setup
  region: REGION
  # All other Canton options are supported as well;
  # camelCase keys here are automatically converted to kebab-case

# Example for configuring authentication to the AWS KMS.
# Adds env vars on the participant pod with credentials read from a k8s secret.
# In order for this to work as-is, you need to create the appropriate k8s secret
# and ensure that it holds valid credentials
# (under the `accessKeyId` and `secretAccessKey` keys).
additionalEnvVars:
  - name: AWS_ACCESS_KEY_ID
    valueFrom:
      secretKeyRef:
        name: aws-credentials
        key: accessKeyId
  - name: AWS_SECRET_ACCESS_KEY
    valueFrom:
      secretKeyRef:
        name: aws-credentials
        key: secretAccessKey

Please refer to the Canton documentation for a list of supported configuration options and their meaning, as well as for instructions on configuring authentication to the KMS. Note again that Splice participants support the External Key Storage mode of KMS usage, so that (per the relevant Canton docs) the authentication credentials you supply must correspond to an entity with the following IAM permissions:

  • kms:CreateKey

  • kms:TagResource

  • kms:Decrypt

  • kms:Sign

  • kms:DescribeKey

  • kms:GetPublicKey