Creating 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 (DLP) API.

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.

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. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Cloud DLP and Cloud KMS APIs.

    Enable the APIs

  4. Create a service account:

    1. In the Cloud Console, go to the Create service account page.

      Go to Create service account
    2. Select a project.
    3. In the Service account name field, enter a name. The Cloud Console fills in the Service account ID field based on this name.

      In the Service account description field, enter a description. For example, Service account for quickstart.

    4. Click Create and continue.
    5. Click the Select a role field.

      Under Quick access, click Basic, then click Owner.

    6. Click Continue.
    7. Click Done to finish creating the service account.

      Do not close your browser window. You will use it in the next step.

  5. Create a service account key:

    1. In the Cloud Console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, then click Create new key.
    4. Click Create. A JSON key file is downloaded to your computer.
    5. Click Close.
  6. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your service account key. This variable only applies to your current shell session, so if you open a new session, set the variable again.

  7. Install and initialize the Cloud SDK.

Step 1: Create a key ring and a key

Before you start this procedure, decide where you want Cloud DLP 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 Cloud DLP requests. Otherwise, the Cloud DLP requests will fail.

You can find a list of supported locations in Cloud DLP 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.

  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=
    

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:

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