Getting Started

This is the getting started guide. Here we show how to setup a local KES server with an in-memory secret store. This means that all created secrets will be gone once the KES server has been shut down.

1. Install KES

If you haven't installed KES yet, install it first.

2. Setup the server

A KES server can only be run with TLS - since secure-by-default. Here we use self-signed certificates for simplicity.

2.1 Generate a TLS private key and certificate

First, create the TLS private key:

openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key

Then, create the corresponding TLS X.509 certificate:

openssl req -new -x509 -days 30 -key server.key -out server.cert \
  -subj "/C=/ST=/L=/O=/CN=localhost" -addext "subjectAltName = IP:127.0.0.1"

You can ignore output messages like: req: No value provided for Subject Attribute C, skipped. OpenSSL just tells you that you haven't specified a country, state, a.s.o for the certificate subject. Since we generate a self-signed certificate we don't have to worry about this.

2.2 Create the root identity

As the root identity can perform any operation without having to worry about policies for now. A new identity can be created via:

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

2.3 Start the KES server

Now, switch to a new terminal window and start the KES server:

kes server \
    --mtls-auth ignore \
    --tls-key ./server.key \
    --tls-cert ./server.cert \
    --root $(kes tool identity of root.cert)

3. Use the client CLI

Now, we try to connect to the KES server, create a new secret key, derive a new data key and then decrypt the data key ciphertext.

3.1 Specify the mTLS client private key and X.509 certificate

Switch back to the previous terminal window to set the following environment variables:

export KES_CLIENT_TLS_KEY_FILE=root.key
export KES_CLIENT_TLS_CERT_FILE=root.cert

3.2 Create a new secret key

kes key create my-key -k

We have to specify -k since we use self-signed certificates.

3.3 Derive a new data key plaintext/ciphertext pair

kes key derive my-key -k

You will see some output similar to:

{
  plaintext : ...
  ciphertext: ...
}

The plaintext is a base64-encoded 256-bit key. The ciphertext is the plaintext key encrypted with my-key at the server.

3.4 Decrypt the ciphertext and get back the original plaintext key:

kes key decrypt my-key -k <base64-ciphertext>

---

For more CLI commands see:

usage: kes <command>

    server               Start a kes server.

    key                  Manage secret keys.
    policy               Manage the kes server policies.
    identity             Assign policies to identities.
    audit                Manage the kes server audit logs.                  

    tool                 Run specific key and identity management tools.

  -v, --version          Print version information
  -h, --help             Show this list of command line options.