docs: proposal for providing PV key rotation

docs/design/proposals/rbd-pv-key-rotation.md

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