// Copyright 2017 Google Inc.
//
// 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/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Kms.V1";
option go_package = "google.golang.org/genproto/googleapis/cloud/kms/v1;kms";
option java_multiple_files = true;
option java_outer_classname = "KmsResourcesProto";
option java_package = "com.google.cloud.kms.v1";
option php_namespace = "Google\\Cloud\\Kms\\V1";


// A [KeyRing][google.cloud.kms.v1.KeyRing] is a toplevel logical grouping of [CryptoKeys][google.cloud.kms.v1.CryptoKey].
message KeyRing {
  // Output only. The resource name for the [KeyRing][google.cloud.kms.v1.KeyRing] in the format
  // `projects/*/locations/*/keyRings/*`.
  string name = 1;

  // Output only. The time at which this [KeyRing][google.cloud.kms.v1.KeyRing] was created.
  google.protobuf.Timestamp create_time = 2;
}

// A [CryptoKey][google.cloud.kms.v1.CryptoKey] represents a logical key that can be used for cryptographic
// operations.
//
// A [CryptoKey][google.cloud.kms.v1.CryptoKey] is made up of one or more [versions][google.cloud.kms.v1.CryptoKeyVersion], which
// represent the actual key material used in cryptographic operations.
message CryptoKey {
  // [CryptoKeyPurpose][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose] describes the capabilities of a [CryptoKey][google.cloud.kms.v1.CryptoKey]. Two
  // keys with the same purpose may use different underlying algorithms, but
  // must support the same set of operations.
  enum CryptoKeyPurpose {
    // Not specified.
    CRYPTO_KEY_PURPOSE_UNSPECIFIED = 0;

    // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used with
    // [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt] and
    // [Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt].
    ENCRYPT_DECRYPT = 1;
  }

  // Output only. The resource name for this [CryptoKey][google.cloud.kms.v1.CryptoKey] in the format
  // `projects/*/locations/*/keyRings/*/cryptoKeys/*`.
  string name = 1;

  // Output only. A copy of the "primary" [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] that will be used
  // by [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt] when this [CryptoKey][google.cloud.kms.v1.CryptoKey] is given
  // in [EncryptRequest.name][google.cloud.kms.v1.EncryptRequest.name].
  //
  // The [CryptoKey][google.cloud.kms.v1.CryptoKey]'s primary version can be updated via
  // [UpdateCryptoKeyPrimaryVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyPrimaryVersion].
  CryptoKeyVersion primary = 2;

  // The immutable purpose of this [CryptoKey][google.cloud.kms.v1.CryptoKey]. Currently, the only acceptable
  // purpose is [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT].
  CryptoKeyPurpose purpose = 3;

  // Output only. The time at which this [CryptoKey][google.cloud.kms.v1.CryptoKey] was created.
  google.protobuf.Timestamp create_time = 5;

  // At [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time], the Key Management Service will automatically:
  //
  // 1. Create a new version of this [CryptoKey][google.cloud.kms.v1.CryptoKey].
  // 2. Mark the new version as primary.
  //
  // Key rotations performed manually via
  // [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] and
  // [UpdateCryptoKeyPrimaryVersion][google.cloud.kms.v1.KeyManagementService.UpdateCryptoKeyPrimaryVersion]
  // do not affect [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time].
  google.protobuf.Timestamp next_rotation_time = 7;

  // Controls the rate of automatic rotation.
  oneof rotation_schedule {
    // [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time] will be advanced by this period when the service
    // automatically rotates a key. Must be at least one day.
    //
    // If [rotation_period][google.cloud.kms.v1.CryptoKey.rotation_period] is set, [next_rotation_time][google.cloud.kms.v1.CryptoKey.next_rotation_time] must also be set.
    google.protobuf.Duration rotation_period = 8;
  }

  // Labels with user-defined metadata. For more information, see
  // [Labeling Keys](/kms/docs/labeling-keys).
  map<string, string> labels = 10;
}

// A [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] represents an individual cryptographic key, and the
// associated key material.
//
// It can be used for cryptographic operations either directly, or via its
// parent [CryptoKey][google.cloud.kms.v1.CryptoKey], in which case the server will choose the appropriate
// version for the operation.
//
// For security reasons, the raw cryptographic key material represented by a
// [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] can never be viewed or exported. It can only be used to
// encrypt or decrypt data when an authorized user or application invokes Cloud
// KMS.
message CryptoKeyVersion {
  // The state of a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], indicating if it can be used.
  enum CryptoKeyVersionState {
    // Not specified.
    CRYPTO_KEY_VERSION_STATE_UNSPECIFIED = 0;

    // This version may be used in [Encrypt][google.cloud.kms.v1.KeyManagementService.Encrypt] and
    // [Decrypt][google.cloud.kms.v1.KeyManagementService.Decrypt] requests.
    ENABLED = 1;

    // This version may not be used, but the key material is still available,
    // and the version can be placed back into the [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] state.
    DISABLED = 2;

    // This version is destroyed, and the key material is no longer stored.
    // A version may not leave this state once entered.
    DESTROYED = 3;

    // This version is scheduled for destruction, and will be destroyed soon.
    // Call
    // [RestoreCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.RestoreCryptoKeyVersion]
    // to put it back into the [DISABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DISABLED] state.
    DESTROY_SCHEDULED = 4;
  }

  // Output only. The resource name for this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] in the format
  // `projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*`.
  string name = 1;

  // The current state of the [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion].
  CryptoKeyVersionState state = 3;

  // Output only. The time at which this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] was created.
  google.protobuf.Timestamp create_time = 4;

  // Output only. The time this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]'s key material is scheduled
  // for destruction. Only present if [state][google.cloud.kms.v1.CryptoKeyVersion.state] is
  // [DESTROY_SCHEDULED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROY_SCHEDULED].
  google.protobuf.Timestamp destroy_time = 5;

  // Output only. The time this CryptoKeyVersion's key material was
  // destroyed. Only present if [state][google.cloud.kms.v1.CryptoKeyVersion.state] is
  // [DESTROYED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.DESTROYED].
  google.protobuf.Timestamp destroy_event_time = 6;
}
