This topic shows how to use Cloud Key Management Service to protect sensitive application data on the client, before transmitting it across a network. Sensitive data is also called secret data or a secret.
In this walk-through, you encrypt a file using Cloud KMS before you upload it to a Cloud Storage bucket. Next, you download and decrypt the same data so that you can read it on the client.
Cloud Storage also supports automatic server-side encryption using customer-managed encryption keys, which automates this entire process. This walk-through is for demonstration purposes only. You can adapt these principles to protect data before storing it in a database or other persistent storage.
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.
We recommend using two projects and two users to ensure separation of duties. If you follow the steps in this topic, 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.
You create projects in the Google Cloud Console. For step-by-step instructions, see the Cloud Identity and Access Management quickstart.
Within the 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. In the steps below, this project is referred to as my-storage-project.
Optionally, create a second Google Cloud project to manage the Cloud KMS keys used to encrypt and decrypt the secret. In the steps below, this project is called my-kms-project.
You can choose to use the same Google Cloud project for both my-storage-project and my-kms-project.
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.
You create users and grant them roles in the Google Cloud Console. For step-by-step instructions, see the Cloud Identity and Access Management quickstart.
This procedure creates two users. key-admin manages the encryption keys, and key-user can encrypt and decrypt data using the keys.
Perform this procedure in the my-kms-project project.
key-adminuser. To create users, you need the
roles/resourcemanager.organizationAdminrole for the my-kms-project project.
roles/cloudkms.adminCloud Identity and Access Management role.
key-admincan create and manage keys.
roles/cloudkms.cryptoKeyEncrypterDecrypterCloud IAM role.
key-usercan use keys to encrypt and decrypt data.
Create a storage bucket
Perform this procedure in the
- Create a storage bucket called
- Grant key-user the
roles/storage.objectAdminrole for the my-bucket storage bucket.
Create an encryption key
Perform this procedure as the
key-admin user in the
Create a key ring called storage. The name of a key ring is unique to the project. A key ring cannot be renamed or deleted. Use the
gcloudcommand-line tool to create a key ring.
gcloud kms keyrings create storage \ --location global
Create a key named my-key in the storage key ring, for the purpose of encryption. The name of a key is unique to the key ring. A key cannot be renamed or deleted, but its key versions can be destroyed. Use the
gcloudcommand-line tool to create the key. An initial key version is created automatically and becomes the primary version.
gcloud kms keys create my-key \ --location global \ --keyring storage \ --purpose 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 user, using both projects.
On your local machine, create a file called my-secret.txt, which contains the text "This is my secret."
echo "This is my secret" > my-secret.txt
Encrypt my-secret.txt using the my-key key in the
my-kms-projectproject. Write the encrypted file to mysecret.txt.encrypted.
gcloud kms encrypt \ --location global \ --keyring storage \ --key my-key \ --plaintext-file my-secret.txt \ --ciphertext-file my-secret.txt.encrypted
You can learn more about encrypting data by following the encrypt data quickstart.
Upload the encrypted my-secret.txt.encrypted file to the my-bucket storage bucket in the my-storage-project project. You can use the
gsutil cp my-secret.txt.encrypted gs://my-storage-bucket
You can learn more about uploading objects to a storage bucket.
[Optional] Delete the plaintext my-secret.txt file from the local machine. This is a good practice for files containing unencrypted sensitive data.
The my-storage-bucket storage bucket now contains the file my-secret.txt.encrypted, which is encrypted using the my-key key,
Decrypt the file that contains the secret
Perform these steps as the key-user user, using both projects.
Download the my-secret.txt.encrypted file from the my-bucket storage bucket. You can use the
gsutil cp gs://my-storage-bucket/ my-secret.txt.encrypted
You can learn more about downloading objects from a storage bucket.
Try to read the file using a command like
lessor a text editor. Notice that it is not a plain-text file.
Decrypt the my-secret.txt.encrypted and save the decrypted data to a new plaintext file called my-secret.txt.decrypted, using the same key that you used to encrypt my-secret.txt.
gcloud kms decrypt --location global \ --keyring storage \ --key my-key \ --ciphertext-file my-secret.txt.encrypted \ --plaintext-file my-secret.txt.decrypted
You can learn more about decrypting data by following the encrypt data quickstart.
Read the my-secret.txt.decrypted file using the
catcommand. Its contents are identical to the original contents of my-secret.txt.
This is my secret.
[Optional] Delete the my-secret.txt.encrypted and my-secret.txt.decrypted files from the local machine.
To clean up, delete all the files you created on the local machine, then delete
- Read more about secret management.
- Learn about separation of duties.
- Learn about granting, changing, and revoking access to project members.
- Learn about creating a service account.