> For the complete documentation index, see [llms.txt](https://docs.catalyx.solutions/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/kms-integration.md).

# Key Management Service (KMS)

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.

<table><thead><tr><th width="230">Without KMS</th><th>With KMS</th></tr></thead><tbody><tr><td>Keys are generated by the node and stored in the participant database.</td><td>Keys are generated and held in the KMS. Private key material never enters the node.</td></tr><tr><td>Protecting the keys means protecting the database.</td><td>Keys are customer-managed, with the KMS's own access control and audit trail.</td></tr><tr><td>Sufficient for many deployments; it is Canton's out-of-the-box model.</td><td>Supports FIPS 140-2 validated modules and HSM backing where the provider offers them.</td></tr></tbody></table>

{% hint style="info" %}
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](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/external-and-multi-host-parties.md) — and from the Wallet Gateway, which delegates *party* signing to a custody provider.
{% endhint %}

***

## Azure Key Vault

### Prerequisites

{% stepper %}
{% step %}
**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.
{% endstep %}

{% step %}
**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.
{% endstep %}

{% step %}
**Credentials**

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

```bash
kubectl create secret generic azure-kms-credentials \
  --from-literal=client-secret=<azure-client-secret> \
  -n catalyx-system
```

{% endstep %}
{% endstepper %}

### Configuration

```yaml
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
```

<table><thead><tr><th width="230">Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>vaultUrl</code></td><td><strong>Required.</strong> The key vault URL.</td></tr><tr><td><code>preBuiltImage</code></td><td><strong>Required.</strong> The KMS-enabled participant image.</td></tr><tr><td><code>keyNamePrefix</code></td><td>Prefixes generated key names, so several nodes can share one vault without colliding.</td></tr><tr><td><code>credentialType</code></td><td>How the driver authenticates: <code>default</code>, <code>environment</code>, or <code>managedIdentity</code>. Omit it to use a service principal from the secret.</td></tr><tr><td><code>tenantId</code>, <code>clientId</code>, <code>clientSecretRef</code></td><td>Service principal credentials. Not needed with <code>default</code> or <code>managedIdentity</code>.</td></tr><tr><td><code>hardwareBackedKeys</code></td><td>Create HSM-protected keys. Needs a Premium vault or Managed HSM.</td></tr><tr><td><code>imagePullSecret</code></td><td>Pull secret for the participant image's registry.</td></tr></tbody></table>

{% hint style="danger" %}
**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.
{% endhint %}

{% hint style="warning" %}
`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`.
{% endhint %}

### 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](/catalyx-blockchain-manager/canton-network/version-2.0/validator-crd.md) for the full list.

{% hint style="info" %}
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.
{% endhint %}

***

## AWS KMS

{% hint style="warning" %}
**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.
{% endhint %}

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.

```yaml
spec:
  kms:
    enabled: true
    provider: aws
    aws:
      region: eu-central-1
      auditLogging: true
      # Either IRSA:
      serviceAccountName: catalyx-kms-sa
      # or static credentials:
      # credentialsSecretRef:
      #   name: aws-kms-credentials
```

<table><thead><tr><th width="250">Field</th><th>Purpose</th></tr></thead><tbody><tr><td><code>region</code></td><td><strong>Required.</strong> The AWS region holding the keys.</td></tr><tr><td><code>serviceAccountName</code></td><td>A pre-created Kubernetes service account annotated for IAM Roles for Service Accounts. <strong>CAT-BM does not create it</strong> — you do.</td></tr><tr><td><code>credentialsSecretRef</code></td><td>Static credentials, as an alternative to IRSA. Keys default to <code>access-key-id</code> and <code>secret-access-key</code>, with an optional <code>session-token</code> for assumed roles.</td></tr><tr><td><code>multiRegionKey</code></td><td>Use a multi-region key.</td></tr><tr><td><code>auditLogging</code></td><td>Log KMS operations.</td></tr></tbody></table>

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

***

## Verifying it works

{% stepper %}
{% step %}
**Check the validator reconciled**

The [Status](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/status-and-specification.md) tab should show `Ready`. A misconfiguration reports `InvalidSpec` with the exact field named in the message.
{% endstep %}

{% step %}
**Check the participant image**

On the participant's [Application](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/applications.md) detail page, confirm the **Image** is the KMS-enabled one when using Azure.
{% endstep %}

{% step %}
**Check the keys**

The validator's [Keys](/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validators/participant-and-keys.md) 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.
{% endstep %}
{% endstepper %}

***

## Operational consequences

{% hint style="danger" %}
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 & Backups](/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/identity-and-backups.md).
{% endhint %}

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catalyx.solutions/catalyx-blockchain-manager/canton-network/version-2.0/validator-management/kms-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.