Create a wrapped key

This page describes how to use Cloud Key Management Service (Cloud KMS) to create a wrapped key that you can then use to send deidentify and reidentify requests to the Cloud Data Loss Prevention API of Sensitive Data Protection.

The process of using a cryptographic key to de-identify and re-identify content is called pseudonymization (or tokenization). For conceptual information on this process, see Pseudonymization.

For an end-to-end example that demonstrates how to create a wrapped key, tokenize content, and re-identify tokenized content, see Quickstart: De-identifying and re-identifying sensitive text instead.

You can complete the steps in this topic in 5 to 10 minutes, not including the Before you begin steps.

Note: When you use Cloud KMS for cryptographic operations, charges apply. In addition, when you use a Cloud HSM key or a Cloud EKM key, you consume Cloud KMS quota on the project that contains the key. In contrast, if you're using a software Cloud KMS key with Sensitive Data Protection, no quota limits apply. For more information, see Quotas in the Cloud KMS documentation.

Before you begin

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   • Create a Google Cloud project:

     gcloud projects create PROJECT_ID

     Replace PROJECT_ID with a name for the Google Cloud project you are creating.

   • Select the Google Cloud project that you created:

     gcloud config set project PROJECT_ID

     Replace PROJECT_ID with your Google Cloud project name.

5. Make sure that billing is enabled for your Google Cloud project.

6. Enable the Sensitive Data Protection and Cloud KMS APIs:

   gcloud services enable dlp.googleapis.com cloudkms.googleapis.com

7. Grant roles to your Google Account. Run the following command once for each of the following IAM roles: roles/dlp.user

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE

   • Replace PROJECT_ID with your project ID.
   • Replace EMAIL_ADDRESS with your email address.
   • Replace ROLE with each individual role.
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

11. Make sure that billing is enabled for your Google Cloud project.

12. Enable the Sensitive Data Protection and Cloud KMS APIs:

    gcloud services enable dlp.googleapis.com cloudkms.googleapis.com

13. Grant roles to your Google Account. Run the following command once for each of the following IAM roles: roles/dlp.user

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:EMAIL_ADDRESS" --role=ROLE

    • Replace PROJECT_ID with your project ID.
    • Replace EMAIL_ADDRESS with your email address.
    • Replace ROLE with each individual role.

Step 1: Create a key ring and a key

Before you start this procedure, decide where you want Sensitive Data Protection to process your de-identification and re-identification requests. When you create a Cloud KMS key, you must store it in either global or in the same region that you will use for your Sensitive Data Protection requests. Otherwise, the Sensitive Data Protection requests will fail.

You can find a list of supported locations in Sensitive Data Protection locations. Take note of the name of your chosen region (for example, us-west1).

This procedure uses global as the location for all API requests. If you want to use a different region, replace global with the region name.

1. Create a key ring:

   gcloud kms keyrings create "dlp-keyring" \
       --location "global"
   

2. Create a key:

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

3. List your key ring and key:

   gcloud kms keys list \
       --location "global" \
       --keyring "dlp-keyring"
   

   You get the following output:

   NAME                                                                                   PURPOSE          ALGORITHM                    PROTECTION_LEVEL  LABELS  PRIMARY_ID  PRIMARY_STATE
   projects/PROJECT_ID/locations/global/keyRings/dlp-keyring/cryptoKeys/dlp-key  ENCRYPT_DECRYPT  GOOGLE_SYMMETRIC_ENCRYPTION  SOFTWARE                  1           ENABLED
   

   In this output, PROJECT_ID is the ID of your project.

   The path under NAME is the full resource name of your Cloud KMS key. Take note of it because the de-identify and re-identify requests require it.

Step 2: Create a base64-encoded AES key

This section describes how to create an Advanced Encryption Standard (AES) key and encode it in base64 format.

Note: These steps use the openssl and base64 commands, but there are many other ways to perform this task.

1. Create a 128-, 192-, or 256-bit AES key. The following command uses openssl to create a 256-bit key in the current directory:

   openssl rand -out "./aes_key.bin" 32
   

   The file aes_key.bin is added to your current directory.

2. Encode the AES key as a base64 string:

   base64 -i ./aes_key.bin
   

   You get an output similar to the following:

   uEDo6/yKx+zCg2cZ1DBwpwvzMVNk/c+jWs7OwpkMc/s=
   

   Warning: Do not use this example key to protect actual sensitive workloads. This key is provided only to serve as an example. Because it's shared here, this key is not safe to use.

Step 3: Wrap the AES key using the Cloud KMS key

This section describes how to use the Cloud KMS key that you created in Step 1 to wrap the base64-encoded AES key that you created in Step 2.

To wrap the AES key, use curl to send the following request to the Cloud KMS API projects.locations.keyRings.cryptoKeys.encrypt:

curl "https://cloudkms.googleapis.com/v1/projects/PROJECT_ID/locations/global/keyRings/dlp-keyring/cryptoKeys/dlp-key:encrypt" \
  --request "POST" \
  --header "Authorization:Bearer $(gcloud auth application-default print-access-token)" \
  --header "content-type: application/json" \
  --data "{\"plaintext\": \"BASE64_ENCODED_AES_KEY\"}"

Replace the following:

• PROJECT_ID: the ID of your project.
• BASE64_ENCODED_AES_KEY: the base64-encoded string returned in Step 2.

The response that you get from Cloud KMS is similar to the following JSON:

{
  "name": "projects/PROJECT_ID/locations/global/keyRings/dlp-keyring/cryptoKeys/dlp-key/cryptoKeyVersions/1",
  "ciphertext": "CiQAYuuIGo5DVaqdE0YLioWxEhC8LbTmq7Uy2G3qOJlZB7WXBw0SSQAjdwP8ZusZJ3Kr8GD9W0vaFPMDksmHEo6nTDaW/j5sSYpHa1ym2JHk+lUgkC3Zw5bXhfCNOkpXUdHGZKou1893O8BDby/82HY=",
  "ciphertextCrc32c": "901327763",
  "protectionLevel": "SOFTWARE"
}

In this output, PROJECT_ID is the ID of your project.

Take note of the value of ciphertext in the response that you get. That is your wrapped key.

What's next

• Learn more about tokenizing data through a cryptographic key.

• Work through an end-to-end example that demonstrates how to create a wrapped key, tokenize content, and re-identify tokenized content.

• Learn more about de-identification methods that accept this wrapped key, and look through code samples.