.. Copyright (c) 2024 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 .. _validator-security: ================== Security Hardening ================== .. _validator-kms: 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 :ref:`Helm-based deployment ` of the validator. KMS usage is not currently supported for :ref:`Docker Compose-based deployments `. .. _validator-kms-migrating: 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. .. warning:: The GCP and AWS KMS drivers are available only for licensed users of Canton Enterprise. 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 :ref:`above `). Google Cloud KMS ^^^^^^^^^^^^^^^^ The mock configuration below for GCP KMS is included in ``splice-node/examples/sv-helm/kms-participant-gcp-values.yaml``: .. literalinclude:: ../../../apps/app/src/pack/examples/sv-helm/kms-participant-gcp-values.yaml :language: yaml 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``: .. literalinclude:: ../../../apps/app/src/pack/examples/sv-helm/kms-participant-aws-values.yaml :language: yaml 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` .. TODO(#16720): Add a section about offline root namespace keys