Git-Mirrors/constellation
1
0
Fork 0
mirror of https://github.com/edgelesssys/constellation.git synced 2024-10-01 01:36:09 -04:00
Code Issues Packages Projects Releases Wiki Activity

[RFC] HKDF key derivation and the use of salts (#275)

Browse Source 
Signed-off-by: Daniel Weiße <dw@edgeless.systems>
This commit is contained in:
Daniel Weiße 2022-07-20 09:16:13 +02:00 committed by GitHub
parent a660af05f1
commit 877fc7a0d2
1 changed files with 41 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/key-derivation.md Normal file
View File

@ -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.