feat: add client library for KMS Autokey service, which enables autom…

…ated KMS key provision and management PiperOrigin-RevId: 631565226
googleapis · May 7, 2024 · e5b8ffa · e5b8ffa
1 parent f059e8f
commit e5b8ffa
Show file tree

Hide file tree

Showing 5 changed files with 387 additions and 0 deletions.
diff --git a/google/cloud/kms/v1/BUILD.bazel b/google/cloud/kms/v1/BUILD.bazel
@@ -24,6 +24,8 @@ load("@rules_proto//proto:defs.bzl", "proto_library")
 proto_library(
     name = "kms_proto",
     srcs = [
+        "autokey.proto",
+        "autokey_admin.proto",
         "ekm_service.proto",
         "resources.proto",
         "service.proto",
@@ -99,6 +101,10 @@ java_gapic_library(
 java_gapic_test(
     name = "kms_java_gapic_test_suite",
     test_classes = [
+        "com.google.cloud.kms.v1.AutokeyAdminClientHttpJsonTest",
+        "com.google.cloud.kms.v1.AutokeyAdminClientTest",
+        "com.google.cloud.kms.v1.AutokeyClientHttpJsonTest",
+        "com.google.cloud.kms.v1.AutokeyClientTest",
         "com.google.cloud.kms.v1.EkmServiceClientHttpJsonTest",
         "com.google.cloud.kms.v1.EkmServiceClientTest",
         "com.google.cloud.kms.v1.KeyManagementServiceClientHttpJsonTest",

diff --git a/google/cloud/kms/v1/autokey.proto b/google/cloud/kms/v1/autokey.proto
@@ -0,0 +1,194 @@
+// Copyright 2024 Google LLC
+//
+// 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.
+
+syntax = "proto3";
+
+package google.cloud.kms.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/longrunning/operations.proto";
+
+option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb";
+option java_multiple_files = true;
+option java_outer_classname = "AutokeyProto";
+option java_package = "com.google.cloud.kms.v1";
+
+// Provides interfaces for using Cloud KMS Autokey to provision new
+// [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer Managed
+// Encryption Key (CMEK) use, on-demand. To support certain client tooling, this
+// feature is modeled around a [KeyHandle][google.cloud.kms.v1.KeyHandle]
+// resource: creating a [KeyHandle][google.cloud.kms.v1.KeyHandle] in a resource
+// project and given location triggers Cloud KMS Autokey to provision a
+// [CryptoKey][google.cloud.kms.v1.CryptoKey] in the configured key project and
+// the same location.
+//
+// Prior to use in a given resource project,
+// [UpdateAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.UpdateAutokeyConfig]
+// should have been called on an ancestor folder, setting the key project where
+// Cloud KMS Autokey should create new
+// [CryptoKeys][google.cloud.kms.v1.CryptoKey]. See documentation for additional
+// prerequisites. To check what key project, if any, is currently configured on
+// a resource project's ancestor folder, see
+// [ShowEffectiveAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.ShowEffectiveAutokeyConfig].
+service Autokey {
+  option (google.api.default_host) = "cloudkms.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform,"
+      "https://www.googleapis.com/auth/cloudkms";
+
+  // Creates a new [KeyHandle][google.cloud.kms.v1.KeyHandle], triggering the
+  // provisioning of a new [CryptoKey][google.cloud.kms.v1.CryptoKey] for CMEK
+  // use with the given resource type in the configured key project and the same
+  // location. [GetOperation][Operations.GetOperation] should be used to resolve
+  // the resulting long-running operation and get the resulting
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] and
+  // [CryptoKey][google.cloud.kms.v1.CryptoKey].
+  rpc CreateKeyHandle(CreateKeyHandleRequest)
+      returns (google.longrunning.Operation) {
+    option (google.api.http) = {
+      post: "/v1/{parent=projects/*/locations/*}/keyHandles"
+      body: "key_handle"
+    };
+    option (google.api.method_signature) = "parent,key_handle,key_handle_id";
+    option (google.longrunning.operation_info) = {
+      response_type: "KeyHandle"
+      metadata_type: "CreateKeyHandleMetadata"
+    };
+  }
+
+  // Returns the [KeyHandle][google.cloud.kms.v1.KeyHandle].
+  rpc GetKeyHandle(GetKeyHandleRequest) returns (KeyHandle) {
+    option (google.api.http) = {
+      get: "/v1/{name=projects/*/locations/*/keyHandles/*}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists [KeyHandles][google.cloud.kms.v1.KeyHandle].
+  rpc ListKeyHandles(ListKeyHandlesRequest) returns (ListKeyHandlesResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*/locations/*}/keyHandles"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// Request message for
+// [Autokey.CreateKeyHandle][google.cloud.kms.v1.Autokey.CreateKeyHandle].
+message CreateKeyHandleRequest {
+  // Required. Name of the resource project and location to create the
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] in, e.g.
+  // `projects/{PROJECT_ID}/locations/{LOCATION}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
+
+  // Optional. Id of the [KeyHandle][google.cloud.kms.v1.KeyHandle]. Must be
+  // unique to the resource project and location. If not provided by the caller,
+  // a new UUID is used.
+  string key_handle_id = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. [KeyHandle][google.cloud.kms.v1.KeyHandle] to create.
+  KeyHandle key_handle = 3 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request message for [GetKeyHandle][google.cloud.kms.v1.Autokey.GetKeyHandle].
+message GetKeyHandleRequest {
+  // Required. Name of the [KeyHandle][google.cloud.kms.v1.KeyHandle] resource,
+  // e.g.
+  // `projects/{PROJECT_ID}/locations/{LOCATION}/keyHandles/{KEY_HANDLE_ID}`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudkms.googleapis.com/KeyHandle"
+    }
+  ];
+}
+
+// Resource-oriented representation of a request to Cloud KMS Autokey and the
+// resulting provisioning of a [CryptoKey][google.cloud.kms.v1.CryptoKey].
+message KeyHandle {
+  option (google.api.resource) = {
+    type: "cloudkms.googleapis.com/KeyHandle"
+    pattern: "projects/{project}/locations/{location}/keyHandles/{key_handle}"
+    plural: "keyHandles"
+    singular: "keyHandle"
+  };
+
+  // Identifier. Name of the [KeyHandle][google.cloud.kms.v1.KeyHandle]
+  // resource, e.g.
+  // `projects/{PROJECT_ID}/locations/{LOCATION}/keyHandles/{KEY_HANDLE_ID}`.
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Output only. Name of a [CryptoKey][google.cloud.kms.v1.CryptoKey] that has
+  // been provisioned for Customer Managed Encryption Key (CMEK) use in the
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] project and location for the
+  // requested resource type. The [CryptoKey][google.cloud.kms.v1.CryptoKey]
+  // project will reflect the value configured in the
+  // [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig] on the resource
+  // project's ancestor folder at the time of the
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] creation. If more than one
+  // ancestor folder has a configured
+  // [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig], the nearest of these
+  // configurations is used.
+  string kms_key = 3 [
+    (google.api.field_behavior) = OUTPUT_ONLY,
+    (google.api.resource_reference) = {
+      type: "cloudkms.googleapis.com/CryptoKey"
+    }
+  ];
+
+  // Required. Indicates the resource type that the resulting
+  // [CryptoKey][google.cloud.kms.v1.CryptoKey] is meant to protect, e.g.
+  // `{SERVICE}.googleapis.com/{TYPE}`. See documentation for supported resource
+  // types.
+  string resource_type_selector = 4 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Metadata message for
+// [CreateKeyHandle][google.cloud.kms.v1.Autokey.CreateKeyHandle] long-running
+// operation response.
+message CreateKeyHandleMetadata {}
+
+// Request message for
+// [Autokey.ListKeyHandles][google.cloud.kms.v1.Autokey.ListKeyHandles].
+message ListKeyHandlesRequest {
+  // Required. Name of the resource project and location from which to list
+  // [KeyHandles][google.cloud.kms.v1.KeyHandle], e.g.
+  // `projects/{PROJECT_ID}/locations/{LOCATION}`.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "locations.googleapis.com/Location"
+    }
+  ];
+
+  // Optional. Filter to apply when listing
+  // [KeyHandles][google.cloud.kms.v1.KeyHandle], e.g.
+  // `resource_type_selector="{SERVICE}.googleapis.com/{TYPE}"`.
+  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for
+// [Autokey.ListKeyHandles][google.cloud.kms.v1.Autokey.ListKeyHandles].
+message ListKeyHandlesResponse {
+  // Resulting [KeyHandles][google.cloud.kms.v1.KeyHandle].
+  repeated KeyHandle key_handles = 1;
+}
diff --git a/google/cloud/kms/v1/autokey_admin.proto b/google/cloud/kms/v1/autokey_admin.proto
@@ -0,0 +1,151 @@
+// Copyright 2024 Google LLC
+//
+// 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.
+
+syntax = "proto3";
+
+package google.cloud.kms.v1;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/field_mask.proto";
+
+option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb";
+option java_multiple_files = true;
+option java_outer_classname = "AutokeyAdminProto";
+option java_package = "com.google.cloud.kms.v1";
+
+// Provides interfaces for managing Cloud KMS Autokey folder-level
+// configurations. A configuration is inherited by all descendent projects. A
+// configuration at one folder overrides any other configurations in its
+// ancestry. Setting a configuration on a folder is a prerequisite for Cloud KMS
+// Autokey, so that users working in a descendant project can request
+// provisioned [CryptoKeys][google.cloud.kms.v1.CryptoKey], ready for Customer
+// Managed Encryption Key (CMEK) use, on-demand.
+service AutokeyAdmin {
+  option (google.api.default_host) = "cloudkms.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform,"
+      "https://www.googleapis.com/auth/cloudkms";
+
+  // Updates the [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig] for a
+  // folder. The caller must have both `cloudkms.autokeyConfigs.update`
+  // permission on the parent folder and `cloudkms.cryptoKeys.setIamPolicy`
+  // permission on the provided key project. A
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] creation in the folder's
+  // descendant projects will use this configuration to determine where to
+  // create the resulting [CryptoKey][google.cloud.kms.v1.CryptoKey].
+  rpc UpdateAutokeyConfig(UpdateAutokeyConfigRequest) returns (AutokeyConfig) {
+    option (google.api.http) = {
+      patch: "/v1/{autokey_config.name=folders/*/autokeyConfig}"
+      body: "autokey_config"
+    };
+    option (google.api.method_signature) = "autokey_config,update_mask";
+  }
+
+  // Returns the [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig] for a
+  // folder.
+  rpc GetAutokeyConfig(GetAutokeyConfigRequest) returns (AutokeyConfig) {
+    option (google.api.http) = {
+      get: "/v1/{name=folders/*/autokeyConfig}"
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Returns the effective Cloud KMS Autokey configuration for a given project.
+  rpc ShowEffectiveAutokeyConfig(ShowEffectiveAutokeyConfigRequest)
+      returns (ShowEffectiveAutokeyConfigResponse) {
+    option (google.api.http) = {
+      get: "/v1/{parent=projects/*}:showEffectiveAutokeyConfig"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+}
+
+// Request message for
+// [UpdateAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.UpdateAutokeyConfig].
+message UpdateAutokeyConfigRequest {
+  // Required. [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig] with values to
+  // update.
+  AutokeyConfig autokey_config = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. Masks which fields of the
+  // [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig] to update, e.g.
+  // `keyProject`.
+  google.protobuf.FieldMask update_mask = 2
+      [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request message for
+// [GetAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.GetAutokeyConfig].
+message GetAutokeyConfigRequest {
+  // Required. Name of the [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig]
+  // resource, e.g. `folders/{FOLDER_NUMBER}/autokeyConfig`.
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudkms.googleapis.com/AutokeyConfig"
+    }
+  ];
+}
+
+// Cloud KMS Autokey configuration for a folder.
+message AutokeyConfig {
+  option (google.api.resource) = {
+    type: "cloudkms.googleapis.com/AutokeyConfig"
+    pattern: "folders/{folder}/autokeyConfig"
+    plural: "autokeyConfigs"
+    singular: "autokeyConfig"
+  };
+
+  // Identifier. Name of the [AutokeyConfig][google.cloud.kms.v1.AutokeyConfig]
+  // resource, e.g. `folders/{FOLDER_NUMBER}/autokeyConfig`.
+  string name = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // Optional. Name of the key project, e.g. `projects/{PROJECT_ID}` or
+  // `projects/{PROJECT_NUMBER}`, where Cloud KMS Autokey will provision a new
+  // [CryptoKey][google.cloud.kms.v1.CryptoKey] when a
+  // [KeyHandle][google.cloud.kms.v1.KeyHandle] is created. On
+  // [UpdateAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.UpdateAutokeyConfig],
+  // the caller will require `cloudkms.cryptoKeys.setIamPolicy` permission on
+  // this key project. Once configured, for Cloud KMS Autokey to function
+  // properly, this key project must have the Cloud KMS API activated and the
+  // Cloud KMS Service Agent for this key project must be granted the
+  // `cloudkms.admin` role (or pertinent permissions). A request with an empty
+  // key project field will clear the configuration.
+  string key_project = 2 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request message for
+// [ShowEffectiveAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.ShowEffectiveAutokeyConfig].
+message ShowEffectiveAutokeyConfigRequest {
+  // Required. Name of the resource project to the show effective Cloud KMS
+  // Autokey configuration for. This may be helpful for interrogating the effect
+  // of nested folder configurations on a given resource project.
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "cloudresourcemanager.googleapis.com/Project"
+    }
+  ];
+}
+
+// Response message for
+// [ShowEffectiveAutokeyConfig][google.cloud.kms.v1.AutokeyAdmin.ShowEffectiveAutokeyConfig].
+message ShowEffectiveAutokeyConfigResponse {
+  // Name of the key project configured in the resource project's folder
+  // ancestry.
+  string key_project = 1;
+}