Enable customer-managed encryption keys for Parameter Manager

By default, Parameter Manager encrypts user data at rest. Parameter Manager handles encryption for you without any additional actions. This option is Google default encryption.

You can enforce granular control over your encryption keys by using Customer-Managed Encryption Keys (CMEKs) within Cloud Key Management Service. Services like Parameter Manager integrate seamlessly with CMEKs, letting you manage protection levels, locations, usage, access permissions, and cryptographic boundaries of your keys directly in Cloud KMS. Using Cloud KMS also lets you view audit logs, and control key life cycles. Instead of Google owning and managing the symmetric key encryption keys that protect your data, you control and manage these keys in Cloud KMS.

Accessing your Parameter Manager resources with CMEKs is similar to using Google default encryption. For more information about your encryption options, see Customer-managed encryption keys (CMEKs).

You can configure a CMEK on the parameter resource. This key is used to protect the parameter version payload. Parameter version payload data is encrypted using envelope encryption upon creation.

How CMEK works in Parameter Manager

Before writing a parameter version to persistent storage in a specific location, Parameter Manager encrypts the data with a unique data encryption key (DEK). This DEK is then encrypted with a replica-specific key encryption key (KEK) owned by the Parameter Manager service.

When you use CMEK for Parameter Manager, the KEK is a symmetric key that you manage in Cloud KMS. The CMEK key must be in the same Google Cloud location as the parameter version replica. You can also use an Cloud EKM key as a CMEK for encryption and decryption.

The expected format for a CMEK is projects/*/locations/*/keyRings/*/cryptoKeys/*.

For more information about CMEK, including when and why to enable it, see the Cloud Key Management Service documentation.

Before you begin

Complete the following prerequisites to set up Parameter Manager and Cloud KMS:

Set the following variables to your Parameter Manager and Cloud KMS project IDs.

  • PM_PROJECT_ID: the Parameter Manager project ID. Used in all commands on this page.
  • KMS_PROJECT_ID: the Cloud KMS project ID. Used in all commands on this page.

You can store the key ring within the same project as your resources, or in a different project. Using different projects provides more fine-grained control and supports the separation of duties.

Configure CMEK on a parameter

To set up a CMEK to protect a specific parameter, follow these steps:

  1. Create a new symmetric Cloud KMS key or use an existing one. This example demonstrates creating a new key ring and key.

    gcloud

    gcloud kms keyrings create "KEY_RING" \
    --project "KMS_PROJECT_ID" \
    --location "LOCATION"
    gcloud kms keys create "KEY_NAME" \
    --project "KMS_PROJECT_ID" \
    --location "LOCATION" \
    --keyring "parameter-manager-cmek" \
    --purpose "encryption"

    Replace the following variables:

    • KEY_RING: the name of the key ring that contains the key.
    • KMS_PROJECT_ID: the Cloud KMS project ID.
    • LOCATION: the Cloud KMS location of the key ring. Choose the same location as the parameter resource. Otherwise, the parameter version creation request is rejected.
    • KEY_NAME: the name of the key.

  2. Create a parameter. The resource name of the CMEK is stored as metadata on the parameter.

    gcloud

    gcloud parametermanager parameters create "PARAMETER_ID" \
    --kms-key "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME" \
    --project "PM_PROJECT_ID"

    API

    curl "https://parametermanager.googleapis.com/v1/projects/PM_PROJECT_ID/parameters?parameter_id=PARAMETER_ID" \
    --request "POST" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data-binary @- <<EOF

    Replace the following variables:

    • PARAMETER_ID: the name of the parameter
    • PM_PROJECT_ID: the Parameter Manager project ID

  3. Grant the Parameter Manager service identity, which is specific to your project, the permission to use your encryption key. This lets Parameter Manager encrypt and decrypt data as needed, using your chosen key. To do this, assign the Cloud KMS CryptoKey Encrypter/Decrypter role (roles/cloudkms.cryptoKeyEncrypterDecrypter) to the service identity. Note that the service identity is automatically created when you create the first parameter in your project.

    gcloud

    gcloud kms keys add-iam-policy-binding "my-cmek-key" \
    --project "KMS_PROJECT_ID" \
    --location "LOCATION" \
    --keyring "parameter-manager-cmek" \
    --member "service-PROJECT_NUMBER@gcp-sa-pm.iam.gserviceaccount.com" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

    Replace PROJECT_NUMBER with the project number of the Google Cloud project where the parameter is stored.

    When the service creates a parameter version, it automatically encrypts the parameter version's payload with the key before writing it to persistent storage, if the service identity can access the customer-managed encryption key (CMEK). If the service identity can't access the key, attempts to create or access parameter versions return an error.

  4. Create a new parameter version. Notice that if you don't specify the Cloud KMS key's resource name, it is read from the parameter's metadata.

    gcloud

    gcloud parametermanager parameters versions create PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION --payload-data="PARAMETER_PAYLOAD"

    Replace the following variables:

    • PARAMETER_VERSION_ID: the ID that you want to assign to the parameter version. Parameter version IDs must be 63 characters or less and consist only of alphanumeric characters (A-Z, a-z, 0-9), dashes (-), and underscores (_). IDs cannot begin with a dash.
    • PARAMETER_PAYLOAD: the data, in plaintext, that you want to store within the parameter.

    The parameter version is created, even if the caller doesn't have direct access to use the CMEK key. The service identity for Parameter Manager, rather than the caller, is responsible for encrypting and decrypting parameters when reading or writing them.

    Similarly, you don't need direct access to the CMEK key in order to access the parameter. The service identity accesses the key and encrypts or decrypts the parameter on your behalf.

  5. View the parameter version you just created:

    gcloud

    gcloud parametermanager parameters versions describe PARAMETER_VERSION_ID --parameter=PARAMETER_ID --location=LOCATION

Update CMEK configuration

To change the encryption key used to protect your data, follow these steps:

  1. Create a new symmetric KMS key in the selected Cloud KMS location.

    gcloud

    gcloud kms keys create "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "LOCATION" \
    --keyring "parameter-manager-cmek" \
    --purpose "encryption"

  2. Assign the Parameter Manager service identity the necessary permissions to use your encryption key.

    gcloud

    gcloud kms keys add-iam-policy-binding "my-other-key" \
    --project "KMS_PROJECT_ID" \
    --location "LOCATION" \
    --keyring "parameter-manager-cmek" \
    --member "service-PROJECT_NUMBER@gcp-sa-pm.iam.gserviceaccount.com" \
    --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

  3. Modify the CMEK configuration on a parameter by updating the parameter with the new Cloud KMS key resource names.

    gcloud

    gcloud parametermanager parameters update "PARAMETER_ID" --location "LOCATION" --kms-key "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/parameter-manager-cmek/cryptoKeys/my-other-key"

    API

    curl "https://parametermanager.googleapis.com/v1/projects/PM_PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID?update_mask=kmsKey" \
    --request "PATCH" \
    --header "Authorization: Bearer $(gcloud auth print-access-token)" \
    --header "Content-Type: application/json" \
    --data-binary @- <<EOF
 {
 "kmsKey": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/parameter-manager-cmek/cryptoKeys/my-other-key"
 }
 EOF

View parameter version CMEK configuration

To inspect the metadata of a parameter version, including whether the parameter version is CMEK-enabled and the resource name of the CMEK key version, run the command to view its metadata.

gcloud

gcloud parametermanager parameters versions describe "PARAMETER_VERSION_ID" \
    --parameter= "PARAMETER_ID" \
    --location= "LOCATION"
    --project "PM_PROJECT_ID"

API

curl "https://parametermanager.<var>LOCATION</var>.rep.googleapis.com/v1/projects/PM_PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions/PARAMETER_VERSION_ID?view=FULL" \
    --request "GET" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json"

This returns the full Cloud KMS resource name of the key version used to encrypt the parameter version. The output is similar to the following:

   {
      "name": "projects/PM_PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID/versions/PARAMETER_VERSION_ID",
      "createTime": "2024-10-30T05:27:51.206825427Z",
      "updateTime": "2024-10-30T05:27:51.442194863Z",
      "payload": {
        "data": "YTogYgo="
      }
   "kmsKeyVersion": "projects/KMS_PROJECT_ID/locations/LOCATION/keyRings/parameter-manager-cmek/cryptoKeys/my-cmek-key/cryptoKeyVersions/1"
   }

Add a Cloud EKM key to a CMEK policy

This section explains how to incorporate an Cloud EKM key into a CMEK policy for parameter encryption and decryption. As Cloud EKM doesn't support the global multi-region, these keys are limited to regional parameters.

To add a Cloud EKM key to a CMEK policy, follow these steps:

  1. Create a manually managed Cloud EKM key.
  2. Configure a CMEK enabled parameter that uses this Cloud EKM key.

Disable CMEK

To remove CMEK configuration from a parameter, use the following command:

API

curl "https://parametermanager.googleapis.com/v1/projects/PM_PROJECT_ID/locations/LOCATION/parameters/PARAMETER_ID?update_mask=kmsKey" \
    --request "PATCH" \
    --header "Authorization: Bearer $(gcloud auth print-access-token)" \
    --header "Content-Type: application/json" \
    --data-binary '{}'

Additional information

  • Existing parameters can be updated to use CMEK.
  • Parameters that already use CMEK can have their CMEK keys changed, or removed to revert to Google default encryption.

Error handling

  • Operations fail if the CMEK key is unavailable or if the service identity lacks the necessary permissions.
  • The parameter version creation fails if the CMEK and parameter are not in the same location.

What's next

  • Learn more about CMEK.