Key version state
A key version has a state:
Pending generation (
PENDING_GENERATION): (Applies to asymmetric keys only.) This key version is still being generated. It may not be used, enabled, disabled, or destroyed yet. Cloud Key Management Service will automatically change the state to enabled as soon as the version is ready.
Pending import (
PENDING_IMPORT): (Applies to imported keys only.) This key version is still being imported. It may not be used, enabled, disabled, or destroyed yet. Cloud Key Management Service will automatically change the state to enabled as soon as the version is ready.
ENABLED): The key version is ready for use.
DISABLED): This key version may not be used, but the key material is still available, and the version can be placed back into the enabled state.
Scheduled for destruction (
DESTROY_SCHEDULED): This key version is scheduled for destruction, and will be destroyed soon. It can be placed back into the disabled state. This state corresponds with Stage 2 - Soft Deletion in the data deletion pipeline.
DESTROYED): This key version is destroyed, and the key material is no longer stored in Cloud KMS. If the key version was used for asymmetric or symmetric encryption, any ciphertext encrypted with this version is not recoverable. If the key version was used for digital signing, new signatures cannot be created. Additionally, for all asymmetric key versions, the public key is no longer available for download. A key version may not leave the destroyed state once entered. This state corresponds with Stage 3 - Logical Deletion from Active Systems in the data deletion pipeline.
Import failed (
IMPORT_FAILED): This key version could not be imported. See Troubleshooting failed imports for additional information about the conditions that cause import failures.
Changing states of a key version
The following describes how a key version can change states:
When a key version for an asymmetric key is created, it starts with a state of pending generation. When Cloud KMS finishes generating the key version, its state automatically changes to enabled.
When a key version for a symmetric key is created, it starts with a state of enabled.
The following diagram shows the allowable states for a key version.
Note that only key versions for asymmetric keys start in the pending generation state. Key versions for symmetric keys start in the enabled state.
Impact of key version state on cryptographic operations
The impact of key version state on cryptographic operations depends on whether the key is used for:
- Symmetric encryption
- Asymmetric encryption or digital signing
Each symmetric encryption key has a designated primary version which is used at that point in time to encrypt data. In order for a key to be available for use to encrypt data, it needs to have a primary key version which is enabled.
When a key is used to encrypt plaintext, its primary key version is used to encrypt that data. The information as to which version was used to encrypt data is stored in the ciphertext of the data. Only one version of a key can be primary at any given point in time.
If the primary key version is disabled, that key version cannot be used to encrypt data. Note that an enabled primary key version can be disabled, scheduled for destruction or destroyed, and a version which is not enabled can be made the primary version.
Which key version is primary does not impact the ability to decrypt data. A key version can be used to decrypt data as long as it is enabled.
Asymmetric encryption or digital signing
Each time an asymmetric key is used for encryption or digital signing, a key version must be specified. In order for the key version to be available for asymmetric encryption or digital signing, the key version must be enabled. You can retrieve a key version's public key only if the key version is enabled.
Variable soft deletion
- A duration may only be configured when a CryptoKey is newly created.
- Once specified, the duration cannot be changed.
- The duration will apply to all versions of the CryptoKey created in the future.
- The minimum duration is 24 hours, unless the CryptoKey is import-only, in which case the minimum duration is 0.
- The maximum duration is 120 days.
The value is configured using the
destroy_scheduled_duration field of the
We recommend that you use the default duration of 24 hours for all keys unless you have specific application or regulatory requirements that insist on a different value.