Add Spec for EncryptionKeyRotation

This patch adds specification for EncryptionKeyRotation operation of CSI addons. Signed-off-by: Niraj Yadav <[email protected]>
csi-addons · Jun 25, 2024 · 1407a34 · 1407a34
1 parent 6a5ff09
commit 1407a34
Show file tree

Hide file tree

Showing 9 changed files with 898 additions and 115 deletions.
diff --git a/Makefile b/Makefile
@@ -21,6 +21,7 @@ clean-deps:
 	rm -rf bin dist github.com google
 
 %:
+	$(MAKE) -C encryptionkeyrotation $@
 	$(MAKE) -C fence $@
 	$(MAKE) -C identity $@
 	$(MAKE) -C reclaimspace $@

diff --git a/encryptionkeyrotation/Makefile b/encryptionkeyrotation/Makefile
@@ -0,0 +1,20 @@
+# Copyright 2024 The csi-addons Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+PROTO := encryptionkeyrotation.proto
+PROTO_SOURCE := README.md
+
+all: install-deps $(PROTO) build
+
+include ../release-tools/build.make
diff --git a/encryptionkeyrotation/README.md b/encryptionkeyrotation/README.md
@@ -0,0 +1,106 @@
+# CSI Addons Operation: EncryptionKeyRotation
+
+## Terminology
+
+| Term     | Definition                                                                            |
+| -------- | ------------------------------------------------------------------------------------- |
+| VolumeID | The identifier of the volume generated by the plugin.                                 |
+| CO       | Container Orchestration system that communicates with plugins using CSI service RPCs. |
+| SP       | Storage Provider, the vendor of a CSI plugin implementation.                          |
+| RPC      | [Remote Procedure Call](https://en.wikipedia.org/wiki/Remote_procedure_call).         |
+
+## Objective
+
+Define an extension to the CSI specification that will enable storage vendors
+(SP) to develop controllers/plugins that can rotate the Key Encryption Keys (KEK)
+of existing volumes that are encrypted.
+
+### Goals in MVP
+
+The new extension will define a procedure that
+
+- can be called for existing encrypted volumes
+- functions for Block and filesystem access mode volumes
+- interacts with the NodePlugin
+- makes it possible for the SP to rotate encrpytion keys on volumes
+
+### Non-Goals in MVP
+
+- Rotating encrpytion keys for inactive volumes
+
+## Solution Overview
+
+This specification defines an interface along with the minimum operational and
+packaging recommendations for a storage provider (SP) to implement a key rotate operation for volumes. The interface declares the RPCs that a plugin
+MUST expose.
+
+## RPC Interface
+
+- **EncryptionKeyRotate Service**: Either NodePlugin or ControllerPlugin MAY implement this RPC.
+
+```protobuf
+syntax = "proto3";
+package encryptionkeyrotation;
+
+import "github.com/container-storage-interface/spec/lib/go/csi/csi.proto";
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/csi-addons/spec/lib/go/encryptionkeyrotation";
+
+// EncryptionKeyRotationController holds the RPC method for running
+// key rotation operation on the volume.
+service EncryptionKeyRotationController {
+  // EncryptionKeyRotate is a procedure that is called
+  // on the CSI ControllerPlugin or NodePlugin
+  rpc EncryptionKeyRotate(EncryptionKeyRotateRequest)
+  returns (EncryptionKeyRotateResponse){}
+}
+```
+
+### EncryptionKeyRotateRequest
+
+```protobuf
+// EncryptionKeyRotateRequest contains the information needed to identify
+// the volume by the SP and access any backend services so that the key can be
+// rotated.
+message EncryptionKeyRotateRequest {
+  // The ID of the volume for which the key is to be rotated.
+  // This field is required
+  string volume_id = 1;
+
+  // The path where the volume is available.
+  // This field is OPTIONAL
+  // Useful if you are implementing the RPC on CSI Driver NodePlugin
+  string volume_path = 2;
+
+  // Provide the encryption key to be set
+  // This field is OPTIONAL
+  string encryption_key = 3 [(csi.v1.csi_secret) = true];
+
+  // Plugin specific parameters passed in as opaque key-value pairs.
+  map<string, string> parameters = 4;
+
+  // Secrets required by the plugin to complete the request.
+  map<string, string> secrets = 5 [(csi.v1.csi_secret) = true];
+}
+```
+
+### EncryptionKeyRotateResponse
+
+```protobuf
+// EncryptionKeyRotateResponse holds the information about the result of the
+// EncryptionKeyRotateRequest call.
+message EncryptionKeyRotateResponse {
+
+}
+```
+
+### Error Schemes
+
+| Condition                    | gRPC Code          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Recovery Behavior                                                                                                                                                                                                                     |
+| ---------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Missing required field       | 3 INVALID_ARGUMENT | Indicates that a required field is missing from the request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Caller MUST fix the request by adding the missing required field before retrying.                                                                                                                                                     |
+| Volume does not exist        | 5 NOT_FOUND        | Indicates that a volume corresponding to the specified `volume_id` does not exist.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Caller MUST verify that the `volume_id` is correct and that the volume is accessible and has not been deleted before retrying with exponential back off.                                                                              |
+| Operation pending for volume | 10 ABORTED         | Indicates that there is already an operation pending for the specified `volume_id`. In general the CSI-Addons CO plugin is responsible for ensuring that there is no more than one call "in-flight" per `volume_id` at a given time. However, in some circumstances, the CSI-Addons CO plugin MAY lose state (for example when the it crashes and restarts), and MAY issue multiple calls simultaneously for the same `volume_id`. The CSI driver, SHOULD handle this as gracefully as possible, and MAY return this error code to reject secondary calls. | Caller SHOULD ensure that there are no other calls pending for the specified `volume_id`, and then retry with exponential back off.                                                                                                   |
+| Not authenticated            | 16 UNAUTHENTICATED | The invoked RPC does not carry secrets that are valid for authentication.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Caller SHALL either fix the secrets provided in the RPC, or otherwise regalvanize said secrets such that they will pass authentication by the Plugin for the attempted RPC, after which point the caller MAY retry the attempted RPC. |
+| Error is Unknown             | 2 UNKNOWN          | Indicates that a unknown error is generated                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Caller MUST study the logs before retrying                                                                                                                                                                                            |
diff --git a/encryptionkeyrotation/encryptionkeyrotation.proto b/encryptionkeyrotation/encryptionkeyrotation.proto
@@ -0,0 +1,45 @@
+// Code generated by make; DO NOT EDIT.
+syntax = "proto3";
+package encryptionkeyrotation;
+
+import "github.com/container-storage-interface/spec/lib/go/csi/csi.proto";
+import "google/protobuf/descriptor.proto";
+
+option go_package = "github.com/csi-addons/spec/lib/go/encryptionkeyrotation";
+
+// EncryptionKeyRotationController holds the RPC method for running
+// key rotation operation on the volume.
+service EncryptionKeyRotationController {
+  // EncryptionKeyRotate is a procedure that is called
+  // on the CSI ControllerPlugin or NodePlugin
+  rpc EncryptionKeyRotate(EncryptionKeyRotateRequest)
+  returns (EncryptionKeyRotateResponse){}
+}
+// EncryptionKeyRotateRequest contains the information needed to identify
+// the volume by the SP and access any backend services so that the key can be
+// rotated.
+message EncryptionKeyRotateRequest {
+  // The ID of the volume for which the key is to be rotated.
+  // This field is required
+  string volume_id = 1;
+
+  // The path where the volume is available.
+  // This field is OPTIONAL
+  // Useful if you are implementing the RPC on CSI Driver NodePlugin
+  string volume_path = 2;
+
+  // Provide the encryption key to be set
+  // This field is OPTIONAL
+  string encryption_key = 3 [(csi.v1.csi_secret) = true];
+
+  // Plugin specific parameters passed in as opaque key-value pairs.
+  map<string, string> parameters = 4;
+
+  // Secrets required by the plugin to complete the request.
+  map<string, string> secrets = 5 [(csi.v1.csi_secret) = true];
+}
+// EncryptionKeyRotateResponse holds the information about the result of the
+// EncryptionKeyRotateRequest call.
+message EncryptionKeyRotateResponse {
+
+}
diff --git a/identity/README.md b/identity/README.md
@@ -300,6 +300,26 @@ message Capability {
     Type type = 1;
   }
 
+  // EncryptionKeyRotation contains the features of the EncryptionKeyRotation
+  // operation that the CSI driver supports.
+  message EncryptionKeyRotation {
+    // Type describes a CSI Encryption Service that CSI driver can support.
+    enum Type {
+      // UNKNOWN indicates that the CSI driver does not support the
+      // EncryptionKeyRotation operation in the current mode.
+      // The CSI-Addons CO plugin will most likely ignore this node
+      // for the EncryptionKeyRotation operation.
+      UNKNOWN = 0;
+      // ENCRYPTIONKEYROTATION indicates that the CSI driver provides
+      // RPCs for an EncryptionKeyRotation operation.
+      // The presence of this capability determines whether the CSI-Addons CO
+      // plugin can invoke RPCs for rotating the encryption key.
+      ENCRYPTIONKEYROTATION = 1;
+    }
+    // type contains the Type of CSI Service that the CSI driver supports.
+    Type type = 1;
+  }
+
   // Additional CSI-Addons operations will need to be added here.
 
   oneof type {
@@ -313,6 +333,8 @@ message Capability {
     VolumeReplication volume_replication = 4;
     // VolumeGroup operation capabilities.
     VolumeGroup volume_group = 5;
+    // EncryptionKeyRotation operation capabilities.
+    EncryptionKeyRotation encryption_key_rotation = 6;
 
     // Additional CSI-Addons operations need to be appended to this list.
   }

diff --git a/identity/identity.proto b/identity/identity.proto
@@ -200,6 +200,26 @@ message Capability {
     Type type = 1;
   }
 
+  // EncryptionKeyRotation contains the features of the EncryptionKeyRotation
+  // operation that the CSI driver supports.
+  message EncryptionKeyRotation {
+    // Type describes a CSI Encryption Service that CSI driver can support.
+    enum Type {
+      // UNKNOWN indicates that the CSI driver does not support the
+      // EncryptionKeyRotation operation in the current mode.
+      // The CSI-Addons CO plugin will most likely ignore this node
+      // for the EncryptionKeyRotation operation.
+      UNKNOWN = 0;
+      // ENCRYPTIONKEYROTATION indicates that the CSI driver provides
+      // RPCs for an EncryptionKeyRotation operation.
+      // The presence of this capability determines whether the CSI-Addons CO
+      // plugin can invoke RPCs for rotating the encryption key.
+      ENCRYPTIONKEYROTATION = 1;
+    }
+    // type contains the Type of CSI Service that the CSI driver supports.
+    Type type = 1;
+  }
+
   // Additional CSI-Addons operations will need to be added here.
 
   oneof type {
@@ -213,6 +233,8 @@ message Capability {
     VolumeReplication volume_replication = 4;
     // VolumeGroup operation capabilities.
     VolumeGroup volume_group = 5;
+    // EncryptionKeyRotation operation capabilities.
+    EncryptionKeyRotation encryption_key_rotation = 6;
 
     // Additional CSI-Addons operations need to be appended to this list.
   }