# Using server-side encryption with AWS KMS keys (SSE-KMS) KMS keys stored in AWS KMS (SSE-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 CloudTrail logs, S3 Inventory, S3 Storage Lens, the Amazon S3 console, and as an additional Amazon S3 API response header in the AWS CLI and AWS SDKs. For more information, see [Default encryption FAQ](https://docs.aws.amazon.com/AmazonS3/latest/userguide/default-encryption-faq.html). Server-side encryption is the encryption of data at its destination by the application or service that receives it. Amazon S3 automatically enables server-side encryption with Amazon S3 managed keys (SSE-S3) for new object uploads. Unless you specify otherwise, buckets use SSE-S3 by default to encrypt objects. However, you can choose to configure buckets to use server-side encryption with AWS Key Management Service (AWS KMS) keys (SSE-KMS) instead. For more information, see [Specifying server-side encryption with AWS KMS (SSE-KMS)](specifying-kms-encryption.md). AWS KMS is a service that combines secure, highly available hardware and software to provide a key management system scaled for the cloud. Amazon S3 uses server-side encryption with AWS KMS (SSE-KMS) to encrypt your S3 object data. Also, when SSE-KMS is requested for the object, the S3 checksum (as part of the object's metadata) is stored in encrypted form. For more information about checksum, see [Checking object integrity in Amazon S3](checking-object-integrity.md). If you use KMS keys, you can use AWS KMS through the [AWS Management Console](https://console.aws.amazon.com/kms) or the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) to do the following: + Centrally create, view, edit, monitor, enable or disable, rotate, and schedule deletion of KMS keys. + Define the policies that control how and by whom KMS keys can be used. + Audit KMS key usage for correct use. Auditing is supported by the [AWS KMS API](https://docs.aws.amazon.com/kms/latest/APIReference/) but not by the [AWS KMS Console;](https://console.aws.amazon.com/kms). The security controls in AWS KMS can help you meet encryption-related compliance requirements. You can use these KMS keys to protect your data in Amazon S3 buckets. When you use SSE-KMS encryption with an S3 bucket, the AWS KMS keys must be in the same Region as the bucket. There are additional charges for using AWS KMS keys. For more information, see [AWS KMS key concepts](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#kms_keys) in the *AWS Key Management Service Developer Guide* and [AWS KMS pricing](https://aws.amazon.com/kms/pricing). For instructions on allowing IAM users to access KMS-encrypted buckets see [My Amazon S3 bucket has default encryption using a custom AWS KMS key. How can I allow users to download from and upload to the bucket?](https://repost.aws/knowledge-center/s3-bucket-access-default-encryption) in the AWS re:Post Knowledge Center. **Permissions** To successfully make a `PutObject` request to encrypt an object with an AWS KMS key to Amazon S3, you need `kms:GenerateDataKey` permissions on the key. To download an object encrypted with an AWS KMS key, you need `kms:Decrypt` permissions for the key. To [perform a multipart upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#mpuAndPermissions) to encrypt an object with an AWS KMS key, you must have the `kms:GenerateDataKey` and `kms:Decrypt` permissions for the key. **Important** Carefully review the permissions that are granted in your KMS key policies. Always restrict customer-managed KMS key policy permissions only to the IAM principals and AWS services that must access the relevant AWS KMS key action. For more information, see [Key policies in AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html). **Topics** + [ ## AWS KMS keys ](#aws-managed-customer-managed-keys) + [ ## Amazon S3 Bucket Keys ](#sse-kms-bucket-keys) + [ ## Requiring server-side encryption ](#require-sse-kms) + [ ## Encryption context ](#encryption-context) + [ ## Sending requests for AWS KMS encrypted objects ](#aws-signature-version-4-sse-kms) + [ # Specifying server-side encryption with AWS KMS (SSE-KMS) ](specifying-kms-encryption.md) + [ # Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys ](bucket-key.md) ## AWS KMS keys When you use server-side encryption with AWS KMS (SSE-KMS), you can use the default [AWS managed key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk), or you can specify a [customer managed key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) that you have already created. AWS KMS supports *envelope encryption*. S3 uses the AWS KMS features for *envelope encryption* to further protect your data. Envelope encryption is the practice of encrypting your plain text data with a data key, and then encrypting that data key with a KMS key. For more information about envelope encryption, see [Envelope encryption](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#enveloping) in the *AWS Key Management Service Developer Guide*. If you don't specify a customer managed key, Amazon S3 automatically creates an AWS managed key in your AWS account the first time that you add an object encrypted with SSE-KMS to a bucket. By default, Amazon S3 uses this KMS key for SSE-KMS. **Note** Objects encrypted using SSE-KMS with [AWS managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) can't be shared cross-account. If you need to share SSE-KMS data cross-account, you must use a [customer managed key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) from AWS KMS. If you want to use a customer managed key for SSE-KMS, create a symmetric encryption customer managed key before you configure SSE-KMS. Then, when you configure SSE-KMS for your bucket, specify the existing customer managed key. For more information about symmetric encryption key, see [Symmetric encryption KMS keys](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#symmetric-cmks) in the *AWS Key Management Service Developer Guide*. Creating a customer managed key gives you more flexibility and control. For example, you can create, rotate, and disable customer managed keys. You can also define access controls and audit the customer managed key that you use to protect your data. For more information about customer managed and AWS managed keys, see [Customer keys and AWS keys](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#key-mgmt) in the *AWS Key Management Service Developer Guide*. **Note** When you use server-side encryption with a customer managed key that's stored in an external key store, unlike standard KMS keys, you are responsible for ensuring the availability and durability of your key material. For more information about external key stores and how they shift the shared responsibility model, see [External key stores](https://docs.aws.amazon.com//kms/latest/developerguide/keystore-external.html) in the *AWS Key Management Service Developer Guide*. ### Using SSE-KMS encryption for cross-account operations When using encryption for cross-account operations, be aware of the following: + If an AWS KMS key Amazon Resource Name (ARN) or alias is not provided at request time or through the bucket's default encryption configuration, the AWS managed key (`aws/s3`) from the uploading account is used for encryption and required for decryption. + AWS managed key (`aws/s3`) can be used as your KMS key for cross-account operations when the uploading and accessing AWS Identity and Access Management (IAM) principals are from the same AWS account. + If you want to grant cross-account access to your S3 objects, use a customer managed key. You can configure the policy of a customer managed key to allow access from another account. + If you're specifying a customer managed KMS key, we recommend using a fully qualified KMS key ARN. If you use a KMS key alias instead, AWS KMS resolves the key within the requester’s account. This behavior can result in data that's encrypted with a KMS key that belongs to the requester, and not the bucket owner. + You must specify a key that you (the requester) have been granted `Encrypt` permission to. For more information, see [Allow key users to use a KMS key for cryptographic operations](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-users-crypto) in the *AWS Key Management Service Developer Guide*. For more information about when to use customer managed keys and AWS managed KMS keys, see [Should I use an AWS managed key or a customer managed key to encrypt my objects in Amazon S3?](https://aws.amazon.com/premiumsupport/knowledge-center/s3-object-encryption-keys/) ### SSE-KMS encryption workflow If you choose to encrypt your data using an AWS managed key or a customer managed key, AWS KMS and Amazon S3 perform the following envelope encryption actions: 1. Amazon S3 requests a plaintext [ data key](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#data-keys) and a copy of the key encrypted under the specified KMS key. 1. AWS KMS generates a data key, encrypts it under the KMS key, and sends both the plaintext data key and the encrypted data key to Amazon S3. 1. Amazon S3 encrypts the data using the data key and removes the plaintext key from memory as soon as possible after use. 1. Amazon S3 stores the encrypted data key as metadata with the encrypted data. When you request that your data be decrypted, Amazon S3 and AWS KMS perform the following actions: 1. Amazon S3 sends the encrypted data key to AWS KMS in a `Decrypt` request. 1. AWS KMS decrypts the encrypted data key by using the same KMS key and returns the plaintext data key to Amazon S3. 1. Amazon S3 decrypts the encrypted data, using the plaintext data key, and removes the plaintext data key from memory as soon as possible. **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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#symmetric-cmks) in the *AWS Key Management Service Developer Guide*. ### Auditing SSE-KMS encryption To identify requests that specify SSE-KMS, you can use the **All SSE-KMS requests** and **% all SSE-KMS requests** metrics in Amazon S3 Storage Lens metrics. S3 Storage Lens is a cloud-storage analytics feature that you can use to gain organization-wide visibility into object-storage usage and activity. You can also use the SSE-KMS enabled bucket count and % SSE-KMS enabled buckets to understand the count of buckets that (SSE-KMS) for [default bucket encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html). For more information, see [ Assessing your storage activity and usage with S3 Storage Lens](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage_lens.html?icmpid=docs_s3_user_guide_UsingKMSEncryption.html). For a complete list of metrics, see [ S3 Storage Lens metrics glossary](https://docs.aws.amazon.com/AmazonS3/latest/userguide/storage_lens_metrics_glossary.html?icmpid=docs_s3_user_guide_UsingKMSEncryption.html). To audit the usage of your AWS KMS keys for your SSE-KMS encrypted data, you can use AWS CloudTrail logs. You can get insight into your [cryptographic operations](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations), such as [https://docs.aws.amazon.com/kms/latest/developerguide/ct-generatedatakey.html](https://docs.aws.amazon.com/kms/latest/developerguide/ct-generatedatakey.html) and [https://docs.aws.amazon.com/kms/latest/developerguide/ct-decrypt.html](https://docs.aws.amazon.com/kms/latest/developerguide/ct-decrypt.html). CloudTrail supports numerous [attribute values](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_LookupEvents.html) for filtering your search, including event name, user name, and event source. ## Amazon S3 Bucket Keys When you configure server-side encryption using AWS KMS (SSE-KMS), you can configure your buckets to use S3 Bucket Keys for SSE-KMS. Using a bucket-level key for SSE-KMS can reduce your AWS KMS request costs by up to 99 percent by decreasing the request traffic from Amazon S3 to AWS KMS. When you configure a bucket to use an S3 Bucket Key for SSE-KMS on new objects, AWS KMS generates a bucket-level key that is used to create unique [data keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) for objects in the bucket. This S3 Bucket Key is used for a time-limited period within Amazon S3, further reducing the need for Amazon S3 to make requests to AWS KMS to complete encryption operations. For more information about using S3 Bucket Keys, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). ## Requiring server-side encryption To require server-side encryption of all objects in a particular Amazon S3 bucket, you can use a bucket policy. For example, the following bucket policy denies the upload object (`s3:PutObject`) permission to everyone if the request does not include an `x-amz-server-side-encryption-aws-kms-key-id` header that requests server-side encryption with SSE-KMS. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Id":"PutObjectPolicy", "Statement":[{ "Sid":"DenyObjectsThatAreNotSSEKMS", "Effect":"Deny", "Principal":"*", "Action":"s3:PutObject", "Resource":"arn:aws:s3:::amzn-s3-demo-bucket1/*", "Condition":{ "Null":{ "s3:x-amz-server-side-encryption-aws-kms-key-id":"true" } } } ] } ``` ------ To require that a particular AWS KMS key be used to encrypt the objects in a bucket, you can use the `s3:x-amz-server-side-encryption-aws-kms-key-id` condition key. To specify the KMS key, you must use a key Amazon Resource Name (ARN) that is in the `arn:aws:kms:region:acct-id:key/key-id` format. AWS Identity and Access Management does not validate if the string for `s3:x-amz-server-side-encryption-aws-kms-key-id` exists. **Note** When you upload an object, you can specify the KMS key by using the `x-amz-server-side-encryption-aws-kms-key-id` header or rely on your [default bucket encryption configuration](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html). If your PutObject request specifies `aws:kms` in the `x-amz-server-side-encryption` header, but does not specify the `x-amz-server-side-encryption-aws-kms-key-id` header, then Amazon S3 assumes that you want to use the AWS managed key. Regardless, the AWS KMS key ID that Amazon S3 uses for object encryption must match the AWS KMS key ID in the policy, otherwise Amazon S3 denies the request. For a complete list of Amazon S3 specific condition keys, see [ Condition keys for Amazon S3](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html#amazons3-policy-keys) in the *Service Authorization Reference*. ## Encryption context An *encryption context* is a set of key-value pairs that contains additional contextual information about the data. The encryption context is not encrypted. When an encryption context is specified for an encryption operation, Amazon S3 must specify the same encryption context for the decryption operation. Otherwise, the decryption fails. AWS KMS uses the encryption context as [additional authenticated data](https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/concepts.html#digital-sigs) (AAD) to support [authenticated encryption](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations#digital-sigs). For more information about the encryption context, see [Encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) in the *AWS Key Management Service Developer Guide*. By default, Amazon S3 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**, the object ARN is used as the encryption context. ``` arn:aws:s3:::object_ARN ``` + **If you use SSE-KMS and enable an S3 Bucket Key**, the bucket ARN is used as the encryption context. For more information about S3 Bucket Keys, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). ``` arn:aws:s3:::bucket_ARN ``` You can optionally provide an additional encryption context pair by using the `x-amz-server-side-encryption-context` header in an [ s3:PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html#API_PutObject_RequestSyntax) request. 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. When it processes your `PUT` request, Amazon S3 appends the default encryption context of `aws:s3:arn` to the one that you provide. You can use the encryption context to identify and categorize your cryptographic operations. You can also use the default encryption context ARN value to track relevant requests in AWS CloudTrail by viewing which Amazon S3 ARN was used with which encryption key. In the `requestParameters` field of a CloudTrail log file, the encryption context looks similar to the following one. ``` "encryptionContext": { "aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket1/file_name" } ``` When you use SSE-KMS with the optional S3 Bucket Keys feature, the encryption context value is the ARN of the bucket. ``` "encryptionContext": { "aws:s3:arn": "arn:aws:s3:::amzn-s3-demo-bucket1" } ``` ## Sending requests for AWS KMS encrypted objects **Important** All `GET` and `PUT` requests for AWS KMS encrypted objects must be made using Secure Sockets Layer (SSL) or Transport Layer Security (TLS). Requests must also be signed using valid credentials, such as AWS Signature Version 4 (or AWS Signature Version 2). AWS Signature Version 4 is the process of adding authentication information to AWS requests sent by HTTP. For security, most requests to AWS must be signed with an access key, which consists of an access key ID and secret access key. These two keys are commonly referred to as your security credentials. For more information, see [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html) and [Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html). **Important** If your object uses SSE-KMS, don't send encryption request headers for `GET` requests and `HEAD` requests. Otherwise, you’ll get an HTTP 400 Bad Request error. **Topics** + [ ## AWS KMS keys ](#aws-managed-customer-managed-keys) + [ ## Amazon S3 Bucket Keys ](#sse-kms-bucket-keys) + [ ## Requiring server-side encryption ](#require-sse-kms) + [ ## Encryption context ](#encryption-context) + [ ## Sending requests for AWS KMS encrypted objects ](#aws-signature-version-4-sse-kms) + [ # Specifying server-side encryption with AWS KMS (SSE-KMS) ](specifying-kms-encryption.md) + [ # Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys ](bucket-key.md) # Specifying server-side encryption with AWS KMS (SSE-KMS) Specifying 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 update 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. For more information about changing the default encryption configuration for your general purpose buckets, see [Configuring default encryption](default-bucket-encryption.md). When you change the default encryption configuration of your bucket to SSE-KMS, the encryption type of the existing Amazon S3 objects in the bucket is not changed. To change the encryption type of your pre-existing objects after updating the default encryption configuration to SSE-KMS, you can use Amazon S3 Batch Operations. You provide S3 Batch Operations with a list of objects, and Batch Operations calls the respective API operation. You can use the [Copy objects](batch-ops-copy-object.md) action to copy existing objects, which writes them back to the same bucket as SSE-KMS encrypted objects. A single Batch Operations job can perform the specified operation on billions of objects. For more information, see [Performing object operations in bulk with Batch Operations](batch-ops.md) and the *AWS Storage Blog* post [How to retroactively encrypt existing objects in Amazon S3 using S3 Inventory, Amazon Athena, and S3 Batch Operations](https://aws.amazon.com/blogs/security/how-to-retroactively-encrypt-existing-objects-in-amazon-s3-using-s3-inventory-amazon-athena-and-s3-batch-operations/). You can specify SSE-KMS by using the Amazon S3 console, REST API operations, AWS SDKs, 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](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) in the *AWS 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](https://docs.aws.amazon.com//kms/latest/developerguide/key-policy-modifying-external-accounts.html#cross-account-console) in the *AWS Key Management Service Developer Guide*. ## Using the S3 console This topic describes how to set or change the type of encryption of an object to use server-side encryption with AWS Key Management Service (AWS 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 [AWS CLI](mpu-upload-object.md#UsingCLImpUpload) or [AWS SDKs](CopyingObjectsMPUapi.md) 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](using-with-s3-policy-actions.md). For example policies that grant this permission, see [Identity-based policy examples for Amazon S3](example-policies-s3.md). 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** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. 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. 1. Select the check box for the objects you want to change. 1. On the **Actions** menu, choose **Edit server-side encryption** from the list of options that appears. 1. Scroll to the **Server-side encryption** section. 1. 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 AWS KMS. For more information about AWS KMS quotas and how to request a quota increase, see [Quotas](https://docs.aws.amazon.com/kms/latest/developerguide/limits.html) in the *AWS Key Management Service Developer Guide*. 1. If you chose **Override bucket settings for default encryption**, configure the following encryption settings. 1. Under **Encryption type**, choose **Server-side encryption with AWS Key Management Service keys (SSE-KMS)**. 1. 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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#key-mgmt) 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](https://docs.aws.amazon.com//kms/latest/developerguide/create-keys.html) 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 symmetric and asymmetric KMS keys](https://docs.aws.amazon.com//kms/latest/developerguide/find-symm-asymm.html) in the *AWS Key Management Service Developer Guide*. 1. 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. 1. 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. ## Using the REST API 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 AWS 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 ](#sse-request-headers-kms) + [ ### Encryption context (`x-amz-server-side-encryption-context`) ](#s3-kms-encryption-context) + [ ### AWS KMS key ID (`x-amz-server-side-encryption-aws-kms-key-id`) ](#s3-kms-key-id-api) + [ ### S3 Bucket Keys (`x-amz-server-side-encryption-aws-bucket-key-enabled`) ](#bucket-key-api) ### 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. + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) – When you upload data by using the `PUT` API operation, you can specify these request headers. + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) – 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. + [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) – When you use a `POST` operation to upload an object, instead of the request headers, you provide the same information in the form fields. + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) – 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. + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) **Important** All `GET` and `PUT` requests for an object protected by AWS 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 and `HEAD` requests, or you’ll get an HTTP 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:::object_ARN`. However, if you use SSE-KMS and enable an S3 Bucket Key, you use the bucket ARN for your encryption context; for example, `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](UsingKMSEncryption.md#encryption-context). For general information about the encryption context, see [AWS Key Management Service Concepts - Encryption context](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_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` 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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#symmetric-cmks) in the *AWS 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 AWS KMS request costs by decreasing the request traffic from Amazon S3 to AWS KMS. For more information, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). 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](configuring-bucket-key-object.md). ## Using the AWS CLI To use the following example AWS CLI commands, replace the `user input placeholders` with your own information. When you upload a new object or copy an existing object, you can specify the use of server-side encryption with AWS 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 example-key-id` to add your [customer managed AWS KMS key](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#customer-cmk) that you created. If you specify `--server-side-encryption aws:kms`, but don't provide an AWS KMS key ID, Amazon S3 will use an AWS managed key. ``` aws s3api put-object --bucket amzn-s3-demo-bucket --key example-object-key --server-side-encryption aws:kms --ssekms-key-id example-key-id --body filepath ``` 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 AWS KMS request costs by decreasing the request traffic from Amazon S3 to AWS KMS. For more information, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](https://docs.aws.amazon.com//AmazonS3/latest/userguide/bucket-key.html). ``` aws s3api put-object --bucket amzn-s3-demo-bucket --key example-object-key --server-side-encryption aws:kms --bucket-key-enabled --body filepath ``` 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 --key example-object-key --body filepath --bucket amzn-s3-demo-bucket --key example-object-key --sse aws:kms --sse-kms-key-id example-key-id --body filepath ``` ## Using the AWS SDKs When using AWS SDKs, you can request Amazon S3 to use AWS KMS keys for server-side encryption. The following examples show how to use SSE-KMS with the AWS SDKs for Java and .NET. For information about other SDKs, see [Sample code and libraries](https://aws.amazon.com/code) on the AWS Developer Center. **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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#symmetric-cmks) in the *AWS 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 AWS KMS key. For more information about copying objects, see [Copying, moving, and renaming objects](copy-object.md). ### `PUT` operation ------ #### [ Java ] When uploading an object by using the AWS SDK for Java, you can request Amazon S3 to use an AWS KMS key by adding the `SSEAwsKeyManagementParams` property as shown in the following request: ``` PutObjectRequest putRequest = new PutObjectRequest(bucketName, keyName, file).withSSEAwsKeyManagementParams(new SSEAwsKeyManagementParams()); ``` In this case, Amazon S3 uses the AWS managed key (`aws/s3`). For more information, see [Using server-side encryption with AWS KMS keys (SSE-KMS)](UsingKMSEncryption.md). You can optionally create a symmetric encryption KMS key and specify that in the request, as shown in the following example: ``` PutObjectRequest putRequest = new PutObjectRequest(bucketName, keyName, file).withSSEAwsKeyManagementParams(new SSEAwsKeyManagementParams(keyID)); ``` For more information about creating customer managed keys, see [Programming the AWS KMS API](https://docs.aws.amazon.com/kms/latest/developerguide/programming-top.html) in the *AWS Key Management Service Developer Guide*. For working code examples of uploading an object, see the following topics. To use these examples, you must update the code examples and provide encryption information as shown in the preceding code fragment. + For uploading an object in a single operation, see [Uploading objects](upload-objects.md). + For multipart uploads that use the high-level or low-level multipart upload API operations, see [Uploading an object using multipart upload](mpu-upload-object.md). ------ #### [ .NET ] When uploading an object by using the AWS SDK for .NET, you can request Amazon S3 to use an AWS KMS key by adding the `ServerSideEncryptionMethod` property as shown in the following request: ``` PutObjectRequest putRequest = new PutObjectRequest { BucketName = amzn-s3-demo-bucket, Key = keyName, // other properties ServerSideEncryptionMethod = ServerSideEncryptionMethod.AWSKMS }; ``` In this case, Amazon S3 uses the AWS managed key. For more information, see [Using server-side encryption with AWS KMS keys (SSE-KMS)](UsingKMSEncryption.md). You can optionally create your own symmetric encryption customer managed key and specify that in the request, as shown in the following example: ``` PutObjectRequest putRequest1 = new PutObjectRequest { BucketName = amzn-s3-demo-bucket, Key = keyName, // other properties ServerSideEncryptionMethod = ServerSideEncryptionMethod.AWSKMS, ServerSideEncryptionKeyManagementServiceKeyId = keyId }; ``` For more information about creating customer managed keys, see [Programming the AWS KMS API](https://docs.aws.amazon.com/kms/latest/developerguide/programming-top.html) in the *AWS Key Management Service Developer Guide*. For working code examples of uploading an object, see the following topics. To use these examples, you must update the code examples and provide encryption information as shown in the preceding code fragment. + For uploading an object in a single operation, see [Uploading objects](upload-objects.md). + For multipart uploads that use the high-level or low-level multipart upload API operations, see [Uploading an object using multipart upload](mpu-upload-object.md). ------ ### Presigned URLs ------ #### [ Java ] When creating a presigned URL for an object that's encrypted with an AWS KMS key, you must explicitly specify Signature Version 4, as shown in the following example: ``` ClientConfiguration clientConfiguration = new ClientConfiguration(); clientConfiguration.setSignerOverride("AWSS3V4SignerType"); AmazonS3Client s3client = new AmazonS3Client( new ProfileCredentialsProvider(), clientConfiguration); ... ``` For a code example, see [Sharing objects with presigned URLs](ShareObjectPreSignedURL.md). ------ #### [ .NET ] When creating a presigned URL for an object that's encrypted with an AWS KMS key, you must explicitly specify Signature Version 4, as shown in the following example: ``` AWSConfigs.S3Config.UseSignatureVersion4 = true; ``` For a code example, see [Sharing objects with presigned URLs](ShareObjectPreSignedURL.md). ------ # Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys Using Amazon S3 Bucket Keys Amazon S3 Bucket Keys reduce the cost of Amazon S3 server-side encryption with AWS Key Management Service (AWS KMS) keys (SSE-KMS). Using a bucket-level key for SSE-KMS can reduce AWS KMS request costs by up to 99 percent by decreasing the request traffic from Amazon S3 to AWS KMS. With a few clicks in the AWS Management Console, and without any changes to your client applications, you can configure your bucket to use an S3 Bucket Key for SSE-KMS encryption on new objects. **Note** S3 Bucket Keys aren't supported for dual-layer server-side encryption with AWS Key Management Service (AWS KMS) keys (DSSE-KMS). ## S3 Bucket Keys for SSE-KMS Workloads that access millions or billions of objects encrypted with SSE-KMS can generate large volumes of requests to AWS KMS. When you use SSE-KMS to protect your data without an S3 Bucket Key, Amazon S3 uses an individual AWS KMS [data key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) for every object. In this case, Amazon S3 makes a call to AWS KMS every time a request is made against a KMS-encrypted object. For information about how SSE-KMS works, see [Using server-side encryption with AWS KMS keys (SSE-KMS)](UsingKMSEncryption.md). When you configure your bucket to use an S3 Bucket Key for SSE-KMS, AWS generates a short-lived bucket-level key from AWS KMS, then temporarily keeps it in S3. This bucket-level key will create data keys for new objects during its lifecycle. S3 Bucket Keys are used for a limited time period within Amazon S3, reducing the need for S3 to make requests to AWS KMS to complete encryption operations. This reduces traffic from S3 to AWS KMS, allowing you to access AWS KMS-encrypted objects in Amazon S3 at a fraction of the previous cost. Unique bucket-level keys are fetched at least once per requester to ensure that the requester's access to the key is captured in an AWS KMS CloudTrail event. Amazon S3 treats callers as different requesters when they use different roles or accounts, or the same role with different scoping policies. AWS KMS request savings reflect the number of requesters, request patterns, and relative age of the objects requested. For example, a fewer number of requesters, requesting multiple objects in a limited time window, and encrypted with the same bucket-level key, results in greater savings. **Note** Using S3 Bucket Keys allows you to save on AWS KMS request costs by decreasing your requests to AWS KMS for `Encrypt`, `GenerateDataKey`, and `Decrypt` operations through the use of a bucket-level key. By design, subsequent requests that take advantage of this bucket-level key do not result in AWS KMS API requests or validate access against the AWS KMS key policy. When you configure an S3 Bucket Key, objects that are already in the bucket do not use the S3 Bucket Key. To configure an S3 Bucket Key for existing objects, you can use a `CopyObject` operation. For more information, see [Configuring an S3 Bucket Key at the object level](configuring-bucket-key-object.md). Amazon S3 will only share an S3 Bucket Key for objects encrypted by the same AWS KMS key. S3 Bucket Keys are compatible with KMS keys created by AWS KMS, [imported key material](https://docs.aws.amazon.com/kms/latest/developerguide/importing-keys.html), and [key material backed by custom key stores](https://docs.aws.amazon.com/kms/latest/developerguide/custom-key-store-overview.html). ![\[Diagram showing AWS KMS generating a bucket key that creates data keys for objects in a bucket.\]](http://docs.aws.amazon.com/AmazonS3/latest/userguide/images/S3-Bucket-Keys.png) ## Configuring S3 Bucket Keys You can configure your bucket to use an S3 Bucket Key for SSE-KMS on new objects through the Amazon S3 console, AWS SDKs, AWS CLI, or REST API. With S3 Bucket Keys enabled on your bucket, objects uploaded with a different specified SSE-KMS key will use their own S3 Bucket Keys. Regardless of your S3 Bucket Key setting, you can include the `x-amz-server-side-encryption-bucket-key-enabled` header with a `true` or `false` value in your request, to override the bucket setting. Before you configure your bucket to use an S3 Bucket Key, review [Changes to note before enabling an S3 Bucket Key](#bucket-key-changes). ### Configuring an S3 Bucket Key using the Amazon S3 console When you create a new bucket, you can configure your bucket to use an S3 Bucket Key for SSE-KMS on new objects. You can also configure an existing bucket to use an S3 Bucket Key for SSE-KMS on new objects by updating your bucket properties.  For more information, see [Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects](configuring-bucket-key.md). ### REST API, AWS CLI, and AWS SDK support for S3 Bucket Keys You can use the REST API, AWS CLI, or AWS SDK to configure your bucket to use an S3 Bucket Key for SSE-KMS on new objects. You can also enable an S3 Bucket Key at the object level. For more information, see the following:  + [Configuring an S3 Bucket Key at the object level](configuring-bucket-key-object.md) + [Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects](configuring-bucket-key.md) The following API operations support S3 Bucket Keys for SSE-KMS: + [PutBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketEncryption.html) + `ServerSideEncryptionRule` accepts the `BucketKeyEnabled` parameter for enabling and disabling an S3 Bucket Key. + [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html) + `ServerSideEncryptionRule` returns the settings for `BucketKeyEnabled`. + [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html), [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html), [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html), and [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) + The `x-amz-server-side-encryption-bucket-key-enabled` request header enables or disables an S3 Bucket Key at the object level. + [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html), [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html), [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html), [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html), and [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) + The `x-amz-server-side-encryption-bucket-key-enabled` response header indicates if an S3 Bucket Key is enabled or disabled for an object. ### Working with CloudFormation In CloudFormation, the `AWS::S3::Bucket` resource includes an encryption property called `BucketKeyEnabled` that you can use to enable or disable an S3 Bucket Key. For more information, see [Using CloudFormation](configuring-bucket-key.md#enable-bucket-key-cloudformation). ## Changes to note before enabling an S3 Bucket Key Before you enable an S3 Bucket Key, note the following related changes: ### IAM or AWS KMS key policies If your existing AWS Identity and Access Management (IAM) policies or AWS KMS key policies use your object Amazon Resource Name (ARN) as the encryption context to refine or limit access to your KMS key, these policies won't work with an S3 Bucket Key. S3 Bucket Keys use the bucket ARN as encryption context. Before you enable an S3 Bucket Key, update your IAM policies or AWS KMS key policies to use your bucket ARN as the encryption context. For more information about the encryption context and S3 Bucket Keys, see [Encryption context](UsingKMSEncryption.md#encryption-context). ### CloudTrail events for AWS KMS After you enable an S3 Bucket Key, your AWS KMS CloudTrail events log your bucket ARN instead of your object ARN. Additionally, you see fewer KMS CloudTrail events for SSE-KMS objects in your logs. Because key material is time-limited in Amazon S3, fewer requests are made to AWS KMS. ## Using an S3 Bucket Key with replication You can use S3 Bucket Keys with Same-Region Replication (SRR) and Cross-Region Replication (CRR). When Amazon S3 replicates an encrypted object, it generally preserves the encryption settings of the replica object in the destination bucket. However, if the source object is not encrypted and your destination bucket uses default encryption or an S3 Bucket Key, Amazon S3 encrypts the object with the destination bucket’s configuration. The following examples illustrate how an S3 Bucket Key works with replication. For more information, see [Replicating encrypted objects (SSE-S3, SSE-KMS, DSSE-KMS, SSE-C)](replication-config-for-kms-objects.md).  **Example 1 – Source object uses S3 Bucket Keys; destination bucket uses default encryption** If your source object uses an S3 Bucket Key but your destination bucket uses default encryption with SSE-KMS, the replica object maintains its S3 Bucket Key encryption settings in the destination bucket. The destination bucket still uses default encryption with SSE-KMS. **Example 2 – Source object is not encrypted; destination bucket uses an S3 Bucket Key with SSE-KMS** If your source object is not encrypted and the destination bucket uses an S3 Bucket Key with SSE-KMS, the replica object is encrypted by using an S3 Bucket Key with SSE-KMS in the destination bucket. This results in the `ETag` of the source object being different from the `ETag` of the replica object. You must update applications that use the `ETag` to accommodate for this difference. ## Working with S3 Bucket Keys For more information about enabling and working with S3 Bucket Keys, see the following sections: + [Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects](configuring-bucket-key.md) + [Configuring an S3 Bucket Key at the object level](configuring-bucket-key-object.md) + [Viewing the settings for an S3 Bucket Key](viewing-bucket-key-settings.md) # Configuring your bucket to use an S3 Bucket Key with SSE-KMS for new objects Configuring an S3 Bucket Key for your bucket When you configure server-side encryption with AWS Key Management Service (AWS KMS) keys (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 AWS KMS and reduce the cost of SSE-KMS. For more information, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). 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, AWS SDKs, AWS Command Line Interface (AWS CLI), or CloudFormation. If you want to enable or disable an S3 Bucket Key for existing objects, you can use a `CopyObject` operation. For more information, see [Configuring an S3 Bucket Key at the object level](configuring-bucket-key-object.md) and [Using Batch Operations to enable S3 Bucket Keys for SSE-KMS](batch-ops-copy-example-bucket-key.md). 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 [S3 Bucket Keys and replication](replication-config-for-kms-objects.md#bk-replication). The following examples illustrate how an S3 Bucket Key works with replication. For more information, see [Replicating encrypted objects (SSE-S3, SSE-KMS, DSSE-KMS, SSE-C)](replication-config-for-kms-objects.md).  **Prerequisites** Before you configure your bucket to use an S3 Bucket Key, review [Changes to note before enabling an S3 Bucket Key](bucket-key.md#bucket-key-changes). **Topics** ## Using the S3 console Configuring an S3 Bucket Key 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 SSE-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 the 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 is enabled for the object. **To enable an S3 Bucket Key when you create a new bucket** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. Choose **Create bucket**. 1. Enter your bucket name, and choose your AWS Region. 1. Under **Default encryption**, for **Encryption key type**, choose **AWS Key Management Service key (SSE-KMS)**. 1. 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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#key-mgmt) in the *AWS Key Management Service Developer Guide*. + To enter the KMS key ARN, choose **Enter AWS KMS key ARN**, and 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](https://docs.aws.amazon.com//kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*. 1. Under **Bucket Key**, choose **Enable**. 1. 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.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the bucket that you want to enable an S3 Bucket Key for. 1. Choose the **Properties** tab. 1. Under **Default encryption**, choose **Edit**. 1. Under **Default encryption**, for **Encryption key type**, choose **AWS Key Management Service key (SSE-KMS)**. 1. 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](https://docs.aws.amazon.com//kms/latest/developerguide/concepts.html#key-mgmt) in the *AWS Key Management Service Developer Guide*. + To enter the KMS key ARN, choose **Enter AWS KMS key ARN**, and 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](https://docs.aws.amazon.com//kms/latest/developerguide/create-keys.html) in the *AWS Key Management Service Developer Guide*. 1. Under **Bucket Key**, choose **Enable**. 1. 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 configure an S3 Bucket Key for existing objects, you can use a `CopyObject` operation. For more information, see [Configuring an S3 Bucket Key at the object level](configuring-bucket-key-object.md). To disable an S3 Bucket Key, follow the previous steps, and choose **Disable**. ## Using the REST API You can use [PutBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketEncryption.html) to enable or disable an S3 Bucket Key for your bucket. To configure an S3 Bucket Key with `PutBucketEncryption`, use the [ServerSideEncryptionRule](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ServerSideEncryptionRule.html) data type, which includes default encryption with SSE-KMS. 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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketEncryption.html). ## Using the AWS SDK for Java The following example enables default bucket encryption with SSE-KMS and an S3 Bucket Key by using the AWS 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); ``` ------ ## Using the AWS CLI The following example enables default bucket encryption with SSE-KMS and an S3 Bucket Key by using the AWS CLI. Replace the `user input placeholders` with your own information. ``` aws s3api put-bucket-encryption --bucket amzn-s3-demo-bucket --server-side-encryption-configuration '{         "Rules": [             {                 "ApplyServerSideEncryptionByDefault": {                     "SSEAlgorithm": "aws:kms",                     "KMSMasterKeyID": "KMS-Key-ARN"                 },                 "BucketKeyEnabled": true             }         ]     }' ``` ## Using CloudFormation For more information about configuring an S3 Bucket Key with CloudFormation, see [AWS::S3::Bucket ServerSideEncryptionRule](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-serversideencryptionrule.html) in the *AWS CloudFormation User Guide*. # Configuring an S3 Bucket Key at the object level Configuring an S3 Bucket Key for an object 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 by adding the `x-amz-server-side-encryption-bucket-key-enabled` request header with a `true` or `false` value. 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](bucket-key.md). 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 submit a PUT or COPY request for a KMS-encrypted object into a bucket with S3 Bucket Keys enabled, your object level operation will automatically use S3 Bucket Keys unless you disable the keys in the request header. 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](bucket-key.md#bucket-key-changes). **Topics** + [ ## Amazon S3 Batch Operations ](#bucket-key-object-bops) + [ ## Using the REST API ](#bucket-key-object-rest) + [ ## Using the AWS SDK for Java (PutObject) ](#bucket-key-object-sdk) + [ ## Using the AWS CLI (PutObject) ](#bucket-key-object-cli) ## 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/batch-ops-copy-object.html) 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 object operations in bulk with Batch Operations](batch-ops.md) and [Encrypting objects with Amazon S3 Batch Operations](https://aws.amazon.com/blogs/storage/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 by using the following API operations: + [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) – 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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) – 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. + [POST Object](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) – 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. + [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) – When you upload large objects by using the `CreateMultipartUpload` API operation 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](specifying-kms-encryption.md#KMSUsingRESTAPI). ## Using the AWS SDK for 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 = "amzn-s3-demo-bucket1"; 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 amzn-s3-demo-bucket --key object key name --server-side-encryption aws:kms --bucket-key-enabled --body filepath ``` # Viewing the settings for an S3 Bucket Key You can view the settings for an S3 Bucket Key at the bucket or object level by using the Amazon S3 console, REST API, AWS Command Line Interface (AWS CLI), or AWS SDKs. S3 Bucket Keys decrease request traffic from Amazon S3 to AWS KMS and reduce the cost of server-side encryption using AWS Key Management Service (SSE-KMS). For more information, see [Reducing the cost of SSE-KMS with Amazon S3 Bucket Keys](bucket-key.md). To view the S3 Bucket Key settings for a bucket or an object that has inherited S3 Bucket Key settings from the bucket configuration, you need permission to perform the `s3:GetEncryptionConfiguration` action. For more information, see [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html) in the *Amazon Simple Storage Service API Reference*. ## Using the S3 console In the S3 console, you can view the S3 Bucket Key settings for your bucket or object. S3 Bucket Key settings are inherited from the bucket configuration unless the source objects already has an S3 Bucket Key configured. Objects and folders in the same bucket can have different S3 Bucket Key settings. For example, if you upload an object using the REST API and enable an S3 Bucket Key for the object, the object retains its S3 Bucket Key setting in the destination bucket, even if S3 Bucket Key is disabled in the destination bucket. As another example, if you enable an S3 Bucket Key for an existing bucket, objects that are already in the bucket do not use an S3 Bucket Key. However, new objects have an S3 Bucket Key enabled. **To view the S3 Bucket Key setting for your bucket** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the left navigation pane, choose **Buckets**. 1. In the **Buckets** list, choose the bucket that you want to enable an S3 Bucket Key for. 1. Choose **Properties**. 1. In the **Default encryption** section, under **Bucket Key**, you see the S3 Bucket Key setting for your bucket. If you can’t see the S3 Bucket Key setting, you might not have permission to perform the `s3:GetEncryptionConfiguration` action. For more information, see [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html) in the *Amazon Simple Storage Service API Reference*. **To view the S3 Bucket Key setting for your object** 1. Sign in to the AWS Management Console and open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the **Buckets** list, choose the bucket that you want to enable an S3 Bucket Key for. 1. In the **Objects** list, choose your object name. 1. On the **Details** tab, under **Server-side encryption settings**, choose **Edit**. Under **Bucket Key**, you see the S3 Bucket Key setting for your object. You cannot edit this setting. ## Using the AWS CLI **To return bucket-level S3 Bucket Key settings** To use this example, replace each `user input placeholder` with your own information. ``` aws s3api get-bucket-encryption --bucket amzn-s3-demo-bucket1 ``` For more information, see [get-bucket-encryption](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/get-bucket-encryption.html) in the *AWS CLI Command Reference*. **To return object-level S3 Bucket Key settings** To use this example, replace each `user input placeholder` with your own information. ``` aws s3api head-object --bucket amzn-s3-demo-bucket1 --key my_images.tar.bz2 ``` For more information, see [head-object](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/head-object.html) in the *AWS CLI Command Reference*. ## Using the REST API **To return bucket-level S3 Bucket Key settings** To return encryption information for a bucket, including the settings for an S3 Bucket Key, use the `GetBucketEncryption` operation. S3 Bucket Key settings are returned in the response body in the `ServerSideEncryptionConfiguration` element with the `BucketKeyEnabled` setting. For more information, see [GetBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketEncryption.html) in the *Amazon S3 API Reference*. **To return object-level settings for an S3 Bucket Key** To return the S3 Bucket Key status for an object, use the `HeadObject` operation. `HeadObject` returns the `x-amz-server-side-encryption-bucket-key-enabled` response header to show whether an S3 Bucket Key is enabled or disabled for the object. For more information, see [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) in the *Amazon S3 API Reference*. The following API operations also return the `x-amz-server-side-encryption-bucket-key-enabled` response header if an S3 Bucket Key is configured for an object: + [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) + [PostObject](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPOST.html) + [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) + [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) + [UploadPartCopy](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPartCopy.html) + [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) + [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) + [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)