constellation/rfc/001-key-derivation.md

RFC 001: Key derivation

To derive disk-encryption keys and other secret material in a Constellation Kubernetes cluster, we use HKDF.

To derive a key, HKDF depends on four parameters: input keying material (IKM), salt, info, and a hash function. The parameters salt and info are optional.

Key derivation is performed in two steps:

1. Extract

   A pseudorandom key is generated from the secret IKM and an optional independent salt.

2. Expand

   The pseudorandom key generated by the extract phase is used to derive keys. Using the optional info parameter multiple different keys can be created from the key created in the extract phase.

Hash

We use SHA-256 as the hash function.

Initial Key Material

Constellation's master secret is used as IKM for HKDF. The master secret is either provided by the admin, or a randomly generated 32 byte value. It is supplied to the cluster during constellation init and in the following used by Constellation's keyservice and managed by Kubernetes as a secret.

Salt

To salt the extract phase of HKDF, Constellation uses a randomly generated 32 Byte value during constellation init. The salt is returned to the user for data recovery, and kept in the cluster as a Kubernetes secret.

Info

The info field is used to add context-specific information to a derived key. This allows using the same IKM to derive multiple different keys.

Disk-encryption key

For disk-encryption keys, info is set to the string key- appended with the lower-case LUKS2 UUID of the disk.