constellation/rfc/key-derivation.md

42 lines
1.8 KiB
Markdown
Raw Normal View History

# 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 keyservice](../keyservice/) 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.