Getting Started

1. Install KES

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

2. Setup the server

1. Generate a TLS private key and certificate for the kes server. For now, we use self-signed certificates. For production use cases you must use a certificate issued by a CA.
   • openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key
   • openssl req -new -x509 -days 365 -key server.key -out server.cert -subj "/C=/ST=/L=/O=/CN=localhost"
2. Create the root identity:
   kes tool identity new --key="root.key" --cert="root.cert" root
3. Switch to a new terminal window and start the key 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

1. 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
2. Now, can you talk to the server and e.g. create a new secret key (named my-key):
   kes key create my-key -k
3. This key can now be used to derive unique encryption keys for your applications:
   kes key derive my-key -k

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

   The plaintext is a base64-encoded 256-bit key. The ciphertext is the plaintext key encrypted with my-key at the server.
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.

Note: You just started a kes server with a non-persistent in-memory key store. Therefore, by restarting the server all keys created in between will be destroyed. For durable key stores take a look at the toml or yaml config file - or take a look at the Hashicorp Vault guide.