KMS key access and permissions - AWS Key Management Service
KMS key policies KMS key grants

KMS key access and permissions

To use AWS KMS, you must have credentials that AWS can use to authenticate your requests. The credentials must include permissions to access AWS resources: AWS KMS keys and aliases. No AWS principal has any permissions to a KMS key unless that permission is provided explicitly and never denied. There are no implicit or automatic permission to use or manage a KMS key.

To control access to your KMS keys, you can use the following policy mechanisms.

  • Key policy – Every KMS key has a key policy. It is the primary mechanism for controlling access to a KMS key. You can use the key policy alone to control access, which means the full scope of access to the KMS key is defined in a single document (the key policy). For more information about using key policies, see Key policies.

  • IAM policies – You can use IAM policies in combination with the key policy and grants to control access to a KMS key. Controlling access this way enables you to manage all of the permissions for your IAM identities in IAM. To use an IAM policy to allow access to a KMS key, the key policy must explicitly allow it. For more information about using IAM policies, see IAM policies.

  • Grants – You can use grants in combination with the key policy and IAM policies to allow access to a KMS key. Controlling access this way enables you to allow access to the KMS key in the key policy, and to allow identities to delegate their access to others. For more information about using grants, see Grants in AWS KMS.

KMS key policies

The primary way to manage access to your AWS KMS resources is with policies. Policies are documents that describe which principals can access which resources. Policies attached to an IAM identity are called identity-based policies (or IAM policies), and policies attached to other kinds of resources are called resource policies. AWS KMS resource policies for KMS keys are called key policies.

All KMS keys have a key policy. If you don't provide one, AWS KMS creates one for you. The default key policy that AWS KMS uses differs depending on whether you create the key in the AWS KMS console or you use the AWS KMS API. We recommend that you edit the default key policy to align with your organization’s requirements for least-privilege permissions.

You can use the key policy alone to control access if the key and the IAM principal are in the same AWS account, which means the full scope of access to the KMS key is defined in a single document (the key policy). However, when a caller in one account must access a key in a different account, you cannot use key policy alone to grant access. In the cross-account scenario, an IAM policy must be attached to the caller's user or role that explicitly allows the caller to make the API call.

You can also use IAM policies in combination with key policies and grants to control access to a KMS key. To use an IAM policy to control access to a KMS key, the key policy must give the account permission to use IAM policies. You can either specify a key policy statement that enables IAM policies, or you can explicitly specify allowed principals in the key policy.

When writing policies, ensure that you have strong controls restricting who can perform the following actions:

  • Update, create, and delete IAM and KMS key policies

  • Attach and detach IAM policies from users, roles, and groups

  • Attach and detach KMS key polices from your KMS keys

KMS key grants

In addition to IAM and key policies, AWS KMS supports grants. Grants provide a flexible and powerful way to delegate permissions. You can use grants to issue time-bound KMS key access to IAM principals in your AWS account, or in other AWS accounts. We recommend issuing time-bound access if you don't know the names of the principals at the time that the policies are created, or if the principals that require access frequently change. The grantee principal can be in the same account as the KMS key or a different account. If the principal and KMS key are in different accounts, then you must specify an IAM policy in addition to the grant. Grants require additional management because you must call an API to create the grant and to retire or revoke the grant when it is no longer needed.

The following topics provide details about how you can use AWS Identity and Access Management (IAM) and AWS KMS permissions to help secure your resources by controlling who can access them.