Protect your data with CMEK

You can use Cloud Key Management Service customer-managed encryption keys (CMEK) to protect Cloud Functions and related data at rest. Such keys are created and managed through Cloud KMS and stored as software keys, in an HSM cluster, or externally.

Deploying a function with a CMEK protects the data associated with it by using an encryption key that is in your full control. This type of encryption allows you to meet compliance requirements in certain industries, such as financial services. Because the key is owned by you and is not controlled by Google, no one (including you) can access the data protected by these encryption keys when the keys are disabled or destroyed.

The following types of Cloud Functions data are encrypted when using a CMEK:

• Function source code uploaded for deployment and stored by Google in Cloud Storage, used in the build process.
• The results of the function build process, including:
  • The container image built from your function source code.
  • Each instance of the function that is deployed.
• At-rest data for internal event transport channels (1st gen only).

The function build process itself is protected by an ephemeral key uniquely generated for each build. See CMEK compliance in Cloud Build for more information. Additionally, note the following:

• File metadata, such as filesystem paths or modification timestamps, is not encrypted.

• If a key is disabled, the container image cannot be deployed and new instances cannot start.

• Cloud Functions CMEK protection only applies to Google-managed Cloud Functions resources; you are responsible for protecting data and resources managed by you, such as your source code repositories, event channels that live in the customer project (2nd gen only), or any services used by your functions.

Setting up CMEK for Cloud Functions entails the following:

• Granting the necessary service accounts access to the key:

  • For all functions, you need to grant the Cloud Functions, Artifact Registry, and Cloud Storage service accounts access to the key.

  • For event-driven Cloud Functions 2nd gen only, you also need to complete CMEK setup for Cloud Run and Eventarc.

• Creating a CMEK-protected Artifact Registry repository to store your function images.

• Enabling CMEK on your function.

• Optionally, enable CMEK organization policies to enforce all new functions to be CMEK compliant.

These steps are described in more detail below.

Before you begin

1. Create a single-region key to use to encrypt your functions. To learn how to create a key, see Creating symmetric encryption keys.

2. Create an Artifact Registry repository that has CMEK enabled. You must use the same key for the Artifact Registry repository as you do when enabling CMEK for a function.

3. For event-driven 2nd gen functions, follow the additional setup steps outlined in Enable CMEK for a Google channel.

Granting service accounts access to the key

For all functions, you must grant the following service accounts access to the key:

• Cloud Functions service agent ([e-mail])

• Artifact Registry service agent ([e-mail])

• Cloud Storage service agent ([e-mail])

For 2nd gen only, you must additionally grant the following service accounts access to the key:

• Cloud Run service agent ([e-mail])

• Eventarc service agent ([e-mail])

To grant these service accounts access to the key, add each service account as a principal of the key and then grant the service account the Cloud KMS CryptoKey Encrypter/Decrypter role:

Console

1. Go to the Cloud Key Management Service page in the Google Cloud console:
   Go to the Cloud KMS page

2. Click the name of the key ring that contains the desired key.

3. Click the name of the key to view the key details.

4. In the Permissions tab, click Grant access.

5. In the New principals field, enter the email addresses of all three service accounts above to assign permissions to all three accounts at once.

6. In the Select a role dropdown, select Cloud KMS CryptoKey Encrypter/Decrypter.

7. Click Save.

gcloud

For each service account above, run the following command:

gcloud kms keys add-iam-policy-binding KEY \
--keyring KEY_RING \
--location LOCATION \
--member serviceAccount:SERVICE_AGENT_EMAIL \
--role roles/cloudkms.cryptoKeyEncrypterDecrypter

Replace the following:

• KEY: The name of the key. For example, my-key.

• KEY_RING: The name of the key ring. For example, my-keyring.

• LOCATION: The location of the key. For example, us-central1.

• SERVICE_AGENT_EMAIL: The email address of the service account.

Important: Some service agents, such as the Cloud Storage service agent (including its email address), are not initially available when you create a project. Instead, they are activated the first time you access them. For example, to activate the Cloud Storage service agent, you can retrieve its email address. The service agent must be activated prior to assigning permissions to it.

Enabling CMEK for a function

After setting up an Artifact Registry repository with CMEK enabled and granting Cloud Functions access to your key, you're ready to enable CMEK for your function.

To enable CMEK for a function:

Console

1. Go to the Cloud Functions page in the Google Cloud console:
   Go to the Cloud Functions page

2. Click the name of the function you want to enable CMEK on.

3. Click Edit.

4. Click Runtime, build... to expand the advanced configuration options.

5. Select the Security and image repo tab.

6. In the Encryption section, select Customer-managed encryption key (CMEK).

7. Select your chosen key from the dropdown.

8. Under Container location, select Customer-managed Artifact Registry.

9. In the Artifact registry dropdown, select the CMEK-protected repository.

10. Click Next.

11. Click Deploy.

gcloud

Run the following command.

gcloud functions deploy FUNCTION \
[--gen2] \
--kms-key=KEY \
--docker-repository=REPOSITORY \
--source=YOUR_SOURCE_LOCATION
FLAGS...

Replace the following:

• FUNCTION: The name of the function to enable CMEK on. For example, cmek-function.

• KEY: The fully qualified key name, in the following format: projects/PROJECT_NAME/locations/LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME.

• REPOSITORY: The fully qualified Artifact Registry repository name, in the following format: projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY.

• YOUR_SOURCE_LOCATION: When enabling CMEK for a pre-existing function, make sure that the intended source code is being re-deployed by specifying this parameter explicitly.

• FLAGS...: Additional flags that may be required to deploy your function, particularly for create deployments. For details, see Deploy a Cloud Function.

CMEK is enabled for the function.

Note: First-time function deployments with CMEK enabled might fail due to IAM propagation delays. If you encounter an error upon deployment, ensure the permissions are set correctly and try again after a short period.

Note that Cloud Functions always uses the primary version of a key for CMEK protection. You cannot specify a particular key version to use when enabling CMEK for your functions.

If a key is destroyed or disabled, or the requisite permissions on it are revoked, active instances of functions protected by that key are not shut down. Function executions already in progress will continue to run, but new executions will fail as long as Cloud Functions does not have access to the key.

Testing CMEK protection

To verify that CMEK protection is working, you can disable the key you used to enable CMEK for a function, then try to trigger your function:

1. Disable the key used to protect your function.

   Note: It may take up to three hours for the changes to propagate.

2. Attempt to view the source code associated with this function. The attempt should fail.

3. Attempt to trigger the CMEK-protected function. The attempt should fail.

4. After you have verified that CMEK protection is working, enable the key.

The function's CMEK protection is now confirmed.

What's next

• Learn how to rotate your keys.
• Learn more about Google default encryption.
• Learn more about CMEK.
• Learn more about CMEK organization policies.