Cloud KMS is a cloud-hosted key management service that lets you manage cryptographic keys for your cloud services the same way you do on-premises. It includes support for encryption, decryption, signing, and verification using a variety of key types and sources including Cloud HSM for hardware-backed keys. This tutorial teaches you how to encrypt and decrypt data using asymmetric Cloud KMS keys.

You will learn

Self-paced environment setup

If you don't already have a Google Account (Gmail or Google Apps), you must create one. Sign-in to Google Cloud Platform console ( and create a new project:

Screenshot from 2016-02-10 12:45:26.png

Remember the project ID, a unique name across all Google Cloud projects (the name above has already been taken and will not work for you, sorry!). It will be referred to later in this codelab as PROJECT_ID.

Next, you'll need to enable billing in the Cloud Console in order to use Google Cloud resources.

Running through this codelab shouldn't cost you more than a few dollars, but it could be more if you decide to use more resources or if you leave them running (see "cleanup" section at the end of this document).

New users of Google Cloud Platform are eligible for a $300 free trial.

Start Cloud Shell

In this codelab you will use Cloud Shell, a free virtualized environment running on Google Cloud. From the GCP Console click the Cloud Shell icon on the top right toolbar:

It should only take a few moments to provision and connect to the environment. When it is finished, you should see something like this:

This virtual machine is loaded with all the development tools you'll need. It offers a persistent 5GB home directory, and runs on the Google Cloud, greatly enhancing network performance and authentication. Unless otherwise instructed, run all commands from this shell.

Before you can use Cloud KMS, you must first enable the service in your project. This only needs to be done once per project. To enable the Cloud KMS service, run the following command:

$ gcloud services enable \
    --project "${GOOGLE_CLOUD_PROJECT}"

It can take up to a minute to enable. The command will report success when it finishes.

Create a Cloud KMS Key Ring. In Cloud KMS, a Key Ring is a logical collection of cryptographic keys. The Key Ring contains metadata about the keys such as their location. Create a Key Ring named my-keyring in the global region:

$ gcloud kms keyrings create "my-keyring" \
    --location "global"

Now create a Crypto Key named my-asymmetric-encryption-key with the purpose asymmetric-encryption inside the Key Ring you just created.

$ gcloud kms keys create "my-asymmetric-encryption-key" \
    --location "global" \
    --keyring "my-keyring" \
    --purpose "asymmetric-encryption" \
    --default-algorithm "rsa-decrypt-oaep-4096-sha512"

With asymmetric keys, Cloud KMS does not perform the encryption. Instead, it provides access to a public key and you encrypt data using that public key via public key cryptography. With asymmetric keys, encryption can be done completely offline and does not require access to Cloud KMS or any other Google Cloud APIs. Encryption is performed using a cryptographic tool like openssl or with a programming language or library that supports public key cryptography.

Download the public key from Cloud KMS:

$ gcloud kms keys versions get-public-key "1" \
    --location "global" \
    --keyring "my-keyring" \
    --key "my-asymmetric-encryption-key" \
    --output-file ./

Create a file with data to encrypt and use the openssl command line tool to encrypt the data in the file:

$ echo "my-contents" > ./data.txt
$ openssl pkeyutl -encrypt -pubin \
    -in ./data.txt \
    -inkey ./ \
    -pkeyopt "rsa_padding_mode:oaep" \
    -pkeyopt "rsa_oaep_md:sha512" \
    -pkeyopt "rsa_mgf1_md:sha512" > ./data.txt.enc

The encrypted data (also known as "ciphertext") will be saved in data.txt.enc on disk. If you open the data.txt.enc file, you will notice that it has strange, unprintable characters. That is because the resulting data is in binary format.

When storing the ciphertext in a database or transmitting it as part of an HTTP request, you may need to encode the data. The most common encoding mechanism for ciphertext is base64.

Cloud KMS does not store any of the plaintext you provide. You need to save this ciphertext in a secure location as it will be required to retrieve the plaintext value.

Unlike encryption, decrypting data that was encrypted using an asymmetric Cloud KMS key does require online access to the Cloud KMS service. Decrypt the ciphertext from the file using the gcloud command line tool:

$ gcloud kms asymmetric-decrypt \

    --location "global" \
    --keyring "my-keyring" \
    --key "my-asymmetric-encryption-key" \
    --version "1" \
    --plaintext-file - \
    --ciphertext-file ./data.txt.enc

The gcloud command line tool reads the ciphertext from the file and decrypts it using Cloud KMS. Notice this example specifies the --plaintext-file argument as -. This instructs gcloud to print the result to the terminal.

The console will print my-contents, which is the same plaintext value from the file above.

You enabled the Cloud KMS API, created an asymmetric encryption key, and encrypted and decrypted data! Cloud KMS is a powerful product and encryption/decryption just scratches the surface of its capabilities.

Clean up

If you are done exploring, please consider deleting your project.

Learn More


This work is licensed under a Creative Commons Attribution 2.0 Generic License.