Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects - Amazon Simple Storage Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects

When you configure server-side encryption using SSE-KMS, you can configure your bucket to use an S3 Bucket Key for SSE-KMS on new objects. S3 Bucket Keys decrease the request traffic from Amazon S3 to Amazon Key Management Service (Amazon KMS) and reduce the cost of SSE-KMS. For more information, see Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys.

You can configure your bucket to use an S3 Bucket Key for SSE-KMS on new objects by using the Amazon S3 console, REST API, Amazon SDK, Amazon CLI, or Amazon CloudFormation. If you want to enable or disable an S3 Bucket Key for existing objects, you can use a COPY operation. For more information, see Configuring an S3 Bucket Key at the object level using Batch Operations, REST API, Amazon SDKs, or Amazon CLI and Using S3 Batch Operations to encrypt objects with S3 Bucket Keys.

When an S3 Bucket Key is enabled for the source or destination bucket, the encryption context will be the bucket Amazon Resource Name (ARN) and not the object ARN, for example, arn:aws:s3:::bucket_ARN. You need to update your IAM policies to use the bucket ARN for the encryption context. For more information, see Amazon S3 Bucket Keys and replication.

The following examples illustrate how an S3 Bucket Key works with replication. For more information, see Replicating objects created with server-side encryption (SSE-C, SSE-S3, SSE-KMS)

Prerequisite:

Before you configure your bucket to use an S3 Bucket Key, review Changes to note before enabling an S3 Bucket Key.

Topics

    In the S3 console, you can enable or disable an S3 Bucket Key for a new or existing bucket. Objects in the S3 console inherit their S3 Bucket Key setting from the bucket configuration. When you enable an S3 Bucket Key for your bucket, new objects that you upload to the bucket use an S3 Bucket Key for server-side encryption using Amazon KMS.

    Uploading, copying, or modifying objects in buckets that have an S3 Bucket Key enabled

    If you upload, modify, or copy an object in a bucket that has an S3 Bucket Key enabled, the S3 Bucket Key settings for that object might be updated to align with bucket configuration.

    If an object already has an S3 Bucket Key enabled, the S3 Bucket Key settings for that object don't change when you copy or modify the object. However, if you modify or copy an object that doesn’t have an S3 Bucket Key enabled, and the destination bucket has an S3 Bucket Key configuration, the object inherits the destination bucket's S3 Bucket Key settings. For example, if your source object doesn't have an S3 Bucket Key enabled but the destination bucket has S3 Bucket Key enabled, an S3 Bucket Key will be enabled for the object.

    To enable an S3 Bucket Key when you create a new bucket

    1. Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/.

    2. Choose Create bucket.

    3. Enter your bucket name, and choose your Amazon Web Services Region.

    4. Under Default encryption, choose Enable.

    5. Under Encryption type, choose Amazon Key Management Service key (SSE-KMS).

    6. Choose an Amazon KMS key:

      • Choose Amazon managed key (aws/s3).

      • Choose Customer managed key, and choose a symmetric encryption customer managed key in the same Region as your bucket.

    7. Under Bucket Key, choose Enable.

    8. Choose Create bucket.

      Amazon S3 creates your bucket with an S3 Bucket Key enabled. New objects that you upload to the bucket will use an S3 Bucket Key. To disable an S3 Bucket Key, follow the previous steps, and choose disable.

    To enable an S3 Bucket Key for an existing bucket

    1. Open the Amazon S3 console at https://console.amazonaws.cn/s3/.

    2. In the Buckets list, choose the bucket that you want to enable an S3 Bucket Key for.

    3. Choose Properties.

    4. Under Default encryption, choose Edit.

    5. Under Default encryption, choose Enable.

    6. Under Encryption type, choose Amazon Key Management Service key (SSE-KMS).

    7. Choose an Amazon KMS key:

      • Choose Amazon managed key (aws/s3).

      • Choose Customer managed key, and choose a symmetric encryption customer managed key in the same Region as your bucket.

    8. Under Bucket Key, choose Enable.

    9. Choose Save changes.

      Amazon S3 enables an S3 Bucket Key for new objects added to your bucket. Existing objects don't use the S3 Bucket Key. To disable an S3 Bucket Key, follow the previous steps, and choose Disable.

    You can use PutBucketEncryption to enable or disable an S3 Bucket Key for your bucket. To configure an S3 Bucket Key with PutBucketEncryption, specify the ServerSideEncryptionRule, which includes default encryption with server-side encryption using Amazon KMS key. You can also optionally use a customer managed key by specifying the KMS key ID for the customer managed key. 

    For more information and example syntax, see PutBucketEncryption.

    The following example enables default bucket encryption with SSE-KMS and an S3 Bucket Key using the Amazon SDK for Java.

    Java
    AmazonS3 s3client = AmazonS3ClientBuilder.standard()     .withRegion(Regions.DEFAULT_REGION)     .build();     ServerSideEncryptionByDefault serverSideEncryptionByDefault = new ServerSideEncryptionByDefault()     .withSSEAlgorithm(SSEAlgorithm.KMS); ServerSideEncryptionRule rule = new ServerSideEncryptionRule()     .withApplyServerSideEncryptionByDefault(serverSideEncryptionByDefault)     .withBucketKeyEnabled(true); ServerSideEncryptionConfiguration serverSideEncryptionConfiguration =     new ServerSideEncryptionConfiguration().withRules(Collections.singleton(rule)); SetBucketEncryptionRequest setBucketEncryptionRequest = new SetBucketEncryptionRequest()     .withServerSideEncryptionConfiguration(serverSideEncryptionConfiguration)     .withBucketName(bucketName);              s3client.setBucketEncryption(setBucketEncryptionRequest);

    The following example enables default bucket encryption with SSE-KMS and an S3 Bucket Key using the Amazon CLI.

    aws s3api put-bucket-encryption --bucket <bucket-name> --server-side-encryption-configuration '{         "Rules": [             {                 "ApplyServerSideEncryptionByDefault": {                     "SSEAlgorithm": "aws:kms",                     "KMSMasterKeyID": "<KMS-Key-ARN>"                 },                 "BucketKeyEnabled": true             }         ]     }'

    For more information about configuring an S3 Bucket Key using Amazon CloudFormation, see AWS::S3::Bucket ServerSideEncryptionRule in the Amazon CloudFormation User Guide.