与其他 Canton 功能一样，GCP KMS 配置是在 Canton 节点的配置文件中启用的。 GCP 的 KMS 的配置方式如下：

canton.participants.participant2.crypto.kms {
    type = gcp
    location-id = us-east1
    project-id = gcp-kms-testing
    key-ring-id = canton-test-keys-2023
    audit-logging = false # optional, default is false
}

• type 指定要使用的 KMS。
• location-id指定GCP KMS绑定到哪个区域。
• project-id 指定我们要绑定到哪个项目。
• key-ring-id 指定要使用的密钥环。为整个密钥环启用多区域密钥。因此，KMS 操作员负责根据系统的需要正确设置密钥环。
• audit-logging 标志，用于记录对 GCP KMS 的每次调用

配置 GCP 凭据和权限

对于 GCP，Canton 使用 GCP 服务帐户。例如，在为服务帐户设置本地应用程序默认凭据 (ADC) 文件后，可以使用标准环境变量GOOGLE_APPLICATION_CREDENTIALS。对于支持的环境，例如GKE、Canton 可以从元数据服务应用程序默认凭据中获取凭据。

GCP 凭证的保护和轮换是节点运营商的责任。

GCP KMS 所需的授权操作（例如 IAM 权限）取决于在 Canton 中选择的操作模式。

信封加密的权限

使用信封加密时需要以下 IAM 权限：

• cloudkms.cryptoKeyVersions.create
• cloudkms.cryptoKeyVersions.useToEncrypt
• cloudkms.cryptoKeyVersions.useToDecrypt
• cloudkms.cryptoKeys.get

外部 KMS 的权限

使用 外部 KMS 时需要以下 IAM 权限，其中密钥完全由 GCP KMS 管理和直接使用：

• cloudkms.cryptoKeyVersions.create
• cloudkms.cryptoKeyVersions.useToDecrypt
• cloudkms.cryptoKeyVersions.useToSign
• cloudkms.cryptoKeyVersions.get
• cloudkms.cryptoKeyVersions.viewPublicKey

可审计性

GCP 提供了监控 KMS 密钥的工具。有关GCP日志记录信息，您可以参考GCP官方文档。 Canton 记录因使用 KMS 密钥而导致的错误。

日志记录为了进一步进行审计，Canton 可以配置为记录对 GCP KMS 的每次调用。要启用此功能，请将 KMS 配置的 audit-logging 字段设置为 true。默认情况下，当使用基于文件的日志记录配置时，此类日志将写入主 Canton 日志文件中。要将它们写入专用日志文件，请将 KMS_LOG_FILE_NAME 环境变量或 --kms-log-file-name CLI 标志设置为文件的路径。可以使用环境变量或 CLI 标志来配置这些参数和其他参数：

KMS 日志记录配置

GCP KMS 审核日志示例：

2023-09-12 15:44:54,426 [env-execution-context-27] INFO  c.d.c.c.k.g.a.GcpRequestResponseLogger:participant=participant1 tid:40d47592f1bd50f37e6804fbdff404dd - Sending request [67d92ffb-438b-4dd5-8175-7a54ced7ac3a]: DecryptRequest(CiphertextBlob=** Ciphertext placeholder **, KeyId=canton-kms-test-key, EncryptionAlgorithm=RSAES_OAEP_SHA_256).
2023-09-12 15:44:54,538 [env-execution-context-32] INFO  c.d.c.c.k.g.a.GcpRequestResponseLogger:participant=participant1 tid:40d47592f1bd50f37e6804fbdff404dd - Received response DecryptResponse(Plaintext=** Redacted plaintext placeholder **, KeyId=canton-kms-test-key, EncryptionAlgorithm=RSAES_OAEP_SHA_256). Original request [67d92ffb-438b-4dd5-8175-7a54ced7ac3a]
2023-09-12 15:44:54,441 [env-execution-context-138] INFO  c.d.c.c.k.g.a.GcpRequestResponseLogger:participant=participant1 tid:40d47592f1bd50f37e6804fbdff404dd - Sending request [b3aa6202-1734-4751-8ae0-55b7d15c2abb]: SignRequest(KeyId=canton-kms-test-key, Message=** Sign message text placeholder **, MessageType=RAW, SigningAlgorithm=ECDSA_SHA_256).
2023-09-12 15:44:54,554 [env-execution-context-145] INFO  c.d.c.c.k.g.a.GcpRequestResponseLogger:participant=participant1 tid:40d47592f1bd50f37e6804fbdff404dd - Received response SignResponse(KeyId=canton-kms-test-key, Signature=** Signature message text placeholder **, SigningAlgorithm=ECDSA_SHA_256). Original request [b3aa6202-1734-4751-8ae0-55b7d15c2abb]

请注意，敏感数据在记录之前已被删除。一般日志格式如下：tid:<canton_trace_id> - Sending request [<canton_kms_request_id>]: <request details>``tid:<canton_trace_id> - Received response <response details>. Original request [<canton_kms_request_id>]

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/configuration/kms_driver_config.rst” hash=“2ea5fd56” */}

配置基于驱动程序的 KMS

Canton 允许通过 KMS 驱动程序与各种 KMS 和 HSM 解决方案集成。这种方法使您能够通过构建自己的集成层将 Canton 连接到外部密钥管理器。

配置 Canton 以使用 KMS 驱动程序运行的方式与其他 KMS 提供商类似，通过指定：

type = driver
name = <name_of_driver>

例如，对于名为 `participant1` 的参与者：

canton.participants.participant1.crypto.provider = kms
canton.participants.participant1.crypto.kms {
  type = driver
  name = "aws-kms"
    config = {
      region = us-east-1
      multi-region-key = false
      audit-logging = true
    }
}

• type指定使用哪个KMS；在这种情况下，是一名司机。
• name 是为驱动程序配置的唯一标识名称。
• KMS驱动程序特定的配置可以通过config字段传入。

除了此配置之外，您还必须提供一个.jar文件，该文件实现所需的API并充当Canton和目标KMS之间的桥梁。

在类路径上使用驱动程序 .jar 运行 Canton：

java -cp driver.jar:canton.jar com.digitalasset.canton.CantonEnterpriseApp -c canton.conf # further canton arguments

有关在 Canton 开发和部署您自己的 KMS 驱动程序的指南，请参阅 Canton KMS 驱动程序开发人员指南。本指南包括构建自定义驱动程序的说明、必要 API 的详细信息以及配置 Canton 以使用该驱动程序的步骤。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/migration/kms_migration.rst” hash=“024d318f” */}

迁移到 KMS

本节概述从正在运行的非 KMS 参与者迁移到启用 KMS 的参与者所需的步骤，以及使用 KMS 的节点与不使用 KMS 的节点之间的互操作性。迁移过程取决于所选的操作模式：

1. 使用密钥管理服务 (KMS) 迁移到加密私钥存储

   此过程需要将节点配置为使用对称包密钥。 此配置步骤后，迁移将自动完成。

2. 使用密钥管理服务 (KMS) 迁移到外部密钥存储

   此方法涉及创建一个新的启用 KMS 的参与者并从参与者节点传输所有数据（例如合同）。 该过程必须由每个操作员使用提供的脚本和函数手动执行。

   它提供了一个干净且独立的过渡，但需要更改命名空间并与所有受影响的参与者节点运营商进行协调。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/migration/encrypted_key_storage_migration.rst” hash=“81793b9d” */}# 迁移到使用 KMS 加密的私钥存储

要使用带有外部托管对称包密钥的 KMS 从非加密密钥存储迁移到加密私钥存储，您只需将参与者（或任何其他节点）配置为在此模式下运行，如此处所述。该过程是无缝的 - 重新启动参与者后，将采用新配置，并且 Canton 的私钥会自动加密和存储。

恢复加密的私钥存储

加密的私钥存储可以恢复为未加密的存储。为了防止意外恢复，只需删除private-key-store配置并不会恢复到未加密的存储。相反，必须添加以下配置，并重新启动节点：

canton.participants.participant1.crypto.private-key-store.encryption.reverted = true # default is false

通过删除reverted字段并重新配置KMS，可以再次启用加密私钥存储。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/migration/external_key_storage_migration.rst” hash=“00f0a330” */}

使用 KMS 迁移到外部密钥存储

创建具有连接到 KMS 兼容同步器的正确配置的新参与者（例如，使用 KMS 支持的加密和签名密钥运行 KMS 或 JCE）后，您必须将所有Party、活动合同和 DAR 从旧参与者转移到新参与者。两个参与者的身份不同，因此您需要重写合约以引用新的参与者 ID。通过此方法，您可以轻松地将运行较旧协议版本的旧参与者迁移到启用了 KMS 且可以运行较新协议版本的新参与者。此外，您不需要安全保存旧节点的根命名空间密钥，因为您的参与者命名空间发生了变化。然而，要使其发挥作用，单个运营商必须控制所有合同，或者所有参与者运营商必须同意此重写。

首先，您必须在新参与者中重新创建旧参与者的所有Party，保持相同的显示名称，但由于新的命名空间键而导致不同的 id：

其次，您应该将 DAR 迁移到新参与者：

最后，您需要将所有Party的有效合约从旧参与者转移到新参与者，并重写这些合约中提到的Party ID 以匹配新的Party ID。然后您可以连接到新的同步器：

结果是在不同的命名空间中出现一个新的参与者节点，其密钥由连接到同步器的 KMS 存储和管理，同步器可以使用适当的加密方案进行通信。

如果您想要将参与者迁移回使用 non-KMS 提供商，您需要遵循相同的步骤。

与其他节点的互操作性

默认情况下，Canton 节点使用jce 加密提供程序，该提供程序与使用外部 KMS 提供程序存储 Canton 私钥的其他节点兼容。如果您更改默认的jce提供商并使用不同的加密方案，则必须确保它支持与KMS提供商相同的算法和密钥方案，以便与其他启用KMS的Canton节点进行互操作。

有关 KMS 提供程序支持的加密方案和默认使用的加密方案的说明，请参阅支持的加密方案 参考。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/key_rotation/kms_key_rotation.rst” hash=“8b47170c” */}

使用 KMS 轮换密钥

Canton 支持在使用信封加密时轮换包密钥，以及轮换外部存储在 KMS 中的 Canton 密钥。

为了顺利进行灾难恢复，密钥轮换必须与备份交错进行，如备份和恢复中所述。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/key_rotation/rotate_wrapper_key.rst” hash=“dcb0594c” */}

旋转信封包键

一些 KMS 提供商（例如 AWS）提供对称 KMS 密钥的自动轮换（通常每年一次）。 Canton 通过允许节点管理员手动轮换 KMS 包器密钥来扩展此功能。

密钥轮换不会删除先前的密钥。虽然旧密钥变得不活动，但它仍然保留。要永久删除以前的密钥，请参阅删除 Canton 节点密钥。

使用自动生成的密钥进行旋转

使用以下命令：```scala theme={“theme”:{“light”:“github-light”,“dark”:“github-dark”}} participant1.keys.secret.rotate_wrapper_key()

Canton 将使用配置的 KMS 自动创建新的包密钥。

## 使用手动生成的密钥进行轮换

首先，您必须在 KMS 中创建一个满足此处所述要求的新包密钥。之后，您可以使用以下命令轮换到该键：

```scala theme={"theme":{"light":"github-light","dark":"github-dark"}}
participant1.keys.secret.rotate_wrapper_key(newWrapperKeyId)

• `newWrapperKeyId`：要旋转到的包器密钥的标识符。

{/* COPIED_START source=“docs-website:docs/replicated/canton/3.4/participant/howtos/secure/kms/key_rotation/rotate_external_keys.rst” hash=“f1a0d457” */}

轮换外部 KMS 密钥

即使 Canton 密钥外部存储在 KMS 中，仍然可以手动轮换。为此，您可以使用标准旋转密钥命令，或者如果您已经有要旋转到的预生成的 KMS 密钥，请运行以下命令：

val newSigningKeyParticipant = participant1.keys.secret
  .rotate_kms_node_key(
    keyFingerprint,
    newKmsKeyId,
    "kms_key_rotated",
  )

• fingerprint - 我们想要旋转的密钥的指纹。
• newKmsKeyId - 新 KMS 密钥的 ID（例如资源名称）。
• name - 新密钥的可选名称。

当前的 KMS 服务不提供非对称密钥的自动轮换，因此节点运营商需要负责定期轮换这些密钥。

本文由 CC Privacy Club 根据 Canton Network 官方文档（CC-BY-4.0）整理翻译，仅供学习；实现细节以官方最新版本为准。