Rotating keys

A CryptoKey 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 CryptoKey) or to manually rotate a key (Create a new CryptoKeyVersion), a user needs the IAM role roles/cloudkms.admin, roles/owner, or roles/editor.

Automatic rotation: Setting the rotation period for a CryptoKey

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

Command-line

gcloud kms keys set-rotation-schedule CRYPTOKEY_NAME \
    --location LOCATION \
    --keyring KEYRING_NAME \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time NEXT_ROTATION_TIME

Windows cmd.exe

gcloud kms keys set-rotation-schedule CRYPTOKEY_NAME ^
    --location LOCATION ^
    --keyring KEYRING_NAME ^
    --rotation-period ROTATION_PERIOD ^
    --next-rotation-time NEXT_ROTATION_TIME

Powershell

gcloud kms keys set-rotation-schedule CRYPTOKEY_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 RFC3339 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 CryptoKey with a rotation schedule

To create a new key for the KeyRing:

Command-line

gcloud kms keys create CRYPTOKEY_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 CRYPTOKEY_NAME ^
    --location LOCATION ^
    --keyring KEYRING_NAME ^
    --purpose ENCRYPTION ^
    --rotation-period ROTATION_PERIOD ^
    --next-rotation-time NEXT_ROTATION_TIME

Powershell

gcloud kms keys create CRYPTOKEY_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 CRYPTOKEY_NAME for the KeyRing KEYRING_NAME with rotation schedule defined by ROTATION_PERIOD and NEXT_ROTATION_TIME.

Manual rotation: Generating a new CryptoKeyVersion

To create a new CryptoKeyVersion and make it primary with gcloud, for the CryptoKey CRYPTOKEY_NAME for the KeyRing KEYRING_NAME, run

Command-line

gcloud kms keys versions create --location LOCATION \
    --keyring KEYRING_NAME \
    --key CRYPTOKEY_NAME --primary

Windows cmd.exe

gcloud kms keys versions create --location LOCATION ^
    --keyring KEYRING_NAME ^
    --key CRYPTOKEY_NAME --primary

Powershell

gcloud kms keys versions create --location LOCATION `
    --keyring KEYRING_NAME `
    --key CRYPTOKEY_NAME --primary

This is equivalent to you creating a new CryptoKeyVersion that is not primary, then making that version primary. That would require you knowing the version number VERSION_ID of the newly created CryptoKeyVersion. This is equivalent to the following in gcloud,

Command-line

gcloud kms keys versions create \
    --location LOCATION \
    --keyring KEYRING_NAME \
    --key CRYPTOKEY_NAME
gcloud kms keys set-primary-version CRYPTOKEY_NAME \
    --version VERSION_ID \
    --location LOCATION \
    --keyring KEYRING_NAME

Windows cmd.exe

gcloud kms keys versions create ^
    --location LOCATION ^
    --keyring KEYRING_NAME ^
    --key CRYPTOKEY_NAME
gcloud kms keys set-primary-version CRYPTOKEY_NAME ^
    --version VERSION_ID ^
    --location LOCATION ^
    --keyring KEYRING_NAME

Powershell

gcloud kms keys versions create `
    --location LOCATION `
    --keyring KEYRING_NAME `
    --key CRYPTOKEY_NAME
gcloud kms keys set-primary-version CRYPTOKEY_NAME `
    --version VERSION_ID `
    --location LOCATION `
    --keyring KEYRING_NAME

Disable automatic rotation

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

Command-line

gcloud kms keys remove-rotation-schedule CRYPTOKEY_NAME \
    --location LOCATION \
    --keyring KEYRING_NAME

Windows cmd.exe

gcloud kms keys remove-rotation-schedule CRYPTOKEY_NAME ^
    --location LOCATION ^
    --keyring KEYRING_NAME

Powershell

gcloud kms keys remove-rotation-schedule CRYPTOKEY_NAME `
    --location LOCATION `
    --keyring KEYRING_NAME

Setting an existing version as the primary CryptoKeyVersion

The gcloud command to make version 42 (which is enabled) the primary version of the CryptoKey dont-panic in KeyRing hitchhiker is

Command-line

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

Windows cmd.exe

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

Powershell

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

Note: There will be a delay of a few seconds from when you set a different version as the primary version, and the previous primary version is still used for encrypting data.