将密钥导入到 Cloud KMS 中

本主题介绍如何将加密密钥导入到 Cloud HSM 或 Cloud Key Management Service。

如需详细了解如何导入密钥(包括限制和局限),请参阅密钥导入

您可以在 5 至 10 分钟内完成本主题中的步骤,但不包括准备工作步骤。手动封装密钥会增加任务的复杂性。

准备工作

建议您创建一个新项目来测试此特性,以简化测试后的清理工作,并确保您有足够的 IAM 权限来导入密钥。

在导入密钥之前,您需要准备项目、本地系统和密钥本身。

准备项目

  1. 登录您的 Google 帐号。

    如果您还没有 Google 帐号,请注册一个新帐号

  2. 在 Cloud Console 的项目选择器页面上,选择或创建 Cloud 项目。

    转到项目选择器页面

  3. 确保您的 Google Cloud 项目已启用结算功能。 了解如何确认您的项目已启用结算功能

  4. 启用所需的 API。

    启用 API

  5. 安装并初始化 Cloud SDK
  6. 执行导入的用户需要以下 IAM 权限才能创建密钥环、密钥和导入作业。如果用户不是项目所有者,您可以为该用户分配以下两个预定义角色:

    • roles/editor
    • roles/cloudkms.importer

    如需详细了解 Cloud KMS 的可用 IAM 角色和权限,请参阅权限和角色

准备本地系统

选择以下以下选项之一以准备本地系统:对于大多数用户,推荐使用自动封装密钥功能。

  • 如果您想要允许 gcloud 命令行工具在将密钥传输到 Google Cloud 之前自动封装密钥,则必须在本地系统上安装 Pyca 加密库。Pyca 库供导入作业使用,该导入作业用于在将密钥发送到 Google Cloud 之前在本地封装和保护密钥。
  • 如果您想手动封装密钥,则必须配置 OpenSSL 以便手动封装密钥

准备密钥

验证密钥的算法和长度是否受支持。密钥的允许算法取决于密钥是用于对称加密、非对称加密还是非对称签名,以及密钥是存储在软件还是 HSM 中。您可以在导入请求中指定密钥的算法。

您还必须单独验证密钥的编码方式,并在必要时进行调整。

在创建或导入密钥版本后,无法更改以下内容:

  • 密钥的保护级别指示密钥是保存在软件中、HSM 还是外部密钥管理系统中。无法将密钥材料从这些存储环境之一移到另一个存储环境。密钥的版本均具有相同的保护级别。

  • 密钥的用途指示密钥的版本是用于对称加密、非对称加密还是非对称签名。密钥的用途会限制可用于创建该密钥的版本的可能算法。密钥的版本均具有相同的用途。

如果您没有要导入的密钥,但想要验证导入密钥的过程,则可以在本地系统上使用以下命令创建对称密钥:

openssl rand 32 > ${HOME}/test.bin

仅将此密钥用于测试。以这种方式创建的密钥可能不适合生产用途。

如果您需要手动封装密钥,请先完成此步骤,然后再按照本主题的步骤继续操作。

创建目标密钥和密钥环

Cloud KMS 密钥是一个包含零个或多个密钥版本的容器对象。每个密钥版本都包含一个加密密钥。

将密钥导入 Cloud KMS 或 Cloud HSM 时,导入的密钥将成为现有 Cloud KMS 或 Cloud HSM 密钥上的新密钥版本。在本主题的其余部分中,此密钥称为目标密钥。在导入密钥材料之前,目标密钥必须已存在。

导入密钥版本不会影响该密钥的现有版本。但是,建议您在测试密钥导入时创建空密钥。空密钥没有版本,处于无效状态,且无法使用。

密钥环中存在密钥;在本主题中,此密钥环称为目标密钥环。目标密钥环的位置决定了导入后密钥材料的可用位置。无法在某些位置创建或导入 Cloud HSM 密钥。创建密钥后,无法将其移至其他密钥环或位置。

按照以下步骤使用 gcloud 命令行工具或 Google Cloud Console 在新密钥环上创建空密钥。

gcloud

  1. 创建目标密钥环。如果您打算导入到 Cloud HSM 密钥,请选择支持 Cloud HSM 的位置。

    gcloud kms keyrings create key-ring-name \
      --location location
    

    您可以详细了解如何创建密钥环

  2. 创建目标密钥。

    • 设置密钥的用途:
      • 对于对称密钥,请将用途设置为 encryption
      • 对于非对称密钥,请将用途设置为 asymmetric-signingasymmetric-encryption
    • 使用 --skip-initial-version-creation 标志阻止创建初始版本。
    • 切勿设置保护级别。
    • 切勿为目标密钥指定算法。您可以在导入请求的过程中指定导入的密钥的算法。
    gcloud kms keys create key-name \
      --location location \
      --keyring key-ring-name \
      --purpose purpose \
      --skip-initial-version-creation
    

    您可以详细了解如何创建 Cloud KMS 密钥Cloud HSM 密钥

Console

  1. 转到 Cloud Console 中的加密密钥页面。

    转到“加密密钥”页面

  2. 点击创建密钥环

  3. 密钥环名称字段中,输入密钥环的名称。

  4. 位置下拉列表中,选择一个位置。

  5. 点击创建。系统会打开密钥环的详细信息页面。

  6. 点击创建密钥

  7. 选择导入的密钥。这样做可以防止创建初始密钥版本。

  8. 密钥名称字段中,输入密钥的名称。

  9. 保护级别设置为“软件”或“HSM”。

  10. [可选] 对于导入的密钥,自动轮替在默认情况下处于停用状态。 如果启用自动轮替,则导入的密钥版本将不再是轮替之后的默认密钥版本。

  11. [可选] 如果您要 [为密钥添加标签][4],请在标签字段中,点击添加标签

  12. 点击创建

密钥环和密钥现在已存在,但密钥不包含密钥材料,没有版本,且处于无效状态。接下来创建导入作业

创建导入作业

导入作业定义其导入的密钥的特性,包括导入密钥后无法更改的属性。

保护级别定义从此导入作业生成的密钥是位于软件,HSM 还是外部密钥管理系统中。最终导入密钥后,无法更改保护级别。

导入方法定义用于创建封装密钥的算法,用于在从本地系统传输到目标 Google Cloud 项目的过程中保护导入的密钥。您可以选择 3072 位或 4096 位 RSA 密钥。除非您有特定要求,否则建议使用 3072 位封装密钥。

您可以使用 gcloud 工具、Cloud Console 或 Cloud Key Management Service API 创建导入作业。

gcloud

使用如下所示的命令创建导入作业。

gcloud kms import-jobs create import-job \
  --location location \
  --keyring key-ring-name \
  --import-method import-method \
  --protection-level protection-level

  • 使用与目标密钥相同的密钥环和位置。
  • 将保护级别设置为 softwarehsm
  • 将导入方法设置为 rsa-oaep-3072-sha1-aes-256rsa-oaep-4096-sha1-aes-256

Console

  1. 转到 Cloud Console 中的加密密钥页面。

    转到“加密密钥”页面

  2. 点击目标密钥环的名称。

  3. 保护级别设置为软件HSM。使用与您设置给目标密钥相同的保护级别。

  4. 点击创建导入作业

  5. 名称字段中,输入导入作业的名称。

  6. 导入方法下拉列表,将导入方法设置为 3072 位 RSA4096 位 RSA

  7. 点击创建

API

  1. 创建 [ImportJob][importjob_api] 类型的实例,并为 ImportJob.protectionLevelImportJob.importMethod 字段指定值。

  2. 使用 ImportJob 实例作为请求正文调用 ImportJob.create 方法。

检查导入作业的状态

导入作业的初始状态为 PENDING_GENERATION。当状态为 ACTIVE 时,您可以使用它导入密钥。

导入作业将在三天后过期。如果导入作业已过期,则必须创建新导入作业。

您可以使用 gcloud 命令行工具、Google Cloud Console 或 Cloud Key Management Service API 检查导入作业的状态。

gcloud

当导入作业处于有效状态时,您可以使用它来导入密钥。这可能需要几分钟的时间。使用此命令验证导入作业是否处于有效状态。使用创建导入作业的位置和密钥环。

gcloud kms import-jobs describe import-job \
  --location location \
  --keyring key-ring-name \
  --format="value(state)"
state: ACTIVE

Console

  1. 转到 Cloud Console 中的加密密钥页面。

    转到“加密密钥”页面

  2. 点击包含导入作业的密钥环的名称。

  3. 点击页面顶部的导入作业标签页。

  4. 状态将会显示在导入作业名称旁的状态下。

API

调用 ImportJob.get 方法并检查 state 字段。如果 statePENDING_GENERATION,表示导入作业仍在创建中。请定期重新检查状态,直到状态为 ACTIVE

导入作业处于活动状态时,您可以发出导入密钥的请求

防止修改导入作业

导入作业将确定所导入密钥的许多特性,包括密钥的算法以及所导入密钥是 HSM 密钥还是软件密钥。您可以配置 Identity and Access Management 权限,以防止用户创建导入作业,同时允许他们使用导入作业导入密钥。

  1. 仅向密钥管理员授予 importjobs.create
  2. 向要将使用该作业导入密钥的操作员授予特定导入作业的 importjobs.useToImport 权限。
  3. 创建导入作业时,请为使用它导入的密钥指定保护级别和算法。

在导入作业到期之前,具有指定导入作业的 importjobs.useToImport 权限但没有 importjobs.create 权限的用户可以导入密钥,但无法修改导入作业的特性。

导入密钥

检查导入作业的状态后,您可以发出导入请求。

您可以使用不同的标志来发出导入请求,具体取决于您是希望 gcloud 命令行工具自动封装密钥,还是已手动封装密钥

无论您是手动还是自动封装密钥,都必须将算法设置为与要导入的实际密钥的长度匹配的受支持算法,并指定密钥的用途。

  • 用途为 ENCRYPT_DECRYPT 的密钥使用 google-symmetric-encryption 算法,长度为 32。

  • 用途为 ASYMMETRIC_ENCRYPTASYMMETRIC_SIGN 的密钥支持各种算法和长度。

    创建密钥后不能更改密钥的用途,但可以使用与初始密钥版本不同的长度创建后续密钥版本。

自动封装和导入密钥

如果您想使用自动封装功能,则必须使用 gcloud 命令行工具。使用如下所示的命令。将 --target-key-file 设置为要封装并导入的未封装密钥的位置。切勿设置 -rsa-aes-wrapped-key-file

您可以选择将 --public-key-file 标志设置为已下载公钥的位置。导入大量密钥时,这会阻止在每次导入期间下载公钥。例如,您可以编写一个脚本来下载公钥,然后在导入每个密钥时提供其位置。

gcloud kms keys versions import \
  --import-job import-job \
  --location location \
  --keyring key-ring-name \
  --key KEY_NAME \
  --algorithm algorithm-name \
  --target-key-file path-to-unwrapped-key-to-import

密钥由与导入作业关联的封装密钥封装,将被传输到 Google Cloud,并作为目标密钥上的新密钥版本导入。

导入手动封装的密钥

按照本部分中的说明导入已手动封装的密钥。将 --rsa-aes-wrapped-key-file 设置为手动封装的密钥所在的位置。切勿设置 --target-key-file

您可以选择将 --public-key-file 标志设置为已下载公钥的位置。导入大量密钥时,这会阻止在每次导入期间下载公钥。例如,您可以编写一个脚本来下载公钥,然后在导入每个密钥时提供其位置。

gcloud

使用如下所示的命令。

gcloud kms keys versions import \
  --import-job import-job \
  --location location \
  --keyring key-ring-name \
  --key KEY_NAME \
  --algorithm algorithm-name \
  --rsa-aes-wrapped-key-file path-to-wrapped-key-to-import

如需了解详情,请参阅 gcloud kms keys versions import --help 命令的输出。

Console

  1. 在 Cloud Console 中,打开加密密钥页面。

  2. 点击包含导入作业的密钥环的名称。系统会显示目标密钥以及密钥环上的任何其他密钥。

  3. 点击目标密钥的名称,然后点击导入密钥版本

  4. 选择导入作业下拉列表中选择您的导入作业。

  5. 上传封装密钥选择器中,选择已封装的密钥。

  6. 如果要导入非对称密钥,请从算法下拉列表中选择算法。导入密钥版本页面应如下所示:

    导入密钥版本

  7. 点击导入

API

  1. 对于 cryptoKeyVersions.import 方法的请求正文,请将 algorithm 字段设置为要导入的密钥的算法。 其值不必与将导入此版本的 CryptoKeyversionTemplate 匹配。algorithm 字段的类型为 CryptoKeyVersionAlgorithm

  2. 此外,对于上述请求正文,请将 wrappedKeyMaterial 字段设置为您已经封装的密钥材料。

  3. 调用 cryptoKeyVersions.import 方法。cryptoKeyVersions.import 响应的类型为 CryptoKeyVersion。成功导入密钥后,其状态为 ENABLED,您可以在 Cloud KMS 中使用该密钥。

密钥导入请求已启动。您可以监控其状态

检查导入密钥的状态

导入密钥的初始状态为 PENDING_IMPORT。当状态为 ENABLED 时,表示密钥已成功导入。如果导入失败,则状态为 IMPORT_FAILED

您可以使用 gcloud 命令行工具、Google Cloud Console 或 Cloud Key Management Service API 检查导入请求的状态。

gcloud

使用 versions list 命令检查状态。使用您在本主题前面创建的同一个位置、目标密钥环和目标密钥。

gcloud kms keys versions list \
  --keyring keyring \
  --location location \
  --key key

Console

  1. 在 Cloud Console 中,打开加密密钥页面。

  2. 点击包含导入作业的密钥环的名称。

  3. 点击页面顶部的导入作业标签页。

  4. 状态将会显示在导入作业名称旁的状态下。

API

调用 ImportJob.get 方法并检查 state 字段。如果 statePENDING_GENERATION,表示导入作业仍在创建中。请定期重新检查状态,直到状态为 ACTIVE

导入密钥后,其状态会变为有效。对于对称密钥,您必须先将导入的密钥版本设置为主要版本,然后才能使用该密钥。

对称密钥:设置主要版本

导入对称密钥时,必须执行此步骤,非对称密钥则无需执行此步骤。非对称密钥没有主要版本。您必须使用 gcloud 命令行工具设置主要版本。

gcloud kms keys set-primary-version key-name --version=version-number

后续步骤