Encrypting application data

This page shows one way to use Cloud Key Management Service to directly encrypt application data on a client, before transmitting it across a network.

In this example, the encrypted data is transmitted to Google Cloud and is stored in a Cloud Storage bucket. Cloud Storage also supports automatic server-side encryption using customer-managed encryption keys, which automates this entire process. To protect application data before transmitting it to Google Cloud, we recommend that you use the Tink library.

The Tink library is a multi-language, cross-platform library that provides APIs for common cryptographic tasks. This can be used to encrypt data before it enters Google Cloud data stores, and supports Java, Python, C++, Go, Objective-C, and other languages, and both object storage and relational database services.

In this walkthrough, you encrypt a file using Cloud KMS before you upload it to a bucket. Next, you download and decrypt the same data so that you can read it on the client.

When you follow these instructions, your keys and all cryptographic operations remain in Google Cloud and you need to use Cloud KMS for decryption. Raw symmetric encryption lets you encrypt or decrypt data locally on-premises or move encrypted data between different libraries and service providers without having to decrypt it first.

Before you begin

Within your Google Cloud organization, you need permission to create new projects, and to enable billing, create users, and manage permissions within these projects. The roles/resourcemanager.organizationAdmin role grants this permission.

Setup

We recommend using two projects and two users to ensure separation of duties. If you follow the steps in this guide, users and services that manage encryption keys are distinct from users and services that use them. One project contains and manages the keys, and the other project stores the encrypted data in a Cloud Storage bucket, and decrypts it as needed.

Create projects

You create projects in the Google Cloud console. For step-by-step instructions, see the Identity and Access Management quickstart.

Create the following projects within your organization:

Create a Google Cloud project to contain the Cloud Storage bucket used to store the secrets. The secrets will be stored as objects in the bucket. This project is called STORAGE_PROJECT_ID.
Create a second Google Cloud project to manage the Cloud KMS keys used to encrypt and decrypt the secret. This project is called KEY_PROJECT_ID.
For each project, enable the Cloud KMS API and enable billing, by following the steps in the Before you begin section of the Cloud KMS Quickstart.

Create users

You create users and grant them roles in the Google Cloud console. For step-by-step instructions, see the Identity and Access Management quickstart.

This procedure creates two users. The key administrator manages the encryption keys, and the key user can encrypt and decrypt data using the keys.

Perform this procedure in the KEY_PROJECT_ID project.

Create the key administrator account.
Grant the roles/cloudkms.admin Identity and Access Management role to the key administrator. This role lets the key administrator create and manage keys.
Create the key user account.
Grant the roles/cloudkms.cryptoKeyEncrypterDecrypter IAM role to the key user. This role lets the key user encrypt and decrypt data.

Note: If a user or application only needs encryption permissions or only needs decryption permissions, you can use the roles/cloudkms.cryptoKeyEncrypter and roles/cloudkms.cryptoKeyDecrypter IAM roles. This helps you follow the principle of least privilege.

Create a storage bucket

Perform this procedure in the STORAGE_PROJECT_ID project.

Create a storage bucket called STORAGE_BUCKET.
Grant the roles/storage.objectAdmin role on the STORAGE_BUCKET storage bucket to the key user account.

Create an encryption key

Perform this procedure as the key administrator user in the KEY_PROJECT_ID project.

Create a key ring. The name of a key ring must be unique within the project. A key ring can't be renamed or deleted. Use the Google Cloud CLI to create a key ring.
```
gcloud kms keyrings create KEY_RING \
  --location LOCATION
```
Replace the following:
- KEY_RING: the name to use for the storage key ring—for example, storage.
- LOCATION: the location where you want to create the key ring. This should be geographically near the location where you want to create the Cloud Storage bucket.
Create an encryption key in the key ring. The name of the key must be unique within the key ring. Keys can't be renamed or deleted, but their key versions can be destroyed. Use the Google Cloud CLI to create the key. An initial key version is created automatically and becomes the primary version.
```
gcloud kms keys create KEY_NAME \
  --location LOCATION \
  --keyring KEY_RING \
  --purpose encryption
```
Replace the following:
- LOCATION: the location where you created the key ring.
- KEY_NAME: the name to use for the storage key—for example, storage.
- KEY_RING: the name you used for the storage key ring—for example, storage.
Note: To use raw symmetric encryption keys, set the purpose field to raw-encryption.

You can learn more about Creating key rings and keys.

Encrypt the file that contains the secret

Perform this procedure as the key user account, working in both projects.

On your local machine, save the secret.
```
echo "SECRET_TEXT" > PATH_TO_SECRET
```
Replace the following:
- SECRET_TEXT: the secret that you want to protect, in plain text—for example, this is a secret.
- PATH_TO_SECRET: the path where you want to create the secret—for example, secret.txt.
Encrypt the secret using Cloud KMS and the encryption key.
```
gcloud kms encrypt \
  --location LOCATION \
  --keyring KEY_RING \
  --key KEY_NAME \
  --plaintext-file PATH_TO_SECRET \
  --ciphertext-file PATH_TO_ENCRYPTED_SECRET
```
Replace the following:
- LOCATION: the location where you created the key ring.
- KEY_RING: the name of the key ring.
- KEY_NAME: the name of the encryption key.
- PATH_TO_SECRET: the path where you created the secret.
- PATH_TO_ENCRYPTED_SECRET: the path where you want to save the encrypted secret—for example, secret.txt.encrypted.
You can learn more about encrypting data by following the encrypt data quickstart.

Use raw-encrypt instead for raw symmetric encryption.
Upload the encrypted secret file to the storage bucket. You can use the following gcloud CLI command:
```
gcloud storage cp PATH_TO_ENCRYPTED_SECRET gs://STORAGE_BUCKET
```
You can learn more about uploading objects to a storage bucket.
Optional: Delete the plaintext secret file (PATH_TO_SECRET) from the local machine. This is a good practice for files containing unencrypted sensitive data.

The STORAGE_BUCKET storage bucket now contains the encrypted secret file, which is encrypted using the KEY_NAME encryption key.

Decrypt the file that contains the secret

Perform these steps as the key user account, working in both projects.

Download the encrypted secret file from the storage bucket. You can use the following gcloud CLI command:
```
gcloud storage cp gs://STORAGE_BUCKET/PATH_TO_ENCRYPTED_SECRET .
```
You can learn more about downloading objects from a storage bucket.
Decrypt the file using the same key that you used to encrypt it.
```
gcloud kms decrypt --location LOCATION \
  --keyring KEY_RING \
  --key KEY_NAME \
  --ciphertext-file PATH_TO_ENCRYPTED_SECRET \
  --plaintext-file PATH_TO_DECRYPTED_SECRET
```
Replace the following:
- LOCATION: the location where you created the key ring.
- KEY_RING: the name of the key ring.
- KEY_NAME: the name of the encryption key.
- PATH_TO_ENCRYPTED_SECRET: the path to the downloaded encrypted secret—for example, secret.txt.encrypted.
- PATH_TO_DECRYPTED_SECRET: the path where you want to save the decrypted secret—for example, secret_decrypted.txt.
You can learn more about decrypting data by following the encrypt data quickstart.

Use raw-decrypt instead for raw symmetric encryption.

You can now read the decrypted plaintext of the secret using cat or a text editor. The contents are identical to the original contents of PATH_TO_SECRET.
Optional: Delete the PATH_TO_ENCRYPTED_SECRET and PATH_TO_DECRYPTED_SECRET files from the local machine.

Cleaning up

To clean up, delete all the files you created on the local machine, then delete the KEY_PROJECT_ID and STORAGE_PROJECT_ID projects.

What's next

Read more about secret management.
Learn about separation of duties.
Learn about granting, changing, and revoking access to resources.
Learn about creating a service account.