1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.cloud.kms.v1; 18 19import "google/api/annotations.proto"; 20import "google/api/client.proto"; 21import "google/api/field_behavior.proto"; 22import "google/api/resource.proto"; 23import "google/protobuf/field_mask.proto"; 24import "google/protobuf/timestamp.proto"; 25 26option cc_enable_arenas = true; 27option csharp_namespace = "Google.Cloud.Kms.V1"; 28option go_package = "cloud.google.com/go/kms/apiv1/kmspb;kmspb"; 29option java_multiple_files = true; 30option java_outer_classname = "EkmServiceProto"; 31option java_package = "com.google.cloud.kms.v1"; 32option php_namespace = "Google\\Cloud\\Kms\\V1"; 33option (google.api.resource_definition) = { 34 type: "servicedirectory.googleapis.com/Service" 35 pattern: "projects/{project}/locations/{location}/namespaces/{namespace}/services/{service}" 36}; 37 38// Google Cloud Key Management EKM Service 39// 40// Manages external cryptographic keys and operations using those keys. 41// Implements a REST model with the following objects: 42// * [EkmConnection][google.cloud.kms.v1.EkmConnection] 43service EkmService { 44 option (google.api.default_host) = "cloudkms.googleapis.com"; 45 option (google.api.oauth_scopes) = 46 "https://www.googleapis.com/auth/cloud-platform," 47 "https://www.googleapis.com/auth/cloudkms"; 48 49 // Lists [EkmConnections][google.cloud.kms.v1.EkmConnection]. 50 rpc ListEkmConnections(ListEkmConnectionsRequest) 51 returns (ListEkmConnectionsResponse) { 52 option (google.api.http) = { 53 get: "/v1/{parent=projects/*/locations/*}/ekmConnections" 54 }; 55 option (google.api.method_signature) = "parent"; 56 } 57 58 // Returns metadata for a given 59 // [EkmConnection][google.cloud.kms.v1.EkmConnection]. 60 rpc GetEkmConnection(GetEkmConnectionRequest) returns (EkmConnection) { 61 option (google.api.http) = { 62 get: "/v1/{name=projects/*/locations/*/ekmConnections/*}" 63 }; 64 option (google.api.method_signature) = "name"; 65 } 66 67 // Creates a new [EkmConnection][google.cloud.kms.v1.EkmConnection] in a given 68 // Project and Location. 69 rpc CreateEkmConnection(CreateEkmConnectionRequest) returns (EkmConnection) { 70 option (google.api.http) = { 71 post: "/v1/{parent=projects/*/locations/*}/ekmConnections" 72 body: "ekm_connection" 73 }; 74 option (google.api.method_signature) = 75 "parent,ekm_connection_id,ekm_connection"; 76 } 77 78 // Updates an [EkmConnection][google.cloud.kms.v1.EkmConnection]'s metadata. 79 rpc UpdateEkmConnection(UpdateEkmConnectionRequest) returns (EkmConnection) { 80 option (google.api.http) = { 81 patch: "/v1/{ekm_connection.name=projects/*/locations/*/ekmConnections/*}" 82 body: "ekm_connection" 83 }; 84 option (google.api.method_signature) = "ekm_connection,update_mask"; 85 } 86 87 // Returns the [EkmConfig][google.cloud.kms.v1.EkmConfig] singleton resource 88 // for a given project and location. 89 rpc GetEkmConfig(GetEkmConfigRequest) returns (EkmConfig) { 90 option (google.api.http) = { 91 get: "/v1/{name=projects/*/locations/*/ekmConfig}" 92 }; 93 option (google.api.method_signature) = "name"; 94 } 95 96 // Updates the [EkmConfig][google.cloud.kms.v1.EkmConfig] singleton resource 97 // for a given project and location. 98 rpc UpdateEkmConfig(UpdateEkmConfigRequest) returns (EkmConfig) { 99 option (google.api.http) = { 100 patch: "/v1/{ekm_config.name=projects/*/locations/*/ekmConfig}" 101 body: "ekm_config" 102 }; 103 option (google.api.method_signature) = "ekm_config,update_mask"; 104 } 105 106 // Verifies that Cloud KMS can successfully connect to the external key 107 // manager specified by an [EkmConnection][google.cloud.kms.v1.EkmConnection]. 108 // If there is an error connecting to the EKM, this method returns a 109 // FAILED_PRECONDITION status containing structured information as described 110 // at https://cloud.google.com/kms/docs/reference/ekm_errors. 111 rpc VerifyConnectivity(VerifyConnectivityRequest) 112 returns (VerifyConnectivityResponse) { 113 option (google.api.http) = { 114 get: "/v1/{name=projects/*/locations/*/ekmConnections/*}:verifyConnectivity" 115 }; 116 option (google.api.method_signature) = "name"; 117 } 118} 119 120// Request message for 121// [EkmService.ListEkmConnections][google.cloud.kms.v1.EkmService.ListEkmConnections]. 122message ListEkmConnectionsRequest { 123 // Required. The resource name of the location associated with the 124 // [EkmConnections][google.cloud.kms.v1.EkmConnection] to list, in the format 125 // `projects/*/locations/*`. 126 string parent = 1 [ 127 (google.api.field_behavior) = REQUIRED, 128 (google.api.resource_reference) = { 129 type: "locations.googleapis.com/Location" 130 } 131 ]; 132 133 // Optional. Optional limit on the number of 134 // [EkmConnections][google.cloud.kms.v1.EkmConnection] to include in the 135 // response. Further [EkmConnections][google.cloud.kms.v1.EkmConnection] can 136 // subsequently be obtained by including the 137 // [ListEkmConnectionsResponse.next_page_token][google.cloud.kms.v1.ListEkmConnectionsResponse.next_page_token] 138 // in a subsequent request. If unspecified, the server will pick an 139 // appropriate default. 140 int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; 141 142 // Optional. Optional pagination token, returned earlier via 143 // [ListEkmConnectionsResponse.next_page_token][google.cloud.kms.v1.ListEkmConnectionsResponse.next_page_token]. 144 string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; 145 146 // Optional. Only include resources that match the filter in the response. For 147 // more information, see 148 // [Sorting and filtering list 149 // results](https://cloud.google.com/kms/docs/sorting-and-filtering). 150 string filter = 4 [(google.api.field_behavior) = OPTIONAL]; 151 152 // Optional. Specify how the results should be sorted. If not specified, the 153 // results will be sorted in the default order. For more information, see 154 // [Sorting and filtering list 155 // results](https://cloud.google.com/kms/docs/sorting-and-filtering). 156 string order_by = 5 [(google.api.field_behavior) = OPTIONAL]; 157} 158 159// Response message for 160// [EkmService.ListEkmConnections][google.cloud.kms.v1.EkmService.ListEkmConnections]. 161message ListEkmConnectionsResponse { 162 // The list of [EkmConnections][google.cloud.kms.v1.EkmConnection]. 163 repeated EkmConnection ekm_connections = 1; 164 165 // A token to retrieve next page of results. Pass this value in 166 // [ListEkmConnectionsRequest.page_token][google.cloud.kms.v1.ListEkmConnectionsRequest.page_token] 167 // to retrieve the next page of results. 168 string next_page_token = 2; 169 170 // The total number of [EkmConnections][google.cloud.kms.v1.EkmConnection] 171 // that matched the query. 172 int32 total_size = 3; 173} 174 175// Request message for 176// [EkmService.GetEkmConnection][google.cloud.kms.v1.EkmService.GetEkmConnection]. 177message GetEkmConnectionRequest { 178 // Required. The [name][google.cloud.kms.v1.EkmConnection.name] of the 179 // [EkmConnection][google.cloud.kms.v1.EkmConnection] to get. 180 string name = 1 [ 181 (google.api.field_behavior) = REQUIRED, 182 (google.api.resource_reference) = { 183 type: "cloudkms.googleapis.com/EkmConnection" 184 } 185 ]; 186} 187 188// Request message for 189// [EkmService.CreateEkmConnection][google.cloud.kms.v1.EkmService.CreateEkmConnection]. 190message CreateEkmConnectionRequest { 191 // Required. The resource name of the location associated with the 192 // [EkmConnection][google.cloud.kms.v1.EkmConnection], in the format 193 // `projects/*/locations/*`. 194 string parent = 1 [ 195 (google.api.field_behavior) = REQUIRED, 196 (google.api.resource_reference) = { 197 type: "locations.googleapis.com/Location" 198 } 199 ]; 200 201 // Required. It must be unique within a location and match the regular 202 // expression `[a-zA-Z0-9_-]{1,63}`. 203 string ekm_connection_id = 2 [(google.api.field_behavior) = REQUIRED]; 204 205 // Required. An [EkmConnection][google.cloud.kms.v1.EkmConnection] with 206 // initial field values. 207 EkmConnection ekm_connection = 3 [(google.api.field_behavior) = REQUIRED]; 208} 209 210// Request message for 211// [EkmService.UpdateEkmConnection][google.cloud.kms.v1.EkmService.UpdateEkmConnection]. 212message UpdateEkmConnectionRequest { 213 // Required. [EkmConnection][google.cloud.kms.v1.EkmConnection] with updated 214 // values. 215 EkmConnection ekm_connection = 1 [(google.api.field_behavior) = REQUIRED]; 216 217 // Required. List of fields to be updated in this request. 218 google.protobuf.FieldMask update_mask = 2 219 [(google.api.field_behavior) = REQUIRED]; 220} 221 222// Request message for 223// [EkmService.GetEkmConfig][google.cloud.kms.v1.EkmService.GetEkmConfig]. 224message GetEkmConfigRequest { 225 // Required. The [name][google.cloud.kms.v1.EkmConfig.name] of the 226 // [EkmConfig][google.cloud.kms.v1.EkmConfig] to get. 227 string name = 1 [ 228 (google.api.field_behavior) = REQUIRED, 229 (google.api.resource_reference) = { 230 type: "cloudkms.googleapis.com/EkmConfig" 231 } 232 ]; 233} 234 235// Request message for 236// [EkmService.UpdateEkmConfig][google.cloud.kms.v1.EkmService.UpdateEkmConfig]. 237message UpdateEkmConfigRequest { 238 // Required. [EkmConfig][google.cloud.kms.v1.EkmConfig] with updated values. 239 EkmConfig ekm_config = 1 [(google.api.field_behavior) = REQUIRED]; 240 241 // Required. List of fields to be updated in this request. 242 google.protobuf.FieldMask update_mask = 2 243 [(google.api.field_behavior) = REQUIRED]; 244} 245 246// A [Certificate][google.cloud.kms.v1.Certificate] represents an X.509 247// certificate used to authenticate HTTPS connections to EKM replicas. 248message Certificate { 249 // Required. The raw certificate bytes in DER format. 250 bytes raw_der = 1 [(google.api.field_behavior) = REQUIRED]; 251 252 // Output only. True if the certificate was parsed successfully. 253 bool parsed = 2 [(google.api.field_behavior) = OUTPUT_ONLY]; 254 255 // Output only. The issuer distinguished name in RFC 2253 format. Only present 256 // if [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 257 string issuer = 3 [(google.api.field_behavior) = OUTPUT_ONLY]; 258 259 // Output only. The subject distinguished name in RFC 2253 format. Only 260 // present if [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 261 string subject = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; 262 263 // Output only. The subject Alternative DNS names. Only present if 264 // [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 265 repeated string subject_alternative_dns_names = 5 266 [(google.api.field_behavior) = OUTPUT_ONLY]; 267 268 // Output only. The certificate is not valid before this time. Only present if 269 // [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 270 google.protobuf.Timestamp not_before_time = 6 271 [(google.api.field_behavior) = OUTPUT_ONLY]; 272 273 // Output only. The certificate is not valid after this time. Only present if 274 // [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 275 google.protobuf.Timestamp not_after_time = 7 276 [(google.api.field_behavior) = OUTPUT_ONLY]; 277 278 // Output only. The certificate serial number as a hex string. Only present if 279 // [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 280 string serial_number = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; 281 282 // Output only. The SHA-256 certificate fingerprint as a hex string. Only 283 // present if [parsed][google.cloud.kms.v1.Certificate.parsed] is true. 284 string sha256_fingerprint = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; 285} 286 287// An [EkmConnection][google.cloud.kms.v1.EkmConnection] represents an 288// individual EKM connection. It can be used for creating 289// [CryptoKeys][google.cloud.kms.v1.CryptoKey] and 290// [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] with a 291// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of 292// [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC], as well as 293// performing cryptographic operations using keys created within the 294// [EkmConnection][google.cloud.kms.v1.EkmConnection]. 295message EkmConnection { 296 option (google.api.resource) = { 297 type: "cloudkms.googleapis.com/EkmConnection" 298 pattern: "projects/{project}/locations/{location}/ekmConnections/{ekm_connection}" 299 }; 300 301 // A [ServiceResolver][google.cloud.kms.v1.EkmConnection.ServiceResolver] 302 // represents an EKM replica that can be reached within an 303 // [EkmConnection][google.cloud.kms.v1.EkmConnection]. 304 message ServiceResolver { 305 // Required. The resource name of the Service Directory service pointing to 306 // an EKM replica, in the format 307 // `projects/*/locations/*/namespaces/*/services/*`. 308 string service_directory_service = 1 [ 309 (google.api.field_behavior) = REQUIRED, 310 (google.api.resource_reference) = { 311 type: "servicedirectory.googleapis.com/Service" 312 } 313 ]; 314 315 // Optional. The filter applied to the endpoints of the resolved service. If 316 // no filter is specified, all endpoints will be considered. An endpoint 317 // will be chosen arbitrarily from the filtered list for each request. 318 // 319 // For endpoint filter syntax and examples, see 320 // https://cloud.google.com/service-directory/docs/reference/rpc/google.cloud.servicedirectory.v1#resolveservicerequest. 321 string endpoint_filter = 2 [(google.api.field_behavior) = OPTIONAL]; 322 323 // Required. The hostname of the EKM replica used at TLS and HTTP layers. 324 string hostname = 3 [(google.api.field_behavior) = REQUIRED]; 325 326 // Required. A list of leaf server certificates used to authenticate HTTPS 327 // connections to the EKM replica. Currently, a maximum of 10 328 // [Certificate][google.cloud.kms.v1.Certificate] is supported. 329 repeated Certificate server_certificates = 4 330 [(google.api.field_behavior) = REQUIRED]; 331 } 332 333 // [KeyManagementMode][google.cloud.kms.v1.EkmConnection.KeyManagementMode] 334 // describes who can perform control plane cryptographic operations using this 335 // [EkmConnection][google.cloud.kms.v1.EkmConnection]. 336 enum KeyManagementMode { 337 // Not specified. 338 KEY_MANAGEMENT_MODE_UNSPECIFIED = 0; 339 340 // EKM-side key management operations on 341 // [CryptoKeys][google.cloud.kms.v1.CryptoKey] created with this 342 // [EkmConnection][google.cloud.kms.v1.EkmConnection] must be initiated from 343 // the EKM directly and cannot be performed from Cloud KMS. This means that: 344 // * When creating a 345 // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] associated with 346 // this 347 // [EkmConnection][google.cloud.kms.v1.EkmConnection], the caller must 348 // supply the key path of pre-existing external key material that will be 349 // linked to the [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. 350 // * Destruction of external key material cannot be requested via the 351 // Cloud KMS API and must be performed directly in the EKM. 352 // * Automatic rotation of key material is not supported. 353 MANUAL = 1; 354 355 // All [CryptoKeys][google.cloud.kms.v1.CryptoKey] created with this 356 // [EkmConnection][google.cloud.kms.v1.EkmConnection] use EKM-side key 357 // management operations initiated from Cloud KMS. This means that: 358 // * When a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] 359 // associated with this [EkmConnection][google.cloud.kms.v1.EkmConnection] 360 // is 361 // created, the EKM automatically generates new key material and a new 362 // key path. The caller cannot supply the key path of pre-existing 363 // external key material. 364 // * Destruction of external key material associated with this 365 // [EkmConnection][google.cloud.kms.v1.EkmConnection] can be requested by 366 // calling [DestroyCryptoKeyVersion][EkmService.DestroyCryptoKeyVersion]. 367 // * Automatic rotation of key material is supported. 368 CLOUD_KMS = 2; 369 } 370 371 // Output only. The resource name for the 372 // [EkmConnection][google.cloud.kms.v1.EkmConnection] in the format 373 // `projects/*/locations/*/ekmConnections/*`. 374 string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; 375 376 // Output only. The time at which the 377 // [EkmConnection][google.cloud.kms.v1.EkmConnection] was created. 378 google.protobuf.Timestamp create_time = 2 379 [(google.api.field_behavior) = OUTPUT_ONLY]; 380 381 // A list of 382 // [ServiceResolvers][google.cloud.kms.v1.EkmConnection.ServiceResolver] where 383 // the EKM can be reached. There should be one ServiceResolver per EKM 384 // replica. Currently, only a single 385 // [ServiceResolver][google.cloud.kms.v1.EkmConnection.ServiceResolver] is 386 // supported. 387 repeated ServiceResolver service_resolvers = 3; 388 389 // Optional. Etag of the currently stored 390 // [EkmConnection][google.cloud.kms.v1.EkmConnection]. 391 string etag = 5 [(google.api.field_behavior) = OPTIONAL]; 392 393 // Optional. Describes who can perform control plane operations on the EKM. If 394 // unset, this defaults to 395 // [MANUAL][google.cloud.kms.v1.EkmConnection.KeyManagementMode.MANUAL]. 396 KeyManagementMode key_management_mode = 6 397 [(google.api.field_behavior) = OPTIONAL]; 398 399 // Optional. Identifies the EKM Crypto Space that this 400 // [EkmConnection][google.cloud.kms.v1.EkmConnection] maps to. Note: This 401 // field is required if 402 // [KeyManagementMode][google.cloud.kms.v1.EkmConnection.KeyManagementMode] is 403 // [CLOUD_KMS][google.cloud.kms.v1.EkmConnection.KeyManagementMode.CLOUD_KMS]. 404 string crypto_space_path = 7 [(google.api.field_behavior) = OPTIONAL]; 405} 406 407// An [EkmConfig][google.cloud.kms.v1.EkmConfig] is a singleton resource that 408// represents configuration parameters that apply to all 409// [CryptoKeys][google.cloud.kms.v1.CryptoKey] and 410// [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] with a 411// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] of 412// [EXTERNAL_VPC][CryptoKeyVersion.ProtectionLevel.EXTERNAL_VPC] in a given 413// project and location. 414message EkmConfig { 415 option (google.api.resource) = { 416 type: "cloudkms.googleapis.com/EkmConfig" 417 pattern: "projects/{project}/locations/{location}/ekmConfig" 418 }; 419 420 // Output only. The resource name for the 421 // [EkmConfig][google.cloud.kms.v1.EkmConfig] in the format 422 // `projects/*/locations/*/ekmConfig`. 423 string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; 424 425 // Optional. Resource name of the default 426 // [EkmConnection][google.cloud.kms.v1.EkmConnection]. Setting this field to 427 // the empty string removes the default. 428 string default_ekm_connection = 2 [ 429 (google.api.field_behavior) = OPTIONAL, 430 (google.api.resource_reference) = { 431 type: "cloudkms.googleapis.com/EkmConnection" 432 } 433 ]; 434} 435 436// Request message for 437// [EkmService.VerifyConnectivity][google.cloud.kms.v1.EkmService.VerifyConnectivity]. 438message VerifyConnectivityRequest { 439 // Required. The [name][google.cloud.kms.v1.EkmConnection.name] of the 440 // [EkmConnection][google.cloud.kms.v1.EkmConnection] to verify. 441 string name = 1 [ 442 (google.api.field_behavior) = REQUIRED, 443 (google.api.resource_reference) = { 444 type: "cloudkms.googleapis.com/EkmConnection" 445 } 446 ]; 447} 448 449// Response message for 450// [EkmService.VerifyConnectivity][google.cloud.kms.v1.EkmService.VerifyConnectivity]. 451message VerifyConnectivityResponse {} 452