REST Resource: projects.locations.keyRings.cryptoKeys.cryptoKeyVersions

Resource: CryptoKeyVersion

A CryptoKeyVersion represents an individual cryptographic key, and the associated key material.

An ENABLED version can be used for cryptographic operations.

For security reasons, the raw cryptographic key material represented by a 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.

JSON representation 
{
  "name": string,
  "state": enum (CryptoKeyVersionState),
  "protectionLevel": enum (ProtectionLevel),
  "algorithm": enum (CryptoKeyVersionAlgorithm),
  "attestation": {
    object (KeyOperationAttestation)
  },
  "createTime": string,
  "generateTime": string,
  "destroyTime": string,
  "destroyEventTime": string,
  "importJob": string,
  "importTime": string,
  "importFailureReason": string,
  "generationFailureReason": string,
  "externalDestructionFailureReason": string,
  "externalProtectionLevelOptions": {
    object (ExternalProtectionLevelOptions)
  },
  "reimportEligible": boolean
}
Fields
name

string

Output only. The resource name for this CryptoKeyVersion in the format projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*.
state

enum (CryptoKeyVersionState)

The current state of the CryptoKeyVersion.
protectionLevel

enum (ProtectionLevel)

Output only. The ProtectionLevel describing how crypto operations are performed with this CryptoKeyVersion.
algorithm

enum (CryptoKeyVersionAlgorithm)

Output only. The CryptoKeyVersionAlgorithm that this CryptoKeyVersion supports.
attestation

object (KeyOperationAttestation)

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 protectionLevel HSM.
createTime

string (Timestamp format)

Output only. The time at which this CryptoKeyVersion was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
generateTime

string (Timestamp format)

Output only. The time this CryptoKeyVersion's key material was generated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
destroyTime

string (Timestamp format)

Output only. The time this CryptoKeyVersion's key material is scheduled for destruction. Only present if state is DESTROY_SCHEDULED.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
destroyEventTime

string (Timestamp format)

Output only. The time this CryptoKeyVersion's key material was destroyed. Only present if state is DESTROYED.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
importJob

string

Output only. The name of the ImportJob used in the most recent import of this CryptoKeyVersion. Only present if the underlying key material was imported.
importTime

string (Timestamp format)

Output only. The time at which this CryptoKeyVersion's key material was most recently imported.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
importFailureReason

string

Output only. The root cause of the most recent import failure. Only present if state is IMPORT_FAILED.
generationFailureReason

string

Output only. The root cause of the most recent generation failure. Only present if state is GENERATION_FAILED.
externalDestructionFailureReason

string

Output only. The root cause of the most recent external destruction failure. Only present if state is EXTERNAL_DESTRUCTION_FAILED.
externalProtectionLevelOptions

object (ExternalProtectionLevelOptions)

ExternalProtectionLevelOptions stores a group of additional fields for configuring a CryptoKeyVersion that are specific to the EXTERNAL protection level and EXTERNAL_VPC protection levels.
reimportEligible

boolean

Output only. Whether or not this key version is eligible for reimport, by being specified as a target in ImportCryptoKeyVersionRequest.crypto_key_version.

CryptoKeyVersionState

The state of a CryptoKeyVersion, indicating if it can be used.

Enums
CRYPTO_KEY_VERSION_STATE_UNSPECIFIED Not specified.
PENDING_GENERATION This version is still being generated. It may not be used, enabled, disabled, or destroyed yet. Cloud KMS will automatically mark this version ENABLED as soon as the version is ready.
ENABLED This version may be used for cryptographic operations.
DISABLED This version may not be used, but the key material is still available, and the version can be placed back into the ENABLED state.
DESTROYED This version is destroyed, and the key material is no longer stored. This version may only become ENABLED again if this version is reimportEligible and the original key material is reimported with a call to KeyManagementService.ImportCryptoKeyVersion.
DESTROY_SCHEDULED This version is scheduled for destruction, and will be destroyed soon. Call cryptoKeyVersions.restore to put it back into the DISABLED state.
PENDING_IMPORT This version is still being imported. It may not be used, enabled, disabled, or destroyed yet. Cloud KMS will automatically mark this version ENABLED as soon as the version is ready.
IMPORT_FAILED This version was not imported successfully. It may not be used, enabled, disabled, or destroyed. The submitted key material has been discarded. Additional details can be found in CryptoKeyVersion.import_failure_reason.
GENERATION_FAILED This version was not generated successfully. It may not be used, enabled, disabled, or destroyed. Additional details can be found in CryptoKeyVersion.generation_failure_reason.
PENDING_EXTERNAL_DESTRUCTION This version was destroyed, and it may not be used or enabled again. Cloud KMS is waiting for the corresponding key material residing in an external key manager to be destroyed.
EXTERNAL_DESTRUCTION_FAILED This version was destroyed, and it may not be used or enabled again. However, Cloud KMS could not confirm that the corresponding key material residing in an external key manager was destroyed. Additional details can be found in CryptoKeyVersion.external_destruction_failure_reason.

ExternalProtectionLevelOptions

ExternalProtectionLevelOptions stores a group of additional fields for configuring a CryptoKeyVersion that are specific to the EXTERNAL protection level and EXTERNAL_VPC protection levels.

JSON representation 
{
  "externalKeyUri": string,
  "ekmConnectionKeyPath": string
}
Fields
externalKeyUri

string

The URI for an external resource that this CryptoKeyVersion represents.
ekmConnectionKeyPath

string

The path to the external key material on the EKM when using EkmConnection e.g., "v0/my/key". Set this field instead of externalKeyUri when using an EkmConnection.

Methods

asymmetricDecrypt

 Decrypts data that was encrypted with a public key retrieved from GetPublicKey corresponding to a CryptoKeyVersion with CryptoKey.purpose ASYMMETRIC_DECRYPT.

asymmetricSign

 Signs data using a CryptoKeyVersion with CryptoKey.purpose ASYMMETRIC_SIGN, producing a signature that can be verified with the public key retrieved from GetPublicKey.

create

 Create a new CryptoKeyVersion in a CryptoKey.

destroy

 Schedule a CryptoKeyVersion for destruction.

get

 Returns metadata for a given CryptoKeyVersion.

getPublicKey

 Returns the public key for the given CryptoKeyVersion.

import

 Import wrapped key material into a CryptoKeyVersion.

list

 Lists CryptoKeyVersions.

macSign

 Signs data using a CryptoKeyVersion with CryptoKey.purpose MAC, producing a tag that can be verified by another source with the same key.

macVerify

 Verifies MAC tag using a CryptoKeyVersion with CryptoKey.purpose MAC, and returns a response that indicates whether or not the verification was successful.

patch

 Update a CryptoKeyVersion's metadata.

rawDecrypt

 Decrypts data that was originally encrypted using a raw cryptographic mechanism.

rawEncrypt

 Encrypts data using portable cryptographic primitives.

restore

 Restore a CryptoKeyVersion in the DESTROY_SCHEDULED state.