Rotating keys

A key can have a rotation schedule which determines if and when it is automatically rotated.

To automatically rotate a key by setting a rotation period (Update a key) or to manually rotate a key (Create a new key version), a user needs the Cloud Identity and Access Management role roles/cloudkms.admin, roles/owner, or roles/editor.

After rotating a key, its previous key versions (which no longer are primary) are neither disabled or destroyed. This protects against data loss. For example, if you rotate a key, data that was encrypted with a previous key version is not automatically decrypted and re-encrypted with the new primary key version. To re-encrypt data in this circumstance, you need to decrypt and re-encrypt with the new key version. As another example, an application may need need to be upgraded to use a different key version. When no data is protected by an old key version, you can schedule it for destruction.

Note: Rotating a key sets a new key version as the primary key version. There will be a delay of on average 40 minutes, and up to 3 hours, from when you set a different version as the primary version, and the previous primary version is still used for encrypting data. For more information, see Cloud Key Management Service resource consistency.

Automatic rotation: Setting the rotation period for a key

To enable automation rotation of a key, set the rotation schedule with the following gcloud command-line tool syntax:

Command-line

gcloud kms keys update key-name \
  --location location \
  --keyring keyring-name \
  --rotation-period rotation-period \
  --next-rotation-time next-rotation-time

Windows cmd.exe

gcloud kms keys update key ^
  --location location ^
  --keyring keyring-name ^
  --rotation-period rotation-period ^
  --next-rotation-time next-rotation-time

PowerShell

gcloud kms keys update key-name `
  --location location `
  --keyring keyring-name `
  --rotation-period rotation-period `
  --next-rotation-time next-rotation-time

Rotation schedule syntax

The format for the rotation schedule depends on the client library that is used. For the gcloud tool, the next rotation time must be in ISO or RFC 3339 format, and the rotation period must be in the form integerunit, where units can be one of seconds (s), minutes (m), hours (h) or days (d). For example, a valid rotation schedule for use with the gcloud tool could be:

--rotation-period=30d
--next-rotation-time=2016-10-12T12:34:56.1234Z

Create a key with a rotation schedule

To create a new key for the key ring:

Command-line

gcloud kms keys create key-name \
  --location location \
  --keyring keyring-name \
  --purpose ENCRYPTION \
  --rotation-period rotation-period \
  --next-rotation-time next-rotation-time

Windows cmd.exe

gcloud kms keys create key-name ^
  --location location ^
  --keyring keyring-name ^
  --purpose ENCRYPTION ^
  --rotation-period rotation-period ^
  --next-rotation-time next-rotation-time

PowerShell

gcloud kms keys create key-name `
  --location location `
  --keyring keyring-name `
  --purpose ENCRYPTION `
  --rotation-period rotation-period `
  --next-rotation-time next-rotation-time

Where the command uses the following parameters: a new key key-name for the key ring keyring-name with rotation schedule defined by rotation-period and next rotation time next-rotation-time.

Manual rotation: Generating a new key version

To create a new key version and make it primary with the gcloud tool, for the key key-name for the key ring keyring-name, run:

Command-line

gcloud kms keys versions create \
  --location location \
  --keyring keyring-name \
  --key key-name \
  --primary

Windows cmd.exe

gcloud kms keys versions create --location location ^
  --keyring keyring-name ^
  --key key-name ^
  --primary

PowerShell

gcloud kms keys versions create --location location `
  --keyring keyring-name `
  --key key-name --primary

This is equivalent to you creating a new key version that is not primary, then making that version primary. That would require you to know the version number key-version of the newly created key version. This is equivalent to the following gcloud tool commands:

Command-line

gcloud kms keys versions create \
  --location location \
  --keyring keyring-name \
  --key key-name

gcloud kms keys update key-name \
  --primary-version key-version \
  --location location \
  --keyring keyring-name

Windows cmd.exe

gcloud kms keys versions create ^
  --location location ^
  --keyring keyring-name ^
  --key key-name

gcloud kms keys update key-name ^
  --primary-version key-version ^
  --location location ^
  --keyring keyring-name

PowerShell

gcloud kms keys versions create `
  --location location `
  --keyring keyring-name `
  --key key-name

gcloud kms keys update key-name `
  --primary-version key-version `
  --location location `
  --keyring keyring-name

Disable automatic rotation

To disable an automatic rotation, clear the rotation schedule of the key:

Command-line

gcloud kms keys update key-name \
  --remove-rotation-schedule \
  --location location \
  --keyring keyring-name

Windows cmd.exe

gcloud kms keys update key-name ^
  --remove-rotation-schedule ^
  --location location ^
  --keyring keyring-name

PowerShell

gcloud kms keys update key-name `
  --remove-rotation-schedule `
  --location location `
  --keyring keyring-name

Setting an existing version as the primary key version

To make an enabled version the primary version for a key:

Command-line

gcloud kms keys update key-name \
  --primary-version key-version \
  --location location \
  --keyring keyring-name

Windows cmd.exe

gcloud kms keys update key-name ^
  --primary-version key-version ^
  --location location ^
  --keyring keyring-name

PowerShell

gcloud kms keys update key-name `
  --set-=primary-version key-version `
  --location location `
  --keyring keyring-name

Note: There will be a delay of on average 40 minutes, and up to 3 hours, from when you set a different version as the primary version, and the previous primary version is still used for encrypting data. For more information, see Cloud KMS resource consistency.