Specifying dual-layer server-side encryption with AWS KMS keys (DSSE-KMS) - Amazon Simple Storage Service

Specifying dual-layer server-side encryption with AWS KMS keys (DSSE-KMS)

Important

Amazon S3 now applies server-side encryption with Amazon S3 managed keys (SSE-S3) as the base level of encryption for every bucket in Amazon S3. Starting January 5, 2023, all new object uploads to Amazon S3 are automatically encrypted at no additional cost and with no impact on performance. The automatic encryption status for S3 bucket default encryption configuration and for new object uploads is available in AWS CloudTrail logs, S3 Inventory, S3 Storage Lens, the Amazon S3 console, and as an additional Amazon S3 API response header in the AWS Command Line Interface and AWS SDKs. For more information, see Default encryption FAQ.

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 AWS Key Management Service (AWS KMS) keys (SSE-KMS), dual-layer server-side encryption with AWS 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 DSSE-KMS by using the Amazon S3 console, Amazon S3 REST API, and the AWS Command Line Interface (AWS CLI). For more information, see the following topics.

Note

You can use multi-Region AWS 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 AWS Key Management Service Developer Guide.

Note

If you want to use a KMS key that is 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 AWS Key Management Service Developer Guide.

This section describes how to set or change the type of encryption of an object to use dual-layer server-side encryption with AWS Key Management Service (AWS KMS) keys (DSSE-KMS) by using the Amazon S3 console.

Note
  • If you change an object's method of 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).

  • If you change the encryption type for an object that has user-defined tags, you must have the s3:GetObjectTagging permission. If you're changing the encryption type for an object that doesn't have user-defined tags but is over 16 MB in size, you must also have the s3:GetObjectTagging permission.

    If the destination bucket policy denies the s3:GetObjectTagging action, the encryption type for the object will be updated, but the user-defined tags will be removed from the object, and you will receive an error.

To add or change encryption for an object
  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. In the left navigation pane, choose Buckets.

  3. In the Buckets list, choose the name of the bucket that contains the object that you want to encrypt.

  4. In the Objects list, select the check box next to the object that you want to add or change encryption for.

    The object's details page appears, with several sections that display the properties for your object.

  5. Choose the Properties tab.

  6. Scroll down to the Default encryption section and choose Edit.

    The Edit default encryption page opens.

  7. Under Encryption type, choose Dual-layer server-side encryption with AWS Key Management Service keys (DSSE-KMS).

  8. Under AWS 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 AWS KMS keys, and then choose your KMS key from the list of available keys.

      Both the AWS managed key (aws/s3) and your customer managed keys appear in this list. For more information about customer managed keys, see Customer keys and AWS keys in the AWS Key Management Service Developer Guide.

    • To enter the KMS key ARN, choose Enter AWS KMS key ARN, and then enter your KMS key ARN in the field that appears.

    • To create a new customer managed key in the AWS KMS console, choose Create a KMS key.

      For more information about creating an AWS KMS key, see Creating keys in the AWS Key Management Service Developer Guide.

    Important

    You can use only KMS keys that are available in the same AWS 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 asymmetric KMS keys in the AWS Key Management Service Developer Guide.

  9. For Bucket Key, choose Disable. S3 Bucket Keys aren't supported for DSSE-KMS.

  10. 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 dual-layer server-side encryption with AWS KMS keys (DSSE-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:dsse. Amazon S3 confirms that your object is stored with DSSE-KMS encryption 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:dsse, you can also use the following request headers:

  • x-amz-server-side-encryption-aws-kms-key-id: SSEKMSKeyId

  • x-amz-server-side-encryption-context: SSEKMSEncryptionContext

Amazon S3 REST API operations that support DSSE-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 DSSE-KMS headers with the CopyObject operation, they are 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 is not 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 a multipart upload, you can 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 with server-side encryption.

Important
  • All GET and PUT requests for an object that's protected by AWS KMS fail if you don't make them by using Secure Sockets Layer (SSL), Transport Layer Security (TLS), or Signature Version 4.

  • If your object uses DSSE-KMS, don't send encryption request headers for GET requests and HEAD requests, or you'll get an HTTP 400 (Bad Request) error.

Encryption context (x-amz-server-side-encryption-context)

If you specify x-amz-server-side-encryption:aws:kms:dsse, 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's Amazon Resource Name (ARN) as the encryption context pair; for example, arn:aws:s3:::object_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 is not encrypted, make sure it does not 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 AWS Key Management Service Concepts - Encryption context in the AWS Key Management Service Developer Guide.

AWS 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:dsse header but don't provide the x-amz-server-side-encryption-aws-kms-key-id header, Amazon S3 uses the AWS 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 AWS 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 AWS Key Management Service Developer Guide.

When you upload a new object or copy an existing object, you can specify the use of DSSE-KMS to encrypt your data. To do this, add the --server-side-encryption aws:kms:dsse parameter to the request. Use the --ssekms-key-id example-key-id parameter to add your customer managed AWS KMS key that you created. If you specify --server-side-encryption aws:kms:dsse, but do not provide an AWS KMS key ID, then Amazon S3 will use the AWS managed key (aws/s3).

aws s3api put-object --bucket amzn-s3-demo-bucket --key example-object-key --server-side-encryption aws:kms:dsse --ssekms-key-id example-key-id --body filepath

You can encrypt an unencrypted object to use DSSE-KMS by copying the object back in place.

aws s3api copy-object --bucket amzn-s3-demo-bucket --key example-object-key --body filepath --bucket amzn-s3-demo-bucket --key example-object-key --sse aws:kms:dsse --sse-kms-key-id example-key-id --body filepath