This page shows how to create a key in Cloud KMS. A key can be a symmetric or asymmetric encryption key, an asymmetric signing key, or a MAC signing key.
When you create a key, you add it to a key ring in a specific Cloud KMS location. You can create a new key ring or use an existing one. In this page, you generate a new Cloud KMS or Cloud HSM key and add it to an existing key ring. To create a Cloud EKM key, see Create an external key. To import a Cloud KMS or Cloud HSM key, see Import a key.
Before you begin
Before completing the tasks on this page, you need the following:
- A Google Cloud project resource to contain your Cloud KMS resources. We recommend using a separate project for your Cloud KMS resources that does not contain any other Google Cloud resources.
- The name and location of the key ring where you want to create your key. Choose a key ring in a location that is near your other resources and that supports your chosen protection level. To view available locations and the protection levels that they support, see Cloud KMS locations. To create a key ring, see Create a key ring.
- Optional: To use the gcloud CLI, prepare your environment.
In the Google Cloud console, activate Cloud Shell.
Required roles
To get the permissions that you need to create keys, ask your administrator to grant you the following IAM roles on the project or a parent resource:
- Cloud KMS Admin (
roles/cloudkms.admin) -
To create single-tenant HSM keys:
Cloud KMS single-tenant HSM Key Creator (
roles/cloudkms.hsmSingleTenantKeyCreator)
For more information about granting roles, see Manage access to projects, folders, and organizations.
These predefined roles contain the permissions required to create keys. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to create keys:
-
cloudkms.cryptoKeys.create -
cloudkms.cryptoKeys.get -
cloudkms.cryptoKeys.list -
cloudkms.cryptoKeyVersions.create -
cloudkms.cryptoKeyVersions.get -
cloudkms.cryptoKeyVersions.list -
cloudkms.keyRings.get -
cloudkms.keyRings.list -
cloudkms.locations.get -
cloudkms.locations.list -
resourcemanager.projects.get -
To retrieve a public key:
cloudkms.cryptoKeyVersions.viewPublicKey -
To create single-tenant HSM keys:
-
cloudkms.singleTenantHsmInstances.get -
cloudkms.singleTenantHsmInstances.use
-
You might also be able to get these permissions with custom roles or other predefined roles.
Create a symmetric encryption key
Console
In the Google Cloud console, go to the Key Management page.
Click the name of the key ring for which you will create a key.
Click Create key.
For Key name, enter a name for your key.
For Protection level, select Software, HSM, or Single-tenant HSM.
If you selected Single-tenant HSM, then select the Single-tenant HSM instance where you want to create the key.
For Key material, select Generated key.
For Purpose, select Symmetric encrypt/decrypt.
Accept the default values for Rotation period and Starting on.
Click Create.
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
To create a software or Multi-tenant Cloud HSM key, use the kms keys create
command:
gcloud kms keys create KEY_NAME \
--keyring KEY_RING \
--location LOCATION \
--purpose "encryption" \
--protection-level "PROTECTION_LEVEL"
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.PROTECTION_LEVEL: the protection level to use for the key—for example,softwareorhsm. You can omit the--protection-levelflag forsoftwarekeys.
For information on all flags and possible values, run the command with the
--help flag.
--crypto-key-backend flag to the kms keys create command:
gcloud kms keys create KEY_NAME \
--keyring KEY_RING \
--location LOCATION \
--purpose "encryption" \
--protection-level "hsm-single-tenant" \
--crypto-key-backend="projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME"
Replace the following:
INSTANCE_PROJECT: the identifier of the project where your Single-tenant Cloud HSM instance exists.INSTANCE_NAME: the name of the Single-tenant Cloud HSM instance where you want to create the key. For more information about Single-tenant Cloud HSM instances, see Create and manage a Single-tenant Cloud HSM instance.
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 software or Multi-tenant Cloud HSM 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": "ENCRYPT_DECRYPT", "versionTemplate": { "protectionLevel": "PROTECTION_LEVEL", "algorithm": "ALGORITHM" }}'
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.PROTECTION_LEVEL: the protection level of the key—for example,SOFTWAREorHSM.ALGORITHM: the HMAC signing algorithm—for example,HMAC_SHA256. To see all supported HMAC algorithms, see HMAC signing algorithms.
PROTECTION_LEVEL to
HSM_SINGLE_TENANT and add the --crypto-key-backend flag to the
kms keys create command:
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": "ENCRYPT_DECRYPT", "versionTemplate": { "protectionLevel": "HSM_SINGLE_TENANT",
"algorithm": "ALGORITHM",
"crypto-key-backend": "projects/INSTANCE_PROJECT/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME" }}'
Replace the following:
INSTANCE_PROJECT: the identifier of the project where your Single-tenant Cloud HSM instance exists.INSTANCE_NAME: the name of the Single-tenant Cloud HSM instance where you want to create the key. For more information about Single-tenant Cloud HSM instances, see Create and manage a Single-tenant Cloud HSM instance.
For information on all flags and possible values, run the command with the
--help flag.
Create a symmetric encryption key with custom automatic rotation
When you create a key, you can specify its rotation period, which is the time between the automatic creation of new key versions. You can also independently specify the next rotation time, so that the next rotation happens earlier or later than one rotation period from now.
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,30dto 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-timeto 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.