From 02b4b7f66f7f8539bccffe433a616e7242bb5c08 Mon Sep 17 00:00:00 2001 From: danielporterda Date: Thu, 14 May 2026 19:05:27 -0400 Subject: [PATCH] Restore full SV Security page --- .../production-operations/sv-security.mdx | 121 ++++++++++-------- 1 file changed, 67 insertions(+), 54 deletions(-) diff --git a/docs-main/global-synchronizer/production-operations/sv-security.mdx b/docs-main/global-synchronizer/production-operations/sv-security.mdx index 008f2747..5eafc822 100644 --- a/docs-main/global-synchronizer/production-operations/sv-security.mdx +++ b/docs-main/global-synchronizer/production-operations/sv-security.mdx @@ -1,8 +1,12 @@ --- title: "SV Security" -description: "Security hardening, KMS configuration, and extra DAR notice for Super Validator nodes" +sidebarTitle: "SV Security" +description: "Security best practices for Super Validator nodes" --- +import CantonDocsGlobalSynchronizerProductionOperationsSecurityHardeningL93 from "/snippets/canton-docs/global-synchronizer_production-operations_security-hardening_L93.mdx"; +import CantonDocsGlobalSynchronizerProductionOperationsSecurityHardeningL112 from "/snippets/canton-docs/global-synchronizer_production-operations_security-hardening_L112.mdx"; + {/* COPIED_START source="splice:docs/src/sv_operator/sv_security.rst" hash="ae70b7be" */} @@ -13,89 +17,98 @@ Reviewers: Skip this section. Remove markers after final approval. ## Third-party Daml apps -## Using an external KMS for managing participant keys +{/* COPIED_START source="splice:docs/src/common/sv_extra_dars_notice.rst" */} + +As an SV operator, you are most welcome to review, install, and use third-party Daml apps provided you **install third-party Daml apps on a validator node separate from your SV node**. -In the following, we describe how to configure an SV so that its participant keys are managed by an external KMS. This guide assumes that you are following `sv-helm` for deploying your SV. +Installing additional Daml apps on an SV node is not supported and may compromise its secure operations. In particular, refrain from manually uploading additional `.dar` files to your SV node or manually connecting it to third-party synchronizers. + +{/* COPIED_END */} -Official support for the KMS-based operation of sequencers and mediators that are part of an SV deployment is planned for a future release. +If you want to run third-party applications, deploy a separate validator node for that purpose. Keep your SV node dedicated to its core functions. -### Migrating an existing SV to use an external KMS for participant keys +## External KMS for managing participant keys -One approach for switching to use KMS for SV participant keys while minimizing the risk of losing rewards is to: +{/* COPIED_START source="splice:docs/src/common/kms_participants_context.rst" */} +By default, Canton participants use cryptographic [keys](https://docs.daml.com/canton/usermanual/security.html) 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. Consult the official [Canton documentation on KMS support](https://docs.daml.com/canton/usermanual/kms/kms.html) for additional details and a list of supported KMS providers. Participants deployed as part of a Splice deployment support the [External Key Storage](https://docs.daml.com/canton/usermanual/kms/external_key_storage/external_key_storage.html) mode of KMS usage. +{/* COPIED_END */} -1. Set up a fresh SV from scratch with the desired KMS configuration. (Rest of this guide.) Coordinate with the other SV operators to onboard it with weight 0. -2. Coordinate with the other SV operators to move your SV weight to the new SV, setting the weight of the older SV to 0. -3. Transfer all relevant assets from the older SV to a validator or the new KMS-enabled SV. -4. Coordinate with the other SV operators to offboard the older SV. -5. Retire the older SV. +Official support for KMS-based operation of sequencers and mediators that are part of an SV deployment is planned for a future release. -### Configuring a fresh SV to use an external KMS +### General configuration -In addition to configuration changes to the participant Helm chart itself, you will also need to change the way in which your CometBFT governance key is managed compared to the default setup. +Refer to the [Canton documentation on configuring KMS support](https://docs.daml.com/canton/usermanual/kms/kms_setup.html) for determining the right configuration options for your desired KMS provider. -#### External management of CometBFT governance key +When configuring KMS through Helm values: -By default, the CometBFT governance key is managed transparently by the SV app, using the participant for key generation and storage. The specific way in which this is realized is not supported for KMS-enabled participants. Therefore, SV operators that wish to use an external KMS for managing their participant keys must manage the CometBFT governance key of their SV externally. +- Values in the `kms` section of the participant Helm chart are implicitly mapped to the Canton participant `crypto.kms` config. All configuration keys supported by Canton are supported, not only those shown in the examples. Key names in camelCase are automatically converted to kebab-case. +- Use `.additionalEnvVars`, `.extraVolumeMounts`, and `.extraVolumes` fields of the Splice participant Helm chart to set extra environment variables and mount files for KMS authentication. +- Make sure your KMS configuration is always included in the values files you pass to `helm install participant ...` or `helm upgrade participant ...`. -This involves the following steps: +### Google Cloud KMS -1. Generate a new CometBFT governance key. -2. Configure your SV app to use this externally generated key. +{/* COPIED_START source="splice:docs/src/common/kms_config_gcp.rst" */} +Refer to the [Canton documentation](https://docs.daml.com/canton/usermanual/kms/kms_gcp_setup.html) for a list of supported configuration options and their meaning, as well as for instructions on configuring authentication to the KMS. Splice participants support the External Key Storage mode, so the authentication credentials you supply must correspond to a GCP service account with the following IAM permissions: -##### Generating a CometBFT governance key +- `cloudkms.cryptoKeyVersions.create` +- `cloudkms.cryptoKeyVersions.useToDecrypt` +- `cloudkms.cryptoKeyVersions.useToSign` +- `cloudkms.cryptoKeyVersions.get` +- `cloudkms.cryptoKeyVersions.viewPublicKey` -Use the following shell commands to generate a keypair in the expected format: : +You can grant the `Cloud KMS Admin` and `Cloud KMS Crypto Operator` roles to the validator KMS service account. +{/* COPIED_END */} -```bash -# Generate the private key -openssl genpkey -algorithm ed25519 -out cometbft-governance-keys.pem +A mock GCP KMS configuration is available in [apps/app/src/pack/examples/sv-helm/kms-participant-gcp-values.yaml](https://github.com/canton-network/splice/blob/main/apps/app/src/pack/examples/sv-helm/kms-participant-gcp-values.yaml). -# Extract and encode the keys -public_key_base64=$(openssl pkey -in cometbft-governance-keys.pem -pubout -outform DER | tail -c 32 | base64 | tr -d "\n") -private_key_base64=$(openssl pkey -in cometbft-governance-keys.pem -outform DER | tail -c 32 | base64 | tr -d "\n") +### Amazon Web Services KMS -echo "{" -# Output the keys -echo " \"publicKey\": \"$public_key_base64\"," -echo " \"privateKey\": \"$private_key_base64\"" -echo "}" +{/* COPIED_START source="splice:docs/src/common/kms_config_aws.rst" */} +Refer to the [Canton documentation](https://docs.daml.com/canton/usermanual/kms/kms_aws_setup.html) for a list of supported configuration options and their meaning, as well as for instructions on configuring authentication to the KMS. Splice participants support the External Key Storage mode, so the authentication credentials you supply must correspond to an entity with the following IAM permissions: -# Clean up -rm cometbft-governance-keys.pem -``` +- `kms:CreateKey` +- `kms:TagResource` +- `kms:Decrypt` +- `kms:Sign` +- `kms:DescribeKey` +- `kms:GetPublicKey` +{/* COPIED_END */} -These commands should result in an output similar to : +A mock AWS KMS configuration is available in [apps/app/src/pack/examples/sv-helm/kms-participant-aws-values.yaml](https://github.com/canton-network/splice/blob/main/apps/app/src/pack/examples/sv-helm/kms-participant-aws-values.yaml). -```json -{ - "public": "A9tWyYq/HIJ3B73ym1eIUV8yqnDBligGJUE8463CBUM=", - "private": "FDG16PaSh9hGLu2fXzEHmTECMjSyQuZnEg+w5HKCEtg=" -} -``` +### Migrating from software keys to KMS -Save this output to a file, e.g., `cometbft-governance-keys.json`. +{/* COPIED_START source="splice:docs/src/common/kms_migration_context.rst" */} +It is not supported to migrate an existing participant from "non-KMS-based" to "KMS-based" operation, or to migrate from one KMS provider to another. The main reason 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. Some KMS providers do not support importing existing keys at all and can only manage keys generated by the KMS itself. +{/* COPIED_END */} -##### Configuring SV app to use the externally generated CometBFT governance key +For SV nodes, the recommended approach to migrate to KMS is: -You inject the externally generated CometBFT governance key into the SV app via storing it in a k8s secret named `splice-app-sv-cometbft-governance-key`. +1. Set up a fresh SV from scratch with the desired KMS configuration. Synchronize with the other SV operators to onboard it with weight 0. +2. Synchronize with the other SV operators to move your SV weight to the new SV, setting the weight of the older SV to 0. +3. Transfer all relevant assets from the older SV to a validator or the new KMS-enabled SV. +4. Synchronize with the other SV operators to offboard the older SV. +5. Retire the older SV. -Assuming that your SV deployment resides in the `sv` namespace, use the following command to create the secret from the JSON file generated above: : +### CometBFT governance key with KMS - kubectl create secret --namespace sv generic splice-app-sv-cometbft-governance-key \ - --from-literal=publicKey="$(jq -r .public cometbft-governance-keys.json)" \ - --from-literal=privateKey="$(jq -r .private cometbft-governance-keys.json)" +When using an external KMS for participant keys, you must also manage the CometBFT governance key externally. The default method of managing this key through the participant is not supported with KMS-enabled participants. -To instruct the SV app to use the externally managed CometBFT governance key instead of generating a fresh one itself, set the `cometBFT.externalGovernanceKey` value in the `splice-sv-node` Helm chart to `true`. (You can comment out the respective line in `splice-node/examples/sv-helm/sv-values.yaml`.) +Generate a CometBFT governance key: -#### Configuring participant to use an external KMS + -Beyond the changes to the SV app deployment described above, the setup of an SV participant to use an external KMS is identical to the setup of a validator participant with KMS. It involves configuration changes to the `splice-participant` Helm chart that depend on the KMS provider you choose. +Save the output to a file (e.g., `cometbft-governance-keys.json`) and create a Kubernetes secret: -Also recall that you need to deploy a **fresh** participant in order for KMS to be used correctly, which implies that you will need to set up the remaining SV components afresh as well (see above). + -##### Google Cloud KMS +Then set `cometBFT.externalGovernanceKey` to `true` in the `splice-sv-node` Helm chart. -##### Amazon Web Services KMS +## General security recommendations +- Back up node identities to a secure location such as a secret manager. Identity backups contain private keys for your participant, sequencer, and mediator. +- Rotate credentials and tokens regularly. +- Restrict network access to your SV node's admin endpoints. +- Monitor participant logs for `ACS_COMMITMENT_MISMATCH` warnings, which may indicate integrity issues. {/* COPIED_END */}