ceph-csi/docs/design/proposals/rbd-pv-key-rotation.md
black-dragon74 64c5be5242 doc: Update docs for rbd-pv-key-rotation
This commit updates the key rotation docs with the following changes:

- Do not call LuksVerify
- Mention specifics of RWX volumes
- Rename the file to represent RBD backed volumes

Signed-off-by: black-dragon74 <niryadav@redhat.com>
2024-07-19 07:15:41 +00:00

72 lines
2.4 KiB
Markdown

# Encryption Key Rotation
## Proposal
Subject of this proposal is to add support for rotation of
encryption keys (KEKs) for encrypted volumes in Ceph-CSI.
Support for rotating keys on RWX/ROX volumes and filesystem encryption
with `fscrypt` is out of scope for now and shall be added later.
## Document Terminology
- Encryption Key: The passphrase that is used to encrypt and open the device.
- LUKS: The specification used by dm-crypt to process encrypted volumes on linux.
## Proposed Solution
The proposed solution in this document, is to address the rotation
of encryption keys for encrypted volumes.
This document outlines the rotation steps for PVCs backed by RBD.
### Implementation Summary
This feature builds upon the foundation laid by encrypted pvcs.
The following new methods are added to `cryptsetup.go` for
handling the key rotation.
- `LuksAddKey`: Adds a new key to specified LUKS slot
- `LuksRemoveKey`: Removes the specified key from its slot using `luksKillSlot`
- `LuksVerifyKey`: Verifies that the given key exists
in the given slot using `luksChangeKey`.
### Implementation Details
The encryption key rotation request will contain with it
the volume ID and secrets.
The secrets are used to generate the credentials for authenticating
against a ceph cluster.
These values are then used to call `GenVolFromVolID` to get the
rbdVolume structure.
The `VolumeEncryption` struct is modified to make
`generateNewEncryptionPassphrase` a public member function.
The `EncryptionKeyRotation` service is registered and implemented
on the node-plugin.
The following steps are followed to process the device for key rotation:
- Create a `rbdvolume` object using volume ID,
this is done by `GenVolFromVolID`.
- Fetch the current key from the KMS, it is needed for
subsequent LUKS operations.
- Get the device path for the volume by calling `waitForPath` as all LUKS
operations require the device path.
- Add the fetched key to LUKS slot 1, this will serve as a backup of the key.
- Generate a new key and store it locally. It will be updated
in the KMS at later steps.
- Remove the existing key from slot 0 upon verifying that the
key in KMS == the key in slot 0.
- Add new key to slot 0.
- Update the new key in the KMS.
- Fetch the key again and verify that the
key in KMS == the new key we generated.
- We can now remove the backup key from slot 1.
Note that the key in the KMS can always be used to unlock the volume.