Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Spec for EncryptionKeyRotation #65

Merged
merged 1 commit into from
Jun 27, 2024
+898 −115
Merged

Add Spec for EncryptionKeyRotation #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
black-dragon74 marked this conversation as resolved.
Show resolved Hide resolved

```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 {
nixpanic marked this conversation as resolved.
Show resolved Hide resolved
// 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 {

black-dragon74 marked this conversation as resolved.
Show resolved Hide resolved
}
```

### 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
Open in desktop
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
Open in desktop
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.
black-dragon74 marked this conversation as resolved.
Show resolved Hide resolved
// 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
Open in desktop
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 {
black-dragon74 marked this conversation as resolved.
Show resolved Hide resolved
// 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;
black-dragon74 marked this conversation as resolved.
Show resolved Hide resolved
}
// 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