Analyzing encrypted S3 objects with Amazon Macie - Amazon Macie
Encryption options for S3 objectsAllowing Macie to use a customer managed KMS key

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::123456789012:role/aws-service-role/macie.me-south-1.amazonaws.com/AWSServiceRoleForAmazonMacie, where 123456789012 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 the Principal 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 the Principal 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 the Principal 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 the StringEquals condition operator and the kms: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 specified GranteePrincipal, 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 with macie.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 be arn:aws:iam::111122223333:role/aws-service-role/macie.amazonaws.com/AWSServiceRoleForAmazonMacie, where 111122223333 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::111122223333:role/aws-service-role/macie.me-south-1.amazonaws.com/AWSServiceRoleForAmazonMacie, where 111122223333 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 the kms: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.