通过创建实例、凭证和主密钥初始化专用 Key Protect

要使专用 Key Protect 起作用，您必须先使用 提供实例，然后使用 生成管理员凭据 来操作加密单元，最后使用 创建并加载主密钥，这样 Key Protect 才能代表您对加密单元执行加密操作。

有关专用 Key Protect 服务关键概念的更多信息，请访问 关于标准和专用 Key Protect。

本专题将介绍每种命令的三种不同版本：Mac/ Linux、Windows Powershell 或 Windows 命令提示符 (CMD)。 确保您使用的是与系统相对应的命令。

准备工作

如果没有最新版本的 IBM Cloud CLI，可能无法初始化实例。 更新至 CLI 插件的最新版本，确保初始化成功。

即使使用控制台部署实例，也必须使用最新版本的 CLI 来完成初始化。 如果在安装最新版 KP CLI 插件时收到 - Unable to obtain plug-in's metadata 错误，请参阅 故障排除步骤。

在控制台中配置实例

要在控制台中配置实例，请按照 此处的 说明操作，并在目录中选择“专用”磁贴。 配置过程可能需要几分钟。

实例配置完成后，您就可以 生成管理凭据并申请加密单元 了。

如果未指定加密单元的数量，则会为实例配置两个加密单元。 您还可以使用下拉菜单指定三个加密单元。 无论指定两个还是三个密码单元，都要注意该值以后不能更改。

在 CLI 中配置实例

在创建加密单元和初始化实例之前，必须先创建实例。 首先，通过发布设置一个资源组作为目标：

ibmcloud target -c <resource-group>

如果您不知道自己的资源组，可以通过发布来查找：

ibmcloud resource groups

设置好资源组后，发出命令创建实例：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south

其中：

  • <INSTANCE_NAME> 是您给实例起的名字。

请注意，该命令默认使用两个加密单元。 您可以通过发出加密命令来指定三个加密单元：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south -p '{"crypto_units": 3}'

如果指定的加密单元数量不是 2 或 3，则会返回错误信息。 以后不能更改加密单元的数量。

配置专用实例可能需要几分钟时间。 您可以发出以下命令来检查实例的状态：

ibmcloud resource service-instance <INSTANCE_NAME>

其中：

  • <INSTANCE_NAME> 是您在上一步中为实例起的名称。

该实例有两种状态：激活或进行中。 请注意，活动实例尚未初始化，因为初始化需要完成本主题中的其余步骤。 在初始化实例之前，该密钥无法使用，因为您的身份尚未与加密单元配置，无法创建主密钥。

获取端点

实例激活后，可通过下达命令获取端点和 GUID：

ibmcloud resource service-instance <INSTANCE_NAME> -o json

其中：

  • <INSTANCE_NAME> 是您在上一步中为实例起的名称。

端点是上述 json 输出 endpoints stanza 中的 public 参数值。 其格式为 https://<instance-id>.api.<region>.kms.appdomain.cloud。 GUID 就是上述输出中的 GUID 参数值。 其格式为 UUID。

您可以通过以下方式获取端点：ibmcloud resource service-instance <\kp-instance-id\> --output json | jq -r '.[].extensions.endpoints'。

在三种支持的操作系统中，在其中一种操作系统上发出两条命令，将完整端点保存为环境变量。

对于 macOS:

export KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

此外：

export KP_INSTANCE_ID=<GUID>

适用于 Windows Powershell：

$Env:KP_INSTANCE_ID = <GUID>

此外：

$Env:KP_TARGET_ADDR = <ST_INSTANCE_ENDPOINT>

对于 Windows CMD：

set KP_INSTANCE_ID=<GUID>

此外：

set KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

其中：

  • <ST_INSTANCE_ENDPOINT> 是实例的完整端点，格式为 https://<instance-id>.api.<region>.kms.appdomain.cloud。
  • <GUID> 是上述输出中的实例 ID。

现在就可以生成管理员凭据了。

配置完成后，您可能需要等待几分钟才能使用加密单元。

有关密码单元状态的更多信息，请查看 密码单元状态。

生成管理员凭证并申请密码单元

加密单元由一个或多个管理员管理，这意味着你需要有可用的身份或创建身份。 如果已正确格式化管理员身份（使用 RSA-2048 的 256 位 AES 对称密钥），则可跳至 创建主密钥。

生成管理员凭证

如果需要创建管理员凭证，请发出：

ibmcloud kp crypto-unit sig-key generate --file <ADMIN_KEY_FILE> --passphrase <PWD> --algo RSA-2048

其中：

  • <ADMIN_KEY_FILE> 是机器上创建身份的位置（例如，admin-keyfile.key ）。
  • <PWD> 是一个可选的密码或口令，用于对文件进行静态加密。 指定"-"，系统会提示输入密码。

保存此密钥文件的副本并记住口令。 在与加密单元交互时，所有经过身份验证的命令都需要输入该密码。

如果 ibmcloud kp crypto-unit 命令返回错误代码 e00bad05，请参阅 故障排除步骤。

申领您的加密货币单位

有关密码单元状态的更多信息，请查看 密码单元状态。

分配给用户的加密单元开始时处于 清除状态。 服务实例中的所有加密单元都需要进行相同的配置。 如果无法访问实例所在区域的一个可用区，则可交替使用运行中的加密单元，以实现负载平衡或高可用性。

同一服务实例中所有加密单元的主密钥必须设置为相同。 必须在所有加密单元中添加同一组管理员，且所有加密单元必须同时进行初始化。

要显示当前用户账户下目标资源组中的服务实例和加密单元，请使用以下命令：

ibmcloud kp crypto-units

以下是显示的输出示例。 输出表中的 ID 列用于标识后续由 KP CLI 插件发出的管理命令所针对的加密单元。

*******************************************************  
Id                                     InstanceID                             State  
6e0aead3-9d44-4c92-a4c4-f7a1ab415420   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
3bb363fc-b1f9-4237-b37b-2c9e07784e3c   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
*******************************************************

RSA 密钥对的公钥被放入证书中，该证书安装在目标加密单元中，用于指定加密单元管理员。 使用 claim 命令将其上载为密码单元的默认管理员，发出：

ibmcloud kp crypto-unit claim --credential <ADMIN_KEY_FILE>

其中：

  • <ADMIN_KEY_FILE> 是存储身份信息的文件。

所有 crypto-unit 命令都适用于所有加密单元。 它们实际上是彼此的克隆体。

生成和导入主密钥

由于您导入的是主密钥凭据，因此 Key Protect 无法访问或备份该密钥。 将万能钥匙的记录保存在安全的地方。

创建了实例和管理员身份后，就可以使用它们创建主密钥了。 主密钥又称 HSM 主密钥，用于加密服务实例以存储密钥。 这是一个 256 位 AES 对称密钥。 借助主密钥，您将获得云HSM的所有权，并掌控用于加密整个加密密钥层次结构的信任根，其中包括密钥管理密钥库中的根密钥和标准密钥。 一个服务实例只能有一个主密钥。 如果您删除了服务实例的主密钥，就可以有效地对所有使用该服务中管理的密钥加密的数据进行加密销毁。

专用 Key Protect 采用“密钥分割”机制，即将加密密钥分割成多个部分，以增强安全性。 至少必须创建 2 个 "keyshares"，但也可以根据使用情况创建更多。

要在本地生成主密钥，请在三种支持的操作系统之一上发出该命令。

对于 macOS:

ibmcloud kp crypto-unit master-key generate --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2>"]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSOWRD3>"}]'

适用于 Windows Powershell：

ibmcloud kp crypto-unit master-key generate --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSOWRD3>"""}]'

对于 Windows CMD：

ibmcloud kp crypto-unit master-key generate --keyshare-files"[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2>\"]" --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSOWRD3>\"}]"

其中：

  • <KEYSHARE_FILE_1>#<PASSWORD1> 是其中一个密钥共享的位置，以及所创建文件的口令。 口令是必填项，必须在 6-255 个字符之间。 省略 #<PASSWORD1>，系统会提示输入密码。
  • <KEYSHARE_FILE_2>#<PASSWORD2> 是另一个密钥共享的位置，以及所创建文件的口令。 口令是必填项，必须在 6-255 个字符之间。 省略 #<PASSWORD2>，系统会提示输入密码。 省略 #<PASSWORD2>，系统会提示输入密码。
  • <KEY_NAME> 是您的主密钥的名称。
  • <ADMIN_KEY_FILE>#<PASSOWRD3> 是您的管理员位置和您之前生成的口令（如果您不携带自己的身份信息）。 省略 #<PASSWORD3>，系统会提示输入密码。

请注意，keyshare-minimum 默认设置为 2，但可以增加，它表示必须指定的最小键槽数（按其位置）。

要将主密钥上传到实例的加密单元，请在三种支持的操作系统之一上发布命令。

对于 macOS:

ibmcloud kp crypto-unit master-key import --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2"]' --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD3>"}]'

适用于 Windows PowerShell:

ibmcloud kp crypto-unit master-key import --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD3>"""}]'

对于 Windows CMD：

ibmcloud kp crypto-unit master-key import --keyshare-files "[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2\"]" --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD3>\"}]"

其中：

  • <KEYSHARE_FILE_1>#<PASSWORD1> 是其中一个密钥共享的位置，以及将要创建的文件的口令。 口令是必填项，必须在 6-255 个字符之间。 省略 #<PASSWORD1>，系统会提示输入密码。
  • <KEYSHARE_FILE_2>#<PASSWORD2> 是另一个密钥共享的位置，以及将要创建的文件的口令。 口令是必填项，必须在 6-255 个字符之间。 省略 #<PASSWORD2>，系统会提示输入密码。
  • <ADMIN_KEY_FILE>#<PASSWORD3> 是您的管理员位置和您之前生成的口令（如果您不携带自己的身份信息）。 省略 #<PASSWORD3>，系统会提示输入密码。

现在主密钥已经创建，您需要允许 Key Protect 服务对加密单元执行操作（例如，创建密钥）。 请注意，授予“Key Protect”的权限级别低于管理员。 使用三种支持的操作系统之一发布命令。

对于 macOS:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD>"}]'

适用于 Windows PowerShell:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD>"""}]'

对于 Windows CMD：

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD>\"}]"

其中：

  • <ADMIN_KEY_FILE>#<PASSWORD> 是先前生成的管理密钥文件及其口令的位置（如果您不携带自己的身份信息）。 省略 #<PASSWORD>，系统会提示输入密码。

该命令还可用于为密码单元添加管理员，方法是制作 --type admin 并添加指向您拥有的管理员身份的 --name 和 --file。 在添加 kmsCryptoUser 时，请勿添加 --name 或 --file。 例如：

ibmcloud kp crypto-unit user add --type admin --name <USERNAME> --credential "<USERNAME_KEY_FILE>" --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PWD>"}]'

其中：

  • <USERNAME> 是您要添加的管理员身份的名称。
  • <USERNAME_KEY_FILE> 是要与新用户关联的证书的文件路径。
  • <ADMIN_KEY_FILE>#<PWD> 是您现有管理员的位置及其之前生成的口令（如果您不使用自己的身份）。 省略 #<PWD>，系统会提示输入密码。

添加 kmsCryptoUser 为管理员时，请勿添加 --name 或 --file。

祝贺您！ 您的实例已完全初始化。

您可能需要等待5到10分钟才能使用该实例。

后续步骤

现在，您的实例已经创建，您拥有了可用于操作实例的管理员身份，创建了主密钥，并赋予 Key Protect 在实例上执行操作的权限，您已经准备好执行以下操作：

Key Protect Dedicated 不支持导入令牌。

不支持的功能

故障诊断

Unable to obtain plug-in's metadata 安装或升级 KP CLI 插件时出现错误

如果在安装 IBM Key Protect CLI 插件时收到以下错误：

Installing binary...
FAILED
Unable to obtain plug-in's metadata. Error: exit status 1

Linux 环境

从发行版的软件包管理器中使用 3.4.26 或更高版本的 GLIBCXX 安装或更新 libstdc++ 系统库。 使用以下示例安装命令：

  • Ubuntu/Debian: apt-get update && apt-get install libstdc++6
  • RHEL/Fedora/CentOS: yum install libstdc++
  • Alpine: apk add --no-cache gcompat libstdc++

如果这样仍无法解决该错误，请联系 Key Protect 技术支持。

Windows 或 macOS 环境

请联系 Key Protect 支持部门。

command failed with error code: e00bad05 错误

如果 ibmcloud kp crypto-unit 命令返回以下错误：

FAILED
command failed with error code: e00bad05

该错误可能表明您的系统与 ibmcloud kp crypto-unit 功能不兼容。 建议的系统要求是

  • Windows: AMD64 （Windows 10 或更高版本）
  • Linux: AMD64 (Debian, Ubuntu, Red Hat)
  • macOS: ARM64 (苹果硅）

清单之外的系统可能仍然兼容 ibmcloud kp crypto-unit 功能。 如果您想确认与特定系统的兼容性，或者尽管满足推荐的系统要求，但 e00bad05 错误仍然存在，请联系 Key Protect 支持。

HTTP 503 no healthy upstream 错误

如果调用 Key Protect 操作 返回 HTTP 503 和信息 no healthy upstream: no crypto units are in kms-initialized state at this time，可能有以下原因：

  • 您尚未完成专用初始化步骤。
  • 您已完成专用初始化步骤，但需要等待几分钟 Key Protect 才能识别新的 kms-initialized 加密单元。
  • 您只有一个密码单元处于 kms-initialized 状态，而该密码单元正在停机维护。
  • 您向一个或多个加密单元上传了不匹配的主密钥材料。

context deadline exceeded 错误

如果 CLI 命令返回错误 context deadline exceeded (Client.Timeout exceeded while awaiting headers)，则您将 KP_TARGET_ADDR 设置为来自不符合专用端点要求的系统的专用端点。

要解决此错误，请执行以下操作：

  • 使用 获取端点 步骤中的公共端点。
  • 如果您打算使用专用端点，请参阅专用 端点，了解有关调用专用端点的信息。

加密单元命令无法应用于所有加密单元

如果 crypto-unit claim、crypto-unit master-key import 或 crypto-unit user add --type kmsCryptoUser 命令未能应用于所有加密单元，则可能会看到与下例类似的输出：

Executing operation Generate Master Key against CryptoUnit with ID fadedbee-0000-0000-0000-1234567890ab
OK
Executing operation Generate Master Key against CryptoUnit with ID addedace-0000-0000-0000-1234567890ab
FAILED

要解决此问题，请完成下列步骤：

  1. 默认情况下，claim、master-key import 和 user add 命令会尝试应用于所有加密单元。 如果这些命令仅部分成功（仅应用于实例中的加密单元子集），则仅针对返回失败的加密单元重试该命令。 每条命令都可配置为针对特定加密单元。 要确定如何使用特定加密单元，请在任何 crypto-unit 命令后附加 -h 以查看帮助文本，或参阅 CLI 参考资料。

  2. 运行 CLI 参考 中的 kp crypto-units 命令，确认所有加密单元处于相同状态。

    • 如果密码单元状态不匹配，请参阅 密码单元状态。
    • 如果任何加密单元处于 maintenance 状态，请稍后重试 kp crypto-unit 命令。