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, and remain available for decrypting data.

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 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_NAME ^
  --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 INTEGER[UNIT], 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.

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 knowing the version number VERSION_ID 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 VERSION_ID \
  --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 VERSION_ID ^
  --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 VERSION_ID `
  --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 version 42 (which is enabled) the primary version of the key dont-panic in key ring hitchhiker:

Command-line

gcloud kms keys update dont-panic \
  --primary-version 42 \
  --location global \
  --keyring hitchhiker

Windows cmd.exe

gcloud kms keys update dont-panic ^
  --primary-version 42 ^
  --location global ^
  --keyring hitchhiker

PowerShell

gcloud kms keys update dont-panic `
  --set-=primary-version 42 `
  --location global `
  --keyring hitchhiker

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 KMS resource consistency.