IBM Cloud Docs
管理私钥版本

管理私钥版本

在 IBM Cloud® Secrets Manager 中旋转密文时，会创建一个新版本的密文值。 您可以使用 IBM Cloud® Secrets Manager 来查看版本历史记录并更新私钥的版本元数据。 如果您意外地替换或覆盖私钥，那么还可以将其复原到先前版本。

准备工作

开始之前，请确保您具有所需的访问级别。 要更新私钥版本的元数据或将私钥复原到其先前版本，您需要 写入者 服务角色或更高版本。 要查看私钥的版本历史记录，您需要 读者 服务角色或更高版本。

查看私钥的版本历史记录

在 IBM Cloud® Secrets Manager 中旋转密文时，会创建一个新版本的密文值。 您可以使用 UI 或 API 快速检查私钥的版本历史记录。

Secrets Manager 为审计目的保留多达 50 个版本的秘密，包括秘密元数据。 不过，只有当前版本和紧接其前的版本才包含秘密数据，早期版本则不包含。

在 UI 中查看版本历史记录

如果您正在审计私钥的版本历史记录，那么可以使用 Secrets Manager UI 来查看每个轮换的一般特征。

  1. 在控制台中，单击 菜单 图标 "菜单" 图标 > 资源列表。
  2. 从服务列表中，选择 Secrets Manager的实例。
  3. 在 Secrets Manager UI 中，转至 密钥 列表。
  4. 在要检查的私钥所在的行中，单击 操作 菜单 "操作" 图标 > 版本历史记录。
  5. 可选: 更新您正在查看的特定私钥版本的元数据。
    1. 要更新私钥版本的元数据，请上载文件或以 JSON 格式输入元数据和版本元数据。
    2. 单击更新。

从 CLI 列出私钥版本

如果您正在审计私钥的版本历史记录，那么可以使用 Secrets Manager CLI 插件来查看每个旋转的一般特征。

要列出与私钥关联的所有版本，请运行 ibmcloud secrets-manager secret-versions 命令。 SECRET_TYPE 的选项有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

ibmcloud secrets-manager secret-versions --secret-id SECRET-ID

该命令输出有关当前版本和先前版本的信息。 例如，创建每个版本的日期。 有关命令选项的更多信息，请参阅 ibmcloud secrets-manager secret-versions。

使用 API 列出私钥版本

如果您正在审计私钥的版本历史记录，那么可以使用 Secrets Manager API 来查看每个轮换的一般特征。

以下示例请求列出了每个版本的元数据属性。 调用 API 时，请将 ID 变量和 IAM 令牌替换为 Secrets Manager 实例的特定值。 {secret_type} 的选项有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

curl -X GET
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

成功响应将返回有关每个私钥版本的元数据详细信息。

{
  "versions": [
    {
      "created_at": "2022-06-27T11:58:15Z",
      "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
      "expiration_date": "2023-10-05T11:49:42Z",
      "id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
      "payload_available": true,
      "secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
      "secret_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
      "secret_name": "example-imported-certificate",
      "secret_type": "imported_cert",
      "serial_number": "38:eb:01:a3:22:e9:de:55:24:56:9b:14:cb:e2:f3:e3:e2:fb:f5:18",
      "validity": {
        "not_after": "2023-10-05T11:49:42Z",
        "not_before": "2022-06-27T11:58:15Z"
      },
      "version_custom_metadata": {
        "custom_version_key": "custom_version_value"
      }
    }
  ],
  "total_count": 1
}

downloaded 属性指示是否已读取或访问每个私钥版本的数据。 如果 payload_available 字段的值为 true，那么表示您能够访问或 复原该版本的私钥数据。 有关必需和可选请求参数的更多信息，请查看 API 参考。

您可以使用 version_custom_metadata 请求参数来存储与组织需求相关的元数据。 机密的自定义元数据与所有其他元数据一样存储，不得包含机密数据。 有关必需和可选请求参数的更多信息，请查看 API 参考。

在 UI 中更新私钥版本元数据

您可以使用 Secrets Manager UI 更新特定密钥版本的元数据。

要更新保密版本的元数据，请完成以下步骤。

  1. 在控制台中，单击 菜单 图标 "菜单" 图标 > 资源列表。

  2. 从服务列表中，选择 Secrets Manager的实例。

  3. 在 Secrets Manager UI 中，转至 密钥 列表。

  4. 在要检查的私钥所在的行中，单击 操作 菜单 "操作" 图标 > 版本历史记录。

    如果先前轮换了私钥，那么页面将显示有关当前版本和先前版本的信息，例如创建每个版本的日期。

  5. 上载文件或输入 JSON 格式的元数据和版本元数据。

  6. 单击更新。

从 CLI 更新私钥版本元数据

您可以使用 Secrets Manager CLI 插件来更新特定版本的私钥的元数据。

要更新私钥的元数据，请运行 ibmcloud secrets-manager secret-metadata-update 命令。

以下示例显示了 ibmcloud secrets-manager secret-metadata-update 命令的格式。

ibmcloud secrets-manager secret-version-metadata-update --secret-id SECRET-ID --id VERSION-ID --version-custom-metadata='{"anyKey": "anyValue"}'

使用 API 更新私钥版本元数据

如果要更新私钥版本的元数据，那么可以使用 Secrets Manager API。

以下示例请求更新每个版本的元数据属性。 调用 API 时，请将 ID 变量和 IAM 令牌替换为 Secrets Manager 实例的特定值。 {secret_type} 的选项有 arbitrary, iam_credentials, imported_cert, kv, private_cert, public_cert, service_credentials, custom_credentials，和 username_password。

curl -X PATCH  
  -H "Authorization: Bearer {iam_token}" \
  -H "Accept: application/json" \
  --H "Content-Type: application/merge-patch+json" \
  -d '{ "version_custom_metadata": { "version_special_id" : "someString" } }' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions/{version_id}/metadata"

成功响应将返回有关每个私钥版本的元数据详细信息。

{
  "alias": "current",
  "created_at": "2022-06-27T11:58:15Z",
  "created_by": "iam-ServiceId-e4a2f0a4-3c76-4bef-b1f2-fbeae11c0f21",
  "expiration_date": "2023-10-05T11:49:42Z",
  "id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712",
  "payload_available": true,
  "secret_group_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
  "secret_id": "67d025e1-0248-418f-83ba-deb0ebfb9b4a",
  "secret_name": "example-arbitrary-secret",
  "secret_type": "arbitrary",
  "version_custom_metadata": {
    "custom_version_key": "custom_version_value"
  }
}

downloaded 属性指示是否已读取或访问每个私钥版本的数据。 如果 payload_available 字段的值为 true，那么表示您能够访问或 复原该版本的私钥数据。

您可以使用 version_custom_metadata 请求参数来存储与组织需求相关的元数据。 机密的自定义元数据与所有其他元数据一样存储，不得包含机密数据。 有关必需和可选请求参数的更多信息，请查看 API 参考

将私钥复原到先前版本

是否意外地替换或覆盖现有私钥? 您可以使用 IBM Cloud® Secrets Manager 来立即回滚到先前版本。

将私钥复原到其先前版本时，将创建新版本的私钥。 例如，如果私钥的当前版本为 3，并且您回滚到 V 2，那么从 V 2 复原的数据将变为 V 4。

您可以在 受支持的密钥类型 上复原一个版本。 出于审计目的，服务针对每个私钥保留最多 50 个版本的元数据，您可以在私钥的 版本历史记录 中查看这些元数据。

受支持的密钥类型

IAM 凭证 支持复原到先前版本。

在 UI 中复原先前版本

您可以使用 Secrets Manager UI 将私钥复原到其先前版本。

  1. 在控制台中，单击 菜单 图标 "菜单" 图标 > 资源列表。

  2. 从服务列表中，选择 Secrets Manager的实例。

  3. 在 Secrets Manager UI 中，转至 密钥 列表。

  4. 在要检查的私钥所在的行中，单击 操作 菜单 "操作" 图标 > 版本历史记录。

    如果先前轮换了私钥，那么页面将显示有关当前版本和先前版本的信息。

  5. 单击要复原的私钥版本旁边的 操作 菜单 "操作" 图标 > 复原。

    目前，只能复原 IAM 凭证密钥类型的一个版本。 仅当未达到定义的生存时间 (TTL) 或租赁持续时间时，才能复原私钥版本。 如果未看到可用选项，那么不支持复原版本。

从 CLI 复原先前版本

您可以使用 Secrets Manager CLI 将私钥复原到其先前版本。

以下示例命令将复原私钥的先前版本。 调用该命令时，请将 secreT_ID 变量替换为特定于 Secrets Manager 实例的值。

ibmcloud sm secret-version-create --secret-d SECRET_ID --secret-version-restore-from-version "previous"

目前，只能复原 IAM 凭证和导入的证书密钥的一个版本。 仅当未达到定义的生存时间 (TTL) 或租赁持续时间时，才能复原私钥版本。

成功响应将返回该私钥的值以及其他元数据。 有关必需和可选请求参数的更多信息，请参阅 API 参考。

使用 API 复原先前版本

您可以使用 Secrets Manager API 将私钥复原到其先前版本。

以下示例请求将复原私钥的先前版本。 调用 API 时，请将 ID 变量和 IAM 令牌替换为 Secrets Manager 实例的特定值。 {secret_type} 的允许值为: iam_credentials。

要列出私钥的版本并获取每个版本的标识，请使用 列出版本 API。

curl -X POST
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
         "restore_from_version": "previous",
         "custom_metadata": {
            "metadata_custom_key": "metadata_custom_value"
         },
         "version_custom_metadata": {
            "custom_version_key": "custom_version_value"
         }
      }' \
   "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/versions"

目前，只能复原 IAM 凭证和导入的证书密钥的一个版本。 仅当未达到定义的生存时间 (TTL) 或租赁持续时间时，才能复原私钥版本。

成功响应将返回该私钥的值以及其他元数据。 有关必需和可选请求参数的更多信息，请参阅 API 参考。