使用 Vault API 管理金鑰值密碼

透過 IBM Cloud® Secrets Manager，您可以管理每個金鑰的多個版本，並透過 HashiCorp Vault HTTP API 存取金鑰 -值密碼 的歷史和元資料。

Secrets Manager 支援 HashiCorp Vault KV Secrets Engine Version 2 API。 有關 KV v2 API 的詳細資訊，請參閱 Vault KV v2 文件。

概觀

如果您已使用 Vault API，則可以使用其 API 格式及準則來與 Secrets Manager互動。Secrets Manager 僅支援 KV 第 2 版。 Vault 文件 中定義之金鑰值密碼引擎的端點與 CLI 及其他適用工具相容。

有關認證的詳細資訊，請參閱 Vault API。

若要將標準 REST API 用於 Secrets Manager，請查看 Secrets Manager API 參考資料。

KV 與 Secrets Manager 之間的差異

Secrets Manager 使用的鍵值密碼引擎與 Vault 的 KV 密碼引擎略有不同。

  • 您無法完全自訂路徑。 金鑰值密碼的路徑必須是:
    • {secret_group_id}/{secret_name} 適用於位於自訂密鑰群組中的密鑰。
    • /{secret_name} 適用於預設群組中的密鑰。
  • Vault 上用來 配置金鑰值引擎 及 讀取配置 的方法不受支援。

建立或更新金鑰值密碼

建立金鑰值密碼的版本。

要求範例

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 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。
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
}

讀取金鑰值密碼的版本

取得鍵值秘訣的版本。 成功要求會傳回與密鑰指定版本相關聯的密鑰資料，以及其他 meta 資料。

要求範例

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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
version 您要讀取的版本。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

在 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}'
刪除最新版本的key-value Secret請求參數
要求參數 說明
instance_id Secrets Manager 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

刪除 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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。
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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。
versions 您要刪除的金鑰值密碼版本。

回應範例

在 default 密鑰群組中還原金鑰值密鑰版本的要求會傳回具有 204 狀態碼的空白回應，以確認已還原指定的版本。

銷毀版本的秘密

永久地毀損鍵值密碼的指定版本。 若要改為軟刪除密鑰的版本，請使用 delete specified versions API 端點。

要求範例

curl -X POST 'https://{instance_id}.{region}.secrets-manager.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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。
versions 您要永久毀損的金鑰值密碼版本。

回應範例

在 default 密鑰群組中永久毀損金鑰值密鑰版本的要求會傳回空白回應，並傳回 204 狀態碼，以確認該密鑰的版本已毀損。

建立或更新金鑰值密碼 meta 資料

建立或更新鍵值密碼的 meta 資料，例如版本數目上限或其他自訂值。 若要更新密鑰的實際內容，請使用 建立或更新密鑰 方法。

要求範例

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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

用於更新 default 密鑰群組中金鑰值密鑰的 meta 資料的要求會傳回具有 204 狀態碼的空白回應，以確認密鑰的 meta 資料已更新。

讀取金鑰值密碼的 meta 資料

透過指定版本的 ID，取得金鑰值密碼的 meta 資料。

要求範例

curl -X GET '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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

取得 default 密鑰群組中金鑰值密鑰的 meta 資料的要求會傳回下列回應:

{
    "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
}

刪除鍵值密鑰的 meta 資料及所有版本

永久刪除指定鍵值密碼的 meta 資料及所有版本資料。 當您使用此 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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
secret_name 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

刪除 default 密鑰群組中金鑰值密鑰的 meta 資料及所有版本的要求會傳回下列回應:

{
    "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 動詞來取得鍵名清單。 您只能在 Vault 的 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 實例的 ID。
region 在其中建立 Secrets Manager 實例的地區。
Vault-Token 從 Vault 擷取的鑑別記號。

回應範例

列出 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 鍵值秘訣的名稱。
Vault-Token 從 Vault 擷取的鑑別記號。
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
}