KMS Key Policies and Grants

AWS Key Management Service (KMS) uses key policies as the primary way to control access to customer master keys (CMKs). A key policy is a JSON document attached to a CMK that defines which principals (users, roles, AWS services) can perform which actions on the key. Every CMK must have exactly one key policy. The key policy, combined with IAM policies, determines the effective permissions. If the key policy explicitly denies access, no IAM policy can override it.

Key policies exist because CMKs are resources that need independent access control separate from IAM. This allows cross-account access and ensures that even if an IAM policy grants broad permissions, the key itself can restrict usage. For example, you can allow an IAM role in another account to use a CMK by adding a statement in the key policy that grants the external role access. Without key policies, you would need to rely solely on IAM policies, which cannot grant access to principals outside your account.

A key policy contains the following elements:

- Version: Always 2012-10-17 (the policy language version). - Id: Optional identifier. - Statement: One or more statements, each with: - Sid: Optional statement ID. - Effect: Allow or Deny. - Principal: The entity to which the policy applies. Can be an AWS account, IAM user, IAM role, or AWS service. For cross-account access, use the ARN of the external principal. - Action: KMS API actions like kms:Encrypt, kms:Decrypt, kms:CreateGrant, etc. - Resource: Always * because the policy is attached to the CMK. - Condition: Optional conditions (e.g., IP address, MFA, encryption context).

When you create a CMK using the AWS Management Console, KMS applies a default key policy. This policy gives the AWS account root user full access to the CMK and grants IAM users and roles in the account access if they have an IAM policy that allows KMS actions. The default policy looks like this:

{
  "Version": "2012-10-17",
  "Id": "key-consolepolicy-3",
  "Statement": [
    {
      "Sid": "Enable IAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:root"
      },
      "Action": "kms:*",
      "Resource": "*"
    }
  ]
}

This policy allows the root user to delegate permissions via IAM. Without this statement, IAM policies alone cannot grant access to the CMK.

KMS evaluates access by combining the key policy and any applicable IAM policies. The evaluation logic is:

For cross-account access, the key policy must explicitly grant access to the external principal. The external account's IAM policy must also allow the action. Both policies must allow; this is a two-way permission.

A grant is an alternative way to grant access to a CMK. It is a temporary, fine-grained permission that can be created and retired without modifying the key policy. Grants are often used to delegate access to AWS services (like Lambda, S3, or DynamoDB) or to allow cross-account access for specific operations.

When you create a grant, you specify:

Grants are created using the CreateGrant API. The grant is valid until it is retired or revoked. To create a grant, the caller must have kms:CreateGrant permission on the CMK, and the key policy must allow it (either via the default policy or an explicit statement).

Example using AWS CLI:

aws kms create-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grantee-principal arn:aws:iam::123456789012:role/MyRole \
    --operations Encrypt Decrypt \
    --constraints EncryptionContextSubset={Department=Finance}

This creates a grant allowing the role to encrypt and decrypt only when the encryption context includes Department=Finance.

To retire a grant, use:

aws kms retire-grant \
    --grant-token <token> \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab

Or the grantee can retire it if they have RetireGrant permission.

Only the key owner can revoke a grant:

aws kms revoke-grant \
    --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \
    --grant-id <id>

Grants are an additional layer. Even if a grant allows an action, the grantee must have an IAM policy that allows the KMS action (unless the key policy explicitly allows the grantee principal without requiring IAM). However, for cross-account grants, the grantee principal in the external account must have an IAM policy allowing the action; the key policy must allow the external account to create grants (or allow the grantee principal via the key policy).

Use AWS CloudTrail to log CreateGrant and RetireGrant events. Use ListGrants API to view active grants:

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

| Feature | Key Policy | Grant | |---------|------------|-------| | Persistence | Permanent until edited | Temporary, can be retired | | Granularity | Actions, principals, conditions | Actions, principals, encryption context constraints | | Cross-account | Yes | Yes | | Delegation | No | Yes (can delegate to create grants) | | Modification | Edit policy JSON | Revoke and recreate | | Use case | Permanent access control | Temporary, fine-grained delegation |

A large enterprise has separate AWS accounts for development, staging, and production. The production account stores sensitive customer data encrypted with a CMK. The analytics team in the staging account needs to decrypt this data for reporting once a month. The security team wants to avoid giving permanent cross-account access. They create a grant in the production account's CMK that allows a specific IAM role in the staging account to perform kms:Decrypt, with an encryption context constraint that limits the operation to a specific dataset. The grant is retired after the monthly report is generated. This ensures least privilege and temporary access. A common mistake is to instead modify the key policy to allow the staging account's root, which would give permanent access to all roles in that account. The grant approach avoids this.

A company uses a third-party security tool that requires permission to rotate CMKs. The tool runs as an IAM role in the same account. The security team wants to allow only the rotation operation (kms:ScheduleKeyDeletion, kms:CancelKeyDeletion, kms:EnableKey, kms:DisableKey) but not encrypt/decrypt. They create a grant that allows these specific operations to the tool's role. The key policy remains restrictive, allowing only the security team to manage the key policy itself. This prevents the tool from accessing data but allows it to manage key lifecycle. Without grants, the security team would have to update the key policy, which is riskier and less granular.

Grants are stored in KMS and count towards service limits. Each CMK can have up to 10,000 grants (default limit). Creating many grants can impact performance slightly due to internal storage, but for most use cases this is negligible. For high-frequency operations, using a key policy with IAM is more efficient because grants require an additional lookup. In production, it is common to use key policies for broad access and grants for narrow, temporary needs. Misconfiguration often occurs when administrators forget to retire grants, leading to lingering access. Automated scripts should be used to retire grants after a defined period.