View a markdown version of this page

Sharing KMS keys with Amazon RAM - Amazon Key Management Service
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).

Sharing KMS keys with Amazon RAM

Amazon Key Management Service (Amazon KMS) integrates with Amazon Resource Access Manager (Amazon RAM). With Amazon RAM, you can share KMS keys across your Amazon Web Services accounts, within your organization in Amazon Organizations, and with specific IAM roles and users. You share resources that you own by creating a resource share. For Amazon KMS, a resource share specifies the KMS keys that you want to share and the principals to share them with.

Sharing a KMS key through Amazon RAM doesn't change its existing key policy, which is named default. Every KMS key has a default key policy, whether you wrote it or Amazon KMS created it for you. Amazon RAM generates a second key policy for the KMS key, named AWS_RAM, from the managed permission that you choose for the resource share. The KMS key stays in your account, and you continue to manage it and its default key policy. Amazon KMS evaluates the default key policy and the AWS_RAM key policy together.

For more information about Amazon RAM, see the Amazon RAM User Guide.

This topic explains how to share KMS keys that you own, and how to use KMS keys that are shared with you.

Terminology

This topic uses the following terms.

Owner

The Amazon Web Services account that owns the KMS key and shares it by adding it to a resource share.

Consumer

A principal that a resource share shares the KMS key with.

Managed permission

The Amazon RAM permission that determines what consumers can do with the shared KMS key. Amazon RAM generates the AWS_RAM key policy from it.

When to use Amazon RAM

You can give another principal permission to use a KMS key in two ways. You can add a statement to the default key policy, as described in Allowing users in other accounts to use a KMS key. Or, you can add the KMS key to a resource share in Amazon RAM. You can use both methods for the same KMS key.

Use Amazon RAM

Use Amazon RAM in the following cases:

  • You want to share a KMS key together with related Amazon resources in one resource share.

  • You want to share KMS keys consistently with many Amazon Web Services accounts, with your organization, or with organizational units (OUs) in Amazon Organizations, by using one managed permission instead of writing multiple key policy statements.

  • You want someone else that you trust, such as your central security team or a trusted third-party service provider, to author and manage the permissions on your KMS keys through an Amazon RAM customer managed permission. For more information, see Sharing and using customer managed permissions across accounts in the Amazon RAM User Guide.

Amazon RAM creates and manages the AWS_RAM key policy for you. Consumers can find the KMS keys that are shared with them through Amazon RAM on the Keys shared with me page of the Amazon KMS console and by using the ListKeys operation with the ResourceOwners parameter.

Use a key policy statement

Use a key policy statement when you need granular control, such as Deny statements or condition keys that managed permissions don't support. Amazon RAM managed permissions support only Allow statements.

When a KMS key has both key policies, Amazon KMS evaluates them together. A permission in either key policy can allow access to the KMS key. For more information about how Amazon KMS evaluates the two key policies, see How permissions are evaluated.

Prerequisites and supported KMS keys

Before you share a KMS key, review the following requirements.

  • You can share customer managed keys through Amazon RAM. You can't share Amazon managed keys.

  • To share a KMS key, you must own it in your Amazon Web Services account. You can't share a KMS key that is shared with you.

  • To share a KMS key, you need the following permissions:

    • ram:CreateResourceShare to create a resource share, or ram:AssociateResourceShare to add the KMS key to an existing resource share.

    • kms:PutKeyPolicy on the KMS key. Amazon RAM uses your permissions to create and update the AWS_RAM key policy.

  • The KMS key and the resource share must be in the same Amazon Web Services Region. To add a KMS key to a resource share, specify its key ARN.

  • You can't add a KMS key to a resource share by its alias ARN.

You can share the following types of KMS keys:

  • Symmetric encryption KMS keys

  • Asymmetric KMS keys

  • HMAC KMS keys

  • Multi-Region primary and replica keys

  • KMS keys with imported key material

  • KMS keys in custom key stores (Amazon CloudHSM key stores and external key stores)

Managed permissions for KMS keys

When you create a resource share, you choose a managed permission for each resource type in the share. The managed permission determines the actions that consumers can perform on the shared KMS key. Amazon RAM writes the statements that result from the managed permission into the key's AWS_RAM key policy. For more information about managed permissions, see Managing permissions in Amazon RAM in the Amazon RAM User Guide.

There are two types of managed permissions:

  • Amazon managed permissions are defined by Amazon KMS and managed by Amazon RAM. There is one default managed permission for the KMS key resource type, AWSRAMPermissionKMSKeySymmetricEncryption. If you don't choose a managed permission, Amazon RAM uses the default managed permission. Use an Amazon managed permission when it allows the actions that your consumers need.

  • Customer managed permissions are managed permissions that you author and maintain. Use a customer managed permission when you want to allow a different set of actions, or add conditions. For more information about how managed permissions work, see How managed permissions work in the Amazon RAM User Guide.

    You can also share a customer managed permission with other Amazon Web Services accounts through Amazon RAM. The accounts that you share it with can use it in their own resource shares, but only you can change it. For example, a central security team can author a customer managed permission for KMS keys, share it, and other teams can use it when they share their KMS keys. For more information, see Sharing and using customer managed permissions across accounts in the Amazon RAM User Guide.

Amazon managed permissions don't have a description in Amazon RAM. The following table describes the Amazon managed permissions for KMS keys and when to use each one.

Amazon managed permissions When to use it

AWSRAMPermissionKMSKeySymmetricEncryption (default)

Actions included: kms:Encrypt, kms:Decrypt, kms:ReEncrypt*, kms:GenerateDataKey*, kms:DescribeKey, and kms:ListGrants.

kms:CreateGrant, with a condition that requires kms:GrantIsForAWSResource to be true. Consumers can't create grants directly, but an Amazon service that's integrated with Amazon KMS can create grants for them when it calls Amazon KMS on their behalf.

Amazon RAM uses this managed permission when you don't choose one. It lets the consumers use the KMS key for symmetric encryption, view the KMS key and its grants, and let Amazon services that are integrated with Amazon KMS create grants on their behalf.

AWSRAMPermissionKMSKeyLockoutResistant

Actions included: kms:DescribeKey, kms:GetKeyPolicy, kms:List*, and kms:PutKeyPolicy, only when the caller is the root user of the Amazon Web Services account that owns the KMS key.

Use it to keep the Amazon Web Services account that owns the KMS key able to view and replace the key policy of the shared KMS key, through the account's root user.

Considerations for using managed permissions with KMS keys

Keep the following in mind when you choose or create a managed permission for KMS keys:

  • The default managed permission allows the operations of symmetric encryption KMS keys. To share another kind of KMS key, such as a signing key or an HMAC key, use a customer managed permission that allows the operations that the key supports, such as kms:Sign and kms:Verify, or kms:GenerateMac and kms:VerifyMac.

  • Not every Amazon KMS action can be in a customer managed permission. For example, a customer managed permission can't include kms:PutKeyPolicy, and a statement with kms:CreateGrant needs a condition. To find out which actions a customer managed permission can include, see the Amazon RAM customer managed permission column in Amazon KMS permissions.

  • Managed permissions can only allow actions, and some condition keys aren't supported in customer managed permissions. For details, see Considerations for using customer managed permissions in the Amazon RAM User Guide.

  • A managed permission can have versions. For more information, see Managed permission version in the Amazon RAM User Guide.

How managed permissions are shown in KMS keys

A KMS key can have two key policies. The default key policy is the one that you create and manage. The AWS_RAM key policy is created and managed by Amazon RAM when you share the KMS key.

Amazon RAM combines the permissions from all resource shares that include the KMS key into the key's single AWS_RAM key policy. If the resource shares use different managed permissions, the AWS_RAM key policy has a separate statement for each managed permission. Each statement allows the actions in its managed permission. A principal that is named in more than one statement can use the actions in all of them.

You can't create, change, or delete the AWS_RAM key policy. Amazon RAM manages it. To change who can use the KMS key through Amazon RAM, change the resource share.

You can view the AWS_RAM key policy by using the Amazon KMS console or the Amazon KMS API. You need kms:GetKeyPolicy permission in the Amazon Web Services account that owns the KMS key.

To view the AWS_RAM key policy (Amazon KMS console)
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. In the list of KMS keys, choose the alias or key ID of the shared KMS key.

  5. Choose the Resource shares tab, and then choose Policy view (JSON).

    The Resource shares tab shows the AWS_RAM key policy, but you can't edit it there. The default key policy is on the Key policy tab.

You can use the ListKeyPolicies operation to find out whether a KMS key has an AWS_RAM key policy. If it has one, the response includes default and AWS_RAM. You can use the GetKeyPolicy operation with PolicyName set to AWS_RAM to view the AWS_RAM key policy.

The following Amazon CLI example uses the list-key-policies command to get the names of the key policies of a shared KMS key. Replace 1234abcd-12ab-34cd-56ef-1234567890ab with the key ID or key ARN of your KMS key.

$ aws kms list-key-policies --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

The output shows that the KMS key has a default key policy and an AWS_RAM key policy.

{ "PolicyNames": [ "AWS_RAM", "default" ] }

The following Amazon CLI example uses the get-key-policy command to get the AWS_RAM key policy of a KMS key that is shared with one Amazon Web Services account by using the default managed permission. The --query Policy and --output text parameters return only the key policy document, rather than a JSON object that contains it.

$ aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name AWS_RAM --query Policy --output text

The output is similar to the following key policy document, which is formatted here for readability. Amazon RAM sets the statement IDs (Sid), which are shown here as placeholders.

{ "Version": "2012-10-17", "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "Statement": [ { "Sid": "managed-permission-statement-id", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey", "kms:ListGrants" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, { "Sid": "managed-permission-statement-id", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::444455556666:root" }, "Action": [ "kms:CreateGrant" ], "Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } } ] }

How permissions are evaluated

Amazon KMS evaluates the default key policy and the AWS_RAM key policy together. A permission in either key policy can allow access to the KMS key.

An explicit Deny statement in the default key policy overrides an Allow statement in the AWS_RAM key policy. For example, if the default key policy denies kms:Encrypt to an account that the AWS_RAM key policy allows to use the KMS key, principals in that account can't use the KMS key to encrypt data. Managed permissions can only allow actions, so the AWS_RAM key policy can't contain Deny statements.

The following considerations also apply to a shared KMS key.

IAM policies

As with any KMS key in another account, a consumer needs two permissions to use a shared KMS key. A key policy (default or AWS_RAM) must allow the action for the consumer account, and an IAM policy in the consumer account must allow the action for the user or role that makes the request. The key policy decides what the account can do. The IAM policy decides which users and roles in the account can do it. In the IAM policy, identify the KMS key by its key ARN in the Resource element. For more information about IAM policies for KMS keys in other accounts, see Step 2: Add IAM policies in the external account.

Grants

Sharing a KMS key through Amazon RAM doesn't change its grants. Deleting a resource share doesn't remove access that a grant or the default key policy allows.

Policy lockout safety check

When you change the default key policy, Amazon KMS checks that the new key policy still allows the principal that makes the request to change the key policy later, so you don't lose control of the KMS key. This policy lockout safety check considers only the default key policy. The BypassPolicyLockoutSafetyCheck parameter of PutKeyPolicy has no effect on the AWS_RAM key policy, which Amazon RAM creates and manages.

Controlling access to each key policy

The kms:PolicyName condition key controls access to the GetKeyPolicy and PutKeyPolicy operations based on the value of the PolicyName parameter in the request. For example, you can use it to control which principals in your account can view the AWS_RAM key policy. For more information about this condition key, see kms:PolicyName.

Changes to key policies are eventually consistent. For more information, see Other considerations.

Sharing a KMS key

When you share a KMS key that you own, Amazon RAM creates the AWS_RAM key policy for the KMS key from the managed permission of the resource share. Then, the consumers can attach IAM policies that allow their users and roles to use the KMS key.

To share a KMS key, you add it to a resource share. A resource share is an Amazon RAM resource that specifies the resources to share and the principals to share them with.

If you share a KMS key with accounts outside your organization, Amazon RAM sends them an invitation. Each account must accept the resource share invitation before the resource share gives it access to the KMS key. For more information about invitations, see Sharing your Amazon resources in the Amazon RAM User Guide.

You can share a KMS key that you own using the Amazon KMS console, Amazon RAM console, or the Amazon CLI. The Amazon KMS console can start a resource share only for a KMS key that isn't in a resource share yet. To add a KMS key to an existing resource share, or to add a KMS key that is already shared to another resource share, use the Amazon RAM console or the Amazon CLI. For instructions, see Update a resource share in the Amazon RAM User Guide.

Use the following procedure to start a resource share from the Amazon KMS console for a KMS key that isn't shared yet.

To share a KMS key (Amazon KMS console)
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. In the list of KMS keys, choose the alias or key ID of the KMS key that you want to share.

  5. On the details page of the KMS key, choose the Resource shares tab.

    If the tab shows No resource shares and a Create resource share button, the KMS key isn't in a resource share. If the tab lists resource shares instead, the KMS key is shared in each one with a Resource status of Associated. The tab also lists resource shares that the KMS key was removed from, with a Resource status of Disassociated. To add the KMS key to another resource share, use the Amazon RAM console or the Amazon CLI.

  6. Choose Create resource share. The Create resource share page of the Amazon RAM console opens in a new tab.

  7. Complete the resource share. For instructions, see Creating a resource share in the Amazon RAM User Guide.

Use the create-resource-share command. Use the --permission-arns parameter to specify the managed permission. To add the KMS key to an existing resource share, use the associate-resource-share command.

The following Amazon CLI example shares a KMS key with the Amazon Web Services account 444455556666. Replace the following values with your own:

  • Replace my-key-share with a name for the resource share.

  • Replace arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab with the key ARN of the KMS key to share.

  • Replace 444455556666 with the principal to share the KMS key with.

The example uses the ARN of the default Amazon managed permission for KMS keys. To use a different managed permission, replace the value of --permission-arns with the ARN of that managed permission.

$ aws ram create-resource-share \ --name my-key-share \ --resource-arns arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \ --principals 444455556666 \ --permission-arns arn:aws:ram::aws:permission/AWSRAMPermissionKMSKeySymmetricEncryption

Revoking access to a shared KMS key

Revoke access to a shared KMS key when you no longer want the consumers of a resource share to use it. If a KMS key is in only one resource share, deleting that share also removes the key's AWS_RAM key policy. The consumers then no longer have the access that the share gave them. Access that they have through the key's default key policy or through grants isn't affected.

Disabling a shared KMS key, or scheduling its deletion, doesn't remove it from the resource share or change its AWS_RAM key policy. While the KMS key is disabled or pending deletion, the consumers can still view it and find it in ListKeys results for keys shared with them, but they can't use it to encrypt data. Before you schedule a shared KMS key for deletion, remove it from its resource shares.

When you remove a KMS key from its only resource share, Amazon RAM deletes the AWS_RAM key policy, and the consumers lose the permissions that the resource share gave them. They can no longer find the KMS key in ListKeys results for keys shared with them. Permissions that the default key policy or grants give them aren't affected.

If a KMS key is in two resource shares that use different managed permissions, and you remove the KMS key from one of them, Amazon RAM removes that resource share's statement from the AWS_RAM key policy. The statement for the other resource share doesn't change.

To revoke access to a shared KMS key that you own, remove it from the resource share or delete the resource share. Remove the KMS key when the resource share also shares other Amazon resources that you want to keep sharing. Delete the resource share when you no longer want to share any of its resources. Use the Amazon KMS console, Amazon RAM console, or the Amazon CLI to do either.

To revoke access to a shared KMS key (Amazon KMS console)
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. In the list of KMS keys, choose the alias or key ID of the shared KMS key.

  5. On the details page of the KMS key, choose the Resource shares tab.

  6. In the Resource share name column, choose the name of the resource share. The resource share opens in the Amazon RAM console in a new tab.

  7. Remove the KMS key from the resource share or delete the resource share. For instructions on updating or deleting a resource share, see Update a resource share and Deleting a resource share in the Amazon RAM User Guide.

Use the disassociate-resource-share command to remove the KMS key from a resource share, or the delete-resource-share command to delete the resource share.

The following Amazon CLI example uses the disassociate-resource-share command to remove a KMS key from a resource share. Replace resource-share-arn with the ARN of your resource share, and arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab with the key ARN of the KMS key.

$ aws ram disassociate-resource-share \ --resource-share-arn resource-share-arn \ --resource-arns arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

Identifying a shared KMS key

Owners and consumers can identify shared KMS keys by using the Amazon KMS console or the Amazon CLI.

To find the resource shares that include your KMS key (owners)
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. In the list of KMS keys, choose the alias or key ID of the KMS key.

  5. Choose the Resource shares tab. The KMS key is in each resource share with a Resource status of Associated.

    To list the resource shares, you need ram:GetResourceShareAssociations permission. Without it, the tab shows Not authorized. You can still choose Policy view (JSON) to view the AWS_RAM key policy, which requires kms:GetKeyPolicy permission.

To find the KMS keys that are shared with you (consumers)
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms.

  2. To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Keys shared with me.

    The page lists the KMS keys that other Amazon Web Services accounts shared with you through Amazon RAM, with the Owner account ID and Key ARN of each KMS key. To show the Key ID column, change the table preferences.

    To view this page, you need kms:ListKeys permission. You don't need Amazon RAM permissions.

As an owner, use the list-key-policies command. If the KMS key is shared through Amazon RAM, the response includes AWS_RAM. A KMS key that you share stays in your account, and ListKeys still returns it with your other KMS keys. It doesn't appear on the Keys shared with me page or in ListKeys results for OTHER_ACCOUNTS_VIA_RAM, which list only KMS keys that other Amazon Web Services accounts shared with you.

As a consumer, use the list-keys command with the ResourceOwners parameter. Set it to OTHER_ACCOUNTS_VIA_RAM to list the KMS keys that other accounts shared with you through Amazon RAM, or to both SELF and OTHER_ACCOUNTS_VIA_RAM to list your own KMS keys and the keys shared with you. You need kms:ListKeys permission, the same permission that lists the KMS keys in your account. For more information about the ResourceOwners parameter, see the Amazon KMS API Reference.

The following Amazon CLI example lists the KMS keys that are shared with you.

$ aws kms list-keys --resource-owners OTHER_ACCOUNTS_VIA_RAM

The output lists two KMS keys that the Amazon Web Services account 111122223333 shared with you. The key ARN of each KMS key contains the owner's account ID.

{ "Keys": [ { "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, { "KeyId": "0987dcba-09fe-87dc-65ba-ab0987654321", "KeyArn": "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" } ], "Truncated": false }

For an example of the CloudTrail log entry for a PutKeyPolicy request in which Amazon RAM writes the AWS_RAM key policy, see PutKeyPolicy.

Security best practices for sharing KMS keys

Consumers of a resource share can use your KMS key without being named in a key policy statement that you write.

Use the following practices to control who can share your KMS keys, limit what consumers can do, and detect changes. They're general guidelines, not a complete security solution, so adapt them to your environment.

Preventative best practices

Use the following preventative practices to avoid unintended sharing and access:

Control who can share your KMS keys

When you create or change a resource share that includes a KMS key, Amazon RAM writes the AWS_RAM key policy. It does this by calling PutKeyPolicy on your behalf. The principal that makes the Amazon RAM request needs permission to call the Amazon RAM operation, such as ram:CreateResourceShare or ram:AssociateResourceShare, and kms:PutKeyPolicy permission on the KMS key.

To let a principal share a KMS key without letting it change the default key policy, allow kms:PutKeyPolicy only when the value of the kms:PolicyName condition key is AWS_RAM. With the following key policy statement, the kms-key-sharing-role role can share the KMS key through Amazon RAM. In a key policy, the "*" in the Resource element means this KMS key. To use this example, replace the account ID and role name with your own.

{ "Sid": "AllowSharingThroughRAM", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/kms-key-sharing-role" }, "Action": "kms:PutKeyPolicy", "Resource": "*", "Condition": { "StringEquals": { "kms:PolicyName": "AWS_RAM" } } }

Principals that have kms:PutKeyPolicy permission without a kms:PolicyName condition, such as key administrators, can also share the KMS key if they have permission to use Amazon RAM.

Restrict sharing across your organization

Use service control policies (SCPs) to limit which principals can share KMS keys. The ram:RequestedResourceType condition key identifies requests that share KMS keys, whose resource type is kms:Key.

For example, the following SCP restricts sharing of KMS keys to the kms-key-sharing-role role in one account. It uses the StringEqualsIfExists operator, so it also applies to requests that don't specify a resource type, such as adding principals to an existing resource share. To use this example, replace the account ID and role name with your own.

{ "Version": "2012-10-17", "Statement": [ { "Sid": "RestrictKMSKeySharingToOneRole", "Effect": "Deny", "Action": [ "ram:CreateResourceShare", "ram:AssociateResourceShare" ], "Resource": "*", "Condition": { "StringEqualsIfExists": { "ram:RequestedResourceType": "kms:Key" }, "ArnNotEquals": { "aws:PrincipalArn": "arn:aws:iam::111122223333:role/kms-key-sharing-role" } } } ] }

To prevent sharing with accounts outside your organization, deny ram:CreateResourceShare and ram:UpdateResourceShare when the value of the ram:RequestedAllowsExternalPrincipals condition key is true. For this and other examples, see Example service control policies for Amazon Organizations and Amazon RAM in the Amazon RAM User Guide.

Give consumers only the permissions they need

Use the default managed permission only when consumers need all of its actions. Otherwise, create a customer managed permission that allows only the actions that the consumers need. Before you share a KMS key or accept a resource share, review the managed permission in the Amazon RAM console, or by using the get-permission command in the Amazon CLI. For more information about the actions that you can include, see Considerations for using managed permissions with KMS keys.

Keep guardrails in the default key policy

An explicit Deny statement in the default key policy overrides an Allow statement in the AWS_RAM key policy, so you can use the default key policy to deny actions that no consumer should have. You can also use resource control policies (RCPs) to set the maximum permissions for the KMS keys in your organization. For more information about how Amazon KMS evaluates the two key policies, see How permissions are evaluated.

Detective best practices

Use the following detective practices to find sharing and changes to shared KMS keys:

Monitor sharing activity

CloudTrail records the Amazon RAM operations that create and change resource shares, such as CreateResourceShare, AssociateResourceShare, and DisassociateResourceShare. Amazon KMS also records a PutKeyPolicy entry in your account each time Amazon RAM writes the AWS_RAM key policy of your KMS key. Create alerts for these events, for example by using an EventBridge rule. For an example of the PutKeyPolicy entry, see PutKeyPolicy.

Review shared KMS keys regularly

As the owner, review the resource shares that include your KMS keys and the AWS_RAM key policy of each shared KMS key. As a consumer, review the KMS keys that other Amazon Web Services accounts shared with you. For more information about identifying shared KMS keys, see Identifying a shared KMS key.

Grants after you stop sharing

When you remove a KMS key from a resource share, or delete the resource share, the consumers lose the permissions that the resource share gave them. Grants aren't affected. Grants that Amazon Web Services services created for principals in a consumer account while the KMS key was shared stay in effect until they're retired or revoked.

To find these grants, use the ListGrants operation on the KMS key. The IssuingAccount field of each grant shows the Amazon Web Services account that created it. To remove a grant, use the RevokeGrant operation. For more information about viewing and revoking grants, see Viewing grants and Retiring and revoking grants.

Other considerations

Keep the following in mind when you share KMS keys through Amazon RAM.

Quotas

The AWS_RAM key policy can be up to 32,768 characters, and it doesn't count toward the key policy size quota for the default key policy. Because Amazon RAM combines all resource shares that include the KMS key into this one key policy, adding resource shares or principals makes it larger, and splitting principals across resource shares doesn't avoid the limit. Amazon KMS doesn't otherwise limit how many resource shares include a KMS key or how many principals they share it with. The policy template of a customer managed permission can be up to 20,480 bytes. Amazon RAM quotas, such as the number of principals and resources in a resource share, also apply. For more information about Amazon RAM quotas, see Amazon Resource Access Manager endpoints and quotas in the Amazon General Reference.

Regions

Sharing KMS keys through Amazon RAM isn't available in the Middle East (UAE) and Middle East (Bahrain) Regions.

Eventual consistency

Like other changes to Amazon KMS resources, changes to a resource share, and the AWS_RAM key policy that Amazon RAM writes, are eventually consistent. After you create, change, or delete a resource share, it might take a short time before ListKeys results and access to the shared KMS key reflect the change. For more information about eventual consistency, see Amazon KMS eventual consistency.