// Copyright 2018 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/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 cryptographic capabilities of a
  // [CryptoKey][google.cloud.kms.v1.CryptoKey]. A given key can only be used for the operations allowed by
  // its purpose.
  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;

    // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used with
    // [AsymmetricSign][google.cloud.kms.v1.KeyManagementService.AsymmetricSign] and
    // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey].
    ASYMMETRIC_SIGN = 5;

    // [CryptoKeys][google.cloud.kms.v1.CryptoKey] with this purpose may be used with
    // [AsymmetricDecrypt][google.cloud.kms.v1.KeyManagementService.AsymmetricDecrypt] and
    // [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey].
    ASYMMETRIC_DECRYPT = 6;
  }

  // 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].
  //
  // All keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] have a
  // primary. For other keys, this field will be omitted.
  CryptoKeyVersion primary = 2;

  // The immutable purpose of this [CryptoKey][google.cloud.kms.v1.CryptoKey].
  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].
  //
  // Keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] support
  // automatic rotation. For other keys, this field must be omitted.
  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.
    //
    // Keys with [purpose][google.cloud.kms.v1.CryptoKey.purpose]
    // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT] support
    // automatic rotation. For other keys, this field must be omitted.
    google.protobuf.Duration rotation_period = 8;
  }

  // A template describing settings for new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] instances.
  // The properties of new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] instances created by either
  // [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] or
  // auto-rotation are controlled by this template.
  CryptoKeyVersionTemplate version_template = 11;

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

// A [CryptoKeyVersionTemplate][google.cloud.kms.v1.CryptoKeyVersionTemplate] specifies the properties to use when creating
// a new [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], either manually with
// [CreateCryptoKeyVersion][google.cloud.kms.v1.KeyManagementService.CreateCryptoKeyVersion] or
// automatically as a result of auto-rotation.
message CryptoKeyVersionTemplate {
  // [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] to use when creating a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] based on
  // this template. Immutable. Defaults to [SOFTWARE][google.cloud.kms.v1.ProtectionLevel.SOFTWARE].
  ProtectionLevel protection_level = 1;

  // Required. [Algorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] to use
  // when creating a [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] based on this template.
  //
  // For backwards compatibility, GOOGLE_SYMMETRIC_ENCRYPTION is implied if both
  // this field is omitted and [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose] is
  // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT].
  CryptoKeyVersion.CryptoKeyVersionAlgorithm algorithm = 3;
}

// Contains an HSM-generated attestation about a key operation.
message KeyOperationAttestation {
  // Attestion formats provided by the HSM.
  enum AttestationFormat {
    ATTESTATION_FORMAT_UNSPECIFIED = 0;

    // Cavium HSM attestation compressed with gzip. Note that this format is
    // defined by Cavium and subject to change at any time.
    CAVIUM_V1_COMPRESSED = 3;
  }

  // Output only. The format of the attestation data.
  AttestationFormat format = 4;

  // Output only. The attestation data provided by the HSM when the key
  // operation was performed.
  bytes content = 5;
}

// A [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] represents an individual cryptographic key, and the
// associated key material.
//
// An [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] version can be
// used for cryptographic operations.
//
// 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, decrypt, or sign data when an authorized user or application invokes
// Cloud KMS.
message CryptoKeyVersion {
  // The algorithm of the [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], indicating what
  // parameters must be used for each cryptographic operation.
  //
  // The
  // [GOOGLE_SYMMETRIC_ENCRYPTION][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm.GOOGLE_SYMMETRIC_ENCRYPTION]
  // algorithm is usable with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ENCRYPT_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ENCRYPT_DECRYPT].
  //
  // Algorithms beginning with "RSA_SIGN_" are usable with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ASYMMETRIC_SIGN][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN].
  //
  // The fields in the name after "RSA_SIGN_" correspond to the following
  // parameters: padding algorithm, modulus bit length, and digest algorithm.
  //
  // For PSS, the salt length used is equal to the length of digest
  // algorithm. For example,
  // [RSA_SIGN_PSS_2048_SHA256][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm.RSA_SIGN_PSS_2048_SHA256]
  // will use PSS with a salt length of 256 bits or 32 bytes.
  //
  // Algorithms beginning with "RSA_DECRYPT_" are usable with
  // [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ASYMMETRIC_DECRYPT][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_DECRYPT].
  //
  // The fields in the name after "RSA_DECRYPT_" correspond to the following
  // parameters: padding algorithm, modulus bit length, and digest algorithm.
  //
  // Algorithms beginning with "EC_SIGN_" are usable with [CryptoKey.purpose][google.cloud.kms.v1.CryptoKey.purpose]
  // [ASYMMETRIC_SIGN][google.cloud.kms.v1.CryptoKey.CryptoKeyPurpose.ASYMMETRIC_SIGN].
  //
  // The fields in the name after "EC_SIGN_" correspond to the following
  // parameters: elliptic curve, digest algorithm.
  enum CryptoKeyVersionAlgorithm {
    // Not specified.
    CRYPTO_KEY_VERSION_ALGORITHM_UNSPECIFIED = 0;

    // Creates symmetric encryption keys.
    GOOGLE_SYMMETRIC_ENCRYPTION = 1;

    // RSASSA-PSS 2048 bit key with a SHA256 digest.
    RSA_SIGN_PSS_2048_SHA256 = 2;

    // RSASSA-PSS 3072 bit key with a SHA256 digest.
    RSA_SIGN_PSS_3072_SHA256 = 3;

    // RSASSA-PSS 4096 bit key with a SHA256 digest.
    RSA_SIGN_PSS_4096_SHA256 = 4;

    // RSASSA-PKCS1-v1_5 with a 2048 bit key and a SHA256 digest.
    RSA_SIGN_PKCS1_2048_SHA256 = 5;

    // RSASSA-PKCS1-v1_5 with a 3072 bit key and a SHA256 digest.
    RSA_SIGN_PKCS1_3072_SHA256 = 6;

    // RSASSA-PKCS1-v1_5 with a 4096 bit key and a SHA256 digest.
    RSA_SIGN_PKCS1_4096_SHA256 = 7;

    // RSAES-OAEP 2048 bit key with a SHA256 digest.
    RSA_DECRYPT_OAEP_2048_SHA256 = 8;

    // RSAES-OAEP 3072 bit key with a SHA256 digest.
    RSA_DECRYPT_OAEP_3072_SHA256 = 9;

    // RSAES-OAEP 4096 bit key with a SHA256 digest.
    RSA_DECRYPT_OAEP_4096_SHA256 = 10;

    // ECDSA on the NIST P-256 curve with a SHA256 digest.
    EC_SIGN_P256_SHA256 = 12;

    // ECDSA on the NIST P-384 curve with a SHA384 digest.
    EC_SIGN_P384_SHA384 = 13;
  }

  // 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 is still being generated. It may not be used, enabled,
    // disabled, or destroyed yet. Cloud KMS will automatically mark this
    // version [ENABLED][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionState.ENABLED] as soon as the version is ready.
    PENDING_GENERATION = 5;

    // This version may be used for cryptographic operations.
    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;
  }

  // A view for [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]s. Controls the level of detail returned
  // for [CryptoKeyVersions][google.cloud.kms.v1.CryptoKeyVersion] in
  // [KeyManagementService.ListCryptoKeyVersions][google.cloud.kms.v1.KeyManagementService.ListCryptoKeyVersions] and
  // [KeyManagementService.ListCryptoKeys][google.cloud.kms.v1.KeyManagementService.ListCryptoKeys].
  enum CryptoKeyVersionView {
    // Default view for each [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Does not include
    // the [attestation][google.cloud.kms.v1.CryptoKeyVersion.attestation] field.
    CRYPTO_KEY_VERSION_VIEW_UNSPECIFIED = 0;

    // Provides all fields in each [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion], including the
    // [attestation][google.cloud.kms.v1.CryptoKeyVersion.attestation].
    FULL = 1;
  }

  // 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 [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] describing how crypto operations are
  // performed with this [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion].
  ProtectionLevel protection_level = 7;

  // Output only. The [CryptoKeyVersionAlgorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] that this
  // [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion] supports.
  CryptoKeyVersionAlgorithm algorithm = 10;

  // Output only. Statement that was generated and signed by the HSM at key
  // creation time. Use this statement to verify attributes of the key as stored
  // on the HSM, independently of Google. Only provided for key versions with
  // [protection_level][google.cloud.kms.v1.CryptoKeyVersion.protection_level] [HSM][google.cloud.kms.v1.ProtectionLevel.HSM].
  KeyOperationAttestation attestation = 8;

  // 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 was
  // generated.
  google.protobuf.Timestamp generate_time = 11;

  // 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;
}

// The public key for a given [CryptoKeyVersion][google.cloud.kms.v1.CryptoKeyVersion]. Obtained via
// [GetPublicKey][google.cloud.kms.v1.KeyManagementService.GetPublicKey].
message PublicKey {
  // The public key, encoded in PEM format. For more information, see the
  // [RFC 7468](https://tools.ietf.org/html/rfc7468) sections for
  // [General Considerations](https://tools.ietf.org/html/rfc7468#section-2) and
  // [Textual Encoding of Subject Public Key Info]
  // (https://tools.ietf.org/html/rfc7468#section-13).
  string pem = 1;

  // The [Algorithm][google.cloud.kms.v1.CryptoKeyVersion.CryptoKeyVersionAlgorithm] associated
  // with this key.
  CryptoKeyVersion.CryptoKeyVersionAlgorithm algorithm = 2;
}

// [ProtectionLevel][google.cloud.kms.v1.ProtectionLevel] specifies how cryptographic operations are performed.
enum ProtectionLevel {
  // Not specified.
  PROTECTION_LEVEL_UNSPECIFIED = 0;

  // Crypto operations are performed in software.
  SOFTWARE = 1;

  // Crypto operations are performed in a Hardware Security Module.
  HSM = 2;
}