This page shows how to automatically or manually rotate a key. For more information about key rotation in general, see Key rotation.
Required roles
To get the permissions that you need to rotate keys, ask your administrator to grant you the following IAM roles on your key:
-
Cloud KMS Admin (
roles/cloudkms.admin
) -
Re-encrypt data:
Cloud KMS CryptoKey Encrypter/Decrypter (
roles/cloudkms.cryptoKeyEncrypterDecrypter
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to rotate keys. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to rotate keys:
-
Change primary key version:
cloudkms.cryptoKeys.update
-
Change or disable auto-rotate:
cloudkms.cryptoKeys.update
-
Create new key version:
cloudkms.cryptoKeyVersions.create
-
Disable old key versions:
cloudkms.cryptoKeyVersions.update
-
Re-encrypt data:
-
cloudkms.cryptoKeyVersions.useToDecrypt
-
cloudkms.cryptoKeyVersions.useToEncrypt
-
You might also be able to get these permissions with custom roles or other predefined roles.
A single user with a custom role containing all of these permissions can rotate keys and re-encrypt data on their own. Users in the Cloud KMS Admin role and Cloud KMS CryptoKey Encrypter/Decrypter role can work together to rotate keys and re-encrypt data. Follow the principle of least privilege when assigning roles. For more details, see Permissions and roles.
When you rotate a key, data that was encrypted with previous key versions isn't automatically re-encrypted. To learn more, see decrypt and re-encrypt. Rotating a key does not automatically disable or destroy any existing key versions. Destroying key versions that are no longer needed helps to reduce costs.
Configure automatic rotation
To configure automatic rotation when creating a new key:
Console
When you use the Google Cloud console to create a key, Cloud KMS sets the rotation period and next rotation time automatically. You can choose to use the default values or specify different values.
To specify a different rotation period and starting time, when you're creating your key, but before you click the Create button:
For Key rotation period, select an option.
For Starting on, select the date when you want the first automatic rotation to happen. You can leave Starting on at its default value to start the first automatic rotation one key rotation period from when you create the key.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys create KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --purpose "encryption" \ --rotation-period ROTATION_PERIOD \ --next-rotation-time NEXT_ROTATION_TIME
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.ROTATION_PERIOD
: the interval to rotate the key—for example,30d
to rotate the key every 30 days. The rotation period must be at least 1 day and at most 100 years. For more information, see CryptoKey.rotationPeriod.NEXT_ROTATION_TIME
: the timestamp at which to complete the first rotation—for example,2023-01-01T01:02:03
. You can omit--next-rotation-time
to schedule the first rotation for one rotation period from when you run the command. For more information, seeCryptoKey.nextRotationTime
.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To create a key, use the
CryptoKey.create
method:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys?crypto_key_id=KEY_NAME" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"purpose": "PURPOSE", "rotationPeriod": "ROTATION_PERIOD", "nextRotationTime": "NEXT_ROTATION_TIME"}'
Replace the following:
PURPOSE
: the purpose of the key.ROTATION_PERIOD
: the interval to rotate the key—for example,30d
to rotate the key every 30 days. The rotation period must be at least 1 day and at most 100 years. For more information, see CryptoKey.rotationPeriod.NEXT_ROTATION_TIME
: the timestamp at which to complete the first rotation—for example,2023-01-01T01:02:03
. For more information, seeCryptoKey.nextRotationTime
.
To configure automatic rotation on an existing key:
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key for which you want to add a rotation schedule.
Click the key you want to add a rotation schedule to.
In the header, click Edit Rotation Period.
In the prompt, choose new values for the Rotation period and Starting on fields.
In the prompt, click Save.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys update KEY_NAME \ --location LOCATION \ --keyring KEY_RING \ --rotation-period ROTATION_PERIOD \ --next-rotation-time NEXT_ROTATION_TIME
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.ROTATION_PERIOD
: the interval to rotate the key—for example,30d
to rotate the key every 30 days. The rotation period must be at least 1 day and at most 100 years. For more information, see CryptoKey.rotationPeriod.NEXT_ROTATION_TIME
: the timestamp at which to complete the next rotation—for example,2023-01-01T01:02:03
. You can omit--next-rotation-time
to schedule the next rotation for one rotation period from when you run the command. For more information, seeCryptoKey.nextRotationTime
.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To update a key, use the
CryptoKey.patch
method:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?updateMask=rotationPeriod,nextRotationTime" \ --request "PATCH" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"rotationPeriod": "ROTATION_PERIOD", "nextRotationTime": "NEXT_ROTATION_TIME"}'
Replace the following:
ROTATION_PERIOD
: the interval to rotate the key—for example,30d
to rotate the key every 30 days. The rotation period must be at least 1 day and at most 100 years. For more information, see CryptoKey.rotationPeriod.NEXT_ROTATION_TIME
: the timestamp at which to complete the next rotation—for example,2023-01-01T01:02:03
. For more information, seeCryptoKey.nextRotationTime
.
Manually rotate a key
First, create a new key version:
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key for which you will create a new key version.
Click the key for which you will create a new key version.
In the header, click Rotate.
In the prompt, click Rotate to confirm.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
Key versions are numbered sequentially.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To manually rotate a key, first create a new key version by calling the CryptoKeyVersions.create method.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions" \ --request "POST" \ --header "authorization: Bearer TOKEN"
This command creates a new key version, but doesn't set it as the primary version.
To set your new key version as primary, see Setting an existing version as the primary key version.
If necessary, re-encrypt data that was encrypted using the previous key version.
Set an existing version as the primary key version
To set different key version as the primary version for a key, update the key with the new primary version information. A key version must be enabled before you can configure it as the primary version.
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key whose primary version you want to update.
Click the key whose primary version you want to update.
On the row corresponding to the key version you want to make primary, click View More
.Click Make primary version in menu.
In the confirmation prompt, click Make primary.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys update KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --primary-version KEY_VERSION
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.- KEY_VERSION: the version number of the new primary key version.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Change the primary key version by calling the CryptoKey.updatePrimaryVersion method.
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME:updatePrimaryVersion" \ --request "POST" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"cryptoKeyVersionId": "KEY_VERSION"}'
Replace the following:
PROJECT_ID
: the ID of the project that contains the key ring.LOCATION
: the Cloud KMS location of the key ring.KEY_RING
: the name of the key ring that contains the key.KEY_NAME
: the name of the key.- KEY_VERSION: the version number of the new primary key version.
When you change the primary key version, the change typically becomes consistent within 1 minute. However, this change can take up to 3 hours to propagate in exceptional cases. During this time, the prior primary version might be used to encrypt data. For more information, see Cloud KMS resource consistency.
Disable automatic rotation
To disable automatic rotation on a key, clear the rotation schedule of the key:
Console
Go to the Key Management page in the Google Cloud console.
Click the name of the key ring that contains the key for which you want to remove the rotation schedule.
Click the key you want to remove the rotation schedule from.
In the header, click Edit Rotation Period.
In the prompt, click the Rotation period field and select Never (manual rotation).
In the prompt, click Save.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms keys update KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --remove-rotation-schedule
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
To update a key, use the
CryptoKey.patch
method:
curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME?updateMask=rotationPeriod,nextRotationTime" \ --request "PATCH" \ --header "authorization: Bearer TOKEN" \ --header "content-type: application/json" \ --data '{"rotationPeriod": null, "nextRotationTime": null}'
For additional details about rotationPeriod
and nextRotationTime
, see
keyRings.cryptoKeys
.
Rotate an external key
Rotate a coordinated external key
You can configure automatic rotation for symmetric coordinated external keys. You can also manually create a new key version for symmetric or asymmetric coordinated external keys.
Rotating or creating a new key version causes all newly created data protected with that key to be encrypted with the new key version. Data protected with a previous key version isn't re-encrypted. As a result, your external key manager must continue to make the key material of the previous key version available to be used.
To create a new key version for a coordinated external key, complete the following steps:
Console
In the Google Cloud console, go to the Key Management page.
Select the key ring, and then select the key.
Click Create version. A message indicates that your new key version will be generated in both Cloud KMS and your EKM. If you see a Key path or Key URI field, the selected key isn't a coordinated external key.
To confirm that you want to create a new key version, click Create version.
The new key version appears in Pending generation state. For symmetric keys, manually created key versions aren't automatically set as the primary key version. You can set your new key version as primary.
gcloud CLI
To create a new symmetric key version and set it as the primary key version,
use the kms keys versions create
command with the --primary
flag:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --primary
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
To create a new asymmetric key version or to create a new symmetric key
version that isn't the primary key version, use the kms keys versions
create
command:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.
Rotate a manually managed Cloud EKM via VPC key
First, rotate the external key material on your external key manager. If that results in a new key path, you need to rotate or create a new Cloud EKM key version with the new key path. For symmetric encryption keys, rotate the Cloud EKM key and specify the new key path from your external key manager. For asymmetric keys, create a new key version and specify the new key path.
Rotating or creating a new key version causes all newly created data protected with that key to be encrypted with the new key version. Data protected with a previous key version isn't re-encrypted. As a result, your external key manager must continue to make the key material of the previous key version available to be used.
If the key material in the external key management partner system doesn't change, but the key path changes, you can update the key's external path without rotating the key.
Console
In the Google Cloud console, go to the Key Management page.
Select the key ring, and then select the key.
Click Rotate key.
For Key path, enter the key path for the new version.
Click Rotate Key to confirm.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
To create a new symmetric key version and set it as the primary key version,
use the kms keys versions create
command with the --primary
flag:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --ekm-connection-key-path EXTERNAL_KEY_PATH \ --primary
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.EXTERNAL_KEY_PATH
: the path to the new external key version.
To create a new asymmetric key version or to create a new symmetric key
version that isn't the primary key version, use the kms keys versions
create
command:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --ekm-connection-key-path EXTERNAL_KEY_PATH
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.EXTERNAL_KEY_PATH
: the path to the new external key version.
For information on all flags and possible values, run the command with the
--help
flag.
After the key version is successfully created, you can use it just as you would use any other Cloud KMS key version.
Rotate a manually managed Cloud EKM via internet key
First, rotate the external key material on your external key manager. If that results in a new URI, you need to rotate or create a new Cloud EKM key version with the new URI. For symmetric encryption keys, rotate the Cloud EKM key and specify the new key URI from your external key manager. For asymmetric keys, create a new key version and specify the new key URI.
Rotating or creating a new key version causes all newly created data protected with that key to be encrypted with the new key version. Data protected with a previous key version isn't re-encrypted. As a result, your external key manager must continue to make the key material of the previous key version available to be used.
If the key material in the external key management partner system doesn't change, but the URI changes, you can update the key's external URI without rotating the key.
Console
In the Google Cloud console, go to the Key Management page.
Select the key ring, and then select the key.
Select Rotate key for symmetric keys or Create version for asymmetric keys.
Enter the new key URI, then select Rotate Key for symmetric keys or Create version for asymmetric keys.
The new key version becomes the primary version.
gcloud CLI
To create a new symmetric key version and set it as the primary key version,
use the kms keys versions create
command with the --primary
flag:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --external-key-uri EXTERNAL_KEY_URI \ --primary
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.EXTERNAL_KEY_URI
: the key URI of the new external key version.
To create a new asymmetric key version or to create a new symmetric key
version that isn't the primary key version, use the kms keys versions
create
command:
gcloud kms keys versions create \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --external-key-uri EXTERNAL_KEY_URI
Replace the following:
KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.EXTERNAL_KEY_URI
: the key URI of the new external key version.
What's next
- After rotating a key, you can re-encrypt data that was encrypted with that key.
- After you re-encrypt your data, you can check whether the key version is in use.
- After you have confirmed that a key version is no longer in use, you can destroy a key version.