Skip to content

Server API

Jump to bottom
Andreas Auernhammer edited this page Nov 6, 2023 · 52 revisions

API Overview

API
/version Get version information.
/v1/api Get a list of supported API endpoints.
/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/describe Fetch information about a policy.
/v1/policy/read Fetch a policy.
/v1/policy/list List policies.
Identity API
/v1/identity/describe Fetch information about an identity.
/v1/identity/self/describe Fetch information about the identity issuing the request.
/v1/identity/list List identities.
Log API
/v1/log/audit Subscribe to the audit log.
/v1/log/error Subscribe to the error log.

Version

Method Path Content-Type
GET /version application/json

Get the KES server version information.

Response Type 
{
    "version": string,  
    "commit": string
}
Example

Sample Request

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

Sample Response

{ 
  "version": "2023-05-02T22-48-10Z",  
  "commit":"1e46c482c170614d9e61f16b50de39cac3593a22"
}

API

Method Path Content-Type
GET /v1/api application/json

Get a list of API endpoints supported by the server.

Response Type 
[
  {
    "method"  : string
    "path"    : string
    "max_body": number   // in bytes
    "timeout" : number   // in seconds, 0 indicates never times out
  }
]
Example

Sample Request

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

Sample Response

[
  {
    "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": "POST",
    "path": "/v1/key/create/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "POST",
    "path": "/v1/key/import/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "DELETE",
    "path": "/v1/key/delete/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "POST",
    "path": "/v1/key/generate/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "POST",
    "path": "/v1/key/encrypt/",
    "max_body": 1048576,
    "timeout": 15
  },
  {
    "method": "POST",
    "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": "DELETE",
    "path": "/v1/policy/delete/",
    "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": "DELETE",
    "path": "/v1/identity/forget/",
    "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
  },
  {
    "method": "POST",
    "path": "/v1/enclave/create/",
    "max_body": 0,
    "timeout": 15
  },
  {
    "method": "POST",
    "path": "/v1/enclave/delete/",
    "max_body": 0,
    "timeout": 15
  }
]

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.

Response Type 
# 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
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 Content-Type
GET /v1/status application/json

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.

Response Type 
{
    "version": string
    "uptime" : number       // in seconds
    "kms"    : {
        "state"  : string   // optional
        "latency": number   // optional, in milliseconds
    }
}
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 Content-Type
POST /v1/key/create/<name> application/json

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 Content-Type
POST /v1/key/import/<name> application/json

Import a cryptographic key into the KES server.

Request Type 
{
   "bytes": string   // base64-encoded byte-string
}
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 Content-Type
DELETE /v1/key/delete/<name> application/json

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 Content-Type
GET /v1/key/list/<pattern> application/x-ndjson

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

Response Type 
{
   "name"      : string
   "created_at": string    // optional, time (RFC 3339) with sub-second precision
   "created_by": string    // optional, KES identity
   "error"     : string    // optional
}
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 Content-Type
POST /v1/key/generate/<name> application/json

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.

Request Type 
{
   "context": string    // optional, base64-encoded byte-string
}
Response Type 
{
   "plaintext" : string    // base64-encoded byte-string
   "ciphertext": string    // base64-encoded byte-string
}
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 Content-Type
POST /v1/key/encrypt/<name> application/json

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.

Request Type 
{
   "plaintext": string    // base64-encoded byte string
   "context"  : string    // optional, base64-encoded byte-string
}
Response Type 
{
   "ciphertext": string    // base64-encoded byte-string
}
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 Content-Type
POST /v1/key/decrypt/<name> application/json

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.

Request Type 
{
   "ciphertext": string    // base64-encoded byte string
   "context"   : string    // optional, base64-encoded byte-string
}
Response Type 
{
   "plaintext": string    // base64-encoded byte-string
}
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

Describe Policy

Method Path Content-Type
GET /v1/policy/describe/<policy> application/json

Describes a policy by returning its metadata - e.g. who created the policy at which point in time.

Response Type 
{
   "created_at": string    // RFC 3339 encoded timestamp
   "created_by": string    // KES identity
}
Example

Sample Request

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

Sample Response

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

Read Policy

Method Path Content-Type
GET /v1/policy/read/<policy> application/json

Get a policy from the KES server.

Response Type 
{
   "allow": [string]   // optional
   "deny" : [string]   // optional
}
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 Content-Type
GET /v1/policy/list/<pattern> application/x-ndjson

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

Response Type 
{
   "name"      : string
   "created_at": string    // optional, time (RFC 3339) with sub-second precision
   "created_by": string    // optional, KES identity
   "error"     : string    // optional
}
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"
}

Identity API

Describe Identity

Method Path Content-Type
GET /v1/identity/describe/<identity> application/json

Describes an identity by returning its metadata - e.g. which policy is currently assigned and whether its an admin identity.

Response Type 
{
   "policy"    : string    // Name of assigned policy. Empty if admin is true
   "admin"     : boolean   // True if the identity is an admin
   "created_at": string    // RFC 3339 encoded timestamp
   "created_by": string    // KES identity
}
Example

Sample Request

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

Sample Response

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

Self Describe Identity

Method Path Content-Type
GET /v1/identity/self/describe application/json

Describes the identity issuing the request. It infers the identity from the TLS client certificate used to authenticate. It returns the identity and policy information for the client identity.

The self-describe API endpoint is publicly available and does not require any special permissions. Any client can query its own identity and policy information.

Response Type 
{
   "identity"   : string    // KES identity issuing the request
   "policy_name": string    // Name of assigned policy. Empty if admin is true
   "admin"      : boolean   // True if the identity is an admin
   "created_at" : string    // RFC 3339 encoded timestamp
   "created_by" : string    // KES identity
   "policy"     : {
      "allow": [string]     // optional
      "deny" : [string]     // optional
   }
}
Example

Sample Request

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

Sample Response

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

List Identity

Method Path Content-Type
GET /v1/identity/list/<pattern> application/x-ndjson

List all identity metadata hat match the specified pattern. In particular, the pattern * lists all identity metadata.

Response Type 
{
   "identity"  : string    // KES identity
   "policy"    : string
   "created_at": string    // optional, time (RFC 3339) with sub-second precision
   "created_by": string    // optional, KES identity
   "error"     : string    // optional
}
Example

Sample Request

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

Sample Response

{
  "identity": "413c35cb06a9e1aa142ccebf829c96cbfd16162131a92f5ec8c9006f6fc5c9dc",
  "policy": "my-policy",
  "created_at": "2022-03-02T12:25:36.938167Z",
}
{
  "identity": "1d7562ffd775ed4da949e4b08fe1085fba4991cadba4a96142a578c30106ba23",
  "policy": "my-policy2",
  "created_at": "2022-03-02T12:27:47.554596Z",
}

Log API

Audit Log

Method Path Content-Type
GET /v1/log/audit application/x-ndjson

Connect to the KES server audit log such that all new audit events are streamed to the client.

Response Type 
{
    "time"    : string
    "request" : {
        "path"    : string
        "identity": string   // optional, KES identity
        "ip"      : string   // optional, IPv4 or IPv6 address
    }
    "response": {
        "code": number
        "time": string
    }
}
Example

Sample Request

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

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

Error Log

Method Path Content-Type
GET /v1/log/error application/x-ndjson

Connect to the KES server error log such that all new error events are streamed to the client.

Response Type 
{
    "message": string
}
Example

Sample Request

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

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