Concepts

The Concepts section helps you learn about how KES works. In particular, it contains information about the general architecture, authentication as well as authorization and other important aspects.

Components

    ╔═════════════════════════════════════════════════════════════════════════╗
    ║                                ┌───────┐                                ║
    ║                                |  KMS  ├─────┐                          ║
    ║                                └───┬───┘     |                          ║
    ║                                    |         |                          ║
    ║                                    |         |                          ║
    ║  ┌────────────┐              ┌─────┴──────┐  |           ┌───────────┐  ║
    ║  │ KES Client ├──────────────┤ KES Server ├──┴───────────┤ Key Store │  ║
    ║  └────────────┘              └────────────┘              └───────────┘  ║
    ╚═════════════════════════════════════════════════════════════════════════╝

Let's start with one KES server and one KES client - even though, in the general case, there can be arbitrary many clients talking to arbitrary many servers.

The KES client connects to the KES server over TLS and uses the KES server API to perform operations - for example creating a new key. The KES server itself is stateless and gets started with an initial configuration. However, to perform certain stateful operations - like creating a key - it needs to keep some state somewhere. Therefore, a KES server requires a key store / secret store, specified as part of the initial configuration. Whenever a client request changes the overall state, the KES server updates the key store to represent this new state. Multiple independent KES servers synchronize themselves via a common key store.

In addition to a key store, the KES server can also be connected to a Key-Management-System (KMS). If available, the KES server will use to the KMS to protect keys / secrets stored at the key store. The KMS is an optional component, and only required when trying to achieve certain (additional) security guarantees.

---

Access Control

In general, all KES server operations require authentication and authorization. However, KES uses the same application-independent mechanism for both: TLS - i.e. mutual TLS authentication (mTLS).

           ┌──────────────┐                   ┌──────────────┐
           │  KES Client  ├───────────────────┤  KES Server  |
           └──────────────┘        TLS        └──────────────┘
                (🗝️,📜)             🔒              (📜,🔑)

Therefore, a KES client needs a private key / public key pair and a X.509 certificate. Here, we explicitly distinguish the public key from the certificate to explain how authentication and authorization works:

Authentication

In general, a KES server only accepts TLS connections from clients that can present a valid and authentic TLS certificate (📜) during the TLS handshake. By valid we mean a well-formed and e.g. not expired certificate. By authentic we refer to a certificate that has been issued, and therefore cryptographically signed, by a certificate authority (CA) that the KES server trusts.

Now, when a KES client tries to establish a connection to the KES server the TLS protocol will ensure that:

• The KES client actually has the private key (🗝️) that corresponds to the public key in the certificate (📜) presented by the client.
• The certificate presented by a client has been issued by a CA that the KES server trusts.

=> If the TLS handshake succeeds then the KES server considers the request as authentic.

It is possible to skip the certificate verification - for example during testing or development. To do so, start the KES server with the --mtls-auth=ignore option. Then clients still have to provide a certificate but the server will not verify whether the certificate has been issued by a trusted CA. Instead, the client can present a self-signed certificate.
Please note that CA-issued certificates are highly recommended for production deployments and --mtls-auth=ignore should only be used for testing or development.

Authorization

Once the KES server has considered a client request as authentic, it checks whether the client is actually authorized to perform the request operation - e.g. create a new secret key. Therefore, the server verifies that the request complies to the policy associated to the client. So, KES relies on a role and policy-based authorization model.

To associate clients to policies the KES server again relies on TLS - i.e. on the client certificate (📜). More precisely, the KES server computes an identity from the certificate: 🆔 ═ H(📜). Technically, the identity function (H) could be any unique mapping. KES uses a cryptographic hash of the client's public key as identity function: 🆔 ═ SHA-256(📜.PublicKey).

So, when the KES server receives an authentic client request, it computes the client identity (🆔) from the client certificate (📜) and checks whether this identity is associated to a named policy. If such an identity-policy mapping exists, the KES server validates that the request complies to the policy. Otherwise, the server rejects the request.

=> The KES server considers a request as authorized if the following two statements hold:

• A policy associated to the identity (🆔) computed from the client certificate (📜) exists.
• The associated policy explicitly allows the operation that the request wants to perform.

Policies

A policy specifies a set of allowed API operations. All not explicitly allowed operations are forbidden. In general, a policy consists of API path glob patterns that have the following form:

<API-version>/<API>/<operation>/<argument>

For example, the API pattern for creating arbitrarily named keys looks like this:

/v1/key/create/*

Similarly, the API pattern for creating named keys that start with my-key- looks like this:

/v1/key/create/my-key-*

Now, a policy contains one or multiple of these patterns.

It's important to know that an identity can only be assigned to at most one policy at one point in time. However, multiple identities can be assigned to the same policy.