feat: add support for Key Reimport

Google APIs · copybara-github · commit e3d9b11abaec · 2021-08-30T05:27:26.000-07:00
PiperOrigin-RevId: 393749648
diff --git a/google/cloud/kms/v1/resources.proto b/google/cloud/kms/v1/resources.proto
@@ -335,6 +335,10 @@ message CryptoKeyVersion {
     DISABLED = 2;
 
     // This version is destroyed, and the key material is no longer stored.
+    // This version may only become [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] again if this version is
+    // [reimport_eligible][google.cloud.kms.v1.CryptoKeyVersion.reimport_eligible] and the original
+    // key material is reimported with a call to
+    // [KeyManagementService.ImportCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.ImportCryptoKeyVersion].
     DESTROYED = 3;
 
     // This version is scheduled for destruction, and will be destroyed soon.
@@ -407,16 +411,16 @@ message CryptoKeyVersion {
   // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED].
   google.protobuf.Timestamp destroy_event_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The name of the [ImportJob][google.cloud.kms.v1.ImportJob] used to import this
+  // Output only. The name of the [ImportJob][google.cloud.kms.v1.ImportJob] used in the most recent import of this
   // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Only present if the underlying key material was
   // imported.
   string import_job = 14 [(google.api.field_behavior) = OUTPUT_ONLY];
 
   // Output only. The time at which this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s key material
-  // was imported.
+  // was most recently imported.
   google.protobuf.Timestamp import_time = 15 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Output only. The root cause of an import failure. Only present if
+  // Output only. The root cause of the most recent import failure. Only present if
   // [state][google.cloud.kms.v1.CryptoKeyVersion.state] is
   // [IMPORT_FAILED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.IMPORT_FAILED].
   string import_failure_reason = 16 [(google.api.field_behavior) = OUTPUT_ONLY];
@@ -425,6 +429,11 @@ message CryptoKeyVersion {
   // configuring a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] that are specific to the
   // [EXTERNAL][google.cloud.kms.v1.ProtectionLevel.EXTERNAL] protection level.
   ExternalProtectionLevelOptions external_protection_level_options = 17;
+
+  // Output only. Whether or not this key version is eligible for reimport, by being
+  // specified as a target in
+  // [ImportCryptoKeyVersionRequest.crypto_key_version][google.cloud.kms.v1.ImportCryptoKeyVersionRequest.crypto_key_version].
+  bool reimport_eligible = 18 [(google.api.field_behavior) = OUTPUT_ONLY];
 }
 
 // The public key for a given [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Obtained via
diff --git a/google/cloud/kms/v1/service.proto b/google/cloud/kms/v1/service.proto
@@ -161,11 +161,12 @@ service KeyManagementService {
     option (google.api.method_signature) = "parent,crypto_key_version";
   }
 
-  // Imports a new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] into an existing [CryptoKey][google.cloud.kms.v1.CryptoKey] using the
-  // wrapped key material provided in the request.
+  // Import wrapped key material into a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion].
   //
-  // The version ID will be assigned the next sequential id within the
-  // [CryptoKey][google.cloud.kms.v1.CryptoKey].
+  // All requests must specify a [CryptoKey][google.cloud.kms.v1.CryptoKey]. If a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] is
+  // additionally specified in the request, key material will be reimported into
+  // that version. Otherwise, a new version will be created, and will be
+  // assigned the next sequential id within the [CryptoKey][google.cloud.kms.v1.CryptoKey].
   rpc ImportCryptoKeyVersion(ImportCryptoKeyVersionRequest) returns (CryptoKeyVersion) {
     option (google.api.http) = {
       post: "/v1/{parent=projects/*/locations/*/keyRings/*/cryptoKeys/*}/cryptoKeyVersions:import"
@@ -223,10 +224,11 @@ service KeyManagementService {
   // Schedule a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] for destruction.
   //
   // Upon calling this method, [CryptoKeyVersion.state][google.cloud.kms.v1.CryptoKeyVersion.state] will be set to
-  // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED]
-  // and [destroy_time][google.cloud.kms.v1.CryptoKeyVersion.destroy_time] will be set to a time 24
-  // hours in the future, at which point the [state][google.cloud.kms.v1.CryptoKeyVersion.state]
-  // will be changed to
+  // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED],
+  // and [destroy_time][google.cloud.kms.v1.CryptoKeyVersion.destroy_time] will be set to the time
+  // [destroy_scheduled_duration][google.cloud.kms.v1.CryptoKey.destroy_scheduled_duration] in the
+  // future. At that time, the [state][google.cloud.kms.v1.CryptoKeyVersion.state] will
+  // automatically change to
   // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED], and the key
   // material will be irrevocably destroyed.
   //
@@ -646,15 +648,39 @@ message CreateCryptoKeyVersionRequest {
 
 // Request message for [KeyManagementService.ImportCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.ImportCryptoKeyVersion].
 message ImportCryptoKeyVersionRequest {
-  // Required. The [name][google.cloud.kms.v1.CryptoKey.name] of the [CryptoKey][google.cloud.kms.v1.CryptoKey] to
-  // be imported into.
+  // Required. The [name][google.cloud.kms.v1.CryptoKey.name] of the [CryptoKey][google.cloud.kms.v1.CryptoKey] to be imported into.
+  //
+  // The create permission is only required on this key when creating a new
+  // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion].
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
       type: "cloudkms.googleapis.com/CryptoKey"
     }
   ];
 
+  // Optional. The optional [name][google.cloud.kms.v1.CryptoKeyVersion.name] of an existing
+  // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] to target for an import operation.
+  // If this field is not present, a new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] containing the
+  // supplied key material is created.
+  //
+  // If this field is present, the supplied key material is imported into
+  // the existing [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. To import into an existing
+  // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], the [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] must be a child of
+  // [ImportCryptoKeyVersionRequest.parent][google.cloud.kms.v1.ImportCryptoKeyVersionRequest.parent], have been previously created via
+  // [ImportCryptoKeyVersion][], and be in
+  // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED] or
+  // [IMPORT_FAILED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.IMPORT_FAILED]
+  // state. The key material and algorithm must match the previous
+  // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] exactly if the [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] has ever contained
+  // key material.
+  string crypto_key_version = 6 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = {
+      type: "cloudkms.googleapis.com/CryptoKeyVersion"
+    }
+  ];
+
   // Required. The [algorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] of
   // the key being imported. This does not need to match the
   // [version_template][google.cloud.kms.v1.CryptoKey.version_template] of the [CryptoKey][google.cloud.kms.v1.CryptoKey] this
