Encrypt user data

AI-generated Key Takeaways

Encrypting data for the Data Manager API involves setting up the Google Cloud command line interface, creating a key in Cloud KMS, creating a workload identity pool provider, and encrypting the data using a data encryption key (DEK) that is itself encrypted by your Cloud KMS key.
The setup process includes installing the gcloud CLI, enabling Cloud KMS in a recommended separate project, and setting the project in your environment.
Creating a key requires creating a key ring and then creating the key within that key ring, specifying its purpose and rotation details.
Setting up a workload identity pool provider involves creating a workload identity pool and a provider, and then granting the key decrypter role to the WIP provider and potentially to a specific Google service account for event data.
Data encryption requires formatting and hashing values, then encrypting the hashed values using a DEK, encoding the encrypted output, and finally setting the encryption_info and encoding fields in the API request.

The Data Manager API supports encrypting data using the following key management services:

Google Cloud Key Management Service
AWS Key Management Service

Support for some use cases differs by key management service (KMS):

Category	Use case	Google Cloud KMS	AWS KMS
Audiences	Send audience members
Events	Offline conversions or enhanced conversions for leads
Events	Events sent as an additional data source to a Google Ads destination
Events	Events sent as an additional data source to a Google Analytics destination

Set up Google Cloud KMS

Here are the steps to set up Google Cloud KMS resources for encryption.

Set up the Google Cloud command line interface

Install and initialize the Google Cloud command line interface.
To select or create a new Google Cloud project and enable the Cloud Key Management Service, click Enable Cloud KMS.

Tip: We recommend using a separate project for your Cloud KMS resources that doesn't contain any other Google Cloud resources.

Enable Cloud KMS
To set your project in your environment, use the gcloud config set command. To check if the project is already set in your environment, run gcloud config list.

If no project is set, or you want to use a different project for your key, run gcloud config set:
```
gcloud config set project PROJECT_ID
```

Create a key

For more information, see the Cloud Key Management Service overview.

Create a key ring.

gcloud kms keyrings create KEY_RING_NAME \
    --location KEY_RING_LOCATION

For more information, see Create a key ring.

Create a key in the key ring. The ROTATION_PERIOD indicates the interval to rotate the key, and the NEXT_ROTATION_TIME indicates the date and time when the first rotation should occur.

For example, to rotate the key every 30 days and perform the first rotation in 1 week, set ROTATION_PERIOD to 30d and NEXT_ROTATION_TIME to $(date --utc --date="next week" --iso-8601=seconds).
```
gcloud kms keys create KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --purpose "encryption" \
    --rotation-period ROTATION_PERIOD \
    --next-rotation-time "NEXT_ROTATION_TIME"
```
For more information, see Create a key.

Create a workload identity pool provider

This section is a short overview of Workload Identity Federation. For more information, see Workload Identity Federation.

Create a workload identity pool (WIP). The location for the pool must be global.

gcloud iam workload-identity-pools create WIP_ID \
   --location=global \
   --display-name="WIP_DISPLAY_NAME" \
   --description="WIP_DESCRIPTION"

For more information, see Manage workload identity pools and providers.

Create a workload identity pool provider. The --attribute-condition argument verifies that the caller is a confidential match service account.

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
   --location=global \
   --workload-identity-pool=WIP_ID \
   --display-name="PROVIDER_DISPLAY_NAME" \
   --description="PROVIDER_DESCRIPTION" \
   --attribute-mapping="google.subject=assertion.sub,google.groups=[\"PROVIDER_ID\"]" \
   --attribute-condition="assertion.swname == 'CONFIDENTIAL_SPACE' &&
     'STABLE' in assertion.submods.confidential_space.support_attributes &&
     ['cfm-services@admcloud-cfm-services.iam.gserviceaccount.com'].exists(
         a, a in assertion.google_service_accounts) &&
     'ECDSA_P256_SHA256:6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9'
     in assertion.submods.container.image_signatures.map(sig, sig.signature_algorithm+':'+sig.key_id)" \
   --issuer-uri="https://confidentialcomputing.googleapis.com" \
   --allowed-audiences="https://sts.googleapis.com"

Grant the key decrypter role to the WIP provider.

# Grants the role to the WIP provider.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "principalSet://iam.googleapis.com/projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/group/PROVIDER_ID" \
    --role "roles/cloudkms.cryptoKeyDecrypter"

If you want to encrypt event data for offline conversions and enhanced conversions for leads, grant the key decrypter role to the Google service account datamanager-api@datamanager-ga.iam.gserviceaccount.com.

# Grants the role to the Google service account.
gcloud kms keys add-iam-policy-binding KEY_NAME \
    --keyring KEY_RING_NAME \
    --location KEY_RING_LOCATION \
    --member "serviceAccount:datamanager-api@datamanager-ga.iam.gserviceaccount.com" \
    --role "roles/cloudkms.cryptoKeyDecrypter"

Proceed to the Encrypt data section.

Set up AWS KMS

Here are the steps to set up AWS KMS resources for encryption.

Set up the AWS Command Line Interface

Install the AWS Command Line Interface.
Run the following command to verify the installation:
```
aws --version
```
Here's a snippet of the output for a successful installation:
```
aws-cli/2.31.12 Python/3.13.7 ...
```

Set up an AWS user and sign in

Complete the prerequisites for using the AWS Command Line Interface.
Sign in to an IAM Identity Center session.

Create a key

Create a symmetric KMS key (KEK).

aws kms create-key \
  --key-usage ENCRYPT_DECRYPT \
  --key-spec SYMMETRIC_DEFAULT \
  --description "KEK for Confidential Matching Data Encryption"

Note the Arn under KeyMetadata in the output. You'll need this Amazon Resource Name (ARN) in other steps.

AWS_KEY_ARN

Optional: Create a key alias using an alias name of your choice.

aws kms create-alias \
  --alias-name "alias/AWS_KEY_ALIAS" \
  --target-key-id AWS_KEY_ARN

An alias isn't required, but it's useful for constructing AWS Command Line Interface commands. For example, you can retrieve the key ARN using the alias:

aws kms describe-key --key-id "alias/AWS_KEY_ALIAS" \
  --query 'KeyMetadata.Arn' \
  --output text

Create an OpenID Connect identity provider

Create an OpenID Connect (OIDC) identity provider. You only need to perform this step once per AWS account.

aws iam create-open-id-connect-provider \
  --url https://confidentialcomputing.googleapis.com \
  --client-id-list AUDIENCE \
  --thumbprint-list "08745487e891c19e3078c1f2a07e452950ef36f6"

Note the OIDC provider ARN from the output. You'll need this in other steps.

AWS_OIDC_PROVIDER_ARN

Create an IAM policy

Create a JSON file named kms-decrypt-policy.json with the following contents:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "kms:Decrypt",
      "Resource": "AWS_KEY_ARN"
    }
  ]
}

Create an IAM policy using the JSON file and a policy name of your choosing.
```
aws iam create-policy \
  --policy-name "AWS_POLICY_NAME" \
  --policy-document file://kms-decrypt-policy.json
```
Note the IAM policy ARN in the output. You'll need this in other steps.
```
AWS_IAM_POLICY_ARN
```

Create and attach an IAM role

Create a JSON file named role-trust-policy.json with the following contents and the OIDC provider ARN from the earlier step:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "AWS_OIDC_PROVIDER_ARN"
            },
            "Action": [
                "sts:AssumeRoleWithWebIdentity",
                "sts:TagSession"
            ],
            "Condition": {
                "StringEquals": {
                    "confidentialcomputing.googleapis.com:aud": "cfm-awsresource",
                    "aws:RequestTag/swname": "CONFIDENTIAL_SPACE",
                    "aws:RequestTag/container.signatures.key_ids": "6b1f357b59e9407fb017ca0e3e783b2bd5acbfea6c83dd82971a4150df5b25f9"
                },
                "StringLike": {
                    "aws:RequestTag/confidential_space.support_attributes": "*STABLE*"
                }
            }
        }
    ]
}

Create an IAM role with a role name of your choosing.

aws iam create-role \
  --role-name "AWS_IAM_ROLE_NAME" \
  --assume-role-policy-document file://role-trust-policy.json

Attach the role policy to the IAM policy.

aws iam attach-role-policy \
  --role-name "AWS_IAM_ROLE_NAME" \
  --policy-arn "AWS_IAM_POLICY_ARN"

Encrypt data

Encryption in the Data Manager API requires a data encryption key (DEK). A DEK is a symmetric key that you use to encrypt data. Your DEK is encrypted using your Google Cloud or AWS KMS key. You send the encrypted DEK as part of the request.

To prepare the data in the request for encryption, follow the same formatting and hashing guidelines you'd use for unencrypted data.

Don't encrypt unhashed values. For example, the region_code or postal_code of an AddressInfo.

Once the data for each field is formatted and hashed, encrypt the hashed value using the following steps:

Encode the hash bytes using Base64 encoding.
Encrypt the Base64-encoded hash using your DEK.
Encode the output from the encryption process using either hex or Base64 encoding.
Use the encoded value for the field.
Set the encryption_info and encoding on the request.

To complete the last step, modify the IngestAudienceMembersRequest or IngestEventsRequest to indicate you encrypted your data:

Set the encryption_info field.
Set the encoding field to the encoding used to encode the encrypted field values.

Here's a snippet of a request using a Google Cloud KMS key and with the encryption and encoding fields set:

{
  ...
  "encryptionInfo": {
    "gcpWrappedKeyInfo": {
      "kekUri": "gcp-kms://projects/PROJECT_ID/locations/KEY_RING_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME",
      "wipProvider": "projects/PROJECT_ID/locations/global/workloadIdentityPools/WIP_ID/providers/PROVIDER_ID",
      "keyType": "XCHACHA20_POLY1305",
      "encryptedDek": "ENCRYPTED_DEK"
    }
  },
  "encoding": "ENCODING"
}

To use the Data Manager API library and utilities to construct and send a request, see the IngestAudienceMembersWithEncryption code sample for Java or the ingest_audience_members_with_encryption code sample for Python.

Format user data

Best practices

Encrypt user data Stay organized with collections Save and categorize content based on your preferences.

AI-generated Key Takeaways

Set up Google Cloud KMS

Set up the Google Cloud command line interface

Create a key

Create a workload identity pool provider

Set up AWS KMS

Set up the AWS Command Line Interface

Set up an AWS user and sign in

Create a key

Create an OpenID Connect identity provider

Create an IAM policy

Create and attach an IAM role

Encrypt data

Encrypt user data