mirrors/ceph-csi
1
0
Fork 0
mirror of https://github.com/ceph/ceph-csi.git synced 2024-12-18 11:00:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: Update docs for rbd-pv-key-rotation

Browse Source 
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>
This commit is contained in:
black-dragon74 2024-06-05 15:27:41 +05:30 committed by mergify[bot]
parent 4be5e4cbca
commit 64c5be5242
2 changed files with 71 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/design/proposals/pv-key-rotation.md
View File

@ -1,55 +0,0 @@
# Encryption Key Rotation
## Proposal
Subject of this proposal is to add support for rotation of encryption keys (KEKs) for encrypted volumes in Ceph-CSI.
## 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 periodic rotation of encryption keys for encrypted volumes.
This document outlines the rotation steps for PVCs backed by RBD and will be updated with other volume types as they are supported.
### Implementation Summary
This feature builds upon the foundation laid by encrypted pvcs.
An existing storage class can be annotated with `keyrotation.csiaddons.openshift.io/schedule` to enable the key rotation. The value of this annotation can be schedule in cron format or one of the macros supported by K8s CronJob spec.
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, credentials and secrets.
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.
A metadata is set on the RBD image to indicate that the image is being processed for keyrotation. Presence of this metadata will prevent the same image being processed again.
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 exsitng key from slot 0 upon verifying that the key in KMS == the key in slot 0.
- Add new key to slot 0 and then call `LuksVerifyKey` to verify that the slot was successfully updated.
- 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.
These order of the above steps guarantees that we always have one key that can unlock the encrypted volume.
The set metadata is removed once the key rotation is complete.

71
docs/design/proposals/rbd-pv-key-rotation.md Normal file
View File

@ -0,0 +1,71 @@
# 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.