Getting Started

This is the Getting Started guide. Here we show how to setup a local KES server that stores keys in-memory. Therefore, all keys will be gone once the KES server has been shut down.

                   ╔══════════════════════════════════════════╗
┌────────────┐     ║   ┌────────────┐          ┌───────────┐  ║
│ KES Client ├─────╫───┤ KES Server ├──────────┤ In-Memory │  ║
└────────────┘     ║   └────────────┘          └───────────┘  ║
                   ╚══════════════════════════════════════════╝

---

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 we 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 \
    --key=server.key \
    --cert=server.cert \
    --root=$(kes tool identity of root.cert) \
    --auth=off

--auth=off is required since our root.cert certificates is self-signed

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_KEY=root.key
export KES_CLIENT_CERT=root.cert

3.2 Create a new secret key

kes key create -k my-key

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

3.3 Derive a new data key plaintext/ciphertext pair

kes key derive -k my-key

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 -k my-key <base64-ciphertext>

---

For more CLI commands see:

Usage:
    kes [options] <command>

Commands:
    server                   Starts a KES server.
    key                      Manage secret keys.
    log                      Work with server logs.
    policy                   Manage the kes server policies.
    identity                 Assign policies to identities.
    tool                     Run specific key and identity management tools.

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