Enforce or restrict the encryption types for a bucket

This document describes how to configure which encryption methods are allowed or restricted for new objects in a Cloud Storage bucket. You can configure a bucket to enforce or restrict the use of standard encryption (Google default encryption), customer-managed encryption keys (CMEK), or customer-supplied encryption keys (CSEK) for any new objects that are created within the bucket.

For example, to help protect against ransomware attacks, you can require that all new objects are encrypted with either standard encryption or CMEK, and restrict the use of customer-supplied encryption keys.

For more information about the encryption methods that are available, see Data encryption options.

Cloud Storage enforces the encryption configuration for all actions that create a new object, such as uploading an object, copying an object, composing objects, and restoring a soft-deleted object.

Before you begin

To get the permissions that you need to configure encryption enforcement for a bucket, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on bucket. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to configure encryption enforcement for a bucket. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to configure encryption enforcement for a bucket:

Set the configuration when creating a new bucket: storage.buckets.create
Update the configuration for an existing bucket: storage.buckets.update

You might also be able to get these permissions with custom roles or other predefined roles.

Create a bucket that enforces encryption types

You can specify the encryption methods that are allowed or restricted for the objects in a bucket when you create a new bucket.

If you set a default Cloud KMS key for the bucket, then you must also allow encryption using CMEKs or customer-supplied encryption keys.

gcloud

Create a JSON file that contains the following information:
```
{
  "gmekEnforcement": {"restrictionMode": "STANDARD_ENCRYPTION_RESTRICTION_MODE"},
  "cmekEnforcement": {"restrictionMode": "CMEK_RESTRICTION_MODE"},
  "csekEnforcement": {"restrictionMode": "CSEK_RESTRICTION_MODE"}
}
```
Replace the following:
- STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use standard encryption.
  - FullyRestricted: new objects can't use standard encryption.
- CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use CMEKs.
  - FullyRestricted: new objects can't use CMEKs.
- CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use customer-supplied encryption keys.
  - FullyRestricted: new objects can't use customer-supplied encryption keys.
You must allow at least one encryption type. If you omit the enforcement configuration for a specific encryption type, then that encryption type is allowed by default.
Use the gcloud storage buckets create command with the --encryption-enforcement-file flag:
```
gcloud storage buckets create gs://BUCKET_NAME \
  --encryption-enforcement-file=ENCRYPTION_ENFORCEMENT_FILE
```
Replace the following:
- BUCKET_NAME: the name of the bucket.
- ENCRYPTION_ENFORCEMENT_FILE: the path to the JSON file that you created in the previous step.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create a JSON file that contains the settings for the bucket. For a complete list of settings, see the Buckets: Insert documentation. The following settings define only the bucket name and encryption:
```
{
  "name": "BUCKET_NAME",
  "encryption": {
    "googleManagedEncryptionEnforcementConfig": {
      "restrictionMode": "STANDARD_ENCRYPTION_RESTRICTION_MODE"
    },
    "customerManagedEncryptionEnforcementConfig": {
      "restrictionMode": "CMEK_RESTRICTION_MODE"
    },
    "customerSuppliedEncryptionEnforcementConfig": {
      "restrictionMode": "CSEK_RESTRICTION_MODE"
    }
  }
}
```
Replace the following:
- BUCKET_NAME: The name of the bucket.
- STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use standard encryption.
  - FullyRestricted: new objects can't use standard encryption.
- CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use CMEKs.
  - FullyRestricted: new objects can't use CMEKs.
- CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use customer-supplied encryption keys.
  - FullyRestricted: new objects can't use customer-supplied encryption keys.
You must allow at least one encryption type. If you omit the enforcement configuration for a specific encryption type, then that encryption type is allowed by default.

Use cURL to call the JSON API with a POST Bucket request:

curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b?project=PROJECT_ID"

Replace the following:

JSON_FILE_NAME: the path to the JSON file that you created in the previous step.
PROJECT_ID: the ID or number of the project for your bucket.

XML API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create an XML file that contains the settings for the bucket. For a complete list of settings, see the XML: Create a bucket documentation. The following settings define only the encryption enforcement:
```
<CreateBucketConfiguration>
  <EncryptionConfiguration>
    <GoogleManagedEncryptionEnforcement>
      <RestrictionMode>STANDARD_ENCRYPTION_RESTRICTION_MODE</RestrictionMode>
    </GoogleManagedEncryptionEnforcement>
    <CustomerManagedEncryptionEnforcement>
      <RestrictionMode>CMEK_RESTRICTION_MODE</RestrictionMode>
    </CustomerManagedEncryptionEnforcement>
    <CustomerSuppliedEncryptionEnforcement>
      <RestrictionMode>CSEK_RESTRICTION_MODE</RestrictionMode>
    </CustomerSuppliedEncryptionEnforcement>
  </EncryptionConfiguration>
</CreateBucketConfiguration>
```
Replace the following:
- STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use standard encryption.
  - FullyRestricted: new objects can't use standard encryption.
- CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use CMEKs.
  - FullyRestricted: new objects can't use CMEKs.
- CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use customer-supplied encryption keys.
  - FullyRestricted: new objects can't use customer-supplied encryption keys.
You must allow at least one encryption type. If you omit the enforcement configuration for a specific encryption type, then that encryption type is allowed by default.
Use cURL to call the XML API with a PUT Bucket request:
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-project-id: PROJECT_ID" \
  "https://storage.googleapis.com/BUCKET_NAME"
```
Replace the following:
- XML_FILE_NAME: the path to the XML file that you created in the previous step.
- PROJECT_ID: the ID or number of the project for your bucket.
- BUCKET_NAME: the name of the bucket.

Update the encryption types that are allowed for a bucket

To update which encryption methods are allowed for new objects in an existing bucket, complete the following steps.

If the bucket has a default KMS key set, then you can't restrict both CMEK and customer-supplied encryption keys because that would prevent new objects from being created. Either allow CMEK or CSEK on such a bucket, or remove the default Cloud KMS key from the bucket.

gcloud

Create a JSON file that contains the following information:
```
{
  "gmekEnforcement": {"restrictionMode": "STANDARD_ENCRYPTION_RESTRICTION_MODE"},
  "cmekEnforcement": {"restrictionMode": "CMEK_RESTRICTION_MODE"},
  "csekEnforcement": {"restrictionMode": "CSEK_RESTRICTION_MODE"}
}
```
Replace the following:
- STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use standard encryption.
  - FullyRestricted: new objects can't use standard encryption.
- CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use CMEKs.
  - FullyRestricted: new objects can't use CMEKs.
- CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:
  - NotRestricted: new objects can use customer-supplied encryption keys.
  - FullyRestricted: new objects can't use customer-supplied encryption keys.
You must allow at least one encryption type. If you omit an encryption type, the existing configuration is retained.
Use the gcloud storage buckets update command with the --encryption-enforcement-file flag:
```
gcloud storage buckets update gs://BUCKET_NAME \
  --encryption-enforcement-file=ENCRYPTION_ENFORCEMENT_FILE
```
Replace the following:
- BUCKET_NAME: the name of the bucket.
- ENCRYPTION_ENFORCEMENT_FILE: the path to the JSON file that you created in the previous step.
It might take up to two minutes for the updated configuration to take effect.

REST APIs

JSON API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create a JSON file that contains the following information:

{
  "encryption": {
    "googleManagedEncryptionEnforcementConfig": {
      "restrictionMode": "STANDARD_ENCRYPTION_RESTRICTION_MODE"
    },
    "customerManagedEncryptionEnforcementConfig": {
      "restrictionMode": "CMEK_RESTRICTION_MODE"
    },
    "customerSuppliedEncryptionEnforcementConfig": {
      "restrictionMode": "CSEK_RESTRICTION_MODE"
    }
  }
}

Replace the following:

STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:
- NotRestricted: new objects can use standard encryption.
- FullyRestricted: new objects can't use standard encryption.
CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:
- NotRestricted: new objects can use CMEKs.
- FullyRestricted: new objects can't use CMEKs.
CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:
- NotRestricted: new objects can use customer-supplied encryption keys.
- FullyRestricted: new objects can't use customer-supplied encryption keys.

You must allow at least one encryption type. If you omit an encryption type, the existing configuration is retained.

Use cURL to call the JSON API with a PATCH Bucket request:
```
curl -X PATCH --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?fields=encryption"
```
Replace the following:
- JSON_FILE_NAME: the path to the JSON file that you created in the previous step.
- BUCKET_NAME: the name of the bucket.
It might take up to two minutes for the updated configuration to take effect.

XML API

Have gcloud CLI installed and initialized , which lets you generate an access token for the Authorization header.

Create an XML file that contains the encryption settings for the bucket. The following settings define only the encryption enforcement configuration.

Caution: The contents of the request body replace any existing settings, so include all values that you want to apply. For a complete list of encryption settings, see the EncryptionConfiguration request body elements.

<EncryptionConfiguration> <GoogleManagedEncryptionEnforcement> <RestrictionMode>STANDARD_ENCRYPTION_RESTRICTION_MODE</RestrictionMode> </GoogleManagedEncryptionEnforcement> <CustomerManagedEncryptionEnforcement> <RestrictionMode>CMEK_RESTRICTION_MODE</RestrictionMode> </CustomerManagedEncryptionEnforcement> <CustomerSuppliedEncryptionEnforcement> <RestrictionMode>CSEK_RESTRICTION_MODE</RestrictionMode> </CustomerSuppliedEncryptionEnforcement> </EncryptionConfiguration>

Replace the following:

STANDARD_ENCRYPTION_RESTRICTION_MODE: Whether encryption using standard encryption (Google default encryption) is allowed when creating objects in this bucket. The following values are supported:

NotRestricted: new objects can use standard encryption.

FullyRestricted: new objects can't use standard encryption.

CMEK_RESTRICTION_MODE: Whether encryption using CMEKs is allowed when creating objects in this bucket. The following values are supported:

NotRestricted: new objects can use CMEKs.

FullyRestricted: new objects can't use CMEKs.

CSEK_RESTRICTION_MODE: Whether encryption using customer-supplied encryption keys is allowed when creating objects in this bucket. The following values are supported:

NotRestricted: new objects can use customer-supplied encryption keys.

FullyRestricted: new objects can't use customer-supplied encryption keys.

You must allow at least one encryption type.
Use cURL to call the XML API with a PUT Bucket request scoped to ?encryptionConfig:
```
curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/BUCKET_NAME?encryptionConfig"
```
Replace the following:
- XML_FILE_NAME: the path to the XML file that you created in the previous step.
- BUCKET_NAME: the name of the bucket.
It might take up to two minutes for the updated configuration to take effect.

View the encryption settings for a bucket

For steps to view which encryption methods are allowed for a bucket, see Get bucket metadata.

What's next

Set a default Cloud KMS key on a bucket.
Learn how to use custom constraints to enforce encryption types.

Enforce or restrict the encryption types for a bucket Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required permissions

Create a bucket that enforces encryption types

gcloud

REST APIs

JSON API

XML API

Update the encryption types that are allowed for a bucket

gcloud

REST APIs

JSON API

XML API

View the encryption settings for a bucket

What's next

Enforce or restrict the encryption types for a bucket