Filesystem Keystore

Use this page to setup a KES server that uses the filesystem as persistent key store.

Testing Only:

A plain filesystem does not provide any protection for the stored keys.

Only use the procedures on this page for testing purposes.

Existing Key & Certificate:

If you already have a TLS private key & certificate, such as from a WebPKI or internal Certificate Authority, you can use them instead. Remember to adjust the tls config section.

KES Server Setup

Generate KES Server Private Key & Certificate

Generate a TLS private key and certificate for the KES server.

A KES server is secure-by-default and can only be run with TLS. In this guide, we use self-signed certificates for simplicity.

The following command generates a new TLS private key (private.key) and a self-signed X.509 certificate (public.crt) issued for the IP 127.0.0.1 and DNS name localhost:
```
$ kes identity new --ip "127.0.0.1" localhost

  Private key:  private.key
  Certificate:  public.crt
  Identity:     2e897f99a779cf5dd147e58de0fe55a494f546f4dcae8bc9e5426d2b5cd35680
```
Generate Client Credentials

The client application needs credentials to access the KES server. The following command generates a new TLS private/public key pair:
```
$ kes identity new --key=client.key --cert=client.crt MyApp

  Private key:  client.key
  Certificate:  client.crt
  Identity:     02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
```
The identity 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b is a unique fingerprint of the public key in client.crt. You can re-compute the fingerprint at anytime:
```
$ kes identity of client.crt

  Identity:  02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b
```

Configure KES Server

Create the KES server configuration file: config.yml. Ensure the identity in the policy section matches your client.crt identity.

address: 0.0.0.0:7373 # Listen on all network interfaces on port 7373

admin:
  identity: disabled  # We disable the admin identity since we don't need it in this guide 

tls:
  key: private.key    # The KES server TLS private key
  cert: public.crt    # The KES server TLS certificate

policy:
  my-app: 
    allow:
    - /v1/key/create/my-key*
    - /v1/key/generate/my-key*
    - /v1/key/decrypt/my-key*
    identities:
    - 02ef5321ca409dbc7b10e7e8ee44d1c3b91e4bf6e2198befdebee6312745267b # Use the identity of your client.crt

keystore:
  fs:
    path: ./keys # Choose a directory for the secret keys

Start KES Server
```
kes server --config config.yml --auth off
```
Linux Swap Protection:
In Linux environments, KES can use the mlock syscall to prevent the OS from writing in-memory data to disk (swapping). This prevents leaking sensitive data.

Use the following command to allow KES to use the mlock syscall without running with root privileges:
```
sudo setcap cap_ipc_lock=+ep $(readlink -f $(which kes))
```
Start a KES server instance with memory protection:
```
kes server --config config.yml --auth off --mlock
```

KES CLI Access

Set KES_SERVER endpoint

This variable tells the KES CLI which KES server to access.
```
export KES_SERVER=https://127.0.0.1:7373
```
Use Client Credentials

These variables tell the KES CLI which credentials to use to access to a KES server.
```
export KES_CLIENT_CERT=client.crt
```
```
export KES_CLIENT_KEY=client.key
```

Perform Operations

Perform any API operation that is allowed based on the assigned policy.

When running KES locally for testing purpose, use the -k or --insecure flag to generate a new key or data encryption key

For example we can create a key:

kes key create my-key-1 -k

Then, we can use that key to generate a new data encryption key:

kes key dek my-key-1 -k
{
  plaintext : UGgcVBgyQYwxKzve7UJNV5x8aTiPJFoR+s828reNjh0=
  ciphertext: eyJhZWFkIjoiQUVTLTI1Ni1HQ00tSE1BQy1TSEEtMjU2IiwiaWQiOiIxMTc1ZjJjNDMyMjNjNjNmNjY1MDk5ZDExNmU3Yzc4NCIsIml2IjoiVHBtbHpWTDh5a2t4VVREV1RSTU5Tdz09Iiwibm9uY2UiOiJkeGl0R3A3bFB6S21rTE5HIiwiYnl0ZXMiOiJaaWdobEZrTUFuVVBWSG0wZDhSYUNBY3pnRWRsQzJqWFhCK1YxaWl2MXdnYjhBRytuTWx0Y3BGK0RtV1VoNkZaIn0=
}

Documentation

Filesystem Keystore

KES Server Setup

KES CLI Access

References