Using Customer-Managed Encryption Keys

This page describes how to use a Cloud Key Management Service encryption key with Cloud Storage, including getting started with the feature, using default keys on buckets, and adding keys to individual objects. The Cloud KMS encryption key is a customer-managed encryption key, which is created by Cloud KMS and managed by you. For details about this feature, see Customer-Managed Encryption Keys. For other encryption options in Cloud Storage, see Data Encryption Options.

Prerequisites

Console

Before using this feature with the Google Cloud Platform Console, you should:

  1. Enable the Cloud KMS API for the project that will store your encryption keys.

    Enable the API

  2. Have sufficient permission on the project that will store your encryption keys:

  3. Have sufficient permission to work with objects in your Cloud Storage bucket:

    • If you own the project that contains the bucket, you most likely have the necessary permission.

    • If you use IAM, you should have storage.objects.create permission to write objects to the bucket and storage.objects.get permission to read objects from the bucket. See Using IAM Permissions for instructions on how to do this.

    • If you use ACLs, you should have bucket-scoped WRITER permission to write objects to the bucket and object-scoped READER permission to read objects from the bucket. See Setting ACLs for instructions on how to do this.

  4. Have a Cloud KMS key ring, and have at least one key within the key ring.

  5. Get the email address of the service account associated with the project that contains your Cloud Storage bucket.

    To find the email address of the service account, enter your project name in the get serviceAccount method of the API Explorer and click Authorize and execute.

    The result of this query should look similar to:

    {
    "email_address": "[PROJECT_ID]@gs-project-accounts.iam.gserviceaccount.com",
    "kind": "storage#serviceAccount"
    }

gsutil

Before using this feature with the gsutil command-line tool, you should:

  1. Enable the Cloud KMS API for the project that will store your encryption keys.

    Enable the API

  2. Have sufficient permission on the project that will store your encryption keys:

  3. Have sufficient permission to work with objects in your Cloud Storage bucket:

    • If you own the project that contains the bucket, you most likely have the necessary permission.

    • If you use IAM, you should have storage.objects.create permission to write objects to the bucket and storage.objects.get permission to read objects from the bucket. See Using IAM Permissions for instructions on how to do this.

    • If you use ACLs, you should have bucket-scoped WRITER permission to write objects to the bucket and object-scoped READER permission to read objects from the bucket. See Setting ACLs for instructions on how to do this.

  4. Have a Cloud KMS key ring, and have at least one key within the key ring.

REST APIs

Before using this feature with the JSON API or XML API, you should:

  1. Enable the Cloud KMS API for the project that will store your encryption keys.

    Enable the API

  2. Have sufficient permission on the project that will store your encryption keys:

  3. Have sufficient permission to work with objects in your Cloud Storage bucket:

    • If you own the project that contains the bucket, you most likely have the necessary permission.

    • If you use IAM, you should have storage.objects.create permission to write objects to the bucket and storage.objects.get permission to read objects from the bucket. See Using IAM Permissions for instructions on how to do this.

    • If you use ACLs, you should have bucket-scoped WRITER permission to write objects to the bucket and object-scoped READER permission to read objects from the bucket. See Setting ACLs for instructions on how to do this.

  4. Have a Cloud KMS key ring, and have at least one key within the key ring.

  5. Get the email address of the service account associated with the project that contains your Cloud Storage bucket.

    To find the email address of the service account, query the following URL, replacing [PROJECT_ID] with the name of the project that contains your bucket:

    https://www.googleapis.com/storage/v1/projects/[PROJECT_ID]/serviceAccount

    The result of this query should look similar to:

    {
    "email_address": "[PROJECT_ID]@gs-project-accounts.iam.gserviceaccount.com",
    "kind": "storage#serviceAccount"
    }

Assigning a Cloud KMS key to a service account

In order to use customer-managed encryption keys, you must give your Cloud Storage service account permission to use your Cloud KMS key.

Console

  1. Open the IAM & Admin browser in the Google Cloud Platform Console.
    Open the IAM & Admin browser
  2. Select the project to which you want to add a member.

  3. In the project permissions page, click the Add button.

  4. In the New members dialog, specify the email address of the Cloud Storage service account you are granting access.

  5. In the Select a role drop down, select Cloud KMS CrytoKey Encrypter/Decrypter, found in the Cloud KMS subsection.

  6. Click Save.

gsutil

Use the gsutil kms authorize command to give the service account associated with your bucket permission to encrypt and decrypt objects using your Cloud KMS key, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil kms authorize -p [PROJECT_STORING_OBJECTS] -k [KEY_RESOURCE]

Where [KEY_RESOURCE] has the format:

projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

If you want to remove the granted permission, you need to use either the gcloud command-line tool or the Google Cloud Platform Console.

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    {
      "policy": {
        "bindings": {
          "role": "roles/cloudkms.cryptoKeyEncrypterDecrypter",
          "members": "[SERVICE_ACCOUNT_EMAIL_ADDRESS]"
        },
      }
    }
  3. Use cURL to call the Cloud KMS API with a POST setIamPolicy request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X POST --data-binary @[JSON_FILE_NAME].json \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    -H "Content-Type: application/json" \
    "https://cloudkms.googleapis.com/v1/[KEY_RESOURCE]:setIamPolicy"

    Where [KEY_RESOURCE] has the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

XML API

The XML API cannot be used to assign a Cloud KMS to a service account. Use one of the other Cloud Storage tools, such as gsutil, instead.

Using default encryption keys

Adding or changing the default key for a bucket

To add or change the Cloud KMS key that is used by default when objects are written to a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser
  2. In the list of buckets, click on the desired bucket.

  3. Click the Edit button at the top of the page.

  4. In the edit page, if the bucket isn't currently using a Cloud KMS, use the Encryption drop-down to select Customer-managed key.

  5. In the Encryption key drop-down, select one of the available keys.

  6. Click Save.

gsutil

Use the gsutil kms encryption command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil kms encryption -k [KEY_RESOURCE] gs://[BUCKET_NAME]

Where [KEY_RESOURCE] has the format:

projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

If successful, the response looks like:

Authorized service account [SERVICE_ACCOUNT_NAME] to use key:
[KEY_RESOURCE]

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    {
      "encryption": {
        "defaultKmsKeyName": "[KEY_RESOURCE]"
      }
    }

    Where [KEY_RESOURCE] has the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]
  3. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    -H "Content-Type: application/json" \
    "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=encryption"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .xml file that contains the following information, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    <EncryptionConfiguration>
      <DefaultKmsKeyName>[KEY_RESOURCE]</DefaultKmsKeyName>
    </EncryptionConfiguration>

    Where [KEY_RESOURCE] has the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]
  3. Use cURL to call the XML API with a PUT Bucket request and encryption query string paratmeter, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://storage.googleapis.com/[BUCKET_NAME]?encryptionConfig"

Viewing the default key for a bucket

To view the Cloud KMS key that is currently set as default for your bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser
  2. In the list of buckets, click on the desired bucket.

  3. Click the Edit button at the top of the page.

  4. The current default key for your bucket is selected in the Encryption key field.

gsutil

Use the gsutil kms encryption command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil kms encryption gs://[BUCKET_NAME]

If successful, the response looks like:

Default encryption key for gs://[BUCKET_NAME]:
[KEY_RESOURCE]

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API with a GET Bucket request that includes the desired fields, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=encryption"

    The response looks like the following example:

    {
      "encryption" : {
         "defaultKmsKeyName": "[KEY_RESOURCE]"
       },
    }

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API with a GET Bucket request that includes the encryption query parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X GET -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://storage.googleapis.com/[BUCKET_NAME]?encryptionConfig"

    The response looks like the following example:

    <EncryptionConfiguration>
      <DefaultKmsKeyName>[KEY_RESOURCE]</DefaultKmsKeyName>
    </EncryptionConfiguration>

Removing the default key from a bucket

To remove any default Cloud KMS key set on a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser
  2. In the list of buckets, click on the desired bucket.

  3. Click the Edit button at the top of the page.

  4. In the edit page, use the Encryption drop-down to select Google-managed key.

  5. Click Save.

gsutil

Use the gsutil kms encryption command, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil kms encryption -d gs://[BUCKET_NAME]

If successful, the response looks like:

Clearing default encryption key for gs://[BUCKET_NAME]...

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .json file that contains the following information:

    {
      "encryption": {
        "defaultKmsKeyName": null
      }
    }
  3. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    -H "Content-Type: application/json" \
    "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=encryption"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Create a .xml file that contains the following information:

    <EncryptionConfiguration></EncryptionConfiguration>
  3. Use cURL to call the XML API with a PUT Bucket request and encryption query string paratmeter, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://storage.googleapis.com/[BUCKET_NAME]?encryptionConfig"

Encrypting an object with a Cloud KMS key

You can encrypt an individual object with a Cloud KMS key. This is useful if you want to use a different key from the default key set on the bucket, or if you don't have a default key set on the bucket.

Console

The GCP Console cannot be used to encrypt individual objects. Use gsutil instead.

gsutil

  1. Specify a key in the .boto configuration file for gsutil, in the encryption_key attribute under the [GSUtil] section.

    Your key should have the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]
  2. Write an object to the bucket as you normally would, for example with gsutil cp or gsutil rewrite.

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Add the object's data to the request body.

  3. Use cURL to call the JSON API with a POST Object request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X POST --data-binary @[OBJECT] \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    -H "Content-Type: [OBJECT_CONTENT_TYPE]" \
    "https://www.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/o?uploadType=media&name=[OBJECT_NAME]&kmsKeyName=[KEY_RESOURCE]"

    Where [KEY_RESOURCE] has the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Add the object's data to the request body.

  3. Use cURL to call the JSON API with a PUT Object request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X PUT --data-binary @[OBJECT] \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    -H "Content-Type: [OBJECT_CONTENT_TYPE]" \
    -H "x-goog-encryption-kms-key-name: [KEY_RESOURCE]" \
    "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]"

    Where [KEY_RESOURCE] has the format:

    projects/[PROJECT_STORING_KEYS]/locations/[LOCATION]/keyRings/[KEY_RING_NAME]/cryptoKeys/[KEY_NAME]

Identifying the key used to encrypt an object

To find the name of the Cloud KMS key that was used to encrypt an object:

Console

The GCP Console cannot be used to check the Cloud KMS key that encrypts a specific object. Use gsutil instead.

gsutil

Use the gsutil ls command with the -L flag, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil ls -L gs://[BUCKET_NAME]/[OBJECT_NAME]

If successful, the response contains the key name:

gs://[BUCKET_NAME]/[OBJECT_NAME]:
...
KMS key: [KEY_RESOURCE]
...

REST APIs

JSON API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the JSON API with a GET Object request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X GET \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?fields=kmsKeyName"

XML API

  1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
  2. Use cURL to call the XML API with a GET Object request, replacing [VALUES_IN_BRACKETS] with the appropriate values:

    curl -X GET \
    -H "Authorization: Bearer [OAUTH2_TOKEN]" \
    "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]?encryption"

Decrypting an object

Decrypting an object encrypted with a customer-managed encryption key is performed automatically as long as the relevant service account has access to the key. For more information, see Service accounts with customer-managed encryption keys.

What's next

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Cloud Storage Documentation