IBM Cloud Docs
使用保险库文件 API 管理密钥值私钥

使用保险库文件 API 管理密钥值私钥

通过 IBM Cloud® Secrets Manager，您可以管理每个密钥的多个版本，并使用 HashiCorp Vault HTTP API 访问 键值密文 的历史和元数据。

概述

如果已使用保险库文件 API，那么可以使用其 API 格式和准则与 Secrets Manager进行交互。Secrets Manager 仅支持 KV 版本 2。 保险库文件文档 中定义的密钥值私钥引擎的端点与 CLI 和其他适用工具兼容。

有关身份验证的更多信息，请参阅 Vault API。

要将标准 REST API 用于 Secrets Manager，请查看 Secrets Manager API 参考。

KV 与 Secrets Manager 之间的差异

Secrets Manager 使用的键值私钥引擎与保险库文件的 KV 私钥引擎略有不同。

  • 您无法完全定制路径。 键值私钥的路径必须是:
    • {secret_group_id}/{secret_name} 表示位于定制私钥组中的私钥。
    • /{secret_name} 表示缺省组中的私钥。
  • 不支持保险库文件上用于 配置键值引擎 和 读取配置 的方法。

创建或更新密钥值私钥

创建密钥值私钥的版本。

示例请求

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'
创建或更新键值秘密请求参数
请求参数 描述
instance_id Secrets Manager 实例的 ID。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。
data 必需。 要分配给私钥的 JSON 格式的私钥数据。 最大文件大小为 512 KB。

示例响应

更新 default 私钥组中的密钥值私钥的请求将返回以下响应:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

读取密钥值私钥的版本

获取键值密文的版本。 成功的请求将返回与指定版本的私钥相关联的私钥数据以及其他元数据。

示例请求

curl -X GET 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}?version={version}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'
读取键值密文请求参数的版本
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
version 要读取的版本。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

在 default 私钥组中获取密钥值私钥版本的请求将返回以下响应:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "data": {
            "key": "value"
        },
        "metadata": {
            "created_time": "2022-01-13T21:31:49.893962888Z",
            "deletion_time": "",
            "destroyed": false,
            "version": 1
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

删除密钥值私钥的最新版本

删除密钥值私钥的最新版本。 删除版本后，无法使用 list 或 get API 调用来检索该版本。 但是，这是软删除，不会除去底层数据。 您可以通过调用 undelete API 端点来撤销删除。

示例请求

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}'
删除键值密文请求参数的最新版本
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

删除 default 私钥组中密钥值私钥的最新版本的请求会返回带有 204 状态码的空白响应，以确认已删除最新版本。

删除密钥值私钥的指定版本

删除密钥值私钥的指定版本。 删除版本后，无法使用 list 或 get API 调用来检索这些版本。 但是，这是软删除，不会除去底层数据。 您可以通过调用 undelete API 端点来撤销删除。

示例请求

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/delete/test-kv' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -d '{
            "versions": [1, 2]
            }'
删除键值密文请求参数的指定版本
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。
versions 要删除的指定版本。

示例响应

请求在 default 私钥组中删除指定版本的密钥值私钥将返回以下响应:

{
    "request_id": "43abde16-6a33-971f-1690-469eccc00d91",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

取消删除密钥值私钥

复原先前删除的密钥值私钥版本。

示例请求

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/undelete/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [
                1, 2
                ]
            }
删除键值密文请求参数的一个版本
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。
versions 要删除的密钥值私钥的版本。

示例响应

用于在 default 私钥组中复原密钥值私钥版本的请求会返回带有 204 状态码的空白响应，以确认已复原指定版本。

销毁秘密版本

永久销毁指定版本的密钥值私钥。 要改为软删除私钥的版本，请使用 delete specified versions API 端点。

示例请求

curl -X POST 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/destroy/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "versions": [1, 3]
            }'
销毁键值密文请求参数的版本
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。
versions 要永久销毁的密钥值私钥的版本。

示例响应

在 default 私钥组中永久销毁密钥值私钥版本的请求会返回带有 204 状态码的空白响应，以确认该私钥的版本已销毁。

创建或更新密钥值私钥元数据

创建或更新密钥值私钥的元数据，例如最大版本数或其他定制值。 要更新私钥的实际内容，请使用 创建或更新私钥 方法。

示例请求

curl -X POST 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "custom_metadata": {
                "meta1": "data1",
                "meta2": "data2"
                }
            }'
更新键值密文请求参数的元数据
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

用于更新 default 私钥组中密钥值私钥的元数据的请求将返回带有 204 状态码的空白响应，以确认已更新私钥的元数据。

读取 key-value 私钥的元数据

通过指定版本的标识来获取密钥/值私钥的元数据。

示例请求

curl -X GET 'https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'
读取键值密文请求参数的元数据
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

获取 default 私钥组中密钥值私钥的元数据的请求将返回以下响应:

{
    "request_id": "400000-60000-8e000-0ad0-00000bc0000caebe",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cas_required": false,
        "created_time": "2022-01-13T21:31:49.893962888Z",
        "current_version": 3,
        "custom_metadata" : {
              "meta1": "data1",
              "meta2": "data2"    
        },
        "delete_version_after": "0s",
        "max_versions": 0,
        "oldest_version": 0,
        "updated_time": "2022-02-09T23:54:16.313286558Z",
        "versions": {
            "1": {
                "created_time": "2022-01-13T21:31:49.893962888Z",
                "deletion_time": "",
                "destroyed": false
            },
            "2": {
                "created_time": "2022-02-09T23:41:58.888138788Z",
                "deletion_time": "",
                "destroyed": false
            },
            "3": {
                "created_time": "2022-02-09T23:54:16.313286558Z",
                "deletion_time": "",
                "destroyed": false
            }
        }
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

删除密钥值私钥的元数据和所有版本

永久删除指定密钥值私钥的元数据和所有版本数据。 使用此 API 端点时，将除去所有版本历史记录。

示例请求

curl -X DELETE 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/metadata/{secret_name}' \
    -H 'Accept: application/json'
    -H 'X-Vault-Token: {Vault-Token}'
删除键值密文请求参数的元数据
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

在 default 私钥组中删除密钥值私钥的元数据和所有版本的请求将返回以下响应:

{
    "request_id": "62b1e2c2-801a-6592-0526-edb38896a546",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

列出密钥值私钥的密钥名称

获取密钥值私钥的密钥名称列表。 请勿对密钥名称中的敏感信息进行编码。 无法使用此命令来访问密钥的值。

在 {sm-short} 中，不能使用 LIST HTTP verb 来获取键名列表。 只能在保险库文件的 KV API 中执行此操作。

示例请求

curl -X GET "https://{instance_id}.{region}.secrets-manager.test.appdomain.cloud/v1/ibmcloud/kv/metadata/?list=true" \
    -H 'Accept: application/json'\
    -H 'X-Vault-Token: {Vault-Token}'
列出键值密文请求参数的键名
请求参数 描述
instance_id Secrets Manager 实例的标识。
region 在其中创建 Secrets Manager 实例的区域。
Vault-Token 从保险库文件检索到的认证令牌。

示例响应

用于列出 default 私钥组中的密钥值私钥的密钥名称的请求将返回以下响应:

{
    "request_id": "a21993df-a4b7-21f1-95a9-c1af7be87d1b",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "secret1",
            "secret2"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

修补密钥值私钥

通过仅提供要更改的详细信息来更新现有密钥值私钥。 当您修补密钥时，将创建新版本。 任何未更改的数据都将与先前版本的私钥中的数据完全相同。

示例请求

curl -X PATCH 'https://{instance_id}.{region}.secrets-manager.appdomain.cloud/v1/ibmcloud/kv/data/{secret_name}' \
    -H 'Accept: application/json' \
    -H 'X-Vault-Token: {Vault-Token}' \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
            "data": {
                "key":"value"
            }
    }'
创建或更新键值秘密请求参数
请求参数 描述
instance_id Secrets Manager 实例的 ID。
region 在其中创建 Secrets Manager 实例的区域。
secret_name key-value 私钥的名称。
Vault-Token 从保险库文件检索到的认证令牌。
data 必需。 要用于修补私钥的 JSON 格式的私钥数据。 最大文件大小为 512 KB。

示例响应

更新 default 私钥组中的密钥值私钥的请求将返回以下响应:

{
    "request_id": "9000000d4-f0000-4c000-000000-800000000f",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "created_time": "2022-02-09T23:41:58.888138788Z",
        "deletion_time": "",
        "destroyed": false,
        "version": 2
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}