Skip to content
This repository was archived by the owner on Jun 19, 2025. It is now read-only.

Server API

Jump to bottom
Andreas Auernhammer edited this page Mar 2, 2022 · 52 revisions

API Overview

API
/version Get version information.
/v1/metrics Get server metrics in the Prometheus exposition format.
/v1/status Get server status information
Key API
/v1/key/create Create a new cryptographic key.
/v1/key/import Import a cryptographic key.
/v1/key/delete Delete a cryptographic key.
/v1/key/list List cryptographic keys.
/v1/key/generate Generate a new plain/encrypted data encryption key pair.
/v1/key/encrypt Encrypt a (small) plaintext with a key.
/v1/key/decrypt Decrypt a (small) ciphertext with a key.
Policy API
/v1/policy/assign Assign a policy to an identity.
/v1/policy/write Create or overwrite a policy.
/v1/policy/read Fetch a policy.
/v1/policy/list List policies.
/v1/policy/delete Delete a policy.
Identity API
/v1/identity/list List identities.
/v1/identity/delete Delete an identity.
Log API
/v1/log/audit Subscribe to the audit log.
/v1/log/error Subscribe to the error log.

Version

Method Path
GET /version

Get the KES server version information.

Example

Sample Request

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

Sample Response

{ 
  "version": "0.18.0"
}

Metrics

Method Path
GET /v1/metrics

Get server metrics. For example, the total number of requests. The metrics are exposed in the Prometheus exposition format.

Example

Sample Request

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

Sample Response

# 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

Status

Method Path
GET /v1/status

Get the current status of the KES server. It returns 200 OK and a JSON document that describes status-related server information, like its uptime, if the KES server is up and ready to serve requests.

Example

Sample Request

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

Sample Response

{
  "version": "0.17.1",
  "uptime": 3000000000,
  "kms": {
    "state": "reachable",
    "latency": 148000000
  }
}

Key API

Create Key

Method Path
POST /v1/key/create/<name>

Create a new cryptographic key.

Example

Sample Request

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

Import Key

Method Path
POST /v1/key/import/<name>

Import a cryptographic key into the KES server.

Example

Sample Request

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

Delete Key

Method Path
DELETE /v1/key/delete/<name>

Delete a new cryptographic key.

Please note that is a dangerous operations. Once a key has been deleted all data that has been encrypted with it cannot be decrypted anymore, and therefore, is lost.

Example

Sample Request

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

List Keys

Method Path
GET /v1/key/list/<pattern>

List all key names that match the specified pattern. In particular, the pattern * lists all keys.

Example

Sample Request

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

Sample Response

{
  "name": "my-key"
}
{
  "name": "my-key1"
}
{
  "name": "my-key2"
}

Generate Key

Method Path
POST /v1/key/generate/<name>

Generate a new data encryption key (DEK). The DEK is a plaintext-ciphertext pair. The plaintext is randomly generated key that can be used for cryptographic operations. For example, encrypting some data. The ciphertext is the plaintext encrypted with the key (<name>) at the KES server. Since this key never leaves the KES server, only the KES server can decrypt the generated ciphertext.

An application should use the plaintext DEK for a cryptographic operation and should remember the ciphertext DEK and which key (<name>) was used.

Example

Sample Request

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

Sample Response

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

Encrypt Key

Method Path
POST /v1/key/encrypt/<name>

Decrypts and authenticates a (small) plaintext with the cryptographic key. The plaintext must not exceed 1 MB. The Encrypt Key endpoint is mainly used for wrapping small data. For example another cryptographic key.

Example

Sample Request

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

Sample Response

{
  "ciphertext": "eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaXYiOiIwUXJ0alUvWDJtUEtUK3A1R3JwdktRPT0iLCJub25jZSI6ImpxOGliYXVxKzY0dEZBM0kiLCJieXRlcyI6Im1MQ21hdzVxQW9acXpwOTJoMjZuRTJWR01BVkdCTTlJalNtT05SYz0ifQ=="
}

Decrypt Key

Method Path
POST /v1/key/decrypt/<name>

Decrypt a ciphertext with the cryptographic key. It returns the corresponding plaintext if and only if the ciphertext is authentic and has been produced by the named key.

Example

Sample Request

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

Sample Response

{
  "plaintext": "TIDXCHZxPr84r7ktggCCW7otoz5T4zsRENi4THCjXPo="
}

Policy API

Assign Policy

Method Path
POST /v1/policy/assign/<policy>

Assign a policy to an identity. An identity can have at most one policy while the same policy can be assigned to multiple identities.

The assigned policy defines which API calls this identity can perform. It's not possible to assign a policy to the admin identity. Further, an identity cannot assign a policy to itself.

Example

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request POST \
    --data '{"identity":"a4eac2d875d60ef25b068965c4e850aac074028dc576f3699276c6ea0ae1828f"}' \
    'https://play.min.io:7373/v1/identity/assign/my-policy'

Write Policy

Method Path
POST /v1/policy/write/<policy>

Create or update a policy at the KES server.

Example

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request POST \
    --data '{"allow":["/v1/key/generate/my-key","/v1/key/decrypt/my-key"]}' \
    'https://play.min.io:7373/v1/policy/write/my-policy'

Read Policy

Method Path
GET /v1/policy/read/<policy>

Get a policy from the KES server.

Example

Sample Request

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

Sample Response

{
  "allow": [
    "/v1/key/generate/my-key",
    "/v1/key/decrypt/my-key"
  ]
}

List Policy

Method Path
GET /v1/policy/list/<pattern>

List all policy metadata that match the specified pattern. In particular, the pattern * lists all policy metadata.

Example

Sample Request

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

Sample Response

{
  "name": "my-policy",
  "created_at": "2022-03-02T12:11:06.840267Z",
  "created_by": "3ecfcdf38fcbe141ae26a1030f81e96b753365a46760ae6b578698a97c59fd22"
}
{
  "name": "my-policy2",
  "created_at": "2022-03-02T12:12:10.181179Z",
  "created_by": "3ecfcdf38fcbe141ae26a1030f81e96b753365a46760ae6b578698a97c59fd22"
}

Delete Policy

Method Path
DELETE /v1/policy/delete/<policy>

Delete a policy from KES server.

All identities that have been assigned to this policy will lose all authorization privileges.

Example

Sample Request

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

Identity API

List Identity

The List Identity endpoint list all identities and the policy assigned to it that match the specified glob pattern. In particular, the pattern * lists all identities.

Method Path
GET /v1/identity/list/:pattern

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://127.0.0.1:7373/v1/identity/list/*' -k

Sample Response

{
  "a4eac2d875d60ef25b068965c4e850aac074028dc576f3699276c6ea0ae1828f": "my-policy"
}

Forget Identity

The Forget Identity endpoint removes the identity-policy assignment. Since an identity can have at most one policy assigned to it, it is no longer authorized to perform any API operations.

Method Path
Delete /v1/identity/forget/:identity

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request DELETE \
    'https://127.0.0.1:7373/v1/identity/forget/a4eac2d875d60ef25b068965c4e850aac074028dc576f3699276c6ea0ae1828f' -k

Log API

Trace Audit Log

The Trace Audit Log endpoint connects the client to the audit log such that all audit events are streamed to the client. The event stream is formatted as newline-delimited JSON.

Method Path
GET /v1/log/audit/trace

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://127.0.0.1:7373/v1/log/audit/trace' -k

Sample Response

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

Trace Error Log

The Trace Error Log endpoint connects the client to the error log such that all error events are streamed to the client. The event stream is formatted as newline-delimited JSON.

Method Path
GET /v1/log/error/trace

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://127.0.0.1:7373/v1/log/error/trace' -k

Sample Response

{"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"}
...
Clone this wiki locally