手动旋转按键

您可以使用IBM® Key Protect for IBM Cloud® 手动旋转根密钥。

旋转根键时，会在键上添加新的键材料。这个过程会创建一个新的密钥版本，你可以用它来重新封装或加密数据。

要了解密钥轮换如何帮助您符合行业标准和加密最佳实践，请参阅轮换加密密钥。

轮换仅适用于根密钥。要了解有关 Key Protect 中密钥轮换选项的更多信息，请查看比较密钥轮换选项。

在控制台中旋转根键

创建根密钥后，请完成以下步骤旋转密钥：

登录IBM Cloud控制台。
转到菜单>资源清单查看资源列表。
从 IBM Cloud 资源列表中，选择您供应的 Key Protect 实例。
在应用程序详细信息页面中，使用密钥表来浏览服务中的密钥。如果有很多按键，可以使用搜索栏缩小搜索范围，只搜索已启用的按键（因为其他类型的按键不能旋转）、特定按键环中的按键以及具有特定别名的按键。
找到按键后，点击 ⋯ 图标，打开要旋转的按键的选项列表。
在选项菜单中，单击旋转打开旋转侧面板。
在 “管理轮换策略”下，选择所需的 30 天密钥轮换间隔。例如，如果某个密钥被设置为每 2 个月轮换一次，那么无论某个月有多少天，它都将每 60 天轮换一次。
单击设置策略建立此策略。如果要立即旋转按键，请单击旋转按键。注意：这些行动并不相互排斥。

仅对于导入的根密钥，必须添加要在服务中存储和管理的base64编码密钥材料。确保密钥材料为 128、192 或 256 位，数据字节（例如，256 位为 32 字节）使用base64编码。

使用应用程序接口旋转根密钥

您可以通过 POST 调用以下端点来旋转根键。

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

读取验证凭据，以便在服务中使用密钥。
复制要轮换的根密钥的标识。

您可以在您的 Key Protect实例，方法是检索密钥列表、或访问Key Protect实例。仪表盘。

用新的钥匙材料更换钥匙，方法如下 curl 指挥。

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/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>"
        }'

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

描述在Key Protect 中旋转指定密钥所需的变量。
变量	描述
区域	需要。 The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. 有关更多信息，请参阅区域服务端点。
keyID_or_alias	需要。要旋转的根密钥的唯一标识符或别名。
IAM_token	需要。您的 IBM Cloud 访问令牌。在 curl 请求中包含 IAM 令牌的全部内容，包括承载器值。 For more information, see 读取访问令牌.
instance_ID	需要。分配给Key Protect服务实例的唯一标识符 For more information, see 检索实例 ID.
键环 ID	可选。钥匙所属钥匙圈的唯一标识符。如果未指定，Key Protect将在与指定实例关联的每个钥匙圈中搜索钥匙。建议指定钥匙圈 ID，以优化请求注意：创建的密钥不带 `x-kms-key-ring` 标头，其密钥环 ID 为：default For more information, see 分组键.
key_material	可选要在服务中存储和管理的新base64编码密钥材料。如果最初在将密钥添加到服务时导入了密钥资料，那么此值是必需的。 To rotate a key that was initially generated by Key Protect, omit the payload attribute and pass an empty request entity-body. To rotate an imported key, provide a key material that meets the following requirements: The key must be 128, 192, or 256 bits. 数据字节（例如，对于 256 位，为 32 个字节）必须使用 Base64 编码进行编码。

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

可选：验证钥匙旋转

您可以通过发出密钥列表请求来验证密钥是否已被轮换：

$ 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 令牌。

查看响应实体体中的 lastRotateDate 和 keyVersion 值实体正文中的 * 和 * 值，查看密钥最后一次旋转的日期和时间。

{
    "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:kms: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": "Deprecated",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "algorithmBitSize": 256,
            "algorithmMode": "Deprecated",
            "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
        }
    ]
}

The keyVersion attribute contains identifying information that describes the latest version of the root key.

您还可以使用 Key ProtectAPI. 要了解更多信息，请参阅查看关键版本。

使用导入标记旋转密钥

如果你最初是通过导入令牌导入根密钥的，那么你可以通过调用以下端点来旋转调用以下端点 POST

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

检索您的身份验证凭据，以便在服务中使用密钥。

要旋转密钥，必须为实例或密钥分配_写入_ _器或管理器_访问策略。实例或密钥。要了解 IAM 角色如何映射到 Key Protect服务操作，请查看服务访问角色。
读取要旋转的键的 ID。

您可以通过输入 GET /v2/keys 来检索指定键的 ID 请求，或在 Key Protect仪表盘。
创建和检索导入令牌。
使用导入令牌对要用于旋转现有密钥的密钥材料进行加密。旋转现有密钥。

要了解如何使用导入标记，请查看教程：创建和导入加密密钥。

用新钥匙材料替换现有钥匙，方法如下 curl command.

$ curl -X POST \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys/<keyID_or_alias>/actions/rotate" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -d '{
            "type": "application/vnd.ibm.kms.key+json",
            "name": "<key_alias>",
            "description": "<key_description>",
            "extractable": <key_type>,
            "payload": "<encrypted_key>",
            "encryptionAlgorithm": "RSAES_OAEP_SHA_256",
            "encryptedNonce": "<encrypted_nonce>",
            "iv": "<iv>"
        }'

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

描述了旋转具有导入标记的密钥所需的变量。
变量	描述
区域	需要。地区缩写，如 `us-south` 或 `eu-gb`，表示您的Key Protect实例residesS 所在的地理区域 For more information, see 区域服务终端.
keyID_or_alias	需要。要旋转的密钥的唯一标识符或别名。
IAM_token	需要。您的 IBM Cloud 访问令牌。在curl请求中包含IAM令牌的全部内容，包括承载器值 For more information, see 读取访问令牌.
instance_ID	需要。分配给Key Protect服务实例的唯一标识符 For more information, see 检索实例 ID.
key_alias	需要。密钥的人类可读的唯一名称，以便可轻松识别密钥。为保护隐私，请不要将个人数据存储为密钥的元数据。
key_description	可选项：对密钥的扩展描述。为保护隐私，请不要将个人数据存储为密钥的元数据。
加密密钥	需要。要在服务中存储和管理的加密密钥材料。值必须使用base64编码。 Ensure that the key material meets the following requirements: The key must be 128, 192, or 256 bits.The bytes of data, for example 32 bytes for 256 bits, must be encoded by using base64 encoding.
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.
加密的非货币	需要。 GCM加密 nonce，确保您作为请求的一部分发送的比特与我们收到的完全一致。 nonce 验证您正在恢复的密钥 To learn more, see 教程：创建和导入加密密钥.
IV	需要。 GCM算法在加密 nonce 时生成的初始化向量 (IV)。该值用于解码密钥，以便存储在Key Protect系统中 To learn more, see 教程：创建和导入加密密钥.

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

可选：验证导入令牌密钥轮换

您可以通过发出获取密钥元数据请求来验证通过导入令牌导入的密钥是否已被旋转：

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

其中 <keyID_or_alias> 是密钥的 ID 或别名，<instance_ID> 是你的实例名称，你的 <IAM_token> 是你的 IAM 令牌。

查看响应实体体中的 lastRotateDate 和 keyVersion 值实体正文中的 * 和 * 值，查看密钥最后一次旋转的日期和时间。

您还可以使用 Key ProtectAPI. 要了解更多信息，请参阅查看关键版本。