Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Encryption at rest

Amazon ECR stores images in Amazon S3 buckets that Amazon ECR manages. By default, Amazon ECR uses server-side encryption with Amazon S3-managed encryption keys which encrypts your data at rest using an AES-256 encryption algorithm. This does not require any action on your part and is offered at no additional charge. For more information, see Protecting Data Using Server-Side Encryption with Amazon S3-Managed Encryption Keys (SSE-S3) in the Amazon Simple Storage Service User Guide.

For more control over the encryption for your Amazon ECR repositories, you can use server-side encryption with KMS keys stored in Amazon Key Management Service (Amazon KMS). When you use Amazon KMS to encrypt your data, you can either use the default Amazon managed key, which is managed by Amazon ECR, or specify your own KMS key (referred to as a customer managed key). For more information, see Protecting Data Using Server-Side Encryption with KMS keys Stored in Amazon KMS (SSE-KMS) in the Amazon Simple Storage Service User Guide.

Each Amazon ECR repository has an encryption configuration, which is set when the repository is created. You can use different encryption configurations on each repository. For more information, see Creating a private repository.

When a repository is created with Amazon KMS encryption enabled, a KMS key is used to encrypt the contents of the repository. Moreover, Amazon ECR adds an Amazon KMS grant to the KMS key with the Amazon ECR repository as the grantee principal.

The following provides a high-level understanding of how Amazon ECR is integrated with Amazon KMS to encrypt and decrypt your repositories:

Considerations

The following points should be considered when using Amazon KMS encryption with Amazon ECR.

Required IAM permissions

When creating or deleting an Amazon ECR repository with server-side encryption using Amazon KMS, the permissions required depend on the specific KMS key you are using.

Required IAM permissions when using the Amazon managed key for Amazon ECR

By default, when Amazon KMS encryption is enabled for an Amazon ECR repository but no KMS key is specified, the Amazon managed key for Amazon ECR is used. When the Amazon-managed KMS key for Amazon ECR is used to encrypt a repository, any principal that has permission to create a repository can also enable Amazon KMS encryption on the repository. However, the IAM principal that deletes the repository must have the kms:RetireGrant permission. This enables the retirement of the grants that were added to the Amazon KMS key when the repository was created.

The following example IAM policy can be added as an inline policy to a user to ensure they have the minimum permissions needed to delete a repository that has encryption enabled. The KMS key used to encrypt the repository can be specified using the resource parameter.

{
    "Version": "2012-10-17",
    "Id": "ecr-kms-permissions",
    "Statement": [
        {
            "Sid": "AllowAccessToRetireTheGrantsAssociatedWithTheKey",
            "Effect": "Allow",
            "Action": [
                "kms:RetireGrant"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/b8d9ae76-080c-4043-92EXAMPLE"
        }
    ]
}

Required IAM permissions when using a customer managed key

When creating a repository with Amazon KMS encryption enabled using a customer managed key, there are required permissions for both the KMS keypolicy and the IAM policy for the user or role creating the repository.

When creating your own KMS key, you can either use the default key policy Amazon KMS creates or you can specify your own. To ensure that the customer managed key remains manageable by the account owner, the key policy for the KMS key should allow all Amazon KMS actions for the root user of the account. Additional scoped permissions may be added to the key policy but at minimum the root user should be given permissions to manage the KMS key. To allow the KMS key to be used only for requests that originate in Amazon ECR, you can use the kms:ViaService condition key with the ecr.<region>.amazonaws.com value.

The following example key policy gives the Amazon account (root user) that owns the KMS key full access to the KMS key. For more information about this example key policy, see Allows access to the Amazon account and enables IAM policies in the Amazon Key Management Service Developer Guide.

{
    "Version": "2012-10-17",
    "Id": "ecr-key-policy",
    "Statement": [
        {
            "Sid": "EnableIAMUserPermissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::111122223333:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        }
    ]
}

The IAM user, IAM role, or Amazon account creating your repositories must have the kms:CreateGrant, kms:RetireGrant, and kms:DescribeKey permission in addition to the necessary Amazon ECR permissions.

The following example IAM policy can be added as an inline policy to a user to ensure they have the minimum permissions needed to create a repository with encryption enabled and delete the repository when they are finished with it. The Amazon KMS key used to encrypt the repository can be specified using the resource parameter.

{
    "Version": "2012-10-17",
    "Id": "ecr-kms-permissions",
    "Statement": [
        {
            "Sid": "AllowAccessToCreateAndRetireTheGrantsAssociatedWithTheKeyAsWellAsDescribeTheKey",
            "Effect": "Allow",
            "Action": [
                "kms:CreateGrant",
                "kms:RetireGrant",
                "kms:DescribeKey"
            ],
            "Resource": "arn:aws:kms:us-west-2:111122223333:key/b8d9ae76-080c-4043-92EXAMPLE"
        }
    ]
}

Allow a user to list KMS keys in the console when creating a repository

When using the Amazon ECR console to create a repository, you can grant permissions to enable a user to list the customer managed KMS keys in the Region when enabling encryption for the repository. The following IAM policy example shows the permissions needed to list your KMS keys and aliases when using the console.

{
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Action": [
      "kms:ListKeys",
      "kms:ListAliases",
      "kms:DescribeKey"
    ],
    "Resource": "*"
  }
}

Monitoring Amazon ECR interaction with Amazon KMS

You can use Amazon CloudTrail to track the requests that Amazon ECR sends to Amazon KMS on your behalf. The log entries in the CloudTrail log contain an encryption context key to make them more easily identifiable.

Amazon ECR encryption context

An encryption context is a set of key–value pairs that contains arbitrary nonsecret data. When you include an encryption context in a request to encrypt data, Amazon KMS cryptographically binds the encryption context to the encrypted data. To decrypt the data, you must pass in the same encryption context.

In its GenerateDataKey and Decrypt requests to Amazon KMS, Amazon ECR uses an encryption context with two name–value pairs that identify the repository and Amazon S3 bucket being used. This is shown in the following example. The names do not vary, but combined encryption context values will be different for each value.

"encryptionContext": {
    "aws:s3:arn": "arn:aws:s3:::us-west-2-starport-manifest-bucket/EXAMPLE1-90ab-cdef-fedc-ba987BUCKET1/sha256:a7766145a775d39e53a713c75b6fd6d318740e70327aaa3ed5d09e0ef33fc3df",
    "aws:ecr:arn": "arn:aws:ecr:us-west-2:111122223333:repository/repository-name"
}

You can use the encryption context to identify these cryptographic operation in audit records and logs, such as Amazon CloudTrail and Amazon CloudWatch Logs, and as a condition for authorization in policies and grants.

The Amazon ECR encryption context consists of two name-value pairs.

Troubleshooting

When deleting an Amazon ECR repository with the console, if the repository is successfully deleted but Amazon ECR is unable to retire the grants added to your KMS key for your repository, you will receive the following error.

The repository [{repository-name}] has been deleted successfully but the grants created by the kmsKey [{kms_key}] failed to be retired

When this occurs, you can retire the Amazon KMS grants for the repository yourself.