KES API

API 概述

預設情況下，KES 要求任何 API 呼叫都必須使用有效的憑證。沒有憑證的請求將會失敗並顯示 TLS 錯誤。

您可以在 KES 設定檔中呼叫某些端點時，停用對有效憑證的要求。

如果任何端點不需要憑證，則失敗的呼叫會導致 HTTP 錯誤，而不是 TLS 錯誤。

API
`/version`	取得版本資訊。
`/ready`	傳回 KES 伺服器就緒狀態。
`/v1/api`	取得支援的 API 端點列表。
`/v1/metrics`	以 Prometheus 指標匯出格式取得伺服器指標。
`/v1/status`	取得伺服器狀態資訊。
金鑰 API
`/v1/key/create`	建立新的加密金鑰。
`/v1/key/import`	匯入加密金鑰。
`/v1/key/delete`	刪除加密金鑰。
`/v1/key/list`	列出加密金鑰。
`/v1/key/generate`	產生新的純文字/加密資料加密金鑰配對。
`/v1/key/encrypt`	使用金鑰加密（小）純文字。
`/v1/key/decrypt`	使用金鑰解密（小）密文。
`/v1/key/hmac`
原則 API
`/v1/policy/describe`	擷取關於原則的資訊。
`/v1/policy/read`	擷取原則。
`/v1/policy/list`	列出原則。
身分 API
`/v1/identity/describe`	擷取關於身分的資訊。
`/v1/identity/self/describe`	擷取關於發出請求的身分資訊。
`/v1/identity/list`	列出身分。
記錄 API
`/v1/log/audit`	訂閱稽核記錄。
`/v1/log/error`	訂閱錯誤記錄。

版本

方法	路徑	Content-Type
`GET`	`/version`	`application/json`

取得 KES 伺服器版本資訊。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/version'

範例回應

{
  "version": "2023-10-03T00-48-37Z",
  "commit": "9d1b5ad6dbdd963beabfbc91eb1ca0d330d5cd3d"
}

就緒

方法	路徑	Content-Type
`GET`	`/v1/ready`	`application/json`

KES 伺服器準備探測。如果 KES 已準備就緒，則會傳回 200 OK。

您可以在 KES 設定檔中停用呼叫此端點時需要有效憑證的要求。

範例請求

$ curl \
    -I \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/ready'

範例回應

HTTP/1.1 200 OK
Date: Sat, 28 Oct 2023 16:29:49 GMT
Content-Length: 0

API

方法	路徑	Content-Type
`GET`	`/v1/api`	`application/json`

取得伺服器支援的 API 端點清單。

您可以在 KES 設定檔中停用呼叫此端點時需要有效憑證的要求。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/api'

範例回應

[
  {
    "method": "GET",
    "path": "/version",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/status",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/metrics",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/api",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "PUT",
    "path": "/v1/key/create/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "PUT",
    "path": "/v1/key/import/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "DELETE",
    "path": "/v1/key/delete/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "PUT",
    "path": "/v1/key/generate/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "PUT",
    "path": "/v1/key/encrypt/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "PUT",
    "path": "/v1/key/decrypt/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/key/list/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/policy/describe/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/policy/read/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/policy/list/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/identity/describe/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/identity/self/describe",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/identity/list/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "GET",
    "path": "/v1/log/error",
    "max_body": 0,
    "timeout": 0
  },
  {
    "method": "GET",
    "path": "/v1/log/audit",
    "max_body": 0,
    "timeout": 0
  },
]

指標

方法	路徑
`GET`	`/v1/metrics`

取得伺服器指標。

例如，請求總數。指標以 Prometheus 公開格式傳回。

您可以在 KES 設定檔中停用呼叫此端點時需要有效憑證的要求。

# TYPE kes_http_request_active gauge
kes_http_request_active 0

# TYPE kes_http_request_error counter
kes_http_request_error 0

# TYPE kes_http_request_failure counter
kes_http_request_failure 0

# TYPE kes_http_request_success counter
kes_http_request_success 0

# TYPE kes_http_response_time histogram
kes_http_response_time_bucket{le="0.01"} 0
kes_http_response_time_bucket{le="0.05"} 0
kes_http_response_time_bucket{le="0.1"} 0
kes_http_response_time_bucket{le="0.25"} 0
kes_http_response_time_bucket{le="0.5"} 0
kes_http_response_time_bucket{le="1"} 0
kes_http_response_time_bucket{le="1.5"} 0
kes_http_response_time_bucket{le="3"} 0
kes_http_response_time_bucket{le="5"} 0
kes_http_response_time_bucket{le="10"} 0
kes_http_response_time_bucket{le="+Inf"} 0
kes_http_response_time_sum 0
kes_http_response_time_count 0

# TYPE kes_log_audit_events counter
kes_log_audit_events 0

# TYPE kes_log_error_events counter
kes_log_error_events 0

# TYPE kes_system_up_time gauge
kes_system_up_time 0

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/metrics'

範例回應

# HELP kes_http_request_active Number of active requests that are not finished, yet.
# TYPE kes_http_request_active gauge
kes_http_request_active 0
# HELP kes_http_request_error Number of request that failed due to some error. (HTTP 4xx status code)
# TYPE kes_http_request_error counter
kes_http_request_error 22462
# HELP kes_http_request_failure Number of request that failed due to some internal failure. (HTTP 5xx status code)
# TYPE kes_http_request_failure counter
kes_http_request_failure 0
# HELP kes_http_request_success Number of requests that have been served successfully.
# TYPE kes_http_request_success counter
kes_http_request_success 2.277925e+06
# HELP kes_http_response_time Histogram of request response times spawning from 10ms to 10s.
# TYPE kes_http_response_time histogram
kes_http_response_time_bucket{le="0.01"} 2.279745e+06
kes_http_response_time_bucket{le="0.05"} 2.291429e+06
kes_http_response_time_bucket{le="0.1"} 2.29555e+06
kes_http_response_time_bucket{le="0.25"} 2.299088e+06
kes_http_response_time_bucket{le="0.5"} 2.299715e+06
kes_http_response_time_bucket{le="1"} 2.300182e+06
kes_http_response_time_bucket{le="1.5"} 2.300256e+06
kes_http_response_time_bucket{le="3"} 2.300329e+06
kes_http_response_time_bucket{le="5"} 2.300364e+06
kes_http_response_time_bucket{le="10"} 2.300383e+06
kes_http_response_time_bucket{le="+Inf"} 2.300387e+06
kes_http_response_time_sum 3503.8908393496145
kes_http_response_time_count 2.300387e+06
# HELP kes_log_audit_events Number of audit log events written to the audit log targets.
# TYPE kes_log_audit_events counter
kes_log_audit_events 2.300387e+06
# HELP kes_log_error_events Number of error log events written to the error log targets.
# TYPE kes_log_error_events counter
kes_log_error_events 59
# HELP kes_system_up_time The time the server has been up and running in seconds.
# TYPE kes_system_up_time gauge
kes_system_up_time 837876.75

狀態

方法	路徑	Content-Type
`GET`	`/v1/status`	`application/json`

取得 KES 伺服器的目前狀態。如果伺服器啟動，則請求會傳回 200 OK 和一個描述狀態相關伺服器資訊的 JSON 文件。回應傳回的資訊包括下列內容

版本
正常執行時間（以秒為單位）
作業系統和 CPU 架構
目前記憶體消耗量
金鑰儲存區狀態
金鑰儲存區延遲（毫秒）

您可以在 KES 設定檔中停用呼叫此端點時需要有效憑證的要求。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/status'

範例回應

{
  "version": "2023-10-03T00-48-37Z",
  "os": "linux",
  "arch": "amd64",
  "uptime": 724306, // in seconds
  "num_cpu": 4,
  "num_cpu_used": 4,
  "mem_heap_used": 4960704,
  "mem_stack_used": 1081344,
  "keystore_latency": 1 // in milliseconds
}

金鑰 API

建立金鑰

方法	路徑	Content-Type
`PUT`	`/v1/key/create/<名稱>`	`application/json`

建立新的加密金鑰。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    'https://play.min.io:7373/v1/key/create/my-key'

匯入金鑰

方法	路徑	Content-Type
`PUT`	`/v1/key/import/<名稱>`	`application/json`

將加密金鑰匯入 KES 伺服器。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    --data '{"bytes":"uNta318uv2GvEmMs5U4HiIWE/GtrpADR0cYZg+nhrkI="}' \
    'https://play.min.io:7373/v1/key/import/my-key'

刪除金鑰

方法	路徑	Content-Type
`DELETE`	`/v1/key/delete/<名稱>`	`application/json`

刪除新的加密金鑰。

警告：這是一個危險的操作。刪除金鑰後，您無法解密由該金鑰加密的任何資料。此操作可能會導致資料遺失。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request DELETE \
    'https://play.min.io:7373/v1/key/delete/my-key'

金鑰清單

方法	路徑	Content-Type
`GET`	`/v1/key/list/<字首>`	`application/json`

列出所有金鑰名稱。指定一個可選字首，僅列出以該字首開頭的金鑰名稱。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/key/list/my-key'

範例回應

{
  "names": [ "key-0", "key-1", "key-2" ],
  "continue_at": "key-3" 
}

產生金鑰

方法	路徑	Content-Type
`PUT`	`/v1/key/generate/<名稱>`	`application/json`

產生新的資料加密金鑰 (DEK)。

DEK 是一個明文-密文配對。明文是一個隨機產生的金鑰，可用於加密操作，例如加密資料。密文是用 KES 伺服器上的金鑰 <名稱> 加密的明文。由於此金鑰永遠不會離開 KES 伺服器，因此只有 KES 伺服器才能解密產生的密文。

應用程式應使用明文 DEK 進行加密操作。應用程式應記住密文 DEK 以及使用了哪個金鑰 <名稱>。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    --data '{}' \
    'https://play.min.io:7373/v1/key/generate/my-key'

範例回應

{
  "plaintext": "TIDXCHZxPr84r7ktggCCW7otoz5T4zsRENi4THCjXPo=",
  "ciphertext": "eyJhZWFkIjoiQUVTLTI1Ni1HQ00iLCJpdiI6ImJWbHRZVDdpUEtxUjNFYWpvaHp3cmc9PSIsIm5vbmNlIjoiSWxqaHBNcWViUUF5d1MxbyIsImJ5dGVzIjoiYlpNL1liU0E4ZSswVnFSUDhaR2UvdDJHQThrbzRBeXcwNGZBam1KWkIxKzk2OTg4VXYwcFJmRjEvS3poM1hGeCJ9"
}

加密金鑰

方法	路徑	Content-Type
`PUT`	`/v1/key/encrypt/<name>`	`application/json`

使用加密金鑰解密並驗證小段純文字。純文字大小不得超過 1 MB。使用加密金鑰端點來包裝小量資料，例如另一個加密金鑰。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    --data '{"plaintext":"SGVsbG8gV29ybGQhCg=="}' \
    'https://play.min.io:7373/v1/key/encrypt/my-key'

範例回應

{
  "ciphertext": "eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaXYiOiIwUXJ0alUvWDJtUEtUK3A1R3JwdktRPT0iLCJub25jZSI6ImpxOGliYXVxKzY0dEZBM0kiLCJieXRlcyI6Im1MQ21hdzVxQW9acXpwOTJoMjZuRTJWR01BVkdCTTlJalNtT05SYz0ifQ=="
}

解密金鑰

方法	路徑	Content-Type
`PUT`	`/v1/key/decrypt/<name>`	`application/json`

使用加密金鑰解密密文。當且僅當密文為真且由指定金鑰產生時，才會傳回對應的純文字。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    --data '{"ciphertext":"eyJhZWFkIjoiQUVTLTI1Ni1HQ00iLCJpdiI6ImJWbHRZVDdpUEtxUjNFYWpvaHp3cmc9PSIsIm5vbmNlIjoiSWxqaHBNcWViUUF5d1MxbyIsImJ5dGVzIjoiYlpNL1liU0E4ZSswVnFSUDhaR2UvdDJHQThrbzRBeXcwNGZBam1KWkIxKzk2OTg4VXYwcFJmRjEvS3poM1hGeCJ9"}' \
    'https://play.min.io:7373/v1/key/decrypt/my-key'

範例回應

{
  "plaintext": "TIDXCHZxPr84r7ktggCCW7otoz5T4zsRENi4THCjXPo="
}

HMAC

方法	路徑	Content-Type
`PUT`	`/v1/key/hmac/`	`application/json`

計算請求中傳遞資料的訊息驗證碼 (MAC)。使用此功能來驗證訊息是否真實，或在啟動時產生相同的假隨機密碼。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request PUT \
    --data '{"message":"Data to use to generate the HMAC secret"}'

範例回應

{
  "hmac": "5ded46b0e5450b0790637d71e453bce1fdae61f25a34c211216906a99791c6a5"
}

原則 API

描述原則

方法	路徑	Content-Type
`GET`	`/v1/policy/describe/<policy>`	`application/json`

透過傳回其元資料來描述原則。例如，擷取建立原則的人員以及他們建立的時間。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/identity/describe/my-policy'

範例回應

{
   "name": "my-policy",
   "created_at": "2020-03-24T12:37:33Z",
   "created_by": "2ed3c8c81376106d14a3374e901aa1ec59a978db3133c9619ba526ce6754d2e6"
}

讀取原則

方法	路徑	Content-Type
`GET`	`/v1/policy/read/<policy>`	`application/json`

從 KES 伺服器取得原則。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/policy/read/my-policy'

範例回應

{
  "allow": {
    "/v1/key/generate/my-key": {},
    "/v1/key/decrypt/my-key": {}
  },
  "deny": {    
    "/v1/key/decrypt/my-key-internal*": {}
  }
}

列出原則

方法	路徑	Content-Type
`GET`	`/v1/policy/list/<prefix>`	`application/json`

列出所有原則名稱。指定選用字首，只列出以該字首開頭的原則名稱。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/policy/list/my-policy'

範例回應

{
  "names": ["my-policy", "my-policy-2"],
  "continue_at": ""
}

身分 API

描述身分

方法	路徑	Content-Type
`GET`	`/v1/identity/describe/<identity>`	`application/json`

透過傳回其元資料來描述身分。例如，使用此端點來判斷目前指派的原則或是否為管理員身分。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/identity/describe/650a2580943a87172933b7a8d26fa1dfdd0447762f26397f30c1b8bf8c78b913'

範例回應

{
   "policy": "minio",
   "admin": false,
   "created_at": "2020-03-24T12:37:33Z",
   "created_by": "2ed3c8c81376106d14a3374e901aa1ec59a978db3133c9619ba526ce6754d2e6"
}

自我描述身分

方法	路徑	Content-Type
`GET`	`/v1/identity/self/describe`	`application/json`

描述發出請求的身分。它會從用於驗證的 TLS 用戶端憑證推斷身分。它會傳回用戶端身分的身分和原則資訊。

自我描述 API 端點公開可用，且不需要任何特殊權限。任何用戶端都可以查詢其自身的身分和原則資訊。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/identity/self/describe'

範例回應

{
  "identity": "3ecfcdf38fcbe141ae26a1030f81e96b753365a46760ae6b578698a97c59fd22",
  "admin": true,
  "created_at": "2022-03-28T13:02:32.837365Z",
  "policy": {
    "Allow": null,
    "Deny": null
  }
}

列出身分

方法	路徑	Content-Type
`GET`	`/v1/identity/list/<prefix>`	`application/json`

列出所有身分。指定選用字首，只列出以該字首開頭的身分。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/identity/list/'

範例回應

{
  "identities": [ 
    "413c35cb06a9e1aa142ccebf829c96cbfd16162131a92f5ec8c9006f6fc5c9dc",
    "1d7562ffd775ed4da949e4b08fe1085fba4991cadba4a96142a578c30106ba23"
  ],
  "continue_at": ""
}

日誌 API

稽核日誌

方法	路徑	Content-Type
`GET`	`/v1/log/audit`	`application/x-ndjson`

連線至 KES 伺服器稽核日誌，以便將所有新的稽核事件串流至客戶端。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/log/audit'

範例回應

{"time":"2020-02-06T16:51:55Z","request":{"path":"/v1/log/audit/trace","identity":"dd46485bedc9ad2909d2e8f9017216eec4413bc5c64b236d992f7ec19c843c5f"},"response":{"code":200, "time":1200}}
{"time":"2020-02-06T16:52:18Z","request":{"path":"/v1/policy/list/*","identity":"dd46485bedc9ad2909d2e8f9017216eec4413bc5c64b236d992f7ec19c843c5f"},"response":{"code":200, "time":2800}}
{"time":"2020-02-06T16:52:25Z","request":{"path":"/v1/identity/list/*","identity":"dd46485bedc9ad2909d2e8f9017216eec4413bc5c64b236d992f7ec19c843c5f"},"response":{"code":200, "time":1640}}

錯誤日誌

方法	路徑	Content-Type
`GET`	`/v1/log/error`	`application/x-ndjson`

連線至 KES 伺服器錯誤日誌，以便將所有新的錯誤事件串流至客戶端。

範例請求

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://play.min.io:7373/v1/log/error/'

範例回應

{"message":"2020/03/24 14:46:10 aws: secret was not encrypted with '4f9147d9-a676-47cd-ad3f-3485abf9123d'"}
{"message":"2020/03/24 14:46:17 aws: the CMK 'ff8e2c25-b259-4f74-a001-c7b62d17e0a4' does not exist"}
{"message":"2020/03/24 14:46:25 aws: the CMK '8fc17745-9647-4797-b170-afd8b52ed7c0' cannot be used for decryption"}