When uploading large objects by using the multipart upload API operation, you can specify server-side encryption by adding thex-amz-server-side-encryption header to the Initiate Multipart Upload request. 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.

The response headers of the following REST API operations return thex-amz-server-side-encryption header when an object is stored using SSE-S3.

When using AWS SDKs, you can request Amazon S3 to use server-side encryption with Amazon S3 managed encryption keys (SSE-S3). This section provides examples of using the AWS SDKs in multiple languages. For information about other SDKs, go toSample Code and Libraries.

Java

When you use the AWS SDK for Java to upload an object, you can use SSE-S3 to encrypt it. To request server-side encryption, use theObjectMetadata property of thePutObjectRequest to set thex-amz-server-side-encryption request header. When you call theputObject() method of theAmazonS3Client, Amazon S3 encrypts and saves the data.

You can also request SSE-S3 encryption when uploading objects with the multipart upload API operation:

• When using the high-level multipart upload API operation, you use theTransferManager methods to apply server-side encryption to objects as you upload them. You can use any of the upload methods that takeObjectMetadata as a parameter. For more information, seeUploading an object using multipart upload.

• When using the low-level multipart upload API operation, you specify server-side encryption when you initiate the multipart upload. You add theObjectMetadata property by calling theInitiateMultipartUploadRequest.setObjectMetadata() method. For more information, seeUsing the AWS SDKs (low-level API).

You can't directly change the encryption state of an object (encrypting an unencrypted object or decrypting an encrypted object). To change an object's encryption state, you make a copy of the object, specifying the desired encryption state for the copy, and then delete the original object. Amazon S3 encrypts the copied object only if you explicitly request server-side encryption. To request encryption of the copied object through the Java API, use theObjectMetadata property to specify server-side encryption in theCopyObjectRequest.

Example

The following example shows how to set server-side encryption by using the AWS SDK for Java. It shows how to perform the following tasks:

• Upload a new object by using SSE-S3.

• Change an object's encryption state (in this example, encrypting a previously unencrypted object) by making a copy of the object.

• Check the encryption state of the object.

For more information about server-side encryption, seeUsing the REST API. For instructions on creating and testing a working sample, seeGetting Started in the AWS SDK for Java Developer Guide.

import com.amazonaws.AmazonServiceException;import com.amazonaws.SdkClientException;import com.amazonaws.auth.profile.ProfileCredentialsProvider;import com.amazonaws.regions.Regions;import com.amazonaws.services.s3.AmazonS3;import com.amazonaws.services.s3.AmazonS3ClientBuilder;import com.amazonaws.services.s3.internal.SSEResultBase;import com.amazonaws.services.s3.model.*;import java.io.ByteArrayInputStream;public class SpecifyServerSideEncryption{    public static void main(String[] args){        Regions clientRegion = Regions.DEFAULT_REGION;        String bucketName = "*** Bucket name ***";        String keyNameToEncrypt = "*** Key name for an object to upload and encrypt ***";        String keyNameToCopyAndEncrypt = "*** Key name for an unencrypted object to be encrypted by copying ***";        String copiedObjectKeyName = "*** Key name for the encrypted copy of the unencrypted object ***";        try{            AmazonS3 s3Client = AmazonS3ClientBuilder.standard()                    .withRegion(clientRegion)                    .withCredentials(new ProfileCredentialsProvider())                    .build();            // Upload an object and encrypt it with SSE.            uploadObjectWithSSEEncryption(s3Client, bucketName, keyNameToEncrypt);            // Upload a new unencrypted object, then change its encryption state            // to encrypted by making a copy.            changeSSEEncryptionStatusByCopying(s3Client,                    bucketName,                    keyNameToCopyAndEncrypt,                    copiedObjectKeyName);        } catch (AmazonServiceException e){            // The call was transmitted successfully, but Amazon S3 couldn't process            // it, so it returned an error response.            e.printStackTrace();        } catch (SdkClientException e){            // Amazon S3 couldn't be contacted for a response, or the client            // couldn't parse the response from Amazon S3.            e.printStackTrace();        }    }    private static void uploadObjectWithSSEEncryption(AmazonS3 s3Client, String bucketName, String keyName){        String objectContent = "Test object encrypted with SSE";        byte[] objectBytes = objectContent.getBytes();        // Specify server-side encryption.        ObjectMetadata objectMetadata = new ObjectMetadata();        objectMetadata.setContentLength(objectBytes.length);        objectMetadata.setSSEAlgorithm(ObjectMetadata.AES_256_SERVER_SIDE_ENCRYPTION);        PutObjectRequest putRequest = new PutObjectRequest(bucketName,                keyName,                new ByteArrayInputStream(objectBytes),                objectMetadata);        // Upload the object and check its encryption status.        PutObjectResult putResult = s3Client.putObject(putRequest);        System.out.println("Object \"" + keyName + "\" uploaded with SSE.");        printEncryptionStatus(putResult);    }    private static void changeSSEEncryptionStatusByCopying(AmazonS3 s3Client,            String bucketName,            String sourceKey,            String destKey){        // Upload a new, unencrypted object.        PutObjectResult putResult = s3Client.putObject(bucketName, sourceKey, "Object example to encrypt by copying");        System.out.println("Unencrypted object \"" + sourceKey + "\" uploaded.");        printEncryptionStatus(putResult);        // Make a copy of the object and use server-side encryption when storing the        // copy.        CopyObjectRequest request = new CopyObjectRequest(bucketName,                sourceKey,                bucketName,                destKey);        ObjectMetadata objectMetadata = new ObjectMetadata();        objectMetadata.setSSEAlgorithm(ObjectMetadata.AES_256_SERVER_SIDE_ENCRYPTION);        request.setNewObjectMetadata(objectMetadata);        // Perform the copy operation and display the copy's encryption status.        CopyObjectResult response = s3Client.copyObject(request);        System.out.println("Object \"" + destKey + "\" uploaded with SSE.");        printEncryptionStatus(response);        // Delete the original, unencrypted object, leaving only the encrypted copy in        // Amazon S3.        s3Client.deleteObject(bucketName, sourceKey);        System.out.println("Unencrypted object \"" + sourceKey + "\" deleted.");    }    private static void printEncryptionStatus(SSEResultBase response){        String encryptionStatus = response.getSSEAlgorithm();        if (encryptionStatus == null){            encryptionStatus = "Not encrypted with SSE";        }        System.out.println("Object encryption status is: " + encryptionStatus);    }}

.NET

When you upload an object, you can direct Amazon S3 to encrypt it. To change the encryption state of an existing object, you make a copy of the object and delete the source object. By default, the copy operation encrypts the target only if you explicitly request server-side encryption of the target object. To specify SSE-S3 in theCopyObjectRequest, add the following:

 ServerSideEncryptionMethod = ServerSideEncryptionMethod.AES256

For a working sample of how to copy an object, seeUsing the AWS SDKs.

The following example uploads an object. In the request, the example directs Amazon S3 to encrypt the object. The example then retrieves object metadata and verifies the encryption method that was used. For information about setting up and running the code examples, seeGetting Started with the AWS SDK for .NET in theAWS SDK for .NET Developer Guide.

using Amazon;using Amazon.S3;using Amazon.S3.Model;using System;using System.Threading.Tasks;namespace Amazon.DocSamples.S3{    class SpecifyServerSideEncryptionTest{        private const string bucketName = "*** bucket name ***";        private const string keyName = "*** key name for object created ***";        // Specify your bucket region (an example region is shown).        private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2;        private static IAmazonS3 client;        public static void Main(){            client = new AmazonS3Client(bucketRegion);            WritingAnObjectAsync().Wait();        }        static async Task WritingAnObjectAsync(){            try{                var putRequest = new PutObjectRequest{                    BucketName = bucketName,                    Key = keyName,                    ContentBody = "sample text",                    ServerSideEncryptionMethod = ServerSideEncryptionMethod.AES256                };                var putResponse = await client.PutObjectAsync(putRequest);                // Determine the encryption state of an object.                GetObjectMetadataRequest metadataRequest = new GetObjectMetadataRequest{                    BucketName = bucketName,                    Key = keyName                };                GetObjectMetadataResponse response = await client.GetObjectMetadataAsync(metadataRequest);                ServerSideEncryptionMethod objectEncryption = response.ServerSideEncryptionMethod;                Console.WriteLine("Encryption method used:{0}", objectEncryption.ToString());            }            catch (AmazonS3Exception e){                Console.WriteLine("Error encountered ***. Message:'{0}' when writing an object", e.Message);            }            catch (Exception e){                Console.WriteLine("Unknown encountered on server. Message:'{0}' when writing an object", e.Message);            }        }    }}

PHP

This topic shows how to use classes from version 3 of the AWS SDK for PHP to add SSE-S3 to objects that you upload to Amazon S3. For more information about the AWS SDK for Ruby API, go toAWS SDK for Ruby - Version 2.

To upload an object to Amazon S3, use theAws\S3\S3Client::putObject() method. To add thex-amz-server-side-encryption request header to your upload request, specify theServerSideEncryption parameter with the valueAES256, as shown in the following code example. For information about server-side encryption requests, seeUsing the REST API.

 require 'vendor/autoload.php';use Aws\S3\S3Client;$bucket = '*** Your Bucket Name ***';$keyname = '*** Your Object Key ***';// $filepath should be an absolute path to a file on disk.$filepath = '*** Your File Path ***';$s3 = new S3Client([    'version' => 'latest',    'region'  => 'us-east-1']);// Upload a file with server-side encryption.$result = $s3->putObject([    'Bucket'               => $bucket,    'Key'                  => $keyname,    'SourceFile'           => $filepath,    'ServerSideEncryption' => 'AES256',]);

In response, Amazon S3 returns thex-amz-server-side-encryption header with the value of the encryption algorithm that was used to encrypt your object's data.

When you upload large objects by using the multipart upload API operation, you can specify SSE-S3 for the objects that you are uploading, as follows:

• When you're using the low-level multipart upload API operation, specify server-side encryption when you call the Aws\S3\S3Client::createMultipartUpload() method. To add thex-amz-server-side-encryption request header to your request, specify thearray parameter'sServerSideEncryption key with the valueAES256. For more information about the low-level multipart upload API operation, seeUsing the AWS SDKs (low-level API).

• When you're using the high-level multipart upload API operation, specify server-side encryption by using theServerSideEncryption parameter of theCreateMultipartUpload API operation. For an example of using thesetOption() method with the high-level multipart upload API operation, seeUploading an object using multipart upload.

To determine the encryption state of an existing object, retrieve the object metadata by calling theAws\S3\S3Client::headObject() method as shown in the following PHP code example.

 require 'vendor/autoload.php';use Aws\S3\S3Client;$bucket = '*** Your Bucket Name ***';$keyname = '*** Your Object Key ***';$s3 = new S3Client([    'version' => 'latest',    'region'  => 'us-east-1']);// Check which server-side encryption algorithm is used.$result = $s3->headObject([    'Bucket' => $bucket,    'Key'    => $keyname,]);echo $result['ServerSideEncryption'];

To change the encryption state of an existing object, make a copy of the object by using theAws\S3\S3Client::copyObject() method and delete the source object. By default,copyObject() does not encrypt the target unless you explicitly request server-side encryption of the destination object by using theServerSideEncryption parameter with the valueAES256. The following PHP code example makes a copy of an object and adds server-side encryption to the copied object.

 require 'vendor/autoload.php';use Aws\S3\S3Client;$sourceBucket = '*** Your Source Bucket Name ***';$sourceKeyname = '*** Your Source Object Key ***';$targetBucket = '*** Your Target Bucket Name ***';$targetKeyname = '*** Your Target Object Key ***';$s3 = new S3Client([    'version' => 'latest',    'region'  => 'us-east-1']);// Copy an object and add server-side encryption.$s3->copyObject([    'Bucket'               => $targetBucket,    'Key'                  => $targetKeyname,    'CopySource'           => "$sourceBucket/$sourceKeyname",    'ServerSideEncryption' => 'AES256',]);

For more information, see the following topics:

• AWS SDK for PHP for Amazon S3 Aws\S3\S3Client Class

• AWS SDK for PHP Documentation

Ruby

When using the AWS SDK for Ruby to upload an object, you can specify that the object be stored encrypted at rest with SSE-S3. When you read the object back, it is automatically decrypted.

The following AWS SDK for Ruby Version 3 example demonstrates how to specify that a file uploaded to Amazon S3 be encrypted at rest.

require 'aws-sdk-s3'# Wraps Amazon S3 object actions.class ObjectPutSseWrapper  attr_reader :object  # @param object [Aws::S3::Object] An existing Amazon S3 object.  def initialize(object)    @object = object  end  def put_object_encrypted(object_content, encryption)    @object.put(body: object_content, server_side_encryption: encryption)    true  rescue Aws::Errors::ServiceError => e    puts "Couldn't put your content to #{object.key}. Here's why: #{e.message}"    false  endend# Example usage:def run_demo  bucket_name = "amzn-s3-demo-bucket"  object_key = "my-encrypted-content"  object_content = "This is my super-secret content."  encryption = "AES256"  wrapper = ObjectPutSseWrapper.new(Aws::S3::Object.new(bucket_name, object_content))  return unless wrapper.put_object_encrypted(object_content, encryption)  puts "Put your content into #{bucket_name}:#{object_key} and encrypted it with #{encryption}."endrun_demo if $PROGRAM_NAME == __FILE__

The following code example demonstrates how to determine the encryption state of an existing object.

require 'aws-sdk-s3'# Wraps Amazon S3 object actions.class ObjectGetEncryptionWrapper  attr_reader :object  # @param object [Aws::S3::Object] An existing Amazon S3 object.  def initialize(object)    @object = object  end  # Gets the object into memory.  #  # @return [Aws::S3::Types::GetObjectOutput, nil] The retrieved object data if successful; otherwise nil.  def object    @object.get  rescue Aws::Errors::ServiceError => e    puts "Couldn't get object #{@object.key}. Here's why: #{e.message}"  endend# Example usage:def run_demo  bucket_name = "amzn-s3-demo-bucket"  object_key = "my-object.txt"  wrapper = ObjectGetEncryptionWrapper.new(Aws::S3::Object.new(bucket_name, object_key))  obj_data = wrapper.get_object  return unless obj_data  encryption = obj_data.server_side_encryption.nil? ? 'no' : obj_data.server_side_encryption  puts "Object #{object_key} uses #{encryption} encryption."endrun_demo if $PROGRAM_NAME == __FILE__

If server-side encryption is not used for the object that is stored in Amazon S3, the method returnsnull.

To change the encryption state of an existing object, make a copy of the object and delete the source object. By default, the copy methods do not encrypt the target unless you explicitly request server-side encryption. You can request the encryption of the target object by specifying theserver_side_encryption value in the option's hash argument, as shown in the following Ruby code example. The code example demonstrates how to copy an object and encrypt the copy with SSE-S3.

require 'aws-sdk-s3'# Wraps Amazon S3 object actions.class ObjectCopyEncryptWrapper  attr_reader :source_object  # @param source_object [Aws::S3::Object] An existing Amazon S3 object. This is used as the source object for  #                                        copy actions.  def initialize(source_object)    @source_object = source_object  end  # Copy the source object to the specified target bucket, rename it with the target key, and encrypt it.  #  # @param target_bucket [Aws::S3::Bucket] An existing Amazon S3 bucket where the object is copied.  # @param target_object_key [String] The key to give the copy of the object.  # @return [Aws::S3::Object, nil] The copied object when successful; otherwise, nil.  def copy_object(target_bucket, target_object_key, encryption)    @source_object.copy_to(bucket: target_bucket.name, key: target_object_key, server_side_encryption: encryption)    target_bucket.object(target_object_key)  rescue Aws::Errors::ServiceError => e    puts "Couldn't copy #{@source_object.key} to #{target_object_key}. Here's why: #{e.message}"  endend# Example usage:def run_demo  source_bucket_name = "amzn-s3-demo-bucket1"  source_key = "my-source-file.txt"  target_bucket_name = "amzn-s3-demo-bucket2"  target_key = "my-target-file.txt"  target_encryption = "AES256"  source_bucket = Aws::S3::Bucket.new(source_bucket_name)  wrapper = ObjectCopyEncryptWrapper.new(source_bucket.object(source_key))  target_bucket = Aws::S3::Bucket.new(target_bucket_name)  target_object = wrapper.copy_object(target_bucket, target_key, target_encryption)  return unless target_object  puts "Copied #{source_key} from #{source_bucket_name} to #{target_object.bucket_name}:#{target_object.key} and "\       "encrypted the target with #{target_object.server_side_encryption} encryption."endrun_demo if $PROGRAM_NAME == __FILE__

aws s3api put-object --bucketamzn-s3-demo-bucket1 --keyobject-key-name --server-side-encryption AES256  --bodyfile path

For more information, seeput-object in theAWS CLI reference. To specify SSE-S3 when you copy an object by using the AWS CLI, seecopy-object.

For examples of setting up encryption using AWS CloudFormation, seeCreate a bucket with default encryption and theCreate a bucket by using AWS KMS server-side encryption with an S3 Bucket Key example in theAWS::S3::Bucket ServerSideEncryptionRule topic in theAWS CloudFormation User Guide.