KES API

API 概述

默认情况下，KES 要求所有 API 调用都必须使用有效证书。未提供证书的请求将因 TLS 错误而失败。

在调用 KES 中的某些端点时，您可以禁用对有效证书的要求配置文件.

如果任何端点不需要证书，失败的调用将导致HTTP错误而非TLS错误。

API
`/version`	获取版本信息。
`/ready`	返回 KES 服务器就绪状态。
`/v1/api`	获取支持的API端点列表。
`/v1/metrics`	以 Prometheus 暴露格式获取服务器指标。
`/v1/status`	获取服务器状态信息。
Key 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`
Policy API
`/v1/policy/describe`	获取策略信息。
`/v1/policy/read`	获取策略。
`/v1/policy/list`	列出策略。
Identity API
`/v1/identity/describe`	获取身份信息。
`/v1/identity/self/describe`	获取发出请求的身份信息。
`/v1/identity/list`	列出身份信息。
Log API
`/v1/log/audit`	订阅审计日志。
`/v1/log/error`	订阅错误日志。

Version

方法	路径	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服务器就绪探针。返回200 OK如果 KES 已就绪。

您可以在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 exposition format.

您可以在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文档。响应返回的信息包括以下内容：

Version
正常运行时间（以秒为单位）
操作系统和CPU架构
当前内存消耗
Keystore 状态
Keystore 延迟（单位：毫秒）

您可以在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
}

Key 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 是一个明文-密文pair. The纯文本是一个随机生成的密钥，可用于加密数据等密码学操作。密文是用密钥加密的明文吗<name>在KES服务器上。由于此密钥永远不会离开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"
}

Policy 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": ""
}

Identity 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客户端证书推断身份。返回客户端身份的身份信息和策略信息。

self-describe 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": ""
}

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