Add CMEK encryption to regional secrets

This page describes how you can create new secrets with customer-managed encryption keys (CMEK) and update existing secrets to use CMEK keys.

Overview

CMEK adds an extra layer of security and control over your sensitive data stored as regional secrets. You can use CMEK to meet the following goals:

Have complete control over the encryption keys used to protect your secrets.
Use your own key management system with potentially stricter security policies, auditing capabilities, and compliance features.
Comply with data sovereignty regulations by keeping the keys within your own infrastructure.
Define fine-grained access controls for your encryption keys, specifying who can use them and for what purposes.

Limitations:

Using CMEK with regional secrets has the following limitations:

Cloud Key Management Service Autokey (Preview) isn't supported for regional secrets.
The location of the CMEK key must be the same as the location of the regional secret.

Before you begin

Enable the Secret Manager API, once per project.
Assign the Secret Manager Admin role (roles/secretmanager.admin) on the project, folder, or organization.
Authenticate to the Secret Manager API using one of the following ways:
- If you use client libraries to access the Secret Manager API, set up Application Default Credentials.
- If you use the Google Cloud CLI to access the Secret Manager API, use your Google Cloud CLI credentials to authenticate.
- To authenticate a REST call, use either Google Cloud CLI credentials or Application Default Credentials.
To enable CMEK and to create the CMEK keys and key rings that you require for this step, see Enable customer-managed encryption keys for Secret Manager.

Create a regional secret with CMEK encryption

To create a new secret with CMEK encryption, use one of the following methods:

Console

Go to the Secret Manager page in the Google Cloud console.

Go to Secret Manager
On the Secret Manager page, click the Regional secrets tab, and then click Create regional secret.
On the Create regional secret page, enter a name for the secret in the Name field. A secret name can contain uppercase and lowercase letters, numerals, hyphens, and underscores. The maximum allowed length for a name is 255 characters.
Enter a value for the secret (for example, abcd1234). The secret value can be in any format but must not be larger than 64 KiB. You can also upload a text file containing the secret value using the Upload file option. This action automatically creates the secret version.
Choose the location where you want your regional secret to be stored from the Region list.
Under Encryption, select Customer-managed encryption key (CMEK), and then choose your CMEK key from the Encryption key list. Ensure that your CMEK key exists in the specified location and your Secret Manager project has the necessary permissions to use the key.
Click Create secret.

gcloud

Before using any of the command data below, make the following replacements:

SECRET_ID: the ID of the secret or fully qualified identifier for the secret
LOCATION: the Google Cloud location where you want to create the secret
CMEK_KEY: the fully qualified path to the specific CMEK key in Cloud Key Management Service that will protect the secret

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud secrets create SECRET_ID --location=LOCATION \
    --regional-kms-key-name=CMEK_KEY

Windows (PowerShell)

gcloud secrets create SECRET_ID --location=LOCATION `
    --regional-kms-key-name=CMEK_KEY

Windows (cmd.exe)

gcloud secrets create SECRET_ID --location=LOCATION ^
    --regional-kms-key-name=CMEK_KEY

REST

Before using any of the request data, make the following replacements:

LOCATION: the Google Cloud location where you want to create the secret.
PROJECT_ID: the Google Cloud project ID.
SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
KMS_PROJECT_ID: the ID of your Google Cloud project that is running Cloud Key Management Service.
KMS_KEY_LOCATION: the location name of your Cloud KMS key. This must be the same location as your secret.
YOUR_KEY_RING: the name of the key ring in Cloud KMS where you have stored your CMEK key.
YOUR_CMEK_KEY: the specific Customer-Managed Encryption Key (CMEK) that you have created within your chosen key ring in Cloud KMS.

HTTP method and URL:

POST https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID

Request JSON body:

{"customer_managed_encryption": {"kms_key_name": "projects/KMS_PROJECT_ID/locations/KMS_KEY_LOCATION/keyRings/YOUR_KEY_RING/cryptoKeys/YOUR_CMEK_KEY"}}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID"

PowerShell

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets?secretId=SECRET_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-03-27T13:30:07.437859Z",
  "etag": "\"1614a467b60423\""
  "customerManagedEncryption": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/KMS_KEY_LOCATION/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
  }
}

Update an existing secret to use CMEK

To update an existing secret to use CMEK, use one of the following methods:

Console

Go to the Secret Manager page in the Google Cloud console.

Go to Secret Manager
On the Secret Manager page, click the Regional secrets tab.
To edit a secret, use one of the following methods:
- Locate the secret in the list and click the Actions menu associated with that secret. In the Actions menu, click Edit.
- Click the secret name to go to the secret details page. On the secret details page, click Edit secret.
On the Edit secret page, go to the Encryption section.
Under Encryption, select Customer-managed encryption key (CMEK), and then select your CMEK key from the Encryption key list. Ensure that your CMEK key exists in the specified location and your Secret Manager project has the necessary permissions to use the key.
Click Update secret.

gcloud

Before using any of the command data below, make the following replacements:

SECRET_ID: the ID of the secret or fully qualified identifier for the secret
LOCATION: the Google Cloud location of the secret
CMEK_KEY: the fully qualified path to the specific CMEK key in Cloud Key Management Service that will protect the secret

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud secrets update SECRET_ID --location=LOCATION \
    --regional-kms-key-name=CMEK_KEY

Windows (PowerShell)

gcloud secrets update SECRET_ID --location=LOCATION `
    --regional-kms-key-name=CMEK_KEY

Windows (cmd.exe)

gcloud secrets update SECRET_ID --location=LOCATION ^
    --regional-kms-key-name=CMEK_KEY

REST

Before using any of the request data, make the following replacements:

LOCATION: the Google Cloud location of the secret.
PROJECT_ID: the Google Cloud project ID.
SECRET_ID: the ID of the secret or fully qualified identifier for the secret.
KMS_PROJECT_ID: the ID of your Google Cloud project that is running Cloud Key Management Service.
KMS_KEY_LOCATION: the location of your Cloud KMS key. This must be the same location as your secret.
YOUR_KEY_RING: the name of the key ring in Cloud KMS where you have stored your CMEK key.
YOUR_CMEK_KEY: the specific Customer-Managed Encryption Key (CMEK) that you have created within your chosen key ring in Cloud KMS.

HTTP method and URL:

PATCH https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=customer_managed_encryption

Request JSON body:

{"customer_managed_encryption": {"kms_key_name": "projects/KMS_PROJECT_ID/locations/KMS_KEY_LOCATION/keyRings/YOUR_KEY_RING/cryptoKeys/YOUR_CMEK_KEY"}}"

To send your request, choose one of these options:

curl

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=customer_managed_encryption"

PowerShell

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://secretmanager.LOCATION.rep.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID?updateMask=customer_managed_encryption" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID",
  "createTime": "2024-03-27T13:30:07.437859Z",
  "etag": "\"16211daf5f29c5\""
  "customerManagedEncryption": {
    "kmsKeyName": "projects/KMS_PROJECT_ID/locations/KMS_KEY_LOCATION/keyRings/secret-manager-cmek/cryptoKeys/my-cmek-key"
  }
}

Add CMEK encryption to regional secrets

Overview

Limitations:

Before you begin

Create a regional secret with CMEK encryption

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

Update an existing secret to use CMEK

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

What's next