Create a key (original) (raw)

Skip to main content

Create a key

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 specificCloud 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:

  1. 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.
  2. 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, seeCloud KMS locations. To create a key ring, see Create a key ring.
  3. Optional: To use the gcloud CLI, prepare your environment.
    In the Google Cloud console, activate Cloud Shell.
    Activate Cloud Shell

Required roles

To get the permissions that you need to create keys, ask your administrator to grant you theCloud KMS Admin (roles/cloudkms.admin) IAM role on the project or a parent resource. For more information about granting roles, see Manage access to projects, folders, and organizations.

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:

You might also be able to get these permissions with custom roles or other predefined roles.

Create a symmetric encryption key

Console

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring for which you will create a key.
  3. Click Create key.
  4. For Key name, enter a name for your key.
  5. For Protection level, select Software or HSM.
  6. For Key material, select Generated key.
  7. For Purpose, select Symmetric encrypt/decrypt.
  8. Accept the default values for Rotation period and Starting on.
  9. Click Create.

gcloud

To use Cloud KMS on the command line, firstInstall 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:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

To create a key, use theCryptoKey.createmethod:

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:

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:

  1. For Key rotation period, select an option.
  2. 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, firstInstall 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:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

To create a key, use theCryptoKey.createmethod:

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:

Set the duration of the 'scheduled for destruction' state

By default, key versions in Cloud KMS spend 30 days 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:

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

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring for which you will create a key.
  3. Click Create key.
  4. Configure the settings of the key for your application.
  5. Click Additional settings.
  6. In Duration of 'scheduled for destruction' state, choose the number of days the key will remain scheduled for destruction before being permanently destroyed.
  7. Click Create key.

gcloud

To use Cloud KMS on the command line, firstInstall 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:

For information on all flags and possible values, run the command with the--help flag.

We recommend using the default duration of 30 days for all keys unless you have specific application or regulatory requirements that require a different value.

Create an asymmetric key

The following sections show you how to create asymmetric keys.

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, seeAlgorithms and Protection levels.

When you first create the key, the initial key version has a state ofPending generation. When the state changes to Enabled, you can use the key. To learn more about key version states, see Key version states.

Console

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring for which you will create a key.
  3. Click Create key.
  4. For Key name, enter a name for your key.
  5. For Protection level, select Software or HSM.
  6. For Key material, select Generated key.
  7. For Purpose, select Asymmetric decrypt.
  8. For Algorithm, select 3072 bit RSA - OAEP Padding - SHA256 Digest. You can change this value on future key versions.
  9. Click Create.

gcloud

To use Cloud KMS on the command line, firstInstall 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:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

Create an asymmetric decryption key by callingCryptoKey.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:

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, seeAlgorithms and Protection levels.

When you first create the key, the initial key version has a state ofPending generation. When the state changes to Enabled, you can use the key. To learn more about key version states, see Key version states.

Console

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring for which you will create a key.
  3. Click Create key.
  4. For Key name, enter a name for your key.
  5. For Protection level, select Software or HSM.
  6. For Key material, select Generated key.
  7. For Purpose, select Asymmetric sign.
  8. For Algorithm, select Elliptic Curve P-256 - SHA256 Digest. You can change this value on future key versions.
  9. Click Create.

gcloud

To use Cloud KMS on the command line, firstInstall 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:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

Create an asymmetric signing key by callingCryptoKey.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:

Create a KEM key

Follow these steps to create a key for use in a key encapsulation mechanism (KEM) for 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, seeAlgorithms and Protection levels.

When you first create the key, the initial key version has a state ofPending generation. When the state changes to Enabled, you can use the key. To learn more about key version states, see Key version states.

gcloud

To use Cloud KMS on the command line, firstInstall or upgrade to the latest version of Google Cloud CLI.

gcloud kms keys create KEY_NAME
--keyring KEY_RING
--location LOCATION
--purpose "key-encapsulation"
--default-algorithm "ALGORITHM"

Replace the following:

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, seeAccessing the Cloud KMS API.

Create a key with purpose KEY_ENCAPSULATION by callingCryptoKey.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": "KEY_ENCAPSULATION", "versionTemplate": {"algorithm": "ALGORITHM"}}'

Replace the following:

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

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring that contains the asymmetric key for which you want to retrieve the public key.
  3. Click the name of the key for which you want to retrieve the public key.
  4. On the row corresponding to the key version for which you want to retrieve the public key, click View More .
  5. Click Get public key.
  6. 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 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 exampleringname-keyname-version.pub.

gcloud

To use Cloud KMS on the command line, firstInstall 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
--public-key-format PUBLIC_KEY_FORMAT
--output-file OUTPUT_FILE_PATH

Replace the following:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

Retrieve the public key by calling theCryptoKeyVersions.getPublicKeymethod.

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/KEY_VERSION/publicKey?public_key_format=PUBLIC_KEY_FORMAT"
--request "GET"
--header "authorization: Bearer TOKEN"

Replace the following:

If the public key format is omitted for a non-PQC key, the output is 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": "PROTECTION_LEVEL" }

For a PQC algorithm with public key format NIST_PQC, the output is similar to the following:

{ "publicKeyFormat": "NIST_PQC", "publicKey": { "crc32cChecksum": "1985843562", "data": "kdcOIrFCC5kN8S4i0+R+AoSc9gYIJ9jEQ6zG235ZmCQ=" } "algorithm": "ALGORITHM", "name": "projects/PROJECT_ID/locations/LOCATION/keyRings/ KEY_RING/cryptoKeys/KEY_NAME/cryptoKeyVersions/ KEY_VERSION", "protectionLevel": "PROTECTION_LEVEL" }

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.

Learn about permissions and roles in Cloud KMS release atPermissions and roles.

Create a MAC signing key

Console

  1. In the Google Cloud console, go to the Key Management page.
    Go to Key Management
  2. Click the name of the key ring for which you will create a key.
  3. Click Create key.
  4. For Key name, enter a name for your key.
  5. For Protection level, select either Software orHSM.
  6. For Key material, select Generated key.
  7. For Purpose, select MAC signing/verification.
  8. Optional: for Algorithm, select an HMAC signing algorithm.
  9. Click Create.

gcloud

To use Cloud KMS on the command line, firstInstall 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:

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 andinstall the Cloud KMS C# SDK.

Go

To run this code, first set up a Go development environment andinstall the Cloud KMS Go SDK.

Java

To run this code, first set up a Java development environment andinstall the Cloud KMS Java SDK.

Node.js

To run this code, first set up a Node.js development environment andinstall the Cloud KMS Node.js SDK.

PHP

To run this code, first learn about using PHP on Google Cloud andinstall the Cloud KMS PHP SDK.

Python

To run this code, first set up a Python development environment andinstall the Cloud KMS Python SDK.

Ruby

To run this code, first set up a Ruby development environment andinstall 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, seeAccessing the Cloud KMS API.

To create a key, use theCryptoKey.createmethod:

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:

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-05 UTC.