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 IAM 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 Cloud KMS 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 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 command-line 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 command 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 gcloud, 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 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 Cloud KMS resource consistency.