crypto_key_versions

Creates, updates, deletes, gets or lists a crypto_key_versions resource.

Overview

Name	crypto_key_versions
Type	Resource
Id	google.cloudkms.crypto_key_versions

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	Output only. The resource name for this CryptoKeyVersion in the format projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*.
algorithm	string	Output only. The CryptoKeyVersionAlgorithm that this CryptoKeyVersion supports.
attestation	object	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 HSM. (id: KeyOperationAttestation)
createTime	string (google-datetime)	Output only. The time at which this CryptoKeyVersion was created.
destroyEventTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material was destroyed. Only present if state is DESTROYED.
destroyTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material is scheduled for destruction. Only present if state is DESTROY_SCHEDULED.
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 stores a group of additional fields for configuring a CryptoKeyVersion that are specific to the EXTERNAL protection level and EXTERNAL_VPC protection levels. (id: ExternalProtectionLevelOptions)
generateTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material was generated.
generationFailureReason	string	Output only. The root cause of the most recent generation failure. Only present if state is GENERATION_FAILED.
importFailureReason	string	Output only. The root cause of the most recent import failure. Only present if state is IMPORT_FAILED.
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 (google-datetime)	Output only. The time at which this CryptoKeyVersion's key material was most recently imported.
protectionLevel	string	Output only. The ProtectionLevel describing how crypto operations are performed with this CryptoKeyVersion.
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.
state	string	The current state of the CryptoKeyVersion.

list

Successful response

Name	Datatype	Description
name	string	Output only. The resource name for this CryptoKeyVersion in the format projects/*/locations/*/keyRings/*/cryptoKeys/*/cryptoKeyVersions/*.
algorithm	string	Output only. The CryptoKeyVersionAlgorithm that this CryptoKeyVersion supports.
attestation	object	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 HSM. (id: KeyOperationAttestation)
createTime	string (google-datetime)	Output only. The time at which this CryptoKeyVersion was created.
destroyEventTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material was destroyed. Only present if state is DESTROYED.
destroyTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material is scheduled for destruction. Only present if state is DESTROY_SCHEDULED.
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 stores a group of additional fields for configuring a CryptoKeyVersion that are specific to the EXTERNAL protection level and EXTERNAL_VPC protection levels. (id: ExternalProtectionLevelOptions)
generateTime	string (google-datetime)	Output only. The time this CryptoKeyVersion's key material was generated.
generationFailureReason	string	Output only. The root cause of the most recent generation failure. Only present if state is GENERATION_FAILED.
importFailureReason	string	Output only. The root cause of the most recent import failure. Only present if state is IMPORT_FAILED.
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 (google-datetime)	Output only. The time at which this CryptoKeyVersion's key material was most recently imported.
protectionLevel	string	Output only. The ProtectionLevel describing how crypto operations are performed with this CryptoKeyVersion.
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.
state	string	The current state of the CryptoKeyVersion.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Returns metadata for a given CryptoKeyVersion.
list	select	projectsId, locationsId, keyRingsId, cryptoKeysId	pageSize, pageToken, view, filter, orderBy	Lists CryptoKeyVersions.
create	insert	projectsId, locationsId, keyRingsId, cryptoKeysId		Create a new CryptoKeyVersion in a CryptoKey. The server will assign the next sequential id. If unset, state will be set to ENABLED.
patch	update	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId	updateMask	Update a CryptoKeyVersion's metadata. state may be changed between ENABLED and DISABLED using this method. See DestroyCryptoKeyVersion and RestoreCryptoKeyVersion to move between other states.
destroy	delete	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Schedule a CryptoKeyVersion for destruction. Upon calling this method, CryptoKeyVersion.state will be set to DESTROY_SCHEDULED, and destroy_time will be set to the time destroy_scheduled_duration in the future. At that time, the state will automatically change to DESTROYED, and the key material will be irrevocably destroyed. Before the destroy_time is reached, RestoreCryptoKeyVersion may be called to reverse the process.
import	exec	projectsId, locationsId, keyRingsId, cryptoKeysId		Import wrapped key material into a CryptoKeyVersion. All requests must specify a CryptoKey. If a 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.
restore	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Restore a CryptoKeyVersion in the DESTROY_SCHEDULED state. Upon restoration of the CryptoKeyVersion, state will be set to DISABLED, and destroy_time will be cleared.
raw_encrypt	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Encrypts data using portable cryptographic primitives. Most users should choose Encrypt and Decrypt rather than their raw counterparts. The CryptoKey.purpose must be RAW_ENCRYPT_DECRYPT.
raw_decrypt	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Decrypts data that was originally encrypted using a raw cryptographic mechanism. The CryptoKey.purpose must be RAW_ENCRYPT_DECRYPT.
asymmetric_sign	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Signs data using a CryptoKeyVersion with CryptoKey.purpose ASYMMETRIC_SIGN, producing a signature that can be verified with the public key retrieved from GetPublicKey.
asymmetric_decrypt	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Decrypts data that was encrypted with a public key retrieved from GetPublicKey corresponding to a CryptoKeyVersion with CryptoKey.purpose ASYMMETRIC_DECRYPT.
mac_sign	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Signs data using a CryptoKeyVersion with CryptoKey.purpose MAC, producing a tag that can be verified by another source with the same key.
mac_verify	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Verifies MAC tag using a CryptoKeyVersion with CryptoKey.purpose MAC, and returns a response that indicates whether or not the verification was successful.
decapsulate	exec	projectsId, locationsId, keyRingsId, cryptoKeysId, cryptoKeyVersionsId		Decapsulates data that was encapsulated with a public key retrieved from GetPublicKey corresponding to a CryptoKeyVersion with CryptoKey.purpose KEY_ENCAPSULATION.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
cryptoKeyVersionsId	string
cryptoKeysId	string
keyRingsId	string
locationsId	string
projectsId	string
filter	string
orderBy	string
pageSize	integer (int32)
pageToken	string
updateMask	string (google-fieldmask)
view	string

SELECT examples

get

Returns metadata for a given CryptoKeyVersion.

SELECT
name,
algorithm,
attestation,
createTime,
destroyEventTime,
destroyTime,
externalDestructionFailureReason,
externalProtectionLevelOptions,
generateTime,
generationFailureReason,
importFailureReason,
importJob,
importTime,
protectionLevel,
reimportEligible,
state
FROM google.cloudkms.crypto_key_versions
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND keyRingsId = '{{ keyRingsId }}' -- required
AND cryptoKeysId = '{{ cryptoKeysId }}' -- required
AND cryptoKeyVersionsId = '{{ cryptoKeyVersionsId }}' -- required;

list

Lists CryptoKeyVersions.

SELECT
name,
algorithm,
attestation,
createTime,
destroyEventTime,
destroyTime,
externalDestructionFailureReason,
externalProtectionLevelOptions,
generateTime,
generationFailureReason,
importFailureReason,
importJob,
importTime,
protectionLevel,
reimportEligible,
state
FROM google.cloudkms.crypto_key_versions
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND keyRingsId = '{{ keyRingsId }}' -- required
AND cryptoKeysId = '{{ cryptoKeysId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND view = '{{ view }}'
AND filter = '{{ filter }}'
AND orderBy = '{{ orderBy }}';

INSERT examples

create

Create a new CryptoKeyVersion in a CryptoKey. The server will assign the next sequential id. If unset, state will be set to ENABLED.

INSERT INTO google.cloudkms.crypto_key_versions (
data__state,
data__externalProtectionLevelOptions,
projectsId,
locationsId,
keyRingsId,
cryptoKeysId
)
SELECT 
'{{ state }}',
'{{ externalProtectionLevelOptions }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ keyRingsId }}',
'{{ cryptoKeysId }}'
RETURNING
name,
algorithm,
attestation,
createTime,
destroyEventTime,
destroyTime,
externalDestructionFailureReason,
externalProtectionLevelOptions,
generateTime,
generationFailureReason,
importFailureReason,
importJob,
importTime,
protectionLevel,
reimportEligible,
state
;

Manifest

# Description fields are for documentation purposes
- name: crypto_key_versions
  props:
    - name: projectsId
      value: string
      description: Required parameter for the crypto_key_versions resource.
    - name: locationsId
      value: string
      description: Required parameter for the crypto_key_versions resource.
    - name: keyRingsId
      value: string
      description: Required parameter for the crypto_key_versions resource.
    - name: cryptoKeysId
      value: string
      description: Required parameter for the crypto_key_versions resource.
    - name: state
      value: string
      description: >
        The current state of the CryptoKeyVersion.
        
      valid_values: ['CRYPTO_KEY_VERSION_STATE_UNSPECIFIED', 'PENDING_GENERATION', 'ENABLED', 'DISABLED', 'DESTROYED', 'DESTROY_SCHEDULED', 'PENDING_IMPORT', 'IMPORT_FAILED', 'GENERATION_FAILED', 'PENDING_EXTERNAL_DESTRUCTION', 'EXTERNAL_DESTRUCTION_FAILED']
    - name: externalProtectionLevelOptions
      value: object
      description: >
        ExternalProtectionLevelOptions stores a group of additional fields for configuring a CryptoKeyVersion that are specific to the EXTERNAL protection level and EXTERNAL_VPC protection levels.
        

UPDATE examples

patch

Update a CryptoKeyVersion's metadata. state may be changed between ENABLED and DISABLED using this method. See DestroyCryptoKeyVersion and RestoreCryptoKeyVersion to move between other states.

UPDATE google.cloudkms.crypto_key_versions
SET 
data__state = '{{ state }}',
data__externalProtectionLevelOptions = '{{ externalProtectionLevelOptions }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND keyRingsId = '{{ keyRingsId }}' --required
AND cryptoKeysId = '{{ cryptoKeysId }}' --required
AND cryptoKeyVersionsId = '{{ cryptoKeyVersionsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
algorithm,
attestation,
createTime,
destroyEventTime,
destroyTime,
externalDestructionFailureReason,
externalProtectionLevelOptions,
generateTime,
generationFailureReason,
importFailureReason,
importJob,
importTime,
protectionLevel,
reimportEligible,
state;

DELETE examples

destroy

Schedule a CryptoKeyVersion for destruction. Upon calling this method, CryptoKeyVersion.state will be set to DESTROY_SCHEDULED, and destroy_time will be set to the time destroy_scheduled_duration in the future. At that time, the state will automatically change to DESTROYED, and the key material will be irrevocably destroyed. Before the destroy_time is reached, RestoreCryptoKeyVersion may be called to reverse the process.

DELETE FROM google.cloudkms.crypto_key_versions
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND keyRingsId = '{{ keyRingsId }}' --required
AND cryptoKeysId = '{{ cryptoKeysId }}' --required
AND cryptoKeyVersionsId = '{{ cryptoKeyVersionsId }}' --required;

Lifecycle Methods

import

Import wrapped key material into a CryptoKeyVersion. All requests must specify a CryptoKey. If a 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.

EXEC google.cloudkms.crypto_key_versions.import 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required 
@@json=
'{
"cryptoKeyVersion": "{{ cryptoKeyVersion }}", 
"algorithm": "{{ algorithm }}", 
"importJob": "{{ importJob }}", 
"wrappedKey": "{{ wrappedKey }}", 
"rsaAesWrappedKey": "{{ rsaAesWrappedKey }}"
}';

restore

Restore a CryptoKeyVersion in the DESTROY_SCHEDULED state. Upon restoration of the CryptoKeyVersion, state will be set to DISABLED, and destroy_time will be cleared.

EXEC google.cloudkms.crypto_key_versions.restore 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required;

raw_encrypt

Encrypts data using portable cryptographic primitives. Most users should choose Encrypt and Decrypt rather than their raw counterparts. The CryptoKey.purpose must be RAW_ENCRYPT_DECRYPT.

EXEC google.cloudkms.crypto_key_versions.raw_encrypt 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"plaintext": "{{ plaintext }}", 
"additionalAuthenticatedData": "{{ additionalAuthenticatedData }}", 
"plaintextCrc32c": "{{ plaintextCrc32c }}", 
"additionalAuthenticatedDataCrc32c": "{{ additionalAuthenticatedDataCrc32c }}", 
"initializationVector": "{{ initializationVector }}", 
"initializationVectorCrc32c": "{{ initializationVectorCrc32c }}"
}';

raw_decrypt

Decrypts data that was originally encrypted using a raw cryptographic mechanism. The CryptoKey.purpose must be RAW_ENCRYPT_DECRYPT.

EXEC google.cloudkms.crypto_key_versions.raw_decrypt 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"ciphertext": "{{ ciphertext }}", 
"additionalAuthenticatedData": "{{ additionalAuthenticatedData }}", 
"initializationVector": "{{ initializationVector }}", 
"tagLength": {{ tagLength }}, 
"ciphertextCrc32c": "{{ ciphertextCrc32c }}", 
"additionalAuthenticatedDataCrc32c": "{{ additionalAuthenticatedDataCrc32c }}", 
"initializationVectorCrc32c": "{{ initializationVectorCrc32c }}"
}';

asymmetric_sign

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

EXEC google.cloudkms.crypto_key_versions.asymmetric_sign 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"digest": "{{ digest }}", 
"digestCrc32c": "{{ digestCrc32c }}", 
"data": "{{ data }}", 
"dataCrc32c": "{{ dataCrc32c }}"
}';

asymmetric_decrypt

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

EXEC google.cloudkms.crypto_key_versions.asymmetric_decrypt 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"ciphertext": "{{ ciphertext }}", 
"ciphertextCrc32c": "{{ ciphertextCrc32c }}"
}';

mac_sign

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

EXEC google.cloudkms.crypto_key_versions.mac_sign 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"data": "{{ data }}", 
"dataCrc32c": "{{ dataCrc32c }}"
}';

mac_verify

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

EXEC google.cloudkms.crypto_key_versions.mac_verify 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"data": "{{ data }}", 
"dataCrc32c": "{{ dataCrc32c }}", 
"mac": "{{ mac }}", 
"macCrc32c": "{{ macCrc32c }}"
}';

decapsulate

Decapsulates data that was encapsulated with a public key retrieved from GetPublicKey corresponding to a CryptoKeyVersion with CryptoKey.purpose KEY_ENCAPSULATION.

EXEC google.cloudkms.crypto_key_versions.decapsulate 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@keyRingsId='{{ keyRingsId }}' --required, 
@cryptoKeysId='{{ cryptoKeysId }}' --required, 
@cryptoKeyVersionsId='{{ cryptoKeyVersionsId }}' --required 
@@json=
'{
"ciphertext": "{{ ciphertext }}", 
"ciphertextCrc32c": "{{ ciphertextCrc32c }}"
}';