导入根密钥

您可以使用 IBM® Key Protect for IBM Cloud® 通过导入现有根密钥来保护和管理这些密钥。

根密钥是用于保护云中已加密数据的安全性的对称密钥打包密钥。有关将根密钥导入到 Key Protect 之中的更多信息，请参阅将自己的加密密钥引入到云。

通过查看创建和加密密钥资料的选项提前计划导入密钥。为了提高安全性，您可以在将密钥材料导入云之前，使用导入令牌加密密钥材料，从而启用密钥材料的安全导入。

通过控制台导入根密钥

创建服务实例后，请完成以下步骤以使用 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。
密钥描述	可选。描述是一种有用的方法，用于以无法使用别名或其名称的方式添加有关密钥的信息 (例如，描述其用途的短语)。此描述必须至少为两个字符且不超过 240 个字符，并且以后不能更改。为保护您的隐私，请勿使用个人数据 (例如您的姓名或位置) 作为密钥的描述。
密钥别名	可选。密钥别名是描述密钥的方法，该密钥允许在显示名称限制之外对其进行标识和分组。密钥最多可以有五个别名。
密钥环	可选。密钥环是允许根据需要独立管理这些分组的密钥分组。每个密钥都必须是密钥环的一部分。如果未选择密钥环，那么密钥将放在 `default` 密钥环中。请注意，要将您正在创建的密钥放在密钥环中，您必须具有该密钥环上的管理者角色。有关角色的更多信息，请查看管理用户访问权。

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

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

使用 API 导入根密钥

通过对以下端点进行 POST 调用，将对称密钥导入到 Key Protect。

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" \
    -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添加根密钥所需的变量。应用程序接口
变量	描述
区域	需要。地区缩写，如 `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 `false`, the service designates the key as a root key that you can use for wrap or unwrap operations.

为保护个人数据的机密性，在向服务添加密钥时，避免输入个人可标识信息 (PII)，例如，姓名或位置。

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

可选：运行以下调用以浏览Key Protect实例中的密钥，从而验证是否已添加密钥。

$ 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>"

Base64-encoding 密钥资料

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

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

使用此过程来加密文件中密钥材料的内容。

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

描述对密钥材料进行base64-encode所需的变量。
变量	描述
Infile	密钥材料字符串所在的文件的名称。确保密钥的长度为 16,24 或 32 字节，对应于 128,192 或 256 位长度。密钥必须是 base64-encoded。
输出文件	运行命令后将在其中创建 base64-encoded 密钥资料的文件的名称。

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

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

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

下载并安装 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应用程序接口参考文档。