Home

What is a kes server

A kes server is a stateless server that fetches secret keys from a key store and then uses these keys to perform cryptographic operations.

   +-----------+                  +------------+                  +--------+
   | Key Store |<---------------->| Kes Server |<---------------->| Client |
   +-----------+                  +------------+                  +--------+

The Key Store holds the secret keys. Therefore, we assume it's a secure and/or encrypted storage - e.g. a KMS key-value store. Further, since the kes server fetches secrets from the Key Store we require that the connection is authenticated and encrypted via TLS.

The client, on the other side, connects to the kes server and requests certain cryptographic operations, like generating a new encryption key or decrypting a ciphertext using the secret key from the key store. Therefore, the kes server acts as the logic that connects the Key Store (holding the secrets) and the client who needs to perform some cryptographic operations.

Client Authentication

The kes server uses mTLS to determine whether a client is authenticated. Therefore, the server will verify that the client presents a valid X.509 certificate when establishing the TLS connection. By default, all clients that can present a valid certificate that has been issued by a certificate authority (CA) are considered authentic.

However, just because a client can connect to a kes server does not mean that it can perform arbitrary operations. In fact, a client can only perform operations if it is assigned to a policy - and then only the operations granted by that policy. By default, a client is not assigned to any policy, and therefore, can not perform any operation - even though it can establish a connection to the kes server.

Client Authorization

A client can only perform operations if they are allowed by the policy the client is assigned to. Before we cover policies, we first need to understand how the kes server will identify clients.

Identities

The kes server will determine the client's identity based on the X.509 certificate the client sends when it tries to establish a connection. Recall that the client has to send a valid X.509 certificate - otherwise, the server would not even accept the connection. See Client Authentication.

By default, the server will compute the client identity as the SHA-256 hash of the client public key. The public key is part of the client certificate. For example the CLI command: key tool identity of <cert-file> does exactly that and prints the SHA-256 hash as a hex-encoded string. So, an identity is simply the output of an identity-function that takes an X.509 certificate as input - i.e. the SHA-256 of the public key.

There is one special identity called root. However, it is just a regular identity (SHA-256 hash) that is defined to be the identity that can perform any API operation. You have to specify the root identity when starting a kes server. Usually, you will create the root identity first, then start the server and then, as root, create policies and assign identities. Nevertheless, it's also possible to effectively disable root by setting it to an "invalid" hash value - e.g. xyz123. Since no SHA-256 hash will ever be xyz123 nobody will be able to authenticate as root.

Policies

Since we now know what an identity is, we can take a look at how the kes server enforces access policies. In general, a policy defines which API calls are allowed. All not explicitly allowed calls are forbidden. However, a policy usually does not define concrete API calls but API patterns. For instance the pattern /v1/key/create/* allows creating arbitrary secret keys while the pattern /v1/key/delete/my-key-* only allows deleting secrets keys that have the prefix my-key-.

Now, each identity can be assigned to at most one policy. However, multiple identities can be assigned to the same policy. Assigning an identity just means to tell the kes server that whenever it encounters identity x it should apply policy y.