From 877fc7a0d287e3a21d08bbe7aa582bf50b1a353b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Wei=C3=9Fe?= <66256922+daniel-weisse@users.noreply.github.com> Date: Wed, 20 Jul 2022 09:16:13 +0200 Subject: [PATCH] [RFC] HKDF key derivation and the use of salts (#275) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Daniel Weiße --- docs/key-derivation.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 docs/key-derivation.md diff --git a/docs/key-derivation.md b/docs/key-derivation.md new file mode 100644 index 000000000..2f54482bd --- /dev/null +++ b/docs/key-derivation.md @@ -0,0 +1,41 @@ +# 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.