Skip to content

Commit

Permalink
Add Spec for EncryptionKeyRotation
Browse files Browse the repository at this point in the history 
This patch adds specification for EncryptionKeyRotation
operation of CSI addons.

Signed-off-by: Niraj Yadav <niryadav@redhat.com>
  • Loading branch information
@black-dragon74 @mergify
black-dragon74 authored and mergify[bot] committed Jun 27, 2024
1 parent 150c300 commit 0dd74d5
Show file tree
Hide file tree
Showing 9 changed files with 898 additions and 115 deletions.
1 change: 1 addition & 0 deletions Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 $@
Expand Down
20 changes: 20 additions & 0 deletions encryptionkeyrotation/Makefile
View file
Original file line number Diff line number Diff line change
@@ -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
106 changes: 106 additions & 0 deletions encryptionkeyrotation/README.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
45 changes: 45 additions & 0 deletions encryptionkeyrotation/encryptionkeyrotation.proto
View file
Original file line number Diff line number Diff line change
@@ -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 {

}
22 changes: 22 additions & 0 deletions identity/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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.
}
Expand Down
22 changes: 22 additions & 0 deletions identity/identity.proto
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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.
}
Expand Down
Loading

0 comments on commit 0dd74d5

Please sign in to comment.