Notational Conventions
The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” are to be interpreted as described in RFC 2119.
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. |
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.
Supported Features
This extension defines 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 encryption keys on volumes
Unsupported Features
- Rotating encryption 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.
Architecture
A user instructs the CSI-Addons CO plugin to rotate the encryption key of a
volume. The CO plugin inspects the capabilities advertised by the CSI-driver
(see the Identity EncryptionKeyRotation capability)
and translates the request into a gRPC call that is relayed to the CSI-driver.
The operation MAY be served by either the CSI ControllerPlugin or the CSI
NodePlugin.
Error Handling
All RPCs defined in this specification return a standard
gRPC status.
The status code MUST be a
canonical gRPC error code;
the CO MUST handle all valid error codes. When the code is not OK, the status
message MUST contain a human-readable description of the error, which MAY be
surfaced by the CO to end users. The status details MUST be empty.
Each RPC below documents, in its Errors table, the gRPC codes the CSI-driver returns for the listed conditions and the recovery behavior the caller is expected to implement.
The following error codes are common to all RPCs in this specification. In addition to the conditions below, each RPC MAY define further codes in its own Errors section.
| 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. |
| Invalid or unsupported field in the request | 3 INVALID_ARGUMENT | Indicates that one or more fields in the request is either not allowed by the CSI-driver or has an invalid value. | Caller MUST fix the field before retrying. |
| Operation pending | 10 ABORTED | Indicates that there is already an operation pending for the specified resource. 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 resource, and then retry with exponential back off. |
| Call not implemented | 12 UNIMPLEMENTED | The invoked RPC is not implemented by the CSI-driver or disabled in its current mode of operation. | Caller MUST NOT retry. |
| 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 pass authentication by the CSI-driver for the attempted RPC, after which point the caller MAY retry the attempted RPC. |
| Error is Unknown | 2 UNKNOWN | Indicates that an unknown error occurred. | Caller MUST study the logs before retrying. |
RPC Interface
- EncryptionKeyRotate Service: Either NodePlugin or ControllerPlugin MAY implement this RPC.
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){}
}
EncryptionKeyRotate
Either a Controller Plugin or a Node Plugin MUST implement this RPC call if it
has the EncryptionKeyRotation capability (see the
Identity service). This RPC is called by the CSI-Addons
CO plugin to rotate the Key Encryption Key (KEK) of an existing encrypted volume.
If the operation fails, or the CO does not know whether it succeeded, it MAY call
EncryptionKeyRotate again; the SP SHOULD handle such retries gracefully and
MUST NOT leave the volume inaccessible.
On success the CSI-driver replies 0 OK, indicating the volume’s Key Encryption
Key (KEK) has been replaced while the volume’s data remains intact and
accessible. The RPC MAY be served by the CSI ControllerPlugin or the CSI
NodePlugin; when served on the node, the optional volume_path identifies where
the volume is available. A CSI-driver that does not support key rotation in its
current mode MUST return UNIMPLEMENTED so that the CO does not retry.
EncryptionKeyRotateRequest
// 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];
// Volume capability describing how the CO intends to use this volume.
// This allows SP to determine if volume is being used as a block
// device or mounted file system. This is OPTIONAL.
csi.v1.VolumeCapability volume_capability = 6;
}
EncryptionKeyRotateResponse
// EncryptionKeyRotateResponse holds the information about the result of the
// EncryptionKeyRotateRequest call.
message EncryptionKeyRotateResponse {
}
EncryptionKeyRotate Errors
If the CSI-driver is unable to complete the EncryptionKeyRotate call successfully, it MUST return a non-ok gRPC code in the gRPC status. If the conditions defined below are encountered, the CSI-driver MUST return the specified gRPC error code. The caller MUST implement the specified error recovery behavior when it encounters the gRPC error code.
| Condition | gRPC Code | Description | Recovery Behavior |
|---|---|---|---|
| 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. |