KES API

API 概述

默认情况下，KES 要求任何 API 调用都具有有效的证书。没有证书的请求将以 TLS 错误失败。

您可以在 KES 配置文件中禁用对某些 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/<name>`	`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/<name>`	`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/<name>`	`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/<prefix>`	`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/<name>`	`application/json`

生成新的数据加密密钥 (DEK)。

DEK 是一个明文-密文对。明文是随机生成的密钥，可用于加密操作，例如加密数据。密文是使用 KES 服务器上的密钥 <name> 加密的明文。由于此密钥从未离开 KES 服务器，因此只有 KES 服务器可以解密生成的密文。

应用程序应使用明文 DEK 进行加密操作。应用程序应记住密文 DEK 和使用的密钥 <name>。

示例请求

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