> 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-1.11/validator-management/kms-integration.md).

# Key Management Service (KMS)

CatalyX Blockchain Manager supports External Key Management Services (KMS) for storing Canton Validator Participant cryptographic keys. When KMS is enabled, participant keys are stored and managed in in an external KMS rather than locally on the node, improving key security and enabling compliance with enterprise key management policies.

For background on why KMS matters, the two Canton key storage modes (encrypted vs. external), and the broader key management and wallet strategy for CAT-BM, see the Security & Privacy Implementation page:

{% content-ref url="/pages/bvHLoRkGDY6yVqcoe4i9" %}
[Security & Privacy Implementation](/catalyx-blockchain-manager/canton-network/version-1.11/technical-documentation-canton/security-and-privacy-implementation.md)
{% endcontent-ref %}

{% hint style="info" %}
KMS integration was introduced in **v1.11.8**. This is a Phase 1 implementation — KMS is enabled or disabled at the **environment level** and applies to all newly created validators in that environment. Per-validator KMS configuration will be addressed in a future release.
{% endhint %}

{% hint style="warning" %}
KMS configuration is set at the CAT-BM deployment level via environment variables on the Operator. Changes require redeployment of the Operator. Existing validators deployed before KMS was enabled are **not** affected — their participant pods retain the original configuration.
{% endhint %}

***

## How It Works

When KMS is enabled in the environment, the CAT-BM Operator injects additional Canton crypto configuration into the Participant pod at provisioning time. The Participant authenticates with AWS KMS using IRSA — an IAM Role is associated with a Kubernetes ServiceAccount, and that ServiceAccount is assigned to the Participant pod.

The ServiceAccount is **externally managed** in this phase. It must be created and maintained outside of CAT-BM, and its name is provided to the Operator via environment variable.

Validators already deployed without KMS are not modified when KMS is enabled at the environment level. Specifically, their Participant pods will not contain the KMS crypto config injection.

***

## Prerequisites

Before enabling KMS, ensure the following are in place:

* An AWS KMS key created in the appropriate region
* An IAM Role configured with permissions to use the KMS key
* A Kubernetes ServiceAccount created in the validator namespace with the IAM Role ARN annotated via IRSA:

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: catalyst-canton-kms
  namespace: <validator-namespace>
  annotations:
    eks.amazonaws.com/role-arn: <iam-role-arn>
```

* The ServiceAccount name available to set in the Operator environment

***

## Enabling KMS

KMS is enabled by setting the following environment variables on the CAT-BM Operator:

| Variable                              | Description                                                                                  |
| ------------------------------------- | -------------------------------------------------------------------------------------------- |
| `CANTON_TOPOLOGY_KMS_ENABLED`         | Set to `true` to enable KMS for newly created validators. Default: `false`.                  |
| `CANTON_TOPOLOGY_KMS_VALUE`           | The KMS provider configuration in Canton config format (see below).                          |
| `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` | The name of the externally managed Kubernetes ServiceAccount to use for IRSA authentication. |

### `CANTON_TOPOLOGY_KMS_VALUE` format

This variable takes a Canton configuration fragment. For AWS KMS:

```
{ type = "aws", region = "eu-west-1", audit-logging = true }
```

Adjust `region` to match your AWS KMS key region. Set `audit-logging` to `true` to enable KMS API audit logs (recommended for production).

### Example Operator environment configuration

```yaml
env:
  - name: CANTON_TOPOLOGY_KMS_ENABLED
    value: "true"
  - name: CANTON_TOPOLOGY_KMS_VALUE
    value: '{ type = "aws", region = "eu-west-1", audit-logging = true }'
  - name: CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT
    value: "catalyst-canton-kms"
```

{% hint style="danger" %}
If `CANTON_TOPOLOGY_KMS_ENABLED` is `true` but `CANTON_TOPOLOGY_KMS_SERVICE_ACCOUNT` is missing or empty, the Operator will surface an error and will not proceed with validator provisioning. Ensure all three variables are set before enabling KMS.
{% endhint %}

***

## What the Operator Configures

When a new validator is provisioned with KMS enabled, the Operator makes the following changes to the Participant pod:

**ServiceAccount reference** — the externally managed ServiceAccount is referenced in the Validator CRD spec:

```yaml
spec:
  serviceAccountName: catalyst-canton-kms
```

**KMS crypto config injection** — the following environment variable is injected into the Participant pod:

```
ADDITIONAL_CONFIG_SPLICE_PARTICIPANT_CRYPTO_KMS =
  "canton.participants.participant.crypto.provider = kms
   canton.participants.participant.crypto.kms = { type = "aws", region = "eu-west-1", audit-logging = true }"
```

***

## Verifying KMS Is Active

After provisioning a new validator with KMS enabled, verify that:

1. The Participant pod references the correct ServiceAccount — check with `kubectl get pod <participant-pod> -o yaml | grep serviceAccountName`
2. The `ADDITIONAL_CONFIG_SPLICE_PARTICIPANT_CRYPTO_KMS` environment variable is present on the Participant pod
3. The Participant starts successfully and reaches a Ready state — check the [Status](https://gitlab.com/intellecteu/products/catalyst/cat-bp/catbp-docu/catalyx-gitbook/-/blob/master/catalyx-blockchain-manager/canton-network/version-2.0/console-guide-canton/validator-detail/status.md) page in the console

{% hint style="info" %}
KMS key usage will appear in AWS CloudTrail if audit logging is enabled on your KMS key. This can be used to confirm the Participant is actively using KMS for cryptographic operations.
{% endhint %}

***

## Scope and Limitations

| Capability                                         | Phase 1 (v1.11.8)                                                            |
| -------------------------------------------------- | ---------------------------------------------------------------------------- |
| Environment-level KMS toggle                       | ✅ Supported                                                                  |
| Per-validator KMS toggle                           | ❌ Not yet supported                                                          |
| Operator-managed ServiceAccount lifecycle          | ❌ Not yet supported — SA must be externally managed                          |
| Retroactive KMS enablement for existing validators | ❌ Not supported — only new validators created after enabling KMS will use it |
| KMS key rotation                                   | ❌ Not yet supported                                                          |


---

# 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:

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

The question should be specific, self-contained, and written in natural language.
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.