在 UI 中旋转根密钥

如果您希望使用图形界面来轮换根密钥，那么可以使用 UI。

在创建根密钥或将现有根密钥导入到服务后，请完成以下步骤来轮换密钥：

1. 登录 UI。

2. 转至 菜单 > 资源列表 以查看资源列表。

3. 从 IBM Cloud 资源列表，选择 Hyper Protect Crypto Services 的已供应实例。

4. 在“KMS 密钥”页面上，使用 密钥 表来浏览服务中的密钥。

5. 选择要轮换的密钥，然后单击 操作 图标 以打开密钥的选项列表。

6. 从选项菜单中，单击 旋转键。

   如果最初为密钥提供了密钥资料，请指定要在服务中存储和管理的新的 base64 编码密钥资料。 确保密钥资料满足以下需求：

   • 必须是 128,192 或 256 位。
   • 数据字节（例如，对于 256 位，为 32 个字节）必须使用 Base64 编码进行编码。

7. 单击 旋转密钥 以确认。

使用 API 旋转根密钥

您可以通过对以下端点进行 POST 调用来轮换根密钥。

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

1. 检索服务和认证凭证以使用服务中的密钥。

2. 复制要轮换的根密钥的标识。

   您可以通过 检索密钥列表 或通过访问 UI 在服务实例中找到密钥的标识。

3. 通过运行以下 cURL 命令，将密钥替换为新的密钥资料。

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

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

   表 2. 描述在 Hyper Protect Crypto Services 中轮换指定键所需的变量

   变量	描述
   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 头的情况下创建的密钥的密钥环标识为: 缺省值。 有关更多信息，请参阅 管理密钥环。
   key_material	可选。 要在服务中存储和管理的新 base64 编码密钥资料。 如果最初在将密钥添加到服务时导入了密钥资料，那么此值是必需的。 要轮换最初由 Hyper Protect Crypto Services生成的密钥，请省略 payload 属性并传递空的请求实体主体。 要轮换导入的密钥，请提供满足以下需求的密钥资料: 密钥必须为 128,192 或 256 位。 数据字节（例如，对于 256 位，为 32 个字节）必须使用 Base64 编码进行编码。

   成功的轮换请求会返回 HTTP 204 No Content 响应，这表示根密钥已替换为新的密钥资料。

4. 可选：通过运行以下调用来浏览 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>' \
   

   查看响应 entity-body 中的 lastRotateDate 值，以检查密钥的上次轮换日期和时间。

   {
     "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",
         "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:50:12Z",
         "createdBy": "...",
         "algorithmType": "AES",
         "algorithmMetadata": {
           "bitLength": "256",
           "mode": "CBC_PAD"
         },
         "algorithmBitSize": 256,
         "algorithmMode": "CBC_PAD",
         "lastUpdateDate": "2020-03-12T03:50:12Z",
         "lastRotateDate": "2020-03-12T03:49:01Z",
         "keyVersion": {
           "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
           "creationDate": "2020-03-12T03:50:12Z"
         },
         "dualAuthDelete": {
           "enabled": false
         },
         "deleted": false
       }
     ]
   }
   

   keyVersion 属性包含用于描述最新版本的根密钥的标识信息。

   您还可以使用以下命令列出可用于密钥的版本: Hyper Protect Crypto Services 密钥管理服务 API。 要了解更多信息，请参阅 查看密钥版本。

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