创建根密钥

您可以使用 IBM Cloud® Hyper Protect Crypto Services 通过使用 UI 创建根密钥A symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service.，也可以使用 Hyper Protect Crypto Services 密钥管理服务 API 以编程方式创建根密钥。

根密钥是用于保护云中已加密数据的安全性的对称密钥打包密钥。有关根密钥的更多信息，请参阅包络加密。

使用 UI 创建根密钥

创建服务实例后，请完成以下步骤以使用 UI 创建根密钥。

如果启用 Hyper Protect Crypto Services 实例的双重授权设置，请记住添加到服务的任何密钥都需要两个用户的授权才能删除密钥。

登录 UI。
转至菜单 > 资源列表 以查看资源列表。
从 IBM Cloud 资源列表，选择 Hyper Protect Crypto Services 的已供应实例。
要创建新密钥，请在侧边菜单中选择 KMS 密钥 选项卡。

在“密钥”表中，单击 添加密钥，然后选择 创建密钥。

指定密钥的详细信息：

表 1. 描述用于创建密钥的设置
设置	描述
密钥类型	要在 Hyper Protect Crypto Services 中管理的密钥类型。从密钥类型列表中，选择根密钥。
密钥名称	密钥的人类可读的唯一名称，以便可轻松识别密钥。长度必须在 2 到 90 个字符之间。为保护隐私，请确保密钥名称不包含个人可标识信息 (PII)，例如，姓名或位置。
密钥别名	(可选) 要分配给密钥以方便识别的一个或多个唯一的人类可读别名。别名大小可以是 2-90 个字符。最多可以为密钥设置五个密钥别名，每个别名以逗号分隔。注: 每个别名必须是字母数字，区分大小写，并且不能包含空格或除短划线 (-) 或下划线 (_) 以外的特殊字符。别名不能是 V 4 UUID，也不能是 Hyper Protect Crypto Services 保留名称: `allowed_ip`，`key`，`keys`，`metadata`，`policy`，`policies`，`registration`，`registrations`，`ring`，`rings`，`rotate`，`wrap`，`unwrap`，`rewrap`，`version` 和 `versions`。
密钥环标识	从包含现有密钥环的列表中选择密钥环。如果未指定密钥环，那么会将该密钥添加到 `default` 密钥环。有关密钥环的更多信息，请参阅管理密钥环。
到期日期	(可选) 设置密钥到期的日期和时间。在到期日期之后，密钥将进入“已取消激活”状态。有关密钥状态的更多信息，请参阅监视加密密钥的生命周期。
描述	(可选) 添加密钥的扩展描述。长度可以是 2 到 240 个字符。

填写完密钥的详细信息后，单击 创建密钥 以确认。

服务中创建的密钥是 AES-CBC 算法支持的 256 位对称密钥。对于添加的安全性，密钥由位于安全 IBM Cloud 数据中心的 FIPS 140-2 级别 4 认证的硬件安全模块(HSM)A physical appliance that provides on-demand encryption, key management, and key storage as a managed service. 生成。

使用 API 创建根密钥

通过对以下端点执行 POST 调用来创建根密钥。

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys

检索服务和认证凭证以与服务中的密钥一起使用。

使用以下 curl 命令调用 Hyper Protect Crypto Services 密钥管理服务 API。

curl -X POST \
  "https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys" \
  -H "authorization: Bearer <IAM_token>" \
  -H "bluemix-instance: <instance_ID>" \
  -H "content-type: application/vnd.ibm.kms.key+json" \
  -H "x-kms-key-ring: <key_ring_ID>" \
  -H "correlation-id: <correlation_ID>" \
  -d '{
          "metadata": {
              "collectionType": "application/vnd.ibm.kms.key+json",
              "collectionTotal": 1
          },
          "resources": [
              {
                  "type": "application/vnd.ibm.kms.key+json",
                   "name": "<key_name>",
                   "aliases": [alias_list],
                   "description": "<key_description>",
                   "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
                   "extractable": <key_type>
              }
          ]
      }'

根据下表替换示例请求中的变量。

表 2. 描述使用 API 添加根密钥所需的变量
变量	描述
`region`	必需。区域缩写（例如，`us-south` 或 `au-syd`），表示 Hyper Protect Crypto Services 服务实例所在的地理区域。有关更多信息，请参阅区域服务端点。
`port`	必需。 API 端点的端口号。
`IAM_token`	必需。您的 IBM Cloud 访问令牌。在 cURL 请求中包含 `IAM` 令牌的完整内容，包括 Bearer 值。有关更多信息，请参阅检索访问令牌。
`instance_ID`	必需。指定给您的 Hyper Protect Crypto Services 服务实例的唯一标识。有关更多信息，请参阅检索实例标识。
`key_ring_ID`	可选。要将密钥分配到的目标密钥环的唯一标识。如果未指定，那么头将自动设置为 `default` ，并且密钥属于指定 Hyper Protect Crypto Services 实例中的缺省密钥环。有关更多信息，请参阅管理密钥环。
`correlation_ID`	用于跟踪和关联事务的唯一标识。
`key_name`	必需。密钥的人类可读的唯一名称，以便可轻松识别密钥。重要说明：为保护隐私，请勿存储个人数据作为密钥的元数据。
`alias_list`	可选。分配给密钥的一个或多个唯一的人类可读别名。重要信息: 为了保护隐私，请勿将个人数据存储为密钥的元数据。每个别名必须是字母数字，区分大小写，并且不能包含除短划线 (-) 或下划线 (_) 以外的空格或特殊字符。别名不能是 V 4 UUID，也不能是 Hyper Protect Crypto Services 保留名称: `allowed_ip`，`key`，`keys`，`metadata`，`policy`，`policies`，`registration`，`registrations`，`ring`，`rings`，`rotate`，`wrap`，`unwrap`，`rewrap`，`version` 和 `versions`。别名大小可以是 2-90 个字符 (含)。
`key_description`	可选：密钥的扩展描述。重要说明：为保护隐私，请勿存储个人数据作为密钥的元数据。
`YYYY-MM-DD` `HH:MM:SS.SS`	可选：密钥在系统中到期的日期和时间（RFC 3339 格式）。如果省略了 `expirationDate` 属性，那么键不会到期。
`key_type`	布尔值，用于确定密钥资料是否可以离开服务。在将 `extractable` 属性设置为 `false` 时，服务创建可用于 `wrap` 或 `unwrap` 操作的根密钥。

为保护个人数据的机密性，在向服务添加密钥时，避免输入个人可标识信息 (PII)，例如，姓名或位置。有关 PII 的更多示例，请参阅 NIST Special Publication 800-122的 2.2 部分。

如果在请求中设置 expirationDate，那么密钥将在密钥到期日期之后 1 小时内进入取消激活状态。

成功的 POST /v2/keys 响应会返回密钥的标识值以及其他元数据。该标识是分配给密钥的唯一标识，用于后续调用 Hyper Protect Crypto Services 密钥管理服务 API。

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
    },
    "resources": [
        {
            "type": "application/vnd.ibm.kms.key+json",
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "name": "test-root-key",
            "aliases": [
                "alias-1",
                "alias-2"
              ],
            "description": "A test root key",
            "state": 1,
            "extractable": false,
            "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "imported": false,
            "creationDate": "2020-03-12T03:37:32Z",
            "createdBy": "...",
            "algorithmType": "AES",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "CBC_PAD"
            },
            "algorithmBitSize": 256,
            "algorithmMode": "CBC_PAD",
            "lastUpdateDate": "2020-03-12T03:37:32Z",
            "keyVersion": {
                "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
                "creationDate": "2020-03-12T03:37:32Z"
            },
            "dualAuthDelete": {
                "enabled": false
            },
            "deleted": false
        }
    ]
}

有关响应参数的详细描述，请参阅 Hyper Protect Crypto Services REST API 参考文档。

可选：通过运行以下调用来浏览 Hyper Protect Crypto Services 服务实例中的密钥，以验证是否创建了密钥。

curl -X GET \
  https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
  -H 'accept: application/vnd.ibm.collection+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'correlation-id: <correlation_ID>' \

使用服务创建根密钥后，该密钥将保留在 Hyper Protect Crypto Services的边界内，并且无法检索密钥资料。

下一步

要了解有关使用包络加密保护密钥的更多信息，请查看打包密钥。
要了解有关导入您自己的密钥的指示信息，请查看导入根密钥或导入标准密钥。
要了解有关以编程方式管理密钥的更多信息，请查看 Hyper Protect Crypto Services 密钥管理服务 API 参考文档。