Create encryption keys with Cloud KMS

This quickstart shows you how to create and use encryption keys with Cloud Key Management Service in a project you own. These instructions use the Google Cloud console to create key rings, keys, and key versions in Cloud KMS. For instructions that use other methods, see Autokey overview , Create a key ring , and Create a key .

This quickstart uses the command line to send requests to the Cloud KMS API. For programming examples that use the client libraries to send requests to the Cloud KMS API, see Encrypting and Decrypting .

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project : To create a project, you need the Project Creator ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Enable the Cloud KMS API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role ( roles/serviceusage.serviceUsageAdmin ), which contains the serviceusage.services.enable permission. Learn how to grant roles .

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

To initialize the gcloud CLI, run the following command:

gcloud  
init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project : To create a project, you need the Project Creator ( roles/resourcemanager.projectCreator ), which contains the resourcemanager.projects.create permission. Learn how to grant roles .

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Enable the Cloud KMS API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role ( roles/serviceusage.serviceUsageAdmin ), which contains the serviceusage.services.enable permission. Learn how to grant roles .

Enable the API

Install the Google Cloud CLI.

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

To initialize the gcloud CLI, run the following command:

gcloud  
init

Key rings and keys

To encrypt and decrypt content you will need a Cloud KMS key, which is part of a key ring.

Create a key ring named test , and a key named quickstart . Refer to the object hierarchy overview for more information about these objects and how they are related.

 gcloud  
kms  
keyrings  
create  
 "test" 
  
 \ 
  
--location  
 "global"

 gcloud  
kms  
keys  
create  
 "quickstart" 
  
 \ 
  
--location  
 "global" 
  
 \ 
  
--keyring  
 "test" 
  
 \ 
  
--purpose  
 "encryption"

You can use the list option to view the name and metadata for the key that you just created.

 gcloud  
kms  
keys  
list  
 \ 
  
--location  
 "global" 
  
 \ 
  
--keyring  
 "test"

You should see:

NAME                                                                      PURPOSE          PRIMARY_STATE
projects/ PROJECT_ID 
/locations/global/keyRings/test/cryptoKeys/quickstart  ENCRYPT_DECRYPT  ENABLED

Encrypt data

Now that you have a key, you can use that key to encrypt text or binary content.

Store some text to be encrypted in a file called "mysecret.txt".

  echo 
  
-n  
 "Some text to be encrypted" 
 > 
mysecret.txt

To encrypt the data with gcloud kms encrypt , provide your key information, specify the name of the plaintext file to encrypt, and specify the name of the file that will contain the encrypted content:

 gcloud  
kms  
encrypt  
 \ 
  
--location  
 "global" 
  
 \ 
  
--keyring  
 "test" 
  
 \ 
  
--key  
 "quickstart" 
  
 \ 
  
--plaintext-file  
./mysecret.txt  
 \ 
  
--ciphertext-file  
./mysecret.txt.encrypted

The encrypt method saves your encrypted content in the file specified by the --ciphertext-file flag.

Decrypt ciphertext

To decrypt the data with gcloud kms decrypt , provide your key information, specify the name of the encrypted file (ciphertext file) to decrypt, and specify the name of the file that will contain the decrypted content:

 gcloud  
kms  
decrypt  
 \ 
  
--location  
 "global" 
  
 \ 
  
--keyring  
 "test" 
  
 \ 
  
--key  
 "quickstart" 
  
 \ 
  
--ciphertext-file  
./mysecret.txt.encrypted  
 \ 
  
--plaintext-file  
./mysecret.txt.decrypted

The decrypt method saves your decrypted content in the file specified by the --plaintext-file flag.

To decrypt encrypted content, you must use the same key that was used to encrypt the content.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

List the versions available for your key:

 gcloud  
kms  
keys  
versions  
list  
 \ 
  
--location  
 "global" 
  
 \ 
  
--keyring  
 "test" 
  
 \ 
  
--key  
 "quickstart"

To destroy a version, run the following command, where 1 is the number of the key version that you want to destroy:

gcloud kms keys versions destroy 1 \
    --location "global" \
    --keyring "test" \
    --key "quickstart"

What's next

Start using the API .
Take a look at the API Reference .
Learn more about how to encrypt data at rest .