Analyzing encrypted S3 objects with Amazon Macie
When you enable Amazon Macie for your AWS account, Macie creates a service-linked role that grants Macie the permissions
that it requires to call Amazon Simple Storage Service (Amazon S3) and other AWS services on your behalf. The
permissions policy for this role
(AWSServiceRoleForAmazonMacie
) allows Macie to perform
actions that include retrieving information about your S3 buckets and objects, and retrieving
and analyzing objects in your S3 buckets. If your account is the Macie administrator account for an
organization, the policy also allows Macie to perform these actions for member accounts in
your organization.
If an S3 object is encrypted, the permissions policy for the service-linked role typically grants Macie the permissions that it requires to decrypt and inspect the object for sensitive data. However, this depends on the type of encryption that was used to encrypt the object. It can also depend on whether Macie is allowed to use the appropriate encryption key.
Encryption options for S3 objects
Amazon S3 supports multiple encryption options for S3 objects. For most of these options, Macie
can decrypt and analyze an object by using the
AWSServiceRoleForAmazonMacie
service-linked role for your
account. However, this depends on the type of encryption that was used to encrypt an
object.
- Server-side encryption with Amazon S3 managed keys (SSE-S3)
-
If an object is encrypted using server-side encryption with an Amazon S3 managed key, Macie can decrypt and analyze the object.
To learn about this type of encryption, see Protecting data using server-side encryption with Amazon S3 managed encryption keys in the Amazon Simple Storage Service User Guide.
- Server-side encryption with AWS KMS keys (SSE-KMS)
-
If an object is encrypted using server-side encryption with an AWS managed AWS KMS key, Macie can decrypt and analyze the object.
If an object is encrypted using server-side encryption with a customer managed AWS KMS key, Macie can decrypt and analyze the object only if you allow Macie to use the key. Otherwise, Macie can only store and report metadata for the object.
To learn about this type of encryption, see Protecting data using server-side encryption with KMS keys stored in AWS Key Management Service in the Amazon Simple Storage Service User Guide.
- Server-side encryption with customer-provided keys (SSE-C)
-
If an object is encrypted using server-side encryption with a customer-provided key, Macie can't decrypt and analyze the object. Macie can only store and report metadata for the object.
To learn about this type of encryption, see Protecting data using server-side encryption with customer-provided encryption keys in the Amazon Simple Storage Service User Guide.
- Client-side encryption
-
If an object is encrypted using client-side encryption, Macie can't decrypt and analyze the object. Macie can only store and report metadata for the object. For example, Macie can report the size of the object and the tags that are associated with the object.
To learn about this type of encryption in the context of Amazon S3, see Protecting data using client-side encryption in the Amazon Simple Storage Service User Guide.
You can filter your bucket inventory in Macie to determine which S3 buckets contain objects that use certain types of encryption. You can also determine which buckets use certain types of server-side encryption by default when storing new objects. The following table provides some example filters that you can apply to your bucket inventory to find this information.
To show buckets that... | Apply this filter... |
---|---|
Contain objects that use SSE-C encryption | Object count by encryption is Customer managed and From = 1 |
Contain objects that use SSE-KMS encryption | Object count by encryption is SSE-KMS managed and From = 1 |
Contain objects that use SSE-S3 encryption | Object count by encryption is SSE-S3 managed and From = 1 |
Contain objects that use client-side encryption (or aren't encrypted) | Object count by encryption is No encryption and From = 1 |
Encrypt new objects by default using SSE-KMS encryption | Default encryption = aws:kms |
Encrypt new objects by default using SSE-S3 encryption | Default encryption = AES256 |
If a bucket is configured to encrypt new objects by default using SSE-KMS encryption, you can also determine which AWS KMS key is used. To do this, choose the bucket in the table on the S3 buckets page. In the bucket details panel, under Server-side encryption, refer to the KMS key field. This field shows the Amazon Resource Name (ARN) or unique identifier (key ID) for the key.
Allowing Macie to use a customer managed AWS KMS key
If an S3 object is encrypted using a customer managed AWS KMS key (SSE-KMS encryption), Macie can decrypt and analyze the object only if Macie is allowed to use the KMS key. How to provide this access depends on whether the account that owns the key also owns the S3 bucket that stores the object:
-
If the same account owns the KMS key and the bucket, a user of the account has to update the key's policy.
-
If one account owns the KMS key and a different account owns the bucket, the account that owns the key has to allow cross-account access to the key.
This topic describes how to perform these tasks and provides examples for both scenarios.
Allowing same-account access to a customer managed key
If the same account owns both the AWS KMS key and the bucket, a user of the account has to add a statement to the policy for the KMS key. The additional statement must allow the Macie service-linked role for the account to use the key to decrypt data. For detailed information about updating a key policy, see Changing a key policy in the AWS Key Management Service Developer Guide.
In the statement, the Principal
element must specify the Amazon Resource Name
(ARN) of the Macie service-linked role for the account that owns the KMS key and the
bucket. If the account is in a manually enabled AWS Region, the ARN must include the
appropriate Region code for the Region. For example, if the account is in the
Middle East (Bahrain) Region, which has the Region code me-south-1, the Principal
element must specify
arn:aws:iam::
,
where 123456789012
:role/aws-service-role/macie.me-south-1.amazonaws.com/AWSServiceRoleForAmazonMacie123456789012
is the account ID for the
account.
The Action
array must specify the kms:Decrypt
action. This is the
only AWS KMS action that Macie must be allowed to perform to decrypt an object that was
encrypted with the key.
The following is an example of the statement to add to the policy for a KMS key.
{ "Sid": "Allow the Macie service-linked role to use the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::
123456789012
:role/aws-service-role/macie.amazonaws.com/AWSServiceRoleForAmazonMacie" }, "Action": [ "kms:Decrypt" ], "Resource": "*" }
In the preceding example:
-
The
AWS
field in thePrincipal
element specifies the ARN of the Macie service-linked role (AWSServiceRoleForAmazonMacie
) for the account. It allows the Macie service-linked role to perform the action specified by the policy statement.123456789012
is an example account ID. Replace this ID with the account ID for the account that owns the KMS key and the bucket. -
The
Action
array specifies the action that the Macie service-linked role is allowed to perform using the KMS key—decrypt ciphertext that was encrypted with the key.
Where you add this statement to a key policy depends on the structure and elements that the policy currently contains. When you add the statement, ensure that the syntax is valid. Key policies use JSON format. This means that you have to also add a comma before or after the statement, depending on where you add the statement to the policy.
Allowing cross-account access to a customer managed key
If one account owns the AWS KMS key (key owner) and a different account owns the bucket (bucket owner), the key owner has to provide the bucket owner with cross-account access to the KMS key. To do this, the key owner first ensures that the key's policy allows the bucket owner to both use the key and create a grant for the key. The bucket owner then creates a grant for the key. The grant delegates the relevant permissions to the Macie service-linked role for the bucket owner's account.
A grant is a policy instrument that allows AWS principals to use KMS keys in cryptographic operations if the conditions specified by the grant are met. To learn about grants, see Using grants in the AWS Key Management Service Developer Guide.
In the key policy, the key owner should ensure that the policy includes two statements. The first statement allows the bucket owner to use the key to decrypt data. The second statement allows the bucket owner to create a grant for the Macie service-linked role for the bucket owner's account. For detailed information about updating a key policy, see Changing a key policy in the AWS Key Management Service Developer Guide.
In the first statement, the Principal
element must specify the ARN of the
bucket owner's account. The Action
array must specify the
kms:Decrypt
action. This is the only AWS KMS action that Macie must be
allowed to perform to decrypt an object that was encrypted with the key.
The following is an example of this statement in the policy for a KMS key.
{ "Sid": "Allow account
111122223333
to use the key", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333
:root" }, "Action": [ "kms:Decrypt" ], "Resource": "*" }
In the preceding example:
-
The
AWS
field in thePrincipal
element specifies the ARN of the bucket owner's account (111122223333
). It allows the bucket owner to perform the action specified by the policy statement.111122223333
is an example account ID. Replace this ID with the account ID for the bucket owner's account. -
The
Action
array specifies the action that the bucket owner is allowed to perform using the KMS key—decrypt ciphertext that was encrypted with the key.
The second statement in the key policy allows the bucket owner to create a grant for the
Macie service-linked role for their account. In this statement, the
Principal
element must specify the ARN of the bucket's owner's
account. The Action
array must specify the kms:CreateGrant
action. A Condition
element can filter access to the
kms:CreateGrant
action specified in the statement.
The following is an example of this statement in the policy for a KMS key.
{ "Sid": "Allow account
111122223333
to create a grant", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333
:root" }, "Action": [ "kms:CreateGrant" ], "Resource": "*", "Condition": { "StringEquals": { "kms:GranteePrincipal": "arn:aws:iam::111122223333
:role/aws-service-role/macie.amazonaws.com/AWSServiceRoleForAmazonMacie" } } }
In the preceding example:
-
The
AWS
field in thePrincipal
element specifies the ARN of the bucket owner's account (111122223333
). It allows the bucket owner to perform the action specified by the policy statement.111122223333
is an example account ID. Replace this ID with the account ID for the bucket owner's account. -
The
Action
array specifies the action that the bucket owner is allowed to perform on the KMS key—create a grant for the key. -
The
Condition
element uses theStringEquals
condition operator and thekms:GranteePrincipal
condition key to filter access to the action specified by the policy statement. In this case, the bucket owner can create a grant only for the specifiedGranteePrincipal
, which is the ARN of the Macie service-linked role for the bucket owner’s account. In that ARN,111122223333
is an example account ID. Replace this ID with the account ID for the bucket owner's account.If the bucket owner's account is in a manually enabled AWS Region, also include the appropriate Region code in the ARN of the Macie service-linked role. For example, if the account is in the Middle East (Bahrain) Region, which has the Region code me-south-1, replace
macie.amazonaws.com
withmacie.me-south-1.amazonaws.com
in the ARN.
Where the key owner adds these statements to the key policy depends on the structure and elements that the policy currently contains. When the key owner adds the statement, they should ensure that the syntax is valid. Key policies use JSON format. This means that the key owner has to also add a comma before or after the statement, depending on where they add the statement to the policy.
After the key owner updates the key policy as necessary, the bucket owner must create a
grant for the key. The grant delegates the relevant permissions to the Macie
service-linked role for their (the bucket owner's) account. Before the bucket owner
creates the grant, they should verify that they're allowed to perform the
kms:CreateGrant
action for their account. This action allows them to add
a grant to an existing, customer managed KMS key.
To create the grant, the bucket owner can use the CreateGrant operation of the AWS Key Management Service API. When the bucket owner creates the grant, they should specify the following values for the required parameters:
-
GranteePrincipal – The ARN of the Macie service-linked role (
AWSServiceRoleForAmazonMacie
) for their account. This value should bearn:aws:iam::
, where111122223333
:role/aws-service-role/macie.amazonaws.com/AWSServiceRoleForAmazonMacie111122223333
is the account ID for the bucket owner's account.If their account is in a manually enabled Region, the ARN must include the appropriate Region code. For example, if the account is in the Middle East (Bahrain) Region, which has the Region code me-south-1, the ARN should be
arn:aws:iam::
, where111122223333
:role/aws-service-role/macie.me-south-1.amazonaws.com/AWSServiceRoleForAmazonMacie111122223333
is the account ID for the bucket owner's account. -
KeyId – The ARN of the KMS key. For cross-account access to a KMS key, this value must be an ARN. It can't be a key ID.
-
Operations – The AWS KMS decrypt action (
Decrypt
). This is the only AWS KMS action that Macie must be allowed to perform to decrypt an object that was encrypted with the KMS key.
The following example shows how to use the AWS Command Line Interface (AWS CLI) to create a grant for a customer managed KMS key. The example uses the create-grant command of the AWS Key Management Service API. The example is formatted for Microsoft Windows and it uses the caret (^) line-continuation character to improve readability.
C:\>
aws kms create-grant ^ --key-id arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab ^ --grantee-principal arn:aws:iam::111122223333:role/aws-service-role/macie.amazonaws.com/AWSServiceRoleForAmazonMacie ^ --operations "Decrypt"
Where:
-
key-id
specifies the ARN of the KMS key to apply the grant to. -
grantee-principal
specifies the ARN of the Macie service-linked role for the account that's allowed to perform the operation specified by the grant. This value should match the ARN that's specified by thekms:GranteePrincipal
condition of the second statement in the key policy. -
operations
specifies the operation that the grant allows the specified principal to perform—decrypt ciphertext that was encrypted with the key.
If the command runs successfully, AWS KMS responds with output that's similar to the following.
{
"GrantToken": "<grant token>",
"GrantId": "1a2b3c4d2f5e69f440bae30eaec9570bb1fb7358824f9ddfa1aa5a0dab1a59b2"
}
Where GrantToken
is a unique, non-secret, variable-length,
base64-encoded string that represents the grant that was created, and
GrantId
is the unique identifier for the grant.