Ctrlk
Support Center
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Key Management Service (KMS)

Hold the Canton participant's operational keys in an external key management service.

By default a Canton participant generates its operational keys and stores them in its own PostgreSQL database. For deployments that require stronger key-protection guarantees, CAT-BM can configure the participant to hold those keys in an external KMS instead.

Without KMS
With KMS

Keys are generated by the node and stored in the participant database.

Keys are generated and held in the KMS. Private key material never enters the node.

Protecting the keys means protecting the database.

Keys are customer-managed, with the KMS's own access control and audit trail.

Sufficient for many deployments; it is Canton's out-of-the-box model.

Supports FIPS 140-2 validated modules and HSM backing where the provider offers them.

KMS protects the participant node's operational keys. It is a different concern from external party keys, which are held by the party's owner — see External & Multi-Host Parties — and from the Wallet Gateway, which delegates party signing to a custody provider.

Azure Key Vault

Prerequisites

1

A key vault

An Azure Key Vault the participant can reach, with the identity CAT-BM will use granted permission to create keys and to sign and decrypt with them.

For HSM-backed keys you need a Premium vault or Managed HSM.

2

A KMS-enabled participant image

Azure Key Vault support requires a purpose-built participant image containing the KMS driver. Contact IntellectEU support to obtain it, together with the pull secret for the registry it is published to.

3

Credentials

Either a workload identity, or a service principal whose client secret you store in a Kubernetes Secret.

kubectl create secret generic azure-kms-credentials \
  --from-literal=client-secret=<azure-client-secret> \
  -n <namespace>

Configuration

spec:
  kms:
    enabled: true
    provider: azure
    azure:
      vaultUrl: https://my-vault.vault.azure.net/
      keyNamePrefix: my-validator
      preBuiltImage: <kms-enabled-participant-image>
      imagePullSecret: azure-kms-registry-credentials
      tenantId: <azure-tenant-id>
      clientId: <azure-client-id>
      clientSecretRef:
        name: azure-kms-credentials
        key: client-secret
Field
Purpose

vaultUrl

Required. The key vault URL.

preBuiltImage

Required. The KMS-enabled participant image.

keyNamePrefix

Prefixes generated key names, so several nodes can share one vault without colliding.

credentialType

How the driver authenticates: default, environment, or managedIdentity. Omit it to use a service principal from the secret.

tenantId, clientId, clientSecretRef

Service principal credentials. Not needed with default or managedIdentity.

hardwareBackedKeys

Create HSM-protected keys. Needs a Premium vault or Managed HSM.

imagePullSecret

Pull secret for the participant image's registry.

With Azure KMS enabled, preBuiltImage replaces the participant image entirely. spec.participant.version and spec.network.spliceVersion are ignored for the participant. That means the KMS image's Canton version is what runs — coordinate its version with the rest of your deployment, and re-check it at every upgrade.

spec.kms.provider is matched case-sensitively. Azure or AZURE will not enable KMS — and because the validator otherwise reconciles normally, it will silently come up with keys in the database. Use lowercase azure.

Hardening options

The driver exposes a set of strict-mode checks — pinned key versions, key spec validation, key operation validation, rejection of exportable keys, hardened generated keys, and a minimum key-encryption-key strength. Leave them at their defaults unless you have a specific reason to relax one; they are there to fail closed.

Sizing and connection tunables — cache size and idle window, AES and RSA key sizes, I/O threads, and HTTP timeouts and pool limits — are also available. Omit them to use the driver's defaults. See the Validator CRD Reference for the full list.

Two driver defaults changed after the initial 2.0.0 release: audit logging is now enabled by default, and the default AES key size changed. If you depend on either, set the value explicitly rather than relying on the default.

AWS KMS

Confirm availability before relying on this. An AWS KMS provider is present in the current 2.0 line, but it postdates the 2.0.0 release and is less exercised than the Azure integration. Check with IntellectEU support before adopting it in production.

Unlike Azure, AWS KMS does not require a special participant image — it uses Canton's native AWS KMS support, so the standard participant image applies.

Field
Purpose

region

Required. The AWS region holding the keys.

serviceAccountName

A pre-created Kubernetes service account annotated for IAM Roles for Service Accounts. CAT-BM does not create it — you do.

credentialsSecretRef

Static credentials, as an alternative to IRSA. Keys default to access-key-id and secret-access-key, with an optional session-token for assumed roles.

multiRegionKey

Use a multi-region key.

auditLogging

Log KMS operations.

IRSA is preferable to static credentials: it avoids long-lived secrets in the cluster entirely.

Verifying it works

1

Check the validator reconciled

The Status tab should show Ready. A misconfiguration reports InvalidSpec with the exact field named in the message.

2

Check the participant image

On the participant's Application detail page, confirm the Image is the KMS-enabled one when using Azure.

3

Check the keys

The validator's Keys tab lists the participant's public keys. Cross-check them against your key vault — the vault is the authority on where the private material lives.

Operational consequences

Enabling KMS makes the KMS part of your validator's critical path and its recovery path.

  • Availability — if the participant cannot reach the KMS, it cannot sign, and it cannot operate.

  • Permissions — revoking or rotating the identity's access stops the node.

  • Recovery — losing access to the key vault is unrecoverable. An identity dump does not substitute for keys the node can no longer use.

Give the key vault the same backup, replication, and access-recovery treatment as the databases. See Identity Dumps & Database Backups.

Enable KMS before onboarding a validator where you can. Moving an existing validator's keys into a KMS is a Canton-level key migration, not a configuration change — plan it with IntellectEU support.

PreviousIdentity Dumps & Database Backups
NextParticipant Query Store

Last updated

Was this helpful?