How to encrypt and decrypt a secret file in the Google Cloud Platform

The Google Cloud Key Management Service (KMS) can encrypt and decrypt files in the Google Cloud Platform (GCP) system. To use KMS, we need to understand some basic terminologies.

• Location. A location represents the geographical region where a Cloud KMS resource is stored and can be accessed. A key’s location can impact the performance of applications using the key. It is recommended to specify the same location as the applications that require the key. If the impact on performance is minimal or if the applications span multiple regions, you can specify the global location as in this article.

• Key ring. A key ring organizes keys in a specific Google Cloud location and allows you to manage access control on groups of keys. A key ring’s name does not need to be unique across a Google Cloud project but must be unique within a given location.

• Key. A Cloud KMS key is a named object containing one or more key versions, along with metadata for the key. A key exists on exactly one key ring tied to a specific location.

• Key version. A key has multiple versions. A key’s version is represented by an integer, starting at 1. To decrypt data or verify a signature, you must use the same key version that was used to encrypt or sign the data.

• Purpose. A key can be used for encryption or for signing. There are two types keys that serve these two purposes. A symmetric key is always used for encryption, while an asymmetric key can be used for both encryption and signing. In symmetric encryption, the entire key is required to encrypt or decrypt data, while in asymmetric encryption/signing, the key consists of a public and private key, which is similar to the SSH RSA key pair. We will focus on the symmetric key in this article because our purpose is to encrypt and decrypt a credential file.

• Primary version. A symmetric key can have at most one primary key version. The primary key version is used to encrypt data if you do not specify a key version. When a symmetric key is rotated, a new version will be created and serve as the primary key version. For decryption, Cloud KMS can automatically detect the decryption key version from the ciphertext and you don’t need to specify a key version when you decrypt a file. Therefore, normally we don’t specify the key version when we use the symmetric key in both encryption and decryption steps.

It is recommended to run the commands below in a Cloud Shell because you don’t need to worry about the installation of the Google SDK and the authentication.

Before using Cloud KMS, we must enable this service if it is not enabled yet.

gcloud services enable cloudkms.googleapis.com --project "${GOOGLE_CLOUD_PROJECT}"

GOOGLE_CLOUD_PROJECT represents the project ID. It is an environment variable available in the Cloud Shell. You can find the project ID on the home page in your GCP console.

Then we need to create a key ring to group the keys:

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

We can now create a key in this keyring:

gcloud kms keys create "my-key" \
    --location "global" \
    --keyring "my-keyring" \
    --purpose "encryption"

The keyrings and keys can be managed on the Cryptographic keys page in the GCP console.

Now that we have a key, we can use it to encrypt some text file.

gcloud kms encrypt \
    --location "global" \
    --keyring "my-keyring" \
    --key "my-key" \
    --plaintext-file ./my-certificate.txt \
    --ciphertext-file ./my-certificate.txt.enc

We can encrypt any plain text file. If you don’t have one at hand, you can fake one:

echo "This is my secret file" > ./my-certificate.txt

After encryption, if you open my-certificate.txt.enc you can see that content is encrypted and is not readable.

Please note that Cloud KMS encryption is non-convergent, which means Cloud KMS produces a different ciphertext each time it is invoked, even for the same plaintext data.

To decrypt the encrypted data (also known as "ciphertext"), you can run this command:

gcloud kms decrypt \
    --location "global" \
    --keyring "my-keyring" \
    --key "my-key" \
    --ciphertext-file ./my-certificate.txt.enc \
    --plaintext-file ./my-certificate.txt

If you are not the owner of the project, you would need to ask the administrator of your project to grant you the roles/cloudkms.cryptoKeyEncrypterDecrypter IAM roles.

In this article, you have learned the basics of Google Cloud KMS and how to encrypt/decrypt secret files. You can now add encrypted secret files to your source code with no security issues.