Filesystem Keystore

This guide shows how to setup a KES server that uses the filesystem as persistent key store. A plain filesystem does not provide any protection for the stored keys. It should only be used for testing purposes.

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

---

KES Server setup

First, we need to generate a TLS private key and certificate for our KES server. A KES server can only be run with TLS - since secure-by-default. Here we use self-signed certificates for simplicity. For a production setup we highly recommend to use a certificate signed by CA (e.g. your internal CA or a public CA like Let's Encrypt)

1. Generate a TLS private key and certificate for the KES server.
   The following command will generate a new TLS private key server.key and a X.509 certificate server.cert that is self-signed and issued for the IP 127.0.0.1 and DNS name localhost (as SAN). You may want to customize the command to match your setup.

   kes tool identity new --server --key server.key --cert server.cert --ip "127.0.0.1" --dns localhost

   Any other tooling for X.509 certificate generation works as well. For example, you could use openssl:

   $ openssl ecparam -genkey -name prime256v1 | openssl ec -out server.key
   
   $ 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"
   

2. Then, create private key and certificate for your application:

   kes tool identity new --key=app.key --cert=app.cert app

   You can compute the app identity via:

   kes tool identity of app.cert

3. Now we have defined all entities in our demo setup. Let's wire everything together by creating the config file server-config.yml:

   address: 0.0.0.0:7373
   root:   disabled  # We disable the root identity since we don't need it in this guide 
   
   tls:
     key:  server.key
     cert: server.cert
   
   policy:
     my-app: 
       allow:
       - /v1/key/create/app-key*
       - /v1/key/generate/app-key*
       - /v1/key/decrypt/app-key*
       identities:
       - ${APP_IDENTITY}
   
   keystore:
     fs:
       path: ./keys # Choose a directory for the secret keys

4. Finally we can start a KES server in a new window/tab:

   export APP_IDENTITY=$(kes tool identity of app.cert)
   
   kes server --config=server-config.yml --auth=off

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

5. In the previous window/tab we now can connect to the server by:

   export KES_CLIENT_CERT=app.cert
   export KES_CLIENT_KEY=app.key
   kes key create -k app-key

   -k is required because we use self-signed certificates

   Now, you should see a secret key inside the ./keys directory.

6. Finally, we can derive and decrypt data keys from the previously created app-key:

   kes key derive -k app-key
   {
     plaintext : ...
     ciphertext: ...
   }

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