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 Aug 23, 2021 · 52 revisions

This API documentation assumes that there is a X.509 certificate root.cert (and the corresponding private key root.key) in your working directory. Further, it assumes that the KES server root identity matches:

kes tool identity of root.cert

If there is no such identity in your working directory you can create it via:

kes tool identity new root --key=root.key --cert=root.cert

Remember that you have to restart the KES server with the correct root identity.

API Overview

API Description
/version Get version information.
/v1/metrics Get server metrics in the Prometheus exposition format.
/v1/status Get server status information
/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.
/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.
/v1/identity/assign Assign a policy to an identity.
/v1/identity/list List identities and their assigned policy.
/v1/identity/forget Forget an identity.
/v1/log/audit/trace Subscribe to the audit log event stream.
/v1/log/error/trace Subscribe to the error log event stream.

Version

The Version endpoint returns version information about the KES server.

Method Path
GET /version

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://127.0.0.1:7373/version' -k

Sample Response

{ 
  "version": "0.7.2"
}

Metrics

The Metrics endpoint exposes server metrics - like the total number of requests. The metrics are exposed in the Prometheus exposition format.

Method Path
GET /v1/metrics

Sample Request

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

Sample Response

# 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 1
# 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 5
# 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"} 6
kes_http_response_time_bucket{le="0.05"} 6
kes_http_response_time_bucket{le="0.1"} 6
kes_http_response_time_bucket{le="0.25"} 6
kes_http_response_time_bucket{le="0.5"} 6
kes_http_response_time_bucket{le="1"} 6
kes_http_response_time_bucket{le="1.5"} 6
kes_http_response_time_bucket{le="3"} 6
kes_http_response_time_bucket{le="5"} 6
kes_http_response_time_bucket{le="10"} 6
kes_http_response_time_bucket{le="+Inf"} 6
kes_http_response_time_sum 0.000371124
kes_http_response_time_count 6

Status

The Status endpoint returns 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.

Method Path
GET /v1/status

Sample Request

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

Sample Response

{
  "version": "0.16.1",
  "uptime": 27000000000,
  "certificate": {
    "expiry": 2591930000000000,
    "dns": [
      "localhost"
    ],
    "ip": [
      "127.0.0.1"
    ]
  }
}

Key API

Create Key

The Create Key endpoint creates a new named cryptographic key.

Method Path
POST /v1/key/create/:name

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request POST \
    'https://127.0.0.1:7373/v1/key/create/my-key' -k

Import Key

The Import Key endpoint imports a cryptographic key into the KES server.

Method Path
POST /v1/key/import/:name

Sample Request

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

Delete Key

The Delete Key endpoint deletes a new named cryptographic key.

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

Method Path
DELETE /v1/key/delete/:name

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request DELETE \
    'https://127.0.0.1:7373/v1/key/delete/my-key' -k

List Keys

The List Keys endpoint list all key names that match the specified glob pattern. In particular, the pattern * lists all keys.

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

Sample Request

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

Sample Response

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

The response is a nd-json stream.

Generate Key

The Generate Key endpoint generates a new data encryption key (DEK) protected by the named cryptographic key. It returns the DEK as plaintext and encrypted with the named key. An application should use the plaintext DEK to e.g. encrypt some application data and must remember the encrypted DEK (ciphertext) to decrypt the application data in the future.

Method Path
POST /v1/key/generate/:name

Sample Request

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

Sample Response

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

Encrypt Key

The Encrypt Key endpoint encrypts and authenticates a (small) plaintext with the named cryptographic key. The plaintext cannot be a large stream of data. A typical scenario where the Encrypt Key endpoint may be useful is wrapping another cryptographic key.

Method Path
POST /v1/key/encrypt/:name

Sample Request

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

Sample Response

{
  "ciphertext": "eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaXYiOiIwUXJ0alUvWDJtUEtUK3A1R3JwdktRPT0iLCJub25jZSI6ImpxOGliYXVxKzY0dEZBM0kiLCJieXRlcyI6Im1MQ21hdzVxQW9acXpwOTJoMjZuRTJWR01BVkdCTTlJalNtT05SYz0ifQ=="
}

Decrypt Key

The Decrypt Key endpoint decrypts an encrypted plaintext (ciphertext) with the named cryptographic key. It returns the plaintext if and only if the ciphertext is authentic and has been produced by the named key.

Method Path
POST /v1/key/decrypt/:name

Sample Request

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

Sample Response

{
  "plaintext": "TIDXCHZxPr84r7ktggCCW7otoz5T4zsRENi4THCjXPo="
}

Policy API

Write Policy

The Write Policy endpoint uploads a named policy to the KES server.

Method Path
POST /v1/policy/write/:name

Sample Request

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

Read Policy

The Read Policy endpoint downloads a named policy from the KES server.

Method Path
GET /v1/policy/read/:name

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request GET \
    'https://127.0.0.1:7373/v1/policy/read/my-policy' -k

Sample Response

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

List Policy

The List Policy endpoint lists all policy names that match the specified glob pattern. In particular, the pattern * lists all policies.

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

Sample Request

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

Sample Response

[
  "my-policy"
]

Delete Policy

The Delete Policy endpoint deletes a named policy from KES server. All identities that have been assigned to this policy will lose all authorization privileges.

Method Path
DELETE /v1/policy/delete/:name

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request DELETE \
    'https://127.0.0.1:7373/v1/policy/delete/my-policy' -k

Identity API

Assign Identity

The Assign Identity endpoint assigns a policy to an identity. An identity can have at most one policy but one policy can have arbitrary many identities.

The policy assigned to an identity defines which API calls this identity can perform. However, an identity cannot assign a policy to itself.

Method Path
POST /v1/identity/assign/:policy/:identity

Sample Request

$ curl \
    --key root.key \
    --cert root.cert \
    --request POST \
    'https://127.0.0.1:7373/v1/identity/assign/my-policy/a4eac2d875d60ef25b068965c4e850aac074028dc576f3699276c6ea0ae1828f' -k

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