Filesystem Keystore

This guide shows how to setup a KES server that uses the filesystem as persistent key store.

                              ┌───────┐      
                              |  KMS  ├─────┐  
                              └───┬───┘     |  
                                  |         |  
                         ╔════════╪═════════╪═══════════════════════╗
┌────────────┐           ║  ┌─────┴──────┐  |       ┌────────────┐  ║
│ 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. First, create the TLS private key:

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

2. 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"

3. Now you have a server.key and server.cert file. Next, we create the root identity:

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

   Note that we create a private key (root.key) and a certificate (root.cert) for TLS client authentication. Again, the certificate is not signed by a CA that is trusted by the KES server. That is not a security issue per se since only clients with public keys/certificates that are known to the server can perform operations based on policies. However, we recommend to use client certificates that were issued by a trusted CA. Then the kes server does not even accept connections from untrusted clients.

   You can compute the root identity via:

   kes tool identity of root.cert

4. Since we don't want to give our applications root capabilities we also create an app identity:

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

   You can compute the app identity via:

   kes tool identity of app.cert

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

   address = "0.0.0.0:7373"
   root = "<kes-tool-identity-of root.cert>"
   
   [tls]
   key  = "server.key"
   cert = "server.cert"
   
   [policy.prod-app] 
   paths      = [ "/v1/key/create/app-key", "/v1/key/generate/app-key" , "/v1/key/decrypt/app-key" ]
   identities = [ "<kes-tool-identity-of app.cert>" ]
   
   [keystore.fs]
   path    = "./keys" # Choose a directory for the secret keys

   Please use your own root and app identity and directory.

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

   kes server --config=server-config.toml --mtls-auth=ignore

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

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

   export KES_CLIENT_TLS_CERT_FILE=app.cert
   export KES_CLIENT_TLS_KEY_FILE=app.key
   kes key create app-key -k

   -k is required because we use self-signed certificates

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

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

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

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