Quickstart

This quickstart shows you how to create and use encryption keys with Google Cloud Key Management Service.

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

  1. Sign in to your Google account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Platform Console, go to the Manage resources page and select or create a new project.

    Go to the Manage resources page

  3. Enable billing for your project.

    Enable billing

  4. Enable the Cloud KMS API.

    Enable the API

  5. Install and initialize the Cloud SDK.
  6. Run the following command to let the Google Cloud SDK run using your credentials:

    gcloud auth application-default login
    

KeyRings and CryptoKeys

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

Create a KeyRing named test, and a CryptoKey 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/my-project/locations/global/keyRings/test/cryptoKeys/quickstart  ENCRYPT_DECRYPT  ENABLED

Encrypt data

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

When you supply content to be encrypted as part of a JSON document in a REST request, the content must be encoded using Base64 encoding. For more information on encoding base64-encoded content, see Base64 Encoding.

Encode some text to be encrypted as Base64.

echo -n "Some text to be encrypted" | base64

You should see the base64-encoded text:

U29tZSB0ZXh0IHRvIGJlIGVuY3J5cHRlZA==

Copy the base64-encoded text for use in the next step.

Encrypt the encoded text by calling the encrypt method of your CryptoKey. Supply the base64-encoded content in the plaintext field of the JSON for your request.

curl -s -X POST "https://cloudkms.googleapis.com/v1/projects/my-project/locations/global/keyRings/test/cryptoKeys/quickstart:encrypt" \
-d "{\"plaintext\":\"U29tZSB0ZXh0IHRvIGJlIGVuY3J5cHRlZA==\"}" \
  -H "Authorization:Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type:application/json"

The encryptmethod returns a JSON document containing your encrypted content in the ciphertext field. You should see output similar to:

{
  "name": "projects/my-project/locations/global/keyRings/test/cryptoKeys/quickstart/cryptoKeyVersions/1",
  "ciphertext": "CiQALWM/r6alAxQm0VQe3..."
}

(You will have a different value for the ciphertext field.)

Copy the value for the ciphertext field for use in the next step.

Decrypt ciphertext

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

Decrypt the encrypted text by calling the decrypt method of your CryptoKey, replacing [YOUR_CIPHER_TEXT] with the encrypted content in the ciphertext field:

curl -s -X POST "https://cloudkms.googleapis.com/v1/projects/my-project/locations/global/keyRings/test/cryptoKeys/quickstart:decrypt" \
  -d "{\"ciphertext\":\"[YOUR_CIPHER_TEXT]\"}" \
  -H "Authorization:Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type:application/json"

The decrypt method returns a JSON document containing your decrypted, base64-encoded content in the plaintext field:

{
  "plaintext": "U29tZSB0ZXh0IHRvIGJlIGVuY3J5cHRlZA=="
}

Decode the base64-encoded content. For more information on decoding base64-encoded content, see Base64 Encoding.

Linux

echo "U29tZSB0ZXh0IHRvIGJlIGVuY3J5cHRlZA==" | base64 -d && echo

OS X

echo "U29tZSB0ZXh0IHRvIGJlIGVuY3J5cHRlZA==" | base64 -D && echo

You should see the base64-decoded text:

Some text to be encrypted

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

List the versions available for your CryptoKey:

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

To destroy a version, run the following command, replacing [VERSION_NUMBER] with the version number to be destroyed:

gcloud kms keys versions destroy [VERSION_NUMBER] --location global --keyring test --key quickstart

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud KMS Documentation