From d3de47ceeedd1fae3f3c95595186a028002526d6 Mon Sep 17 00:00:00 2001 From: Nilekh Chaudhari <1626598+nilekhc@users.noreply.github.com> Date: Tue, 17 Oct 2023 22:17:43 +0000 Subject: [PATCH] chore: updates api doc Signed-off-by: Nilekh Chaudhari <1626598+nilekhc@users.noreply.github.com> --- .../storage/value/encrypt/envelope/kmsv2/v2/api.pb.go | 9 +++++++++ .../storage/value/encrypt/envelope/kmsv2/v2/api.proto | 9 +++++++++ staging/src/k8s.io/kms/apis/v2/api.pb.go | 11 ++++++++++- staging/src/k8s.io/kms/apis/v2/api.proto | 11 ++++++++++- 4 files changed, 38 insertions(+), 2 deletions(-) diff --git a/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.pb.go b/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.pb.go index 811c8f67d25..25150288f6e 100644 --- a/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.pb.go +++ b/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.pb.go @@ -71,11 +71,20 @@ type EncryptedObject struct { // EncryptedData is the encrypted data. EncryptedData []byte `protobuf:"bytes,1,opt,name=encryptedData,proto3" json:"encryptedData,omitempty"` // KeyID is the KMS key ID used for encryption operations. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. KeyID string `protobuf:"bytes,2,opt,name=keyID,proto3" json:"keyID,omitempty"` // EncryptedDEKSource is the ciphertext of the source of the DEK used to encrypt the data stored in encryptedData. // encryptedDEKSourceType defines the process of using the plaintext of this field to determine the aforementioned DEK. + // encryptedDEKSource must satisfy the following constraints: + // 1. The encrypted DEK source is not empty. + // 2. The size of encrypted DEK source is less than 1 kB. EncryptedDEKSource []byte `protobuf:"bytes,3,opt,name=encryptedDEKSource,proto3" json:"encryptedDEKSource,omitempty"` // Annotations is additional metadata that was provided by the KMS plugin. + // Annotations must satisfy the following constraints: + // 1. Annotation key must be a fully qualified domain name that conforms to the definition in DNS (RFC 1123). + // 2. The size of annotations keys + values is less than 32 kB. Annotations map[string][]byte `protobuf:"bytes,4,rep,name=annotations,proto3" json:"annotations,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` // encryptedDEKSourceType defines the process of using the plaintext of encryptedDEKSource to determine the DEK. EncryptedDEKSourceType EncryptedDEKSourceType `protobuf:"varint,5,opt,name=encryptedDEKSourceType,proto3,enum=v2.EncryptedDEKSourceType" json:"encryptedDEKSourceType,omitempty"` diff --git a/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.proto b/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.proto index ec1eb2680c8..674b3f4a9ae 100644 --- a/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.proto +++ b/staging/src/k8s.io/apiserver/pkg/storage/value/encrypt/envelope/kmsv2/v2/api.proto @@ -26,13 +26,22 @@ message EncryptedObject { bytes encryptedData = 1; // KeyID is the KMS key ID used for encryption operations. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. string keyID = 2; // EncryptedDEKSource is the ciphertext of the source of the DEK used to encrypt the data stored in encryptedData. // encryptedDEKSourceType defines the process of using the plaintext of this field to determine the aforementioned DEK. + // encryptedDEKSource must satisfy the following constraints: + // 1. The encrypted DEK source is not empty. + // 2. The size of encrypted DEK source is less than 1 kB. bytes encryptedDEKSource = 3; // Annotations is additional metadata that was provided by the KMS plugin. + // Annotations must satisfy the following constraints: + // 1. Annotation key must be a fully qualified domain name that conforms to the definition in DNS (RFC 1123). + // 2. The size of annotations keys + values is less than 32 kB. map annotations = 4; // encryptedDEKSourceType defines the process of using the plaintext of encryptedDEKSource to determine the DEK. diff --git a/staging/src/k8s.io/kms/apis/v2/api.pb.go b/staging/src/k8s.io/kms/apis/v2/api.pb.go index 13715bd9c8c..225cc3f8fc7 100644 --- a/staging/src/k8s.io/kms/apis/v2/api.pb.go +++ b/staging/src/k8s.io/kms/apis/v2/api.pb.go @@ -71,11 +71,14 @@ func (m *StatusRequest) XXX_DiscardUnknown() { var xxx_messageInfo_StatusRequest proto.InternalMessageInfo type StatusResponse struct { - // Version of the KMS plugin API. Must match the configured .resources[].providers[].kms.apiVersion + // Version of the KMS gRPC plugin API. Must equal v2 to v2beta1 (v2 is recommended, but both are equivalent). Version string `protobuf:"bytes,1,opt,name=version,proto3" json:"version,omitempty"` // Any value other than "ok" is failing healthz. On failure, the associated API server healthz endpoint will contain this value as part of the error message. Healthz string `protobuf:"bytes,2,opt,name=healthz,proto3" json:"healthz,omitempty"` // the current write key, used to determine staleness of data updated via value.Transformer.TransformFromStorage. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. KeyId string `protobuf:"bytes,3,opt,name=key_id,json=keyId,proto3" json:"key_id,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -283,9 +286,15 @@ func (m *EncryptRequest) GetUid() string { type EncryptResponse struct { // The encrypted data. + // ciphertext must satisfy the following constraints: + // 1. The ciphertext is not empty. + // 2. The ciphertext is less than 1 kB. Ciphertext []byte `protobuf:"bytes,1,opt,name=ciphertext,proto3" json:"ciphertext,omitempty"` // The KMS key ID used to encrypt the data. This must always refer to the KMS KEK and not any local KEKs that may be in use. // This can be used to inform staleness of data updated via value.Transformer.TransformFromStorage. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. KeyId string `protobuf:"bytes,2,opt,name=key_id,json=keyId,proto3" json:"key_id,omitempty"` // Additional metadata to be stored with the encrypted data. // This data is stored in plaintext in etcd. KMS plugin implementations are responsible for pre-encrypting any sensitive data. diff --git a/staging/src/k8s.io/kms/apis/v2/api.proto b/staging/src/k8s.io/kms/apis/v2/api.proto index d2c90048e77..be4752f477e 100644 --- a/staging/src/k8s.io/kms/apis/v2/api.proto +++ b/staging/src/k8s.io/kms/apis/v2/api.proto @@ -34,11 +34,14 @@ service KeyManagementService { message StatusRequest {} message StatusResponse { - // Version of the KMS plugin API. Must match the configured .resources[].providers[].kms.apiVersion + // Version of the KMS gRPC plugin API. Must equal v2 to v2beta1 (v2 is recommended, but both are equivalent). string version = 1; // Any value other than "ok" is failing healthz. On failure, the associated API server healthz endpoint will contain this value as part of the error message. string healthz = 2; // the current write key, used to determine staleness of data updated via value.Transformer.TransformFromStorage. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. string key_id = 3; } @@ -68,9 +71,15 @@ message EncryptRequest { message EncryptResponse { // The encrypted data. + // ciphertext must satisfy the following constraints: + // 1. The ciphertext is not empty. + // 2. The ciphertext is less than 1 kB. bytes ciphertext = 1; // The KMS key ID used to encrypt the data. This must always refer to the KMS KEK and not any local KEKs that may be in use. // This can be used to inform staleness of data updated via value.Transformer.TransformFromStorage. + // keyID must satisfy the following constraints: + // 1. The keyID is not empty. + // 2. The size of keyID is less than 1 kB. string key_id = 2; // Additional metadata to be stored with the encrypted data. // This data is stored in plaintext in etcd. KMS plugin implementations are responsible for pre-encrypting any sensitive data.