目标

本教程将指导您创建加密密钥并将其安全地导入到 Key Protect 服务中。 面向新用户 Key Protect，但他们可能对密钥管理系统有一些熟悉。 以下步骤大约需要 20 分钟才能完成。

• 设置 Key Protect CLI

• 准备 Key Protect 服务实例以开始导入密钥

• 使用 OpenSSL 密码术工具箱创建和加密密钥

• 将加密密钥导入到 Key Protect 实例

本教程不会对 IBM Cloud 产生任何费用 帐户。

准备工作

要开始使用，您需要 IBM Cloud CLI，以便可以与供应的服务进行交互 IBM Cloud. 您还需要在计算机上本地安装 openssl 和 jq 软件包。

1. 创建一个 IBM Cloud 帐户。

2. 下载并安装 适用于您的操作系统的 IBM Cloud 基本 CLI。

3. 配置并 设置 Key Protect CLI 插件 以开始管理密钥。 如果您已完成先前列出的前两个步骤，请先从链接中的步骤号 3 开始，然后再返回本教程。

4. 下载并安装 OpenSSL 密码术库。

   如果您正在试用，那么可以使用 openssl 命令在本地计算机上生成加密密钥 Key Protect 第一次。 本教程需要 OpenSSL V 1.0.2r 或更高版本。

   如果您使用的是 Mac，那么可以使用以下命令下载 OpenSSL: Homebrew。 如果是首次安装软件包，请运行 brew install openssl，或者运行 brew upgrade openssl 以将现有软件包升级到最新版本。

5. 下载并安装 jq。

   jq 可帮助您对 JSON 数据进行切片。 在本教程中使用 jq 来捕获在调用 Key Protect API。

步骤 1. 创建 Key Protect 实例

设置 IBM Cloud 帐户后，请完成以下步骤以供应 Key Protect 实例。

1. 在终端窗口中，运行以下命令以登录到 IBM Cloud IBM Cloud CLI。

   ibmcloud login
   

   如果登录失败，请运行 ibmcloud login --sso 命令重试。 使用联合标识登录时需要 --sso 参数。 如果使用此选项，请转至 CLI 输出中列出的链接以生成一次性密码。

2. 选择要创建的账户和资源组 Key Protect 实例。

   在本教程中，您将与华盛顿区域进行交互。 如果您已登录到其他区域，请确保通过运行以下命令将 Washington DC 设置为您的目标区域。

   ibmcloud target -r us-east
   

3. 在该帐户和资源组内供应 Key Protect 实例。

   首先，通过发出以下命令来指定实例的资源组:

   ibmcloud target -g <your-resource-group>
   

   例如， ibmcloud target -g Default

   然后，可以通过发出以下命令来创建实例:

   ibmcloud resource service-instance-create "import-keys-demo" kms tiered-pricing us-east
   

   本教程不会对您的 IBM Cloud 帐户产生任何费用。

4. 可选: 通过列出可用的 Key Protect 实例，验证是否已成功创建 Key Protect 实例。

   ibmcloud resource service-instances
   

   成功！ 现在，您已使用 Key Protect 实例进行设置，您可以在该实例中存储和管理加密密钥。 继续下一步。

步骤 2. 设置 Key Protect API

现在，您已供应以下实例: Key Protect，您已准备好开始使用 API。

Key Protect 提供了图形用户界面和 REST API，用于创建，跟踪和管理加密密钥。 该 Key Protect API 需要有效的 IBM Cloud IAM 令牌和用于向服务认证的实例标识。

在此步骤中，使用 IBM Cloud CLI 收集开始与之交互所需的认证凭证 Key Protect API。 要检索并准备凭证以执行后续步骤，还请将凭证设置为终端中的环境变量。

1. 在终端窗口中，设置 Key Protect API 端点作为环境变量。

   export KP_API_URL=https://<region>.kms.cloud.ibm.com
   

2. 使用以下命令生成 IBM Cloud 访问令牌: Key Protect CLI 插件，并将其设置为环境变量。

   环境变量应以授权类型开头， Bearer. 如示例中所示，CLI 命令将自动包含正确的类型。

   export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
   

   IBM Cloud 访问令牌的有效期为 1 小时，但您可以根据需要 但您可以根据需要重新生成。 要生成新的访问令牌，请运行 ibmcloud iam oauth-tokens 指挥。 了解有关检索的更多信息 IBM Cloud 访问令牌，请参阅 检索访问令牌。

3. 检索与您的 Key Protect 实例，然后将值设置为环境变量。

   export INSTANCE_ID=`ibmcloud resource service-instance "import-keys-demo" --output json | jq -r '.[].guid'`
   

4. 可选: 通过将环境变量打印到终端屏幕，验证是否正确设置了这些环境变量。

   $ echo $KP_API_URL
   https://us-east.kms.cloud.ibm.com
   $ echo $ACCESS_TOKEN
   Bearer eyJraWQiOiIyM...
   $ echo $INSTANCE_ID
   c1cf624b-6bed-4d4d-bd54-8e2534258a88
   

   成功！ 现在，您可以使用向 Key Protect API 认证所需的服务凭证进行设置。 继续下一步。

步骤 3. 创建导入令牌

使用服务凭证，您可以开始与 Key Protect API，用于创建加密密钥并将其引入服务。

在以下步骤中，您将创建 Key Protect 实例的 导入令牌。 通过根据您指定的策略创建导入令牌，可以在加密密钥传输到服务时对其启用额外安全性。

1. 使用终端会话，切换到新的 key-protect-test 目录。

   mkdir key-protect-test && cd key-protect-test
   

   您可以使用此目录来存储文件以执行后续步骤。

2. 为您的 Key Protect 实例，然后将响应保存到 JSON 文件。

   $ curl -X POST \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -d '{
               "expiration": 1200,
               "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
   

   在请求主体中，可以对导入令牌指定策略，以根据时间和使用情况计数来限制其使用。 在此示例中，您将导入令牌的到期时间设置为 1200 秒 (20 分钟)，并且还允许在到期时间内仅检索一次该令牌。

3. 查看导入令牌的详细信息。

   jq '.' createImportTokenResponse.json
   

   输出将显示与导入令牌关联的元数据，例如其创建日期和策略详细信息。 以下片段显示了示例输出。

   {
       "creationDate": "2019-04-08T16:58:29Z",
       "expirationDate": "2019-04-08T17:18:29Z",
       "maxAllowedRetrievals": 1,
       "remainingRetrievals": 1
   }
   

步骤 4. 检索导入令牌

在上一步中，您创建了导入令牌，并查看了与该令牌关联的元数据。

{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 1
}

在此步骤中，您将检索与导入令牌关联的公用加密密钥和现时标志值。 您需要公用密钥以在后续步骤中加密数据，并需要现时标志以验证安全导入请求 Key Protect 服务。

要检索导入令牌内容:

1. 检索先前步骤生成的导入令牌，然后将响应保存到 JSON 文件。

   $ curl -X GET \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" > getImportTokenResponse.json
   

2. 可选: 检查导入令牌的内容。

   jq '.' getImportTokenResponse.json
   

   输出显示有关导入令牌的详细信息。 以下片段显示具有截断值的示例输出。

   {
       "creationDate": "2019-04-08T16:58:29Z",
       "expirationDate": "2019-04-08T17:18:29Z",
       "maxAllowedRetrievals": 1,
       "remainingRetrievals": 0,
       "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv...",
       "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   payload 值表示与导入令牌关联的公用密钥。 该值采用 base64 编码。 nonce 值用于验证对服务的请求的独创性。 在后续步骤中导入加密密钥时，需要加密并提供此值。

3. 将公用密钥解码并保存到名为 PublicKey.pem 的文件。

   jq -r '.payload' getImportTokenResponse.json | base64 --decode -o PublicKey.pem
   

   现在，公用密钥将以 PEM 格式下载到您的计算机。 继续 继续下一步。

步骤 5. 创建加密密钥

通过 Key Protect，您可以通过创建和上载自己的密钥以在 IBM Cloud上使用，从而启用自带密钥 (BYOK) 的安全优势。

在以下步骤中，您将在本地计算机上创建 256 位 AES 对称密钥。

本教程使用 OpenSSL 密码术工具箱来生成伪随机密钥，但您可能希望 探索不同的选项，根据您的安全需求生成更强的密钥。 例如 例如，您可能希望使用由内部硬件安全模块（HSM）支持的企业内部密钥管理系统来创建和导出密钥。硬件安全模块 (HSM) 支持的内部密钥管理系统来创建和导出密钥。

1. 在终端窗口中，运行以下 openssl 命令以创建 256 位加密密钥。

   openssl rand 32 > PlainTextKey.bin
   

   成功！ 您的加密密钥现在保存在一个名为 PlainTextKey.bin. 继续下一步。

步骤 6。 加密现时标志

要验证我们接收的位是否与作为请求一部分发送的位完全相同，请 Key Protect 在将对称密钥上载到服务时需要现时标志验证。

在密码术中，现时标志充当会话令牌，用于检查请求的原创性，以防止恶意攻击和未经授权的调用。 通过使用由以下人员分发的同一现时标志 Key Protect，可帮助确保上载密钥的请求有效。 必须使用要导入到服务中的相同密钥对现时标志值进行加密。

要加密现时标志值:

1. 对您在上一步中生成的密钥进行编码，并将编码后的值设置为环境变量。

   KEY_MATERIAL=$(base64 PlainTextKey.bin)
   

2. 收集在步骤 4 中检索到的现时标志值。

   NONCE=$(jq -r '.nonce' getImportTokenResponse.json)
   

3. 执行以下操作以使用您在步骤 5 中生成的加密密钥来加密现时标志值。 然后，将响应保存到名为 EncryptedValues.json.

   ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE --output json > EncryptedValues.json
   

4. 可选: 使用 jq 检查 JSON 文件的内容，如下所示。

   jq '.' EncryptedValues.json
   

   输出将显示需要为下一步提供的值。 以下片段显示具有截断值的示例输出。

   {
       "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
       "iv": "puQrzDX7gU1TcTTx"
   }
   

   encryptedNonce 值表示使用 OpenSSL生成的加密密钥打包 (或加密) 的原始现时标志。 该 iv 值是由 AES-GCM 算法创建的初始化向量 (IV)，稍后需要此值以便 Key Protect 可以成功解密现时标志。

步骤 7. 加密密钥

接下来，使用由以下用户分发的公用密钥: Key Protect，用于加密使用 OpenSSL生成的对称密钥。

1. 使用在步骤 4 中检索的公用密钥对生成的密钥进行加密。

   openssl pkeyutl \
       -encrypt \
       -pubin \
       -keyform PEM \
       -inkey PublicKey.pem \
       -pkeyopt rsa_padding_mode:oaep \
       -pkeyopt rsa_oaep_md:sha256 \
       -in PlainTextKey.bin \
       -out EncryptedKey.bin
   

   如果在运行 openssl 时迂到参数设置错误 在 Mac OSX 上，您可能需要确保为您的环境正确配置 OpenSSL。 如果使用 Homebrew 安装了 OpenSSL，请运行 brew update，然后运行 brew install openssl 以获取最新版本。 然后，运行 export PATH="/usr/local/opt/openssl/bin:$PATH" >> ~/.bash_profile，用于对包进行符号链接。 打开新的终端会话，然后运行 which openssl && openssl version，用于验证最新版本的 OpenSSL 在 /usr/local/ 位置下可用。 如果继续迂到错误，请确保仅使用此示例中列出的参数。

   成功！ 您的加密密钥现在已保存到名为 EncryptedKey.bin. 您都已设置为将加密密钥上载到 Key Protect. 继续下一步。

步骤 8。 导入密钥

现在，您可以使用以下命令导入加密密钥: Key Protect API。

要导入密钥:

1. 收集加密密钥，加密现时标志和初始化向量 (IV) 值。

   ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
   

   ENCRYPTED_NONCE=$(jq -r '.encryptedNonce' EncryptedValues.json)
   

   IV=$(jq -r '.iv' EncryptedValues.json)
   

2. 将加密密钥存储在 Key Protect 实例 (通过运行以下 curl 命令)。

   $ curl -X POST \
       "$KP_API_URL/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -d '{
               "metadata": {
                   "collectionType": "application/vnd.ibm.kms.key+json",
                   "collectionTotal": 1
               },
               "resources": [
                   {
                       "name": "encrypted-root-key",
                       "type": "application/vnd.ibm.kms.key+json",
                       "payload": "'"$ENCRYPTED_KEY"'",
                       "extractable": false,
                       "encryptionAlgorithm": "RSAES_OAEP_SHA_256",
                       "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
                       "iv": "'"$IV"'"
                   }
               ]
           }' > createRootKeyResponse.json
   

   在请求主体中，提供在上一步中准备的加密密钥。 您还提供验证请求所需的加密现时标志和 IV 值。 最后，extractable 值设置为 false 将新密钥指定为服务中可用于包络加密的根密钥。

   Key Protect 通过 TLS 1.2 或 1.3 协议接收加密包。 在硬件安全模块中，系统使用专用密钥来解密对称密钥。 最后，系统使用对称密钥和 IV 对现时标志进行解密并验证请求。

   如果 API 请求失败并返回导入令牌到期错误， 返回到步骤 3 以创建新的导入令牌。 请记住，根据您在创建时指定的策略，导入令牌及其关联的公用密钥将到期。

3. 查看加密密钥的详细信息。

   jq '.' createRootKeyResponse.json
   

   以下片段显示了示例输出。

   {
       "metadata": {
           "collectionType": "application/vnd.ibm.kms.key+json",
           "collectionTotal": 1
       },
       "resources": [
           {
               "id": "02fd6835-6001-4482-a892-13bd2085f75d",
               "type": "application/vnd.ibm.kms.key+json",
               "name": "encrypted-root-key",
               "state": 1,
               "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "extractable": false,
               "imported": true
           }
       ]
   }
   

   id 值是分配给密钥的唯一标识符，用于后续调用密钥时使用。用于后续调用 Key Protect API。 设置为 1 的 state 值指示加密密钥现在位于 活动 密钥状态。 crn 值提供了指定资源位于 IBM Cloud中的位置的键的完整作用域路径。 最后，extractable 和 imported 值将此资源描述为您导入到服务的根密钥。

4. 可选: 浏览至 Key Protect 仪表板，用于查看和管理加密密钥。

   

   您可以在应用程序详细信息页面浏览密钥的一般特征。详细信息页面。 从用于管理密钥的选项列表中进行选择，例如 旋转密钥 或 正在删除密钥。

步骤 9。 清除

1. 收集在上一步中导入的加密密钥的标识。

   ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
   

2. 从您的 Key Protect 实例。

   $ curl -X DELETE \
       "$KP_API_URL/api/v2/keys/$ROOT_KEY_ID" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" | jq .
   

3. 除去与本教程关联的所有本地文件。

   rm *.json *.bin *.pem
   

4. 删除您为此教程创建的测试目录。

   cd .. && rm -r key-protect-test
   

5. 可选: 除去 Key Protect 服务实例。

   ibmcloud resource service-instance-delete import-keys-demo
   

   如果您在 Key Protect 实例，请确保 从实例中除去所有加密密钥，然后再删除或取消供应该实例。

后续步骤

在本教程中，您学习了如何设置 Key Protect API，创建加密密钥，并将加密密钥安全地导入到您的 Key Protect 实例。

• 了解有关 使用根密钥保护静态数据。

• 跨系统部署根密钥 支持的云服务。

• 了解有关 Key Protect API。