Welcome to Citadel!

Citadel (c5l) is a simple daemon that implements the Kubernetes Key Management Service (KMS) interface by acquiring a key encryption key (KEK) from an arbitrary command. This makes it easy to plug in your own key management solution as a simple unix command that returns the KEK.

How does it work?

When c5l starts, it runs the command you provide it. This command returns the KEK on standard output. If this command fails during startup, c5l will exit. Otherwise, it will use the KEK from the command to encrypt and decrypt input from Kubernetes.

c5l caches the KEK, and thus does not call the command on every incoming request. The time limit of this cache is specified by the timeout argument. If c5l is not able to refresh the cache after trying several times, it will purge the KEK and report errors to Kubernetes. If c5l eventually succeeds in acquiring the KEK, normal operation will resume.

To specify the socket to create, use the endpoint argument. Otherwise, socket activation is assumed.

Arguments

Required

• --command string: the command to retrieve the key encryption key

Optional

• --endpoint string: the listen address (ex. unix:///tmp/socket)

• --timeout duration: maximum time to cache KEK locally (default 1h)

• --mode string: encryption mode to use, the options are [aescbc] (default "aescbc")

Crypto Details

The KEK is currently used to do AES-CBC encryption. This does not provide ciphertext authentication. Other methods are being considered with the intent of providing cryptographic agility and features such as authentication.

Examples

Here is an example which uses a Clevis decryption policy to allow access to the KEK only when a Tang server is accessible on the network.

First, you need to generate the KEK and encrypt it using the Clevis policy:

$ dd if=/dev/urandom bs=32 count=1 status=none \
  | clevis encrypt tang '{"url":"http://tang.srv"}' \
  > /var/db/citadel/kek.jwe

Next, you run c5l with the clevis decrypt command:

$ citadel --command 'clevis decrypt < /var/db/citadel/kek.jwe'

When run, c5l will be able to acquire the KEK if, and only if, the Tang server is accessible on the network. Attempts to read the file (/var/db/citadel/kek.jwe) directly will reveal only ciphertext.