导入标准密钥

您可以使用 IBM Cloud 控制台来添加现有加密密钥。

您可以使用 Key Protect API 以编程方式添加现有加密密钥。

通过控制台导入标准键盘

创建服务实例后，请完成以下步骤以使用 IBM Cloud 控制台导入现有密钥。

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

登录到 IBM Cloud 控制台。
转到菜单>资源清单查看资源列表。
从 IBM Cloud 资源列表中，选择您供应的 Key Protect 实例。
要导入新密钥，请单击添加密钥，然后选择导入自己的密钥窗口。

指定密钥的详细信息：

说明导入自己的密钥设置。
设置	描述
密钥类型	您希望在Key Protect 中管理的密钥类型。单击标准键按钮。
名称	人可读的别名，便于识别您的密钥。长度必须在 2 到 90 个字符之间 (包括在内)。为保护隐私，请确保密钥名称不包含个人可标识信息 (PII)，例如，姓名或位置。请注意，密钥名称不需要唯一。
密钥资料	要在服务中存储和管理的base64-encoded密钥材料，如现有的密钥包装密钥。有关更多信息，请查看 Base64 编码密钥资料。确保密钥资料的长度为 16,24 或 32 字节，并且对应于 128,192 或 256 位长度。该密钥还必须是 base64-encoded。
密钥别名	可选。密钥别名是描述密钥的方法，该密钥允许在显示名称限制之外对其进行标识和分组。密钥最多可以有五个别名。
密钥环	可选。密钥环是允许根据需要独立管理这些分组的密钥分组。每个密钥都必须是密钥环的一部分。如果未选择密钥环，那么密钥将放在 `default` 密钥环中。请注意，要将您正在创建的密钥放在密钥环中，您必须具有该密钥环上的管理者角色。有关角色的更多信息，请查看管理用户访问权。

填写完密钥详细信息后，单击导入密钥以进行确认。

如果您知道要将密钥放入哪个密钥环中，并且您是该密钥环的 管理者，那么还可以浏览到“密钥环”面板，选择 ... 并单击 将密钥添加到密钥环。这将打开您通过单击“密钥”页面上的添加而看到的相同面板，其中 密钥环 变量填充了密钥环的名称。

导入标准密钥

通过对以下端点发出 POST 调用来导入标准密钥：

https://<region>.kms.cloud.ibm.com/api/v2/keys

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

使用以下 curl 命令调用 Key Protect API。

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "content-type: application/vnd.ibm.kms.key+json" \
    -H "correlation-id: <correlation_ID>" \
    -H "prefer: <return_preference>" \
    -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": "<expiration_date>",
                    "payload": "<key_material>",
                    "extractable": <key_type>
                }
            ]
        }'

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

描述了使用Key Protect添加标准密钥所需的变量。API
变量	描述
区域	需要。地区缩写，如 `us-south` 或 `eu-gb`，表示您的Key Protect实例所在的地理区域 For more information, see 区域服务终端.
IAM_token	需要。您的 IBM Cloud 访问令牌。在curl请求中包含IAM令牌的全部内容，包括承载器值 For more information, see 读取访问令牌.
instance_ID	需要。分配给Key Protect服务实例的唯一标识符 For more information, see 检索实例 ID.
correlation_ID	用于跟踪和关联事务的唯一标识。
返回首选项	改变 POST 和 DELETE 操作服务器行为的标头 When you set the return_preference variable to return=minimal, the service returns only the key metadata, such as the key name and ID value, in the response entity-body. 将变量设置为 return=representation 时，服务会同时返回密钥材料和密钥元数据。
key_name	需要。密钥的人类可读的唯一名称，以便可轻松识别密钥。为保护隐私，请不要将个人数据存储为密钥的元数据。
alias_list	可选。分配给密钥的一个或多个唯一的人类可读别名。重要信息：为保护隐私，请勿将个人数据存储为密钥的元数据。每个别名必须是字母数字，区分大小写，并且不能包含空格或除-或 _ 以外的特殊字符。别名不能是 UUID，并且不能是 Key Protect 保留名称 :allowed_ip，key，metadata，policy 和 policy。注册，注册，环，环，旋转，包装，解包，重新包装，版本，版本。
key_description	可选项：对密钥的扩展描述。为保护隐私，请不要将个人数据存储为密钥的元数据。
到期日期	可选。系统中密钥到期的日期和时间，格式为 RFC 3339 (YYYY-MM-DD HH:MM:SS.SS，例如 2019-10-12T07:20:50.52Z)。密钥将在密钥到期日期后一小时内转换为取消激活状态。如果省略expirationDate属性，密钥不会过期。
key_material	必填。您要在服务中管理的base64-encoded密钥材料，如对称密钥。有关更多信息，请查看 Base64 编码密钥资料。确保密钥资料满足以下要求: 标准密钥的大小可达 7,500 字节。密钥必须是 base64-encoded。
key_type	布尔值，用于确定密钥资料是否可以离开服务。 When you set the extractable attribute to `true`, the service designates the key as a standard key that you can store in your apps or services.

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

成功的 POST api/v2/keys 响应会返回密钥的标识值以及其他元数据。 ID 是分配给密钥的唯一标识符。的唯一标识符，用于后续调用 Key Protect API。

可选: 验证标准密钥导入

您可以通过发出列表密钥请求来验证是否已导入标准密钥:

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

其中，<instance_ID> 是实例的名称，<IAM_token> 是 IAM 令牌。

Base64-encoding 密钥资料

导入现有标准密钥时，需要包含要在服务中存储和管理的加密密钥资料。

使用 OpenSSL 对现有密钥资料进行加密

要对密钥资料进行编码，首先应下载并安装 OpenSSL。

下载并安装 OpenSSL 后，建议使用两个命令对密钥资料进行编码。 Both methods are equivalent, in that they convert a string , whether <key_material_string> or 如下面所示，将其放入 base64 字符串中。如果您的资料位于文件中 (例如，您可能有一个包含凭证的文件，而不仅仅是加密密钥，您希望存储在 Key Protect中)，那么最佳选项是发出:

```sh {: pre}
openssl base64 -in <infile> -out <outfile>
```
Replace the variables in the example request according to the following table.

描述对密钥材料进行base64-encode所需的变量。
变量	描述
Infile	密钥材料字符串所在的二进制文件的名称。确保文件不超过 7,500 字节。
输出文件	运行命令后将在其中创建 base64-encoded 密钥资料的文件的名称。

如果要直接在命令行而不是文件中输出 base64 材料，请运行命令 openssl enc -base64 <<< '<key_material_string>'，其中 key_material_string 是导入的密钥的密钥材料输入。

如果要将不在文件中的 64 编码密钥资料作为基础，那么可以发出:

```sh {: pre}
echo -n <password> | base64
```
Where "password" is the key material you want to use.

要避免额外的字符 (例如，额外的新行)，最好将 base64 复制到剪贴板，尤其是在要在控制台中发布 base64 字符串时。

使用 OpenSSL 来创建和编码新的密钥资料

使用此过程来创建具有特定字节长度的随机 base64-encoded 密钥资料。建议使用 32 字节 (256 位)。

如果您希望标准密钥具有与根密钥相同的特征，那么将创建一个 16 字节，24 字节或 32 字节的密钥资料，以用作标准密钥。标准密钥是可以离开服务的密钥。标准密钥通常用于应用程序和服务中。

下载并安装 OpenSSL。
Base64-encode 密钥材料字符串，方法是运行以下命令:
```
openssl rand -base64 <byte_length>
```
根据下表替换示例请求中的变量表

描述创建和编码新密钥材料所需的变量。
变量	描述
byte_length	密钥的长度，以字节为单位可接受的字节长度为 16,24 或 32 字节，对应于 128,192 或 256 位长度。密钥必须是 base64-encoded。

密钥材料创建示例

openssl rand -base64 16 将生成 128 位密钥资料。
openssl rand -base64 24 将生成 192 位密钥资料。
openssl rand -base64 32 将生成 256 位密钥资料。

下一步

欲了解更多有关按程序管理按键的信息，请查看Key Protect应用程序接口参考文档。