使用根密钥包装数据加密密钥

如果您是特权用户，那么可以使用 IBM Cloud® Hyper Protect Crypto Services 密钥管理服务 API 通过根密钥A symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service. 来管理和保护加密密钥。

将数据加密密钥(DEK)A cryptographic key used to encrypt data that is stored in an application. 与根密钥合并时，Hyper Protect Crypto Services 会结合多种算法的强大功能，以保护加密数据的隐私和完整性。

要了解密钥打包如何帮助您控制云中静态数据的安全性，请参阅包络加密。

使用 API 打包密钥

可以使用在 Hyper Protect Crypto Services 中管理的根密钥来保护指定的数据加密密钥 (DEK)。

在提供用于打包的根密钥时，请确保根密钥为 128 位、192 位或 256 位，这样打包调用才能成功。如果在服务中创建根密钥，那么 Hyper Protect Crypto Services 将根据 AES-CBC 算法支持的 HSM 生成 256 位密钥。

在服务中指定根密钥后，可以通过对以下端点发出 POST 调用以高级加密方式来打包 DEK。

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

检索服务和认证凭证以使用服务中的密钥。
复制要管理和保护的 DEK 的密钥资料。

如果您具有 Hyper Protect Crypto Services 服务实例的管理员或写程序特权，那么您可以通过发出 GET /v2/keys/<key_ID> 请求来检索特定密钥的密钥资料。
复制要用于打包的根密钥的标识。

运行以下 cURL 命令以使用打包操作保护密钥。

curl -X POST \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap' \
  -H 'accept: application/vnd.ibm.kms.key_action+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.key_action+json' \
  -H 'x-kms-key-ring: <key_ring_ID>' \
  -H 'correlation-id: <correlation_ID>' \
  -d '{
  "plaintext": "<data_key>"
}'

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

表 1. 描述打包指定键所需的变量
变量	描述
`region`	必需。区域缩写（例如，`us-south` 或 `au-syd`），表示 Hyper Protect Crypto Services 服务实例所在的地理区域。有关更多信息，请参阅区域服务端点。
`port`	必需。 API 端点的端口号。
`key_ID`	必需。要用于打包的根密钥的唯一标识。
`IAM_token`	必需。您的 IBM Cloud 访问令牌。在 cURL 请求中包含 `IAM` 令牌的完整内容，包括 Bearer 值。有关更多信息，请参阅检索访问令牌。
`instance_ID`	必需。指定给您的 Hyper Protect Crypto Services 服务实例的唯一标识。有关更多信息，请参阅检索实例标识。
`key_ring_ID`	可选。密钥所属的密钥环的唯一标识。如果未指定，那么 Hyper Protect Crypto Services 将在与指定实例关联的每个密钥环中搜索密钥。因此，建议为更优化的请求指定密钥环标识。注: 在没有 `x-kms-key-ring` 头的情况下创建的密钥的密钥环标识为: 缺省值。有关更多信息，请参阅管理密钥环。
`correlation_ID`	可选。用于跟踪和关联事务的唯一标识。
`data_key`	要管理和保护的 DEK 的密钥资料。 `plaintext` 值必须经过 base64 编码。要生成新的 DEK，请省略 `plaintext` 属性。该服务会生成随机纯文本 (32 字节)，对该值进行包装，然后在响应中返回生成的值和包装的值。生成的值和打包的值都是 base64 编码的，您将需要对它们进行解码以解密密钥。

在响应的 entity-body 中，会返回打包的数据加密密钥，其中包含 Base64 编码的密钥资料。响应主体还包含用于合并所提供纯文本的密钥版本的标识。以下 JSON 对象显示返回值示例。

{
  "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
  "keyVersion": {
    "id": "02fd6835-6001-4482-a892-13bd2085f75d"
  }
}

如果在发出打包请求时省略 plaintext 属性，服务会以 Base64 编码的格式返回生成的数据加密密钥 (DEK) 和打包的 DEK。

{
  "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
  "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
  "keyVersion": {
    "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
  }
}

plaintext 值表示未包装的 DEK，ciphertext 值表示已包装的 DEK，并且都是 base64 编码的。 keyVersion.id 值表示用于回绕的根密钥的版本。

如果想让 Hyper Protect Crypto Services 代表您生成新的数据加密密钥 (DEK)，您也可以在发出打包请求时传入空主体。在响应的 entity-body 中，会返回生成的 DEK（其中包含 Base64 编码的密钥资料）以及打包的 DEK。