创建和管理单租户 Cloud HSM 实例

本指南介绍如何使用 Google Cloud CLI 创建、预配和管理单租户 Cloud HSM 实例。创建并预配实例后，您可以使用 Google Cloud 控制台、Cloud Key Management Service API、gcloud CLI 和客户端库在实例中创建和使用密钥。

创建和管理实例需要进行多数身份验证。创建实例时，您需要定义运行实例操作所需的法定人数成员审批数量。法定人数成员必须始终拥有至少此数量的控制密钥，才能维持对实例的管理控制权。

准备工作

  1. 在创建和维护实例时，请查看并应用单租户 Cloud HSM 最佳实践。
  2. 确定初始法定人数成员数量。 如果获得现有法定人数成员的批准，您日后可以添加其他法定人数成员。法定人数成员的最低数量为 3。
  3. 决定需要多少法定人数成员来批准提案。实例创建后，您无法更改此数量。 您的法定人数成员必须始终有权访问相应数量的控制密钥，才能维护实例。最小法定人数为 2。所需的法定人数必须小于法定人数成员的数量。
  4. 确定如何确保实例及时刷新。 您必须监控实例的 disableDate，并在截止日期之前提出、批准并执行实例刷新操作，以免发生不必要的停机。

  5. 如需获得创建、管理和使用单租户 Cloud HSM 实例所需的权限，请让管理员向您授予项目或父资源的以下 IAM 角色：

    • 创建提案：Cloud KMS Single-Tenant HSM Proposer (cloudkms.hsmSingleTenantProposer)
    • 批准提案： Cloud KMS Single-Tenant HSM Quorum Member (cloudkms.hsmSingleTenantQuorumMember)
    • 执行提案： Cloud KMS single-tenant HSM Executor (cloudkms.hsmSingleTenantExecutor)
    • 创建密钥：Cloud KMS single-tenant HSM Key Creator (roles/cloudkms.hsmSingleTenantKeyCreator)

    如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

    您也可以通过自定义角色或其他预定义角色来获取所需的权限。

  6. 为每个法定人数成员生成一个 RSA-2048 密钥对，用于双重身份验证 (2FA)。建议您为控制密钥使用实体令牌。请遵循您组织的标准，在实体令牌上创建 RSA-2048 密钥对。

    为便于演示，本指南使用 OpenSSL 创建了三个由软件支持的 RSA-2048 密钥：

        openssl genrsa -out rsaprivate1.pem
    openssl genrsa -out rsaprivate2.pem
    openssl genrsa -out rsaprivate3.pem

    openssl rsa -in rsaprivate1.pem  -out rsapub1.pem --pubout
    openssl rsa -in rsaprivate2.pem  -out rsapub2.pem --pubout
    openssl rsa -in rsaprivate3.pem  -out rsapub3.pem --pubout

    妥善存储私钥；您需要使用私钥来批准提案。 请妥善保管公钥；您需要使用它们来创建单租户 Cloud HSM 实例。

  7. 选择支持单租户 Cloud HSM 的 Cloud KMS 位置。如需确定兼容的位置，请查看 Cloud KMS 位置页面上的位置列表。对于 HSM 支持过滤条件，请选择支持单租户 HSM。

创建和预配实例

如需创建和预配单租户 Cloud HSM 实例，您可以使用 gcloud CLI 创建实例资源，创建用于注册身份验证密钥的提案，然后批准并执行该提案。

创建实例

此步骤必须由具有 Cloud KMS Single-Tenant HSM Proposer 角色的实例管理员完成。

  1. 设置默认项目。

    gcloud config set project PROJECT_ID

    将 PROJECT_ID 替换为您的项目标识符。

  2. 创建单租户 Cloud HSM 实例。

    gcloud kms single-tenant-hsm create --location=LOCATION \
    --total-approver-count=QUORUM_MEMBER_COUNT \
    --single-tenant-hsm-instance-id=INSTANCE_ID

    替换以下内容：

    • LOCATION：要在其中创建实例的位置，例如 us-central1。
    • QUORUM_MEMBER_COUNT：法定人数成员总数。这也是您之前创建的控制密钥的数量。最小值为 3。以后可以添加其他密钥，但需要获得法定人数的批准。您必须至少比所需的法定人数多一名法定人数成员，才能在丢失控制密钥后进行恢复。
    • INSTANCE_ID：您要用于实例的标识符，例如 example-sthsm-instance。您可以省略 --single-tenant-hsm-instance-id 标志，让 Cloud HSM 分配 UUID。

  3. 检查实例的状态。

    gcloud kms single-tenant-hsm describe INSTANCE_ID \
    --location=LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。

    如果状态为 PENDING_TWO_FACTOR_AUTH_REGISTRATION，您可以预配实例。通常需要 5 到 30 分钟才能达到此状态。

预配实例

  1. 使用 register_2fa_keys 操作创建提案，以注册双重身份验证密钥。 此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。 与大多数提案不同，register_2fa_keys 提案需要来自所有法定人数成员的签名质询。

    gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
    --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
    --location LOCATION \
    --operation-type register_2fa_keys \
    --required-approver-count MEMBERS_REQUIRED_FOR_APPROVAL \
    --two-factor-public-key-pems=PUBLIC_KEY_LIST

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 您要用于此提案的唯一标识符，例如 set-up-2fa。
    • LOCATION：您创建实例的位置。
    • MEMBERS_REQUIRED_FOR_APPROVAL：必须批准提案的法定人数成员数量，然后才能执行相应操作。最小值为 2。实例预配完毕后，此值便无法更改。法定人数成员必须始终有权访问至少这么多的控制密钥，才能保留对实例的管理控制权。
    • PUBLIC_KEY_LIST：以英文逗号分隔的路径列表，其中包含所有控制键的公钥部分，例如 rsapub1.pem,rsapub2.pem,rsapub3.pem。此列表中的公钥数量必须与您之前使用的 QUORUM_MEMBER_COUNT 值一致。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 set-up-2fa。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 预配新的单租户 Cloud HSM 实例需要法定人数中所有成员的签名质询。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于每个密钥，使用 `basenc --base64url -d` 对质询进行解码，并使用相应的私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 提案获得批准后，使用 execute 命令完成 register_2fa_keys 操作。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

    gcloud kms single-tenant-hsm proposal execute PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    这是一项长时间运行的操作，用于配置用户和创建备份。20 到 30 分钟后，实例会变为 ACTIVE。

  7. 实例 ACTIVE 后，查看实例详情以查看 disableDate：

    gcloud kms single-tenant-hsm describe INSTANCE_ID \
    --location=LOCATION

    记下实例的 disableDate。您必须在此时间之前完成 refresh_sthi 操作，否则您的实例将被停用。

查看实例

拥有以下任一角色的用户可以查看单租户 Cloud HSM 实例及其状态的列表：

  • Cloud KMS Single-Tenant HSM Proposer
  • Cloud KMS Single-Tenant HSM Quorum Member
  • Cloud KMS Single-Tenant HSM Executor
  • Cloud KMS Viewer
  • Cloud KMS 管理员

请务必定期查看实例的状态。必须定期刷新实例，才能保持有效状态。

处于有效状态的实例可以使用。需要在单租户 Cloud HSM 实例中创建或导入密钥的开发者需要该实例的资源标识符。资源标识符采用以下格式：

projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME

如需查看组织中的实例并查找其资源标识符，请按以下步骤操作：

控制台

  1. 在 Google Cloud 控制台中，前往 KMS 基础架构页面。

    前往 KMS 基础架构

  2. 在单租户 HSM 实例卡片上，点击查看。单租户 HSM 实例页面会显示您有权查看的所有单租户 Cloud HSM 实例的列表。

  3. 如需查看实例的详细信息，请点击相应实例的名称。单租户 HSM 实例详情页面会显示所选实例的详细信息，包括实例的完整资源标识符以及为该实例创建的提案列表。

  4. 可选：如需查看或下载与法定人数成员当前的两步验证 (2FA) 密钥相关联的公钥，请点击获取公钥。您可以将公钥与您的私有双重身份验证密钥进行比较，以验证哪些控制密钥处于有效状态。

gcloud

使用 kms single-tenant-hsm list 方法查看现有实例的列表。

gcloud kms single-tenant-hsm list --location=LOCATION

将 LOCATION 替换为要查看单租户 Cloud HSM 实例的位置。

使用 kms single-tenant-hsm describe 方法查看现有实例的详细信息。

gcloud kms single-tenant-hsm describe INSTANCE_ID \
    --location=LOCATION

替换以下内容：

  • INSTANCE_ID：您要查看详细信息的实例。
  • LOCATION：您要查看单租户 Cloud HSM 实例的位置。

使用实例

当实例处于 ACTIVE 状态时，您可以创建和使用密钥。您可以在与有效的 Single-tenant Cloud HSM 实例位于同一位置的任何密钥环上创建 Single-tenant Cloud HSM 密钥。

除了 Cloud KMS Admin 角色之外，创建单租户 Cloud HSM 密钥还需要 Cloud KMS single-tenant HSM Key Creator 角色。

创建单租户 Cloud HSM 密钥后，使用这些密钥无需特殊权限。

创建密钥

创建单租户 Cloud HSM 密钥时，您必须指定要在其中创建该密钥的单租户 Cloud HSM 实例。否则，该过程与创建任何其他密钥类似。如需查看详细说明，请参阅创建密钥。

导入密钥

将密钥材料导入到 single-tenant Cloud HSM 密钥时，您必须指定要存储该密钥材料的 single-tenant Cloud HSM 实例。 否则，该流程与导入任何其他密钥类似。如需详细说明，请参阅将密钥版本导入 Cloud Key Management Service。

使用密钥

创建密钥后，使用单租户 Cloud HSM 密钥与使用任何其他 Cloud HSM 密钥完全相同。您无需指定单租户 Cloud HSM 实例即可使用该密钥。

密钥可移植性

借助密钥可移植性，您可以在单租户 Cloud HSM 实例上管理自己的封装密钥。借助此功能，您可以使用自定义封装密钥封装其他密钥（称为可封装密钥），从而导入和导出这些密钥。密钥可移植性有助于实现不同云提供商之间或不同 Google Cloud区域之间的密钥互操作性。

所有密钥可移植性操作都要求密钥在单租户 Cloud HSM 实例上创建和存储。RFC 5649 是唯一支持的密钥封装算法。

如需使用密钥可移植性，您必须完成以下步骤：

  1. 设置可信的封装密钥。
  2. 创建或导入可封装的密钥。
  3. 使用可信的封装密钥导入预封装的密钥材料或导出可封装的密钥。

设置受信任的封装密钥

可信封装密钥是一种 AES 密钥，用于根据 RFC 5649 中的定义封装和解封其他密钥，以便导出或导入。如需在单租户 Cloud HSM 实例上设置可信封装密钥，您必须将该密钥作为仅限导入的密钥导入，并指定 AES_WRAPPING 用途，然后将其提升为可信密钥。

密钥升级需要获得一名 Quorum 成员的批准。

  1. 创建用途为 AES_WRAPPING 的仅限导入的密钥资源：

        gcloud kms keys create KEY_NAME \
        --location LOCATION \
        --keyring KEY_RING \
        --purpose AES_WRAPPING \
        --protection-level HSM_SINGLE_TENANT \
        --skip-initial-version-creation \
        --import-only \
        --crypto-key-backend "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

    替换以下内容：

    • KEY_NAME：可信封装密钥的标识符。
    • LOCATION：密钥环和单租户 Cloud HSM 实例所在的区域。
    • KEY_RING：您要在其中创建密钥的密钥环。
    • INSTANCE_PROJECT：包含单租户 Cloud HSM 实例的项目的标识符。
    • INSTANCE_NAME：单租户 Cloud HSM 实例的标识符。

  2. 创建用于导入密钥材料的导入作业：

        gcloud kms import-jobs create IMPORT_JOB_NAME \
        --location LOCATION \
        --keyring KEY_RING \
        --import-method IMPORT_METHOD \
        --protection-level HSM_SINGLE_TENANT

    替换以下内容：

    • IMPORT_JOB_NAME：导入作业的标识符。
    • IMPORT_METHOD：封装密钥材料的导入方法，例如 rsa-oaep-4096-sha256-aes-256。

  3. 导入原始 AES 密钥材料。

        gcloud kms keys versions import \
        --import-job IMPORT_JOB_NAME \
        --location LOCATION \
        --keyring KEY_RING \
        --key KEY_NAME \
        --algorithm aes-256-kwp \
        --target-key-file TRUSTED_KEY_PATH

    将 TRUSTED_KEY_PATH 替换为包含原始可信封装密钥字节的文件路径。

  4. 创建提案以将封装密钥提升为受信任。操作类型为 upgrade_key_trust。升迁操作必须由发起该操作的同一法定人数成员签名并获得其批准。

        gcloud kms single-tenant-hsm proposal create INSTANCE_NAME \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type upgrade_key_trust \
        --keyring KEY_RING \
        --key KEY_NAME \
        --two-factor-login-key PATH_TO_PUBLIC_KEY

    替换以下内容：

    • PROPOSAL_ID：相应提案的唯一标识符。
    • PATH_TO_PUBLIC_KEY：发起并签署提案的法定人数成员的公钥的路径。

  5. 查看提案的状态，并等待其变为 PENDING：

        gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
        --single_tenant_hsm_instance INSTANCE_NAME \
        --location LOCATION

    当状态为 PENDING 时，您可以对质询进行签名。

  6. 从提案中获取挑战。

        gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
        --single_tenant_hsm_instance INSTANCE_NAME \
        --location LOCATION \
        --format="json[](requiredActionQuorumParameters.requiredChallenges)"

    此命令会返回一个包含质询的 JSON 格式的数组。

  7. 使用 basenc --base64url -d 解码质询，然后对其进行签名。验证必须由与创建提案时提供的公钥相匹配的私钥签名。

        echo CHALLENGE | basenc --base64url -d > decoded-challenge.txt
    openssl dgst -sign PRIVATE_KEY_PATH -out signed-challenge.txt decoded-challenge.txt

    替换以下内容：

    • CHALLENGE：上一步输出中的质询内容。
    • PRIVATE_KEY_PATH：创建提案的仲裁成员的私钥的路径。

  8. 上传已签名的挑战，以批准提案。此步骤需要 Cloud KMS Single-Tenant HSM Quorum Member 角色。

        gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
        --location LOCATION \
        --single_tenant_hsm_instance INSTANCE_NAME \
        --required-challenge-replies="[('signed-challenge.txt','PUBLIC_KEY_PATH')]"

    将 PUBLIC_KEY_PATH 替换为创建提案的仲裁成员的公钥路径。

    上传已签名的质询后，提案状态会更新为 APPROVED。

  9. 提案获得批准后，执行该提案以完成促销：

        gcloud kms single-tenant-hsm proposal execute PROPOSAL_ID \
        --single_tenant_hsm_instance INSTANCE_NAME \
        --location LOCATION

    提案执行完毕后，该密钥会升级为可信的封装密钥，可用于在单租户 Cloud HSM 实例上导入或导出其他密钥。

管理可封装的密钥

可封装的密钥是一种加密密钥，指定用于使用可信的封装密钥进行安全导入或导出。创建密钥资源时，您必须将密钥配置为可封装。此设置以后不可修改。

创建新的可封装密钥

如需创建新的可封装密钥，请使用 --hsm-trusted-wrapping 标志：

gcloud kms keys create WRAPPABLE_KEY_NAME \
    --location LOCATION \
    --keyring KEY_RING \
    --purpose PURPOSE \
    --protection-level HSM_SINGLE_TENANT \
    --hsm-trusted-wrapping \
    --crypto-key-backend "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

替换以下内容：

  • WRAPPABLE_KEY_NAME：新可封装密钥的名称。
  • PURPOSE：密钥的用途，例如 raw-encryption。导入的密钥不能使用 ENCRYPT_DECRYPT 密钥用途。

导入可封装的密钥

您可以使用导入作业来导入现有密钥材料，以便日后能够导出这些密钥材料。为此，您必须在创建密钥和导入密钥版本时都添加 hsm-trusted-wrapping 标志。

  1. 使用 --hsm-trusted-wrapping 标志创建密钥资源：

    gcloud kms keys create WRAPPABLE_KEY_NAME \
    --location LOCATION \
    --keyring KEY_RING \
    --purpose PURPOSE \
    --protection-level HSM_SINGLE_TENANT \
    --hsm-trusted-wrapping \
    --skip-initial-version-creation \
    --crypto-key-backend "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"

  2. 创建导入作业：

    gcloud kms import-jobs create IMPORT_JOB_NAME \
    --location LOCATION \
    --keyring KEY_RING \
    --import-method IMPORT_METHOD \
    --protection-level HSM_SINGLE_TENANT

  3. 使用 --hsm-trusted-wrapping 标志导入密钥版本：

    gcloud kms keys versions import \
    --import-job IMPORT_JOB_NAME \
    --location LOCATION \
    --keyring KEY_RING \
    --key WRAPPABLE_KEY_NAME \
    --algorithm ALGORITHM \
    --target-key-file UNWRAPPED_KEY_TO_IMPORT \
    --hsm-trusted-wrapping

    替换以下内容：

    • KEY_ALGORITHM：您要导入的密钥的算法。
    • UNWRAPPED_KEY_TO_IMPORT：原始（未封装）密钥资料的路径。

使用可信的密钥进行导入和导出

设置可信的封装密钥后，您可以使用该密钥将预封装的密钥材料导入到可封装的密钥中，或导出可封装的密钥。

导入预先使用可信密钥封装的密钥版本

您可以使用可信封装密钥的本地副本导入封装的密钥材料，而无需使用导入作业。

  1. 确保您已使用 --hsm-trusted-wrapping 标志和 --import-only 选项创建了可封装的目标密钥资源。请参阅创建新的可封装密钥部分。

  2. 导入预封装的密钥版本：

    gcloud kms keys versions import-trusted-key-wrapped \
    --location LOCATION \
    --target-keyring KEY_RING \
    --target-key TARGET_KEY_NAME \
    --trusted-keyring TRUSTED_KEY_RING \
    --trusted-key TRUSTED_KEY_NAME \
    --target-algorithm ALGORITHM \
    --wrapped-key-file PATH_TO_WRAPPED_KEY

    替换以下内容：

    • TARGET_KEY_NAME：要将密钥材料导入到的可封装密钥资源的名称。
    • TRUSTED_KEY_RING：可信封装密钥的密钥环。
    • TRUSTED_KEY_NAME：提升的受信任封装密钥的名称。
    • ALGORITHM：目标密钥的算法。支持的值是除 GOOGLE_SYMMETRIC_ENCRYPTION 之外的所有 Cloud Key Management Service 算法。
    • PATH_TO_WRAPPED_KEY：包含使用可信封装密钥封装的密钥资料的文件的路径。

通过使用可信密钥封装可封装的密钥来导出该密钥

您可以使用可信的封装密钥封装现有的可封装密钥，并将生成的封装密钥材料保存到文件中。

gcloud kms keys versions export-trusted-key-wrapped \
    --location LOCATION \
    --trusted-keyring TRUSTED_KEY_RING \
    --trusted-key TRUSTED_KEY_NAME \
    --target-keyring TARGET_KEY_RING \
    --target-key TARGET_KEY_NAME \
    --wrapped-key-file PATH_TO_OUTPUT_WRAPPED_KEY

替换以下内容：

  • TRUSTED_KEY_RING：可信封装密钥的密钥环。
  • TRUSTED_KEY_NAME：提升的受信任封装密钥的名称。
  • TARGET_KEY_RING：要导出的可封装密钥的密钥环。
  • TARGET_KEY_NAME：要导出的可封装密钥的名称。
  • PATH_TO_OUTPUT_WRAPPED_KEY：将保存封装密钥材料的路径。

维护实例

预配实例后，您有责任维护该实例。您可以通过以下方式维护实例：为维护操作创建提案、获得法定人数的批准，然后执行已获批准的操作。一次只能有一个有效提案；如果您选择不继续执行某个提案，则必须删除有效提案或等到提案过期，才能提出其他操作提案。

您必须在 disableDate之前刷新实例。如果您需要检查实例的 disableDate，可以查看实例详情。

查看实例提案

如需查看实例的提案，请按以下步骤操作：

控制台

  1. 在 Google Cloud 控制台中，前往 KMS 基础架构页面。

    前往 KMS 基础架构

  2. 在单租户 HSM 实例卡片上，点击查看。单租户 HSM 实例页面会显示您有权查看的所有单租户 Cloud HSM 实例的列表。

  3. 找到要查看提案的实例，然后点击该实例的名称。单租户 HSM 实例详情页面会显示该实例的详细信息，包括为该实例创建的提案列表。

  4. 可选：如需过滤建议列表，请点击 过滤条件栏，然后输入过滤条件。例如，您可以过滤列表，以仅显示待审批的提案或仅显示已成功完成的提案。

gcloud

  • 使用 kms single-tenant-hsm proposal list 方法查看现有提案的列表。

    gcloud kms single-tenant-hsm proposal list INSTANCE_ID \
    --location=LOCATION

    替换以下内容：

    • INSTANCE_ID：您要查看提案的单租户 Cloud HSM 实例的标识符。
    • LOCATION：您要查看单租户 Cloud HSM 实例的位置。

刷新实例

您可以刷新实例，使其保持最新状态，并有助于防止意外停机。此操作需要法定人数身份验证。提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

刷新实例时，disableDate 会设置为自刷新时起 730 天。

  1. 创建提案以使用 refresh_sthi 操作类型刷新实例。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type refresh_sthi

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 refresh_instance。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 refresh_instance。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，实例仍处于 `ACTIVE` 状态，并且 disableDate 会设置为自刷新时起 730 天。

添加仲裁成员

您可以向实例添加仲裁成员。此操作需要法定人数身份验证。提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

  1. 为新的法定人数成员生成新的 RSA-2048 密钥对。遵循组织关于在实体令牌上创建 RSA-2048 密钥对的标准。

    请妥善存储私钥；您需要使用它来批准提案。 请妥善保管公钥；您需要使用它将新的法定人数成员添加到单租户 Cloud HSM 实例。

  2. 使用 add_quorum_member 操作创建提案，以向实例添加法定人数成员。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type add_quorum_member \
        --two_factor_public_key_pem PATH_TO_PUBLIC_KEY

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 add_quorum_member。
    • PATH_TO_PUBLIC_KEY：新公钥的路径，例如 rsapub4.pem。

  3. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 add_quorum_member。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  4. 从提案中获取挑战。 添加新的法定人数成员需要来自法定人数的现有成员的签名质询，以及来自新成员的使用新密钥的签名质询。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](requiredActionQuorumParameters.requiredChallenges,requiredActionQuorumParameters.quorumChallenges)"

    此命令会返回一个 JSON 格式的挑战数组。requiredActionQuorumParameters.requiredChallenges 字段包含您正在注册的新密钥的质询。requiredActionQuorumParameters.quorumChallenges 字段包含针对现有密钥的法定人数的质询。您必须对 requiredActionQuorumParameters 对象中的所有质询进行签名。

  5. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  6. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST" \
      --required-challenge-replies="SIGNED_REQUIRED_CHALLENGE_LIST"

    替换以下内容：

    • SIGNED_QUORUM_CHALLENGE_LIST：一个 JSON 格式的数组，其中包含使用已注册的私钥签名的质询，每个列表项都是一个元组，其中包含签名质询的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名质询。
    • SIGNED_REQUIRED_CHALLENGE_LIST：一个 JSON 格式的数组，其中包含使用新私钥签名的质询，该数组的唯一列表项是一个元组，其中包含签名质询的路径和相应公钥的路径，例如 [('signed-challenge-newkey.txt','rsapub-newkey.pem')]。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  7. 执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，新的法定人数成员可以参与质询，以批准提案。您添加的公钥现在已包含在实例详细信息中的公钥列表中。

移除法定人数成员

如果法定人数成员数量超过所需的法定人数规模，您可以从实例中移除法定人数成员。此操作需要法定人数身份验证。 提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

  1. 使用 remove_quorum_member 操作创建提案，以从实例中移除法定人数成员。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type remove_quorum_member \
        --two_factor_public_key_pem PATH_TO_PUBLIC_KEY

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 remove_quorum_member。
    • PATH_TO_PUBLIC_KEY：要从实例中移除的公钥的路径，例如 rsapub3.pem。操作完成后，相应的私钥将无法用于批准提案。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 remove_quorum_member。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，被移除的法定人数成员将无法再参与挑战来批准提案。您移除的公钥不再包含在实例详情中的公钥列表中。

停用实例

您可以停用实例，以暂时阻止对该实例的所有密钥的访问。此操作需要法定人数身份验证。提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

实例处于停用状态时，存储在该实例中的密钥仍会显示为 ACTIVE，但无法使用。尝试使用已停用的实例中的密钥执行加密操作会导致错误。

  1. 使用 disable_sthi 操作类型创建停用实例的提案。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type disable_sthi

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 disable_instance。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 disable_instance。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，实例将保持 DISABLED 状态，并且在重新启用之前无法使用。

启用实例

您可以重新启用 DISABLED 实例，以恢复对该实例及其密钥的访问权限。 此操作需要法定人数身份验证。提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

  1. 创建提案以使用 enable_sthi 操作类型启用实例。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type enable_sthi

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 enable_instance。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 enable_instance。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，实例会恢复为“ACTIVE”状态，并且 disableDate 会设置为自刷新时起 730 天。

删除实例

您可以删除实例，以永久销毁该实例及其密钥。此操作需要法定人数身份验证。提案获得批准后，该操作大约需要 15 到 30 分钟才能完成。

删除实例后，存储在该实例中的密钥仍会显示为 ACTIVE，但无法使用。尝试使用已删除实例中的密钥执行加密操作会导致错误。

  1. 使用 delete_sthi 操作类型创建删除实例的提案。此步骤需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal create INSTANCE_ID \
        --location LOCATION \
        --single-tenant-hsm-instance-proposal-id PROPOSAL_ID \
        --operation-type delete_sthi

    替换以下内容：

    • INSTANCE_ID：您要删除的实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：您要用于相应提案的唯一标识符，例如 delete_instance。

  2. 查看提案的状态，并等待其状态变为 PENDING。

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • PROPOSAL_ID 提案的标识符，例如 delete_instance。
    • LOCATION：您创建实例的位置。

    当状态为 PENDING 时，您可以签署质询。

  3. 从提案中获取挑战。 

      gcloud kms single-tenant-hsm proposal describe PROPOSAL_ID \
      --single_tenant_hsm_instance INSTANCE_ID \
      --location LOCATION \
      --format="json[](quorumParameters.challenges)"

    此命令会返回一个 JSON 格式的挑战数组。

  4. 对于上一步中返回的每个质询，使用 basenc --base64url -d 对质询进行解码，并使用私钥对其进行签名。 

      echo CHALLENGE_N | basenc --base64url -d > decoded-challenge-N.txt
  openssl dgst -sign PRIVATE_KEY_N -out signed-challenge-N.txt decoded-challenge-N.txt

    替换以下内容：

    • N：挑战的编号，例如，1 表示第一个挑战，2 表示第二个挑战，依此类推。
    • CHALLENGE_N：上一步输出中挑战编号 N 的内容。
    • PRIVATE_KEY_N：私钥编号 N 的路径，例如，对于第一个挑战，该值为 rsaprivate1.pem。

  5. 通过上传已签名的质询来批准提案。您可以通过一个命令或多个命令上传这些文件。此步骤需要 Cloud KMS single-tenant HSM Quorum Member 角色。

      gcloud kms single-tenant-hsm proposal approve PROPOSAL_ID \
      --location LOCATION \
      --single_tenant_hsm_instance INSTANCE_ID \
      --quorum-challenge-replies="SIGNED_QUORUM_CHALLENGE_LIST"

    将 SIGNED_QUORUM_CHALLENGE_LIST 替换为 JSON 格式的挑战数组，其中每个列表项都是一个元组，包含签名挑战的路径和相应公钥的路径 - 例如，[('signed-challenge-1.txt','rsapub1.pem'), ('signed-challenge-2.txt','rsapub2.pem')] 可在一个命令中提交前两个签名挑战。

    上传所需数量的签名质询后，提案状态会更新为 APPROVED。

  6. 确保您要继续删除实例并对使用在此实例中创建的密钥加密的所有数据进行密钥销毁，然后执行提案。 此步骤需要 Cloud KMS single-tenant HSM Executor 角色，并且必须在提案创建后的 24 小时内完成。

    警告：以下命令不可逆转。可能会发生数据永久丢失。Google 无法帮助您恢复已删除实例中的密钥。 
        gcloud kms single-tenant-hsm proposal execute  PROPOSAL_ID \
    --single_tenant_hsm_instance INSTANCE_ID --location LOCATION

    操作完成后，实例即会被删除。

删除提案

如果您决定不批准或执行提案，可以在提案过期之前将其删除。删除待批提案后，您将无法批准该提案，但可以创建新提案。删除已获批的提案会阻止您执行相应操作。

  • 使用 proposal delete 命令删除提案。这需要 Cloud KMS Single-Tenant HSM Proposer 角色。

        gcloud kms single-tenant-hsm proposal delete PROPOSAL_ID \
        --location LOCATION \
        --single_tenant_hsm_instance INSTANCE_ID

    替换以下内容：

    • INSTANCE_ID：实例的标识符。
    • LOCATION：您创建实例的位置。
    • PROPOSAL_ID：要删除的提案的唯一标识符，例如 proposal_to_delete。

后续步骤