Configuring an S3 Bucket Key at the object level using Batch Operations, REST API, AWS SDKs, or AWS CLI - Amazon Simple Storage Service

Configuring an S3 Bucket Key at the object level using Batch Operations, REST API, AWS SDKs, or AWS CLI

When you perform a PUT or COPY operation using the REST API, AWS SDKs, or AWS CLI, you can enable or disable an S3 Bucket Key at the object level. S3 Bucket Keys reduce the cost of server-side encryption using AWS Key Management Service (AWS KMS) (SSE-KMS) by decreasing request traffic from Amazon S3 to AWS KMS. For more information, see Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys.

When you configure an S3 Bucket Key for an object using a PUT or COPY operation, Amazon S3 only updates the settings for that object. The S3 Bucket Key settings for the destination bucket do not change. If you don't specify an S3 Bucket Key for your object, Amazon S3 applies the S3 Bucket Key settings for the destination bucket to the object.

Prerequisite:

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

Amazon S3 Batch Operations

To encrypt your existing Amazon S3 objects, you can use Amazon S3 Batch Operations. You provide S3 Batch Operations with a list of objects to operate on, and Batch Operations calls the respective API to perform the specified operation. You can use the S3 Batch Operations Copy operation to copy existing unencrypted objects and write them back to the same bucket as encrypted objects. A single Batch Operations job can perform the specified operation on billions of objects. For more information, see Performing large-scale batch operations on Amazon S3 objects and Encrypting objects with Amazon S3 Batch Operations.

Using the REST API

When you use SSE-KMS, you can enable an S3 Bucket Key for an object using the following APIs:

  • PutObject – When you upload an object, you can specify the x-amz-server-side-encryption-bucket-key-enabled request header to enable or disable an S3 Bucket Key at the object level.

  • CopyObject – When you copy an object and configure SSE-KMS, you can specify the x-amz-server-side-encryption-bucket-key-enabled request header to enable or disable an S3 Bucket Key for your object.

  • PostObject – When you use a POST operation to upload an object and configure SSE-KMS, you can use the x-amz-server-side-encryption-bucket-key-enabled form field to enable or disable an S3 Bucket Key for your object.

  • CreateMutlipartUpload – When you upload large objects using the multipart upload API and configure SSE-KMS, you can use the x-amz-server-side-encryption-bucket-key-enabled request header to enable or disable an S3 Bucket Key for your object.

To enable an S3 Bucket Key at the object level, include the x-amz-server-side-encryption-bucket-key-enabled request header. For more information about SSE-KMS and the REST API, see Using the REST API.

Using the AWS SDK Java (PutObject)

You can use the following example to configure an S3 Bucket Key at the object level using the AWS SDK for Java.

Java
AmazonS3 s3client = AmazonS3ClientBuilder.standard()     .withRegion(Regions.DEFAULT_REGION)     .build(); String bucketName = "bucket name"; String keyName = "key name for object"; String contents = "file contents"; PutObjectRequest putObjectRequest = new PutObjectRequest(bucketName, keyName, contents)     .withBucketKeyEnabled(true);      s3client.putObject(putObjectRequest);

Using the AWS CLI (PutObject)

You can use the following AWS CLI example to configure an S3 Bucket Key at the object level as part of a PutObject request.

aws s3api put-object --bucket <bucket name> --key <object key name> --server-side-encryption aws:kms --bucket-key-enabled --body <filepath>