Specifying server-side encryption with Amazon KMS (SSE-KMS)
All Amazon S3 buckets have encryption configured by default, and all new objects that are uploaded
to an S3 bucket are automatically encrypted at rest. Server-side encryption with Amazon S3 managed keys (SSE-S3) is the default encryption
configuration for every bucket in Amazon S3. To use a different type of encryption, you can either specify the type of server-side encryption
to use in your S3 PUT
requests, or you can set the default encryption configuration in the destination bucket.
If you want to specify a different encryption type in your PUT
requests, you can use server-side encryption with
Amazon Key Management Service (Amazon KMS) keys (SSE-KMS), dual-layer server-side encryption with Amazon KMS keys (DSSE-KMS), or server-side encryption with
customer-provided keys (SSE-C). If you want to set a different default encryption configuration in the destination bucket, you can use
SSE-KMS or DSSE-KMS.
You can apply encryption when you are either uploading a new object or copying an existing object.
You can specify SSE-KMS by using the Amazon S3 console, REST API operations, Amazon SDKs, and the Amazon Command Line Interface (Amazon CLI). For more information, see the following topics.
Note
You can use multi-Region Amazon KMS keys in Amazon S3. However, Amazon S3 currently treats multi-Region keys as though they were single-Region keys, and does not use the multi-Region features of the key. For more information, see Using multi-Region keys in the Amazon Key Management Service Developer Guide.
Note
If you want to use a KMS key that's owned by a different account, you must have permission to use the key. For more information about cross-account permissions for KMS keys, see Creating KMS keys that other accounts can use in the Amazon Key Management Service Developer Guide.
This topic describes how to set or change the type of encryption of an object to use server-side encryption with Amazon Key Management Service (Amazon KMS) keys (SSE-KMS) by using the Amazon S3 console.
Note
-
You can change an object's encryption if your object is less than 5 GB. If your object is greater than 5 GB, you must use the Amazon CLI or Amazon SDKs to change an object's encryption.
-
For a list of additional permissions required to change an object's encryption, see Required permissions for Amazon S3 API operations. For example policies that grant this permission, see Identity-based policy examples for Amazon S3.
If you change an object's encryption, a new object is created to replace the old one. If S3 Versioning is enabled, a new version of the object is created, and the existing object becomes an older version. The role that changes the property also becomes the owner of the new object (or object version).
To add or change encryption for an object
Sign in to the Amazon Web Services Management Console and open the Amazon S3 console at https://console.amazonaws.cn/s3/
. -
In the navigation pane, choose Buckets, and then choose the General purpose buckets tab. Navigate to the Amazon S3 bucket or folder that contains the objects you want to change.
-
Select the check box for the objects you want to change.
-
On the Actions menu, choose Edit server-side encryption from the list of options that appears.
Scroll to the Server-side encryption section.
Under Encryption settings, choose Use bucket settings for default encryption or Override bucket settings for default encryption.
Important
If you use the SSE-KMS option for your default encryption configuration, you are subject to the requests per second (RPS) quotas of Amazon KMS. For more information about Amazon KMS quotas and how to request a quota increase, see Quotas in the Amazon Key Management Service Developer Guide.
-
If you chose Override bucket settings for default encryption, configure the following encryption settings.
-
Under Encryption type, choose Server-side encryption with Amazon Key Management Service keys (SSE-KMS).
-
Under Amazon KMS key, do one of the following to choose your KMS key:
-
To choose from a list of available KMS keys, choose Choose from your Amazon KMS keys, and then choose your KMS key from the list of available keys.
Both the Amazon managed key (
aws/s3
) and your customer managed keys appear in this list. For more information about customer managed keys, see Customer keys and Amazon keys in the Amazon Key Management Service Developer Guide. -
To enter the KMS key ARN, choose Enter Amazon KMS key ARN, and then enter your KMS key ARN in the field that appears.
-
To create a new customer managed key in the Amazon KMS console, choose Create a KMS key.
For more information about creating an Amazon KMS key, see Creating keys in the Amazon Key Management Service Developer Guide.
Important
You can use only KMS keys that are available in the same Amazon Web Services Region as the bucket. The Amazon S3 console lists only the first 100 KMS keys in the same Region as the bucket. To use a KMS key that is not listed, you must enter your KMS key ARN. If you want to use a KMS key that is owned by a different account, you must first have permission to use the key and then you must enter the KMS key ARN.
Amazon S3 supports only symmetric encryption KMS keys, and not asymmetric KMS keys. For more information, see Identifying symmetric and asymmetric KMS keys in the Amazon Key Management Service Developer Guide.
-
-
-
Under Additional copy settings, choose whether you want to Copy source settings, Don’t specify settings, or Specify settings. Copy source settings is the default option. If you only want to copy the object without the source settings attributes, choose Don’t specify settings. Choose Specify settings to specify settings for storage class, ACLs, object tags, metadata, server-side encryption, and additional checksums.
-
Choose Save changes.
Note
This action applies encryption to all specified objects. When you're encrypting folders, wait for the save operation to finish before adding new objects to the folder.
When you create an object—that is, when you upload a new object or copy an
existing object—you can specify the use of server-side encryption with Amazon KMS keys
(SSE-KMS) to encrypt your data. To do this, add the
x-amz-server-side-encryption
header to the request. Set the value of the
header to the encryption algorithm aws:kms
. Amazon S3 confirms that your object is
stored using SSE-KMS by returning the response header
x-amz-server-side-encryption
.
If you specify the x-amz-server-side-encryption
header with a value of
aws:kms
, you can also use the following request headers:
-
x-amz-server-side-encryption-aws-kms-key-id
-
x-amz-server-side-encryption-context
-
x-amz-server-side-encryption-bucket-key-enabled
Topics
Amazon S3 REST API operations that support SSE-KMS
The following REST API operations accept the
x-amz-server-side-encryption
,
x-amz-server-side-encryption-aws-kms-key-id
, and
x-amz-server-side-encryption-context
request headers.
-
PutObject – When you upload data by using the
PUT
API operation, you can specify these request headers. -
CopyObject – When you copy an object, you have both a source object and a target object. When you pass SSE-KMS headers with the
CopyObject
operation, they're applied only to the target object. When you're copying an existing object, regardless of whether the source object is encrypted or not, the destination object isn't encrypted unless you explicitly request server-side encryption. -
POST Object – When you use a
POST
operation to upload an object, instead of the request headers, you provide the same information in the form fields. -
CreateMultipartUpload – When you upload large objects by using the multipart upload API operation, you can specify these headers. You specify these headers in the
CreateMultipartUpload
request.
The response headers of the following REST API operations return the
x-amz-server-side-encryption
header when an object is stored by using
server-side encryption.
Important
-
All
GET
andPUT
requests for an object protected by Amazon KMS fail if you don't make these requests by using Secure Sockets Layer (SSL), Transport Layer Security (TLS), or Signature Version 4. -
If your object uses SSE-KMS, don't send encryption request headers for
GET
requests andHEAD
requests, or you’ll get anHTTP 400 BadRequest
error.
Encryption context
(x-amz-server-side-encryption-context
)
If you specify x-amz-server-side-encryption:aws:kms
, the Amazon S3 API
supports an encryption context with the x-amz-server-side-encryption-context
header. An encryption context is a set of key-value pairs that contain additional
contextual information about the data.
Amazon S3 automatically uses the object or bucket Amazon Resource Name (ARN) as the
encryption context pair. If you use SSE-KMS without enabling an S3 Bucket Key, you use the
object ARN as your encryption context; for example,
arn:aws:s3:::
. However, if you use
SSE-KMS and enable an S3 Bucket Key, you use the bucket ARN for your encryption context;
for example, object_ARN
arn:aws:s3:::
. bucket_ARN
You can optionally provide an additional encryption context pair by using the
x-amz-server-side-encryption-context
header. However, because the
encryption context isn't encrypted, make sure it doesn't include sensitive information.
Amazon S3 stores this additional key pair alongside the default encryption context.
For information about the encryption context in Amazon S3, see Encryption context. For general information about the encryption context, see Amazon Key Management Service Concepts - Encryption context in the Amazon Key Management Service Developer Guide.
Amazon KMS key ID
(x-amz-server-side-encryption-aws-kms-key-id
)
You can use the x-amz-server-side-encryption-aws-kms-key-id
header to
specify the ID of the customer managed key that's used to protect the data. If you specify the
x-amz-server-side-encryption:aws:kms
header but don't provide the
x-amz-server-side-encryption-aws-kms-key-id
header, Amazon S3 uses the
Amazon managed key (aws/s3
) to protect the data. If you want to use a
customer managed key, you must provide the x-amz-server-side-encryption-aws-kms-key-id
header of the customer managed key.
Important
When you use an Amazon KMS key for server-side encryption in Amazon S3, you must choose a symmetric encryption KMS key. Amazon S3 supports only symmetric encryption KMS keys. For more information about these keys, see Symmetric encryption KMS keys in the Amazon Key Management Service Developer Guide.
S3 Bucket Keys
(x-amz-server-side-encryption-aws-bucket-key-enabled
)
You can use the x-amz-server-side-encryption-aws-bucket-key-enabled
request header to enable or disable an S3 Bucket Key at the object level. S3 Bucket Keys reduce
your Amazon KMS request costs by decreasing the request traffic from Amazon S3 to Amazon KMS. For more
information, see Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys.
If you specify the x-amz-server-side-encryption:aws:kms
header but don't
provide the x-amz-server-side-encryption-aws-bucket-key-enabled
header, your
object uses the S3 Bucket Key settings for the destination bucket to encrypt your object.
For more information, see Configuring an S3 Bucket Key at the object
level .
To use the following example Amazon CLI commands, replace the
with your own information.user input
placeholders
When you upload a new object or copy an existing object, you can specify the use of
server-side encryption with Amazon KMS keys to encrypt your data. To do this, add the
--server-side-encryption aws:kms
header to the request. Use the
--ssekms-key-id
to add your customer
managed Amazon KMS key that you created. If you specify example-key-id
--server-side-encryption
aws:kms
, but don't provide an Amazon KMS key ID, Amazon S3 will use an Amazon managed
key.
aws s3api put-object --bucket
amzn-s3-demo-bucket
--keyexample-object-key
--server-side-encryption aws:kms --ssekms-key-idexample-key-id
--bodyfilepath
You can additionally enable or disable Amazon S3 Bucket Keys on your PUT or COPY operations
by adding --bucket-key-enabled
or --no-bucket-key-enabled
. Amazon S3 Bucket Keys can reduce your Amazon KMS request costs by decreasing the request traffic from
Amazon S3 to Amazon KMS. For more information, see Reducing the cost of SSE-KMS with Amazon S3
Bucket Keys.
aws s3api put-object --bucket
amzn-s3-demo-bucket
--keyexample-object-key
--server-side-encryption aws:kms --bucket-key-enabled --bodyfilepath
You can encrypt an unencrypted object to use SSE-KMS by copying the object back in place.
aws s3api copy-object --bucket
amzn-s3-demo-bucket
--keyexample-object-key
--bodyfilepath
--bucketamzn-s3-demo-bucket
--keyexample-object-key
--sse aws:kms --sse-kms-key-idexample-key-id
--bodyfilepath
When using Amazon SDKs, you can request Amazon S3 to use Amazon KMS keys for server-side
encryption. The following examples show how to use SSE-KMS with the Amazon SDKs for Java and
.NET. For information about other SDKs, see Sample code
and libraries
Important
When you use an Amazon KMS key for server-side encryption in Amazon S3, you must choose a symmetric encryption KMS key. Amazon S3 supports only symmetric encryption KMS keys. For more information about these keys, see Symmetric encryption KMS keys in the Amazon Key Management Service Developer Guide.
CopyObject
operation
When copying objects, you add the same request properties
(ServerSideEncryptionMethod
and
ServerSideEncryptionKeyManagementServiceKeyId
) to request Amazon S3 to use an
Amazon KMS key. For more information about copying objects, see Copying, moving, and renaming objects.