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 desired
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.
Required roles
To get the permissions that you need to create keys,
ask your administrator to grant you the
Cloud KMS Admin
(
roles/cloudkms.admin
) IAM role on the project or a parent resource.
For more information about granting roles, see
Manage access
.
This predefined role contains
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
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.
Go to Key Management
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
or
HSM
.
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
.
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,
software
or
hsm
. You can omit the
--protection-level
flag for
software
keys.
For information on all flags and possible values, run the command with the
--help
flag.
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": "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,
SOFTWARE
or
HSM
.
ALGORITHM
: the HMAC signing algorithm—for example,
HMAC_SHA256
. To see all supported HMAC algorithms, see
HMAC signing
algorithms
.
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,
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 7 days from when you run the
command. For more information, see
CryptoKey.nextRotationTime
.
For information on all flags and possible values, run the command with the
--help
flag.
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"
. You can omit
--next-rotation-time
to schedule the first rotation for 7 days from when you run the
command. For more information, see
CryptoKey.nextRotationTime
.
Set the duration of the 'scheduled for destruction' state
By default, key versions in Cloud KMS spend 24 hours in the
scheduled for destruction (
DESTROY_SCHEDULED
) state before they are
destroyed. The scheduled for destruction state is sometimes called the
soft deleted state
. The duration for which key versions remain in this state
is configurable, with the following constraints:
- You can only set the duration during key creation.
- After the duration for the key has been specified, it can't be changed.
- The duration applies to all versions of the key created in the future.
- The minimum duration is 24 hours for all keys, except for import-only keys
which have a minimum duration of 0.
- The maximum duration is 120 days.
- The default duration is 24 hours.
Your organization might have a minimum scheduled for destruction duration
value defined by organization policies. For more information, see
Control
key destruction
.
To create a key which uses a custom duration for the
Scheduled for destruction
state, use the following steps:
Console
In the Google Cloud console, go to the
Key Management
page.
Go to Key Management
Click the name of the key ring for which you will create a key.
Click
Create key
.
Configure the settings of the key for your application.
Click
Additional settings
.
In
Duration of 'scheduled for destruction' state
, choose the number of
days the key will remain
scheduled for destruction
before being
permanently destroyed.
Click
Create 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
PURPOSE
\
--destroy-scheduled-duration
DURATION
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.
PURPOSE
: the purpose of the key—for example,
encryption
.
DURATION
: the amount of time for the key to remain in the
scheduled for destruction
state before being permanently destroyed.
For information on all flags and possible values, run the command with the
--help
flag.
We recommend using the default duration of 24 hours for all keys unless
you have specific application or regulatory requirements that require a
different value.
Create an asymmetric key
Create an asymmetric decryption key
Follow these steps to create an asymmetric decryption key on the specified key
ring and location. These examples can be adapted to specify a different
protection level or algorithm. For more information and alternative values, see
Algorithms
and
Protection levels
.
When you first create the key, the initial key version has a state of
Pending generation
. When the state changes to
Enabled
, you can use
the key. To learn more about key version states, see
Key version
states
.
Console
In the Google Cloud console, go to the
Key Management
page.
Go to Key Management
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
or
HSM
.
For
Key material
, select
Generated key
.
For
Purpose
, select
Asymmetric decrypt
.
For
Algorithm
, select
3072 bit RSA - OAEP Padding - SHA256 Digest
.
You can change this value on future key versions.
Click
Create
.
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 "asymmetric-encryption" \
--default-algorithm "
ALGORITHM
"
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.
ALGORITHM
: the algorithm to use for the key—for
example,
rsa-decrypt-oaep-3072-sha256
. For a list of supported asymmetric
encryption algorithms, see
Asymmetric encryption
algorithms
.
For information on all flags and possible values, run the command with the
--help
flag.
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
.
Create an asymmetric decryption key by calling
CryptoKey.create
.
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": "ASYMMETRIC_DECRYPT", "versionTemplate": {"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.
ALGORITHM
: the algorithm to use for
the key—for example,
RSA_DECRYPT_OAEP_3072_SHA256
. For a list of
supported asymmetric encryption algorithms, see
Asymmetric encryption
algorithms
.
Create an asymmetric signing key
Follow these steps to create an asymmetric signing key on the specified key ring
and location. These examples can be adapted to specify a different
protection level or algorithm. For more information and alternative values, see
Algorithms
and
Protection levels
.
When you first create the key, the initial key version has a state of
Pending generation
. When the state changes to
Enabled
, you can use
the key. To learn more about key version states, see
Key version
states
.
Console
In the Google Cloud console, go to the
Key Management
page.
Go to Key Management
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
or
HSM
.
For
Key material
, select
Generated key
.
For
Purpose
, select
Asymmetric sign
.
For
Algorithm
, select
Elliptic Curve P-256 - SHA256 Digest
. You can
change this value on future key versions.
Click
Create
.
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 "asymmetric-signing" \
--default-algorithm "
ALGORITHM
"
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.
ALGORITHM
: the algorithm to use for the key—for example,
ec-sign-p256-sha256
. For a list of supported algorithms, see
Asymmetric
signing algorithms
.
For information on all flags and possible values, run the command with the
--help
flag.
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
.
Create an asymmetric signing key by calling
CryptoKey.create
.
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": "ASYMMETRIC_SIGN", "versionTemplate": {"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.
ALGORITHM
: the algorithm to use for
the key—for example,
EC_SIGN_P256_SHA256
. For a list of supported
algorithms, see
Asymmetric signing
algorithms
.
Retrieve the public key
When you create an asymmetric key, Cloud KMS creates a public/private
key pair. You can retrieve the public key of an enabled asymmetric key at any
time after the key is generated.
The public key is in the Privacy-enhanced Electronic Mail (PEM) format. For more
information, see the
RFC 7468
sections
General
Considerations
and
Textual Encoding of Subject Public
Key Info
.
To download the public key for an existing asymmetric key version, follow these
steps:
Console
In the Google Cloud console, go to the
Key Management
page.
Go to Key Management
Click the name of the key ring that contains the asymmetric key for which
you want to retrieve the public key.
Click the name of the key for which you want to retrieve the public key.
On the row corresponding to the key version for which you want to retrieve
the public key, click
View More
more_vert
.
Click
Get public key
.
The public key is displayed in the prompt. You can copy the public key to
your clipboard. To download the public key, click
Download
.
If you do not see the
Get public key
option, verify the following:
- The key is an asymmetric key.
- The key version is enabled.
- You have the
cloudkms.cryptoKeyVersions.viewPublicKey
permission.
The filename of a public key downloaded from the Google Cloud console is of
the form:
KEY_RING
-
KEY_NAME
-
KEY_VERSION
.pub
Each portion of the filename is separated by a hyphen, for example
ringname-keyname-version.pub
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 get-public-key
KEY_VERSION
\
--key
KEY_NAME
\
--keyring
KEY_RING
\
--location
LOCATION
\
--output-file
OUTPUT_FILE_PATH
Replace the following:
KEY_VERSION
: the key version number.
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.
OUTPUT_FILE_PATH
: the path where you want to save the
public key file—for example,
public-key.pub
.
For information on all flags and possible values, run the command with the
--help
flag.
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
.
Retrieve the public key by calling the
CryptoKeyVersions.getPublicKey
method.
curl "https://cloudkms.googleapis.com/v1/projects/
PROJECT_ID
/locations/
LOCATION
/keyRings/
KEY_RING
/cryptoKeys/
KEY_NAME
/cryptoKeyVersions/
KEY_VERSION
/publicKey" \
--request "GET" \
--header "authorization: Bearer
TOKEN
"
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 key version number.
The output should look similar to the following:
{
"pem": "-----BEGIN PUBLIC KEY-----\nQ29uZ3JhdHVsYXRpb25zLCB5b3UndmUgZGlzY292ZX
JlZCB0aGF0IHRoaXMgaXNuJ3QgYWN0dWFsbHkgYSBwdWJsaWMga2V5ISBIYXZlIGEgbmlj
ZSBkYXkgOik=\n-----END PUBLIC KEY-----\n",
"algorithm": "
ALGORITHM
",
"pemCrc32c": "2561089887",
"name": "projects/
PROJECT_ID
/locations/
LOCATION
/keyRings/
KEY_RING
/cryptoKeys/
KEY_NAME
/cryptoKeyVersions/
KEY_VERSION
",
"protectionLevel": "SOFTWARE"
}
Convert a public key to JWK format
Cloud KMS lets you retrieve a public key in PEM format.
Some applications may require other key formats such as JSON Web Key (JWK).
For more information about the JWK format, see
RFC 7517
.
To convert a public key to JWK format, follow these steps:
Control access to asymmetric keys
A signer or validator requires the appropriate permission or role on the
asymmetric key.
For a user or service that will perform signing, grant the
cloudkms.cryptoKeyVersions.useToSign
permission on the asymmetric key.
For a user or service that will retrieve the public key, grant the
cloudkms.cryptoKeyVersions.viewPublicKey
on the asymmetric key. The public key
is required for signature validation.
Learn about permissions and roles in Cloud KMS release at
Permissions and roles
.
Create a MAC signing key
Console
In the Google Cloud console, go to the
Key Management
page.
Go to Key Management
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 either
Software
or
HSM
.
For
Key material
, select
Generated key
.
For
Purpose
, select
MAC signing/verification
.
Optional: for
Algorithm
, select an
HMAC signing
algorithm
.
Click
Create
.
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 "mac" \
--default-algorithm "
ALGORITHM
" \
--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.
ALGORITHM
: the HMAC signing algorithm—for example,
hmac-sha256
. To see all supported HMAC algorithms, see
HMAC signing
algorithms
.
PROTECTION_LEVEL
: the protection level of the key—for
example,
hsm
. You can omit the
--protection-level
flag for
software
keys.
For information on all flags and possible values, run the command with the
--help
flag.
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": "MAC", "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
SOFTWARE
or
HSM
.
ALGORITHM
: the HMAC signing algorithm, for example
HMAC_SHA256
.
To see all supported HMAC algorithms, see
HMAC signing
algorithms
.
What's next