constellation/docs/key-derivation.md

# Key derivation

To derive disk-encryption keys and other secret material in a Constellation Kubernetes cluster, we use [HKDF](https://datatracker.ietf.org/doc/html/rfc5869).

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](https://datatracker.ietf.org/doc/html/rfc5869#section-2.2)

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

2. [Expand](https://datatracker.ietf.org/doc/html/rfc5869#section-2.3)

    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 KMS](../kms/) and managed by Kubernetes as a [secret](https://kubernetes.io/docs/concepts/configuration/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.