Replicating encrypted objects
By default, Amazon S3 doesn't replicate objects that are encrypted by using server-side encryption with AWS Key Management Service (AWS KMS) keys (SSE-KMS) or dual-layer server-side encryption with AWS KMS keys (DSSE-KMS). To replicate objects encrypted with SSE-KMS or DSS-KMS, you must modify the bucket replication configuration to tell Amazon S3 to replicate these objects. This example explains how to use the Amazon S3 console and the AWS Command Line Interface (AWS CLI) to change the bucket replication configuration to enable replicating encrypted objects.
For more information, see Replicating objects created with server-side encryption (SSE-C, SSE-S3, SSE-KMS, DSSE-KMS).
Note
When an S3 Bucket Key is enabled for the source or destination bucket, the encryption context will be the bucket's Amazon Resource Name (ARN), not the object's ARN. You must update your IAM policies to use the bucket ARN for the encryption context. For more information, see S3 Bucket Keys and replication.
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 AWS Key Management Service Developer Guide.
For step-by-step instructions, see Configuring replication for source and destination buckets owned by the same account. This topic provides instructions for setting a replication configuration when the buckets are owned by the same and different AWS accounts.
To replicate encrypted objects with the AWS CLI, you do the following:
-
Create source and destination buckets and enable versioning on these buckets.
-
Create an AWS Identity and Access Management (IAM) service role that gives Amazon S3 permission to replicate objects. The IAM role's permissions include the necessary permissions to replicate the encrypted objects.
-
Add a replication configuration to the source bucket. The replication configuration provides information related to replicating objects that are encrypted by using KMS keys.
-
Add encrypted objects to the source bucket.
-
Test the setup to confirm that your encrypted objects are being replicated to the destination bucket.
The following procedures walk you through this process.
To replicate server-side encrypted objects (AWS CLI)
-
In this example, you create both the
andDOC-EXAMPLE-SOURCE-BUCKET
buckets in the same AWS account. You also set a credentials profile for the AWS CLI. This example uses the profile nameDOC-EXAMPLE-DESTINATION-BUCKET
.acctA
For more information about setting credential profiles, see Named Profiles in the AWS Command Line Interface User Guide. To use the commands in this example, replace the
with your own information.user input placeholders
-
Use the following commands to create the
bucket and enable versioning on it. The following example commands create theDOC-EXAMPLE-SOURCE-BUCKET
bucket in the US East (N. Virginia) (DOC-EXAMPLE-SOURCE-BUCKET
us-east-1
) Region.aws s3api create-bucket \ --bucket
\ --regionDOC-EXAMPLE-SOURCE-BUCKET
us-east-1
\ --profileacctA
aws s3api put-bucket-versioning \ --bucket
\ --versioning-configuration Status=Enabled \ --profileDOC-EXAMPLE-SOURCE-BUCKET
acctA
-
Use the following commands to create the
bucket and enable versioning on it. The following example commands create theDOC-EXAMPLE-DESTINATION-BUCKET
bucket in the US West (Oregon) (DOC-EXAMPLE-DESTINATION-BUCKET
us-west-2
) Region.Note
To set up a replication configuration when both
andDOC-EXAMPLE-SOURCE-BUCKET
buckets are in the same AWS account, you use the same profile. In this example, we useDOC-EXAMPLE-DESTINATION-BUCKET
. To configure replication when the buckets are owned by different AWS accounts, you specify different profiles for each.acctA
aws s3api create-bucket \ --bucket
\ --regionDOC-EXAMPLE-DESTINATION-BUCKET
us-west-2
\ --create-bucket-configuration LocationConstraint=us-west-2
\ --profileacctA
aws s3api put-bucket-versioning \ --bucket
\ --versioning-configuration Status=Enabled \ --profileDOC-EXAMPLE-DESTINATION-BUCKET
acctA
-
Next, you create an IAM service role. You will specify this role in the replication configuration that you add to the
bucket later. Amazon S3 assumes this role to replicate objects on your behalf. You create an IAM role in two steps:DOC-EXAMPLE-SOURCE-BUCKET
-
Create a service role.
-
Attach a permissions policy to the role.
-
To create an IAM service role, do the following:
-
Copy the following trust policy and save it to a file called
s3-role-trust-policy-kmsobj.json
in the current directory on your local computer. This policy grants Amazon S3 service principal permissions to assume the role so that Amazon S3 can perform tasks on your behalf.{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"s3.amazonaws.com" }, "Action":"sts:AssumeRole" } ] }
-
Use the following command to create the role:
$
aws iam create-role \ --role-namereplicationRolekmsobj
\ --assume-role-policy-document file://s3-role-trust-policy-kmsobj.json \ --profileacctA
-
-
Next, you attach a permissions policy to the role. This policy grants permissions for various Amazon S3 bucket and object actions.
-
Copy the following permissions policy and save it to a file named
s3-role-permissions-policykmsobj.json
in the current directory on your local computer. You will create an IAM role and attach the policy to it later.Important
In the permissions policy, you specify the AWS KMS key IDs that will be used for encryption of the
andDOC-EXAMPLE-SOURCE-BUCKET
buckets. You must create two separate KMS keys for theDOC-EXAMPLE-DESTINATION-BUCKET
andDOC-EXAMPLE-SOURCE-BUCKET
DOC-EXAMPLE-DESTINATION-BUCKET
buckets. AWS KMS keys are not shared outside the AWS Region in which they were created.{ "Version":"2012-10-17", "Statement":[ { "Action":[ "s3:ListBucket", "s3:GetReplicationConfiguration", "s3:GetObjectVersionForReplication", "s3:GetObjectVersionAcl", "s3:GetObjectVersionTagging" ], "Effect":"Allow", "Resource":[ "arn:aws:s3:::
", "arn:aws:s3:::DOC-EXAMPLE-SOURCE-BUCKET
/*" ] }, { "Action":[ "s3:ReplicateObject", "s3:ReplicateDelete", "s3:ReplicateTags" ], "Effect":"Allow", "Condition":{ "StringLikeIfExists":{ "s3:x-amz-server-side-encryption":[ "aws:kms", "AES256", "aws:kms:dsse" ], "s3:x-amz-server-side-encryption-aws-kms-key-id":[ "DOC-EXAMPLE-SOURCE-BUCKET
AWS KMS key IDs(in ARN format) to use for encrypting object replicas
" ] } }, "Resource":"arn:aws:s3:::
/*" }, { "Action":[ "kms:Decrypt" ], "Effect":"Allow", "Condition":{ "StringLike":{ "kms:ViaService":"s3.us-east-1.amazonaws.com", "kms:EncryptionContext:aws:s3:arn":[ "arn:aws:s3:::DOC-EXAMPLE-DESTINATION-BUCKET
/*" ] } }, "Resource":[ "DOC-EXAMPLE-SOURCE-BUCKET
AWS KMS key IDs(in ARN format) used to encrypt source objects.
" ] }, { "Action":[ "kms:Encrypt" ], "Effect":"Allow", "Condition":{ "StringLike":{ "kms:ViaService":"s3.us-west-2.amazonaws.com", "kms:EncryptionContext:aws:s3:arn":[ "arn:aws:s3:::
/*" ] } }, "Resource":[ "DOC-EXAMPLE-DESTINATION-BUCKET
AWS KMS key IDs(in ARN format) to use for encrypting object replicas
" ] } ] } -
Create a policy and attach it to the role.
$
aws iam put-role-policy \ --role-name replicationRolekmsobj \ --policy-document file://s3-role-permissions-policykmsobj.json \ --policy-name replicationRolechangeownerPolicy \ --profileacctA
-
-
-
Next, add the following replication configuration to the
bucket. It tells Amazon S3 to replicate objects with theDOC-EXAMPLE-SOURCE-BUCKET
Tax/
prefix to the
bucket.DOC-EXAMPLE-DESTINATION-BUCKET
Important
In the replication configuration, you specify the IAM role that Amazon S3 can assume. You can do this only if you have the
iam:PassRole
permission. The profile that you specify in the CLI command must have this permission. For more information, see Granting a user permissions to pass a role to an AWS service in the IAM User Guide.<ReplicationConfiguration> <Role>
IAM-Role-ARN
</Role> <Rule> <Priority>1</Priority> <DeleteMarkerReplication> <Status>Disabled</Status> </DeleteMarkerReplication> <Filter> <Prefix>Tax</Prefix> </Filter> <Status>Enabled</Status> <SourceSelectionCriteria> <SseKmsEncryptedObjects> <Status>Enabled</Status> </SseKmsEncryptedObjects> </SourceSelectionCriteria> <Destination> <Bucket>arn:aws:s3:::
</Bucket> <EncryptionConfiguration> <ReplicaKmsKeyID>DOC-EXAMPLE-DESTINATION-BUCKET
AWS KMS key IDs to use for encrypting object replicas
</ReplicaKmsKeyID> </EncryptionConfiguration> </Destination> </Rule> </ReplicationConfiguration>To add a replication configuration to the
bucket, do the following:DOC-EXAMPLE-SOURCE-BUCKET
-
The AWS CLI requires you to specify the replication configuration as JSON. Save the following JSON in a file (
replication.json
) in the current directory on your local computer.{ "Role":"
IAM-Role-ARN
", "Rules":[ { "Status":"Enabled", "Priority":1, "DeleteMarkerReplication":{ "Status":"Disabled" }, "Filter":{ "Prefix":"Tax" }, "Destination":{ "Bucket":"arn:aws:s3:::
", "EncryptionConfiguration":{ "ReplicaKmsKeyID":"DOC-EXAMPLE-DESTINATION-BUCKET
AWS KMS key IDs (in ARN format) to use for encrypting object replicas
" } }, "SourceSelectionCriteria":{ "SseKmsEncryptedObjects":{ "Status":"Enabled" } } } ] } -
Edit the JSON to provide values for the
bucket,DOC-EXAMPLE-DESTINATION-BUCKET
, andAWS KMS key IDs (in ARN format)
. Save the changes.IAM-role-ARN
-
Use the following command to add the replication configuration to your
bucket. Be sure to provide theDOC-EXAMPLE-SOURCE-BUCKET
bucket name.DOC-EXAMPLE-SOURCE-BUCKET
$
aws s3api put-bucket-replication \ --replication-configuration file://replication.json \ --bucket
\ --profileDOC-EXAMPLE-SOURCE-BUCKET
acctA
-
-
Test the configuration to verify that encrypted objects are replicated. In the Amazon S3 console, do the following:
Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/
. -
In the
bucket, create a folder namedDOC-EXAMPLE-SOURCE-BUCKET
Tax
. -
Add sample objects to the folder. Be sure to choose the encryption option and specify your KMS key to encrypt the objects.
-
Verify that the
bucket contains the object replicas and that they are encrypted by using the KMS key that you specified in the configuration. For more information, see Getting replication status information.DOC-EXAMPLE-DESTINATION-BUCKET
For a code example that shows how to add a replication configuration, see Using the AWS SDKs. You must modify the replication configuration appropriately.
For conceptual information, see Replicating objects created with server-side encryption (SSE-C, SSE-S3, SSE-KMS, DSSE-KMS).