AWS KMS condition keys

AWS KMS provides a set of condition keys that you can use in key policies and IAM policies. These condition keys are specific to AWS KMS. For example, you can use the kms:EncryptionContext:context-key condition key to require a particular encryption context when controlling access to a symmetric encryption KMS key.

Conditions for an API operation request

Many AWS KMS condition keys control access to a KMS key based on the value of a parameter in the request for an AWS KMS operation. For example, you can use the kms:KeySpec condition key in an IAM policy to allow use of the CreateKey operation only when the value of the KeySpec parameter in the CreateKey request is RSA_4096.

This type of condition works even when the parameter doesn't appear in the request, such as when you use the parameter's default value. For example you can use the kms:KeySpec condition key to allow users to use the CreateKey operation only when the value of the KeySpec parameter is SYMMETRIC_DEFAULT, which is the default value. This condition allows requests that have the KeySpec parameter with the SYMMETRIC_DEFAULT value and requests that have no KeySpec parameter.

Conditions for KMS keys used in API operations

Some AWS KMS condition keys can control access to operations based on a property of the KMS key that is used in the operation. For example, you can use the kms:KeyOrigin condition to allow principals to call GenerateDataKey on a KMS key only when the Origin of the KMS key is AWS_KMS. To find out if a condition key can be used in this way, see the description of the condition key.

The operation must be a KMS key resource operation, that is, an operation that is authorized for a particular KMS key. To identify the KMS key resource operations, in the Actions and Resources Table, look for a value of KMS key in the Resources column for the operation. If you use this type of condition key with an operation that is not authorized for a particular KMS key resource, like ListKeys, the permission is not effective because the condition can never be satisfied. There is no KMS key resource involved in authorizing the ListKeys operation and no KeySpec property.

The following topics describe each AWS KMS condition key and include example policy statements that demonstrate policy syntax.

Using set operators with condition keys

When a policy condition compares two set of values, such as the set of tags in a request and the set of tags in a policy, you need tell AWS how to compare the sets. IAM defines two set operators, ForAnyValue and ForAllValues, for this purpose. Use set operators only with multi-valued condition keys, which require them. Do not use set operators with single-valued condition keys. As always, test your policy statements thoroughly before using them in a production environment.

Condition keys are single-valued or multi-valued. To determine whether an AWS KMS condition key is single-valued or multi-valued, see the Value type column in the condition key description.

Note that the difference between single-valued and multi-valued condition keys depends on the number of values in the authorization context; not the number of values in the policy condition.

For detailed information about the ForAnyValue and ForAllValues set operators, see Using multiple keys and values in the IAM User Guide. For information about the risk of using the ForAllValues set operator with a single-valued condition, see Security Warning – ForAllValues with single valued key in the IAM User Guide.

kms:BypassPolicyLockoutSafetyCheck

The kms:BypassPolicyLockoutSafetyCheck condition key controls access to the CreateKey and PutKeyPolicy operations based on the value of the BypassPolicyLockoutSafetyCheck parameter in the request.

The following example IAM policy statement prevents users from bypassing the policy lockout safety check by denying them permission to create KMS keys when the value of the BypassPolicyLockoutSafetyCheck parameter in the CreateKey request is true.

{
  "Effect": "Deny",
  "Action": [
    "kms:CreateKey",
    "kms:PutKeyPolicy"
  ],
  "Resource": "*",
  "Condition": {
    "Bool": {
      "kms:BypassPolicyLockoutSafetyCheck": true
    }
  }
}

You can also use the kms:BypassPolicyLockoutSafetyCheck condition key in an IAM policy or key policy to control access to the PutKeyPolicy operation. The following example policy statement from a key policy prevents users from bypassing the policy lockout safety check when changing the policy of a KMS key.

Instead of using an explicit Deny, this policy statement uses Allow with the Null condition operator to allow access only when the request does not include the BypassPolicyLockoutSafetyCheck parameter. When the parameter is not used, the default value is false. This slightly weaker policy statement can be overridden in the rare case that a bypass is necessary.

{
  "Effect": "Allow",
  "Action": "kms:PutKeyPolicy",
  "Resource": "*",
  "Condition": {
    "Null": {
      "kms:BypassPolicyLockoutSafetyCheck": true
    }
  }
}

See also

kms:CallerAccount

You can use this condition key to allow or deny access to all identities (users and roles) in an AWS account. In key policies, you use the Principal element to specify the identities to which the policy statement applies. The syntax for the Principal element does not provide a way to specify all identities in an AWS account. But you can achieve this effect by combining this condition key with a Principal element that specifies all AWS identities.

You can use it to control access to any KMS key resource operation, that is, any AWS KMS operation that uses a particular KMS key. To identify the KMS key resource operations, in the Actions and Resources Table, look for a value of KMS key in the Resources column for the operation. It is also valid for operations that manage custom key stores.

For example, the following key policy statement demonstrates how to use the kms:CallerAccount condition key. This policy statement is in the key policy for the AWS managed key for Amazon EBS. It combines a Principal element that specifies all AWS identities with the kms:CallerAccount condition key to effectively allow access to all identities in AWS account 111122223333. It contains an additional AWS KMS condition key (kms:ViaService) to further limit the permissions by only allowing requests that come through Amazon EBS. For more information, see kms:ViaService.

{
  "Sid": "Allow access through EBS for all principals in the account that are authorized to use EBS",
  "Effect": "Allow",
  "Principal": {"AWS": "*"},
  "Condition": {
    "StringEquals": {
      "kms:CallerAccount": "111122223333",
      "kms:ViaService": "ec2.us-west-2.amazonaws.com"
    }
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*",
    "kms:CreateGrant",
    "kms:DescribeKey"
  ],
  "Resource": "*"
}

kms:CustomerMasterKeySpec (deprecated)

The kms:CustomerMasterKeySpec condition key is deprecated. Instead, use the kms:KeySpec condition key.

The kms:CustomerMasterKeySpec and kms:KeySpec condition keys work the same way. Only the names differ. We recommend that you use kms:KeySpec. However, to avoid breaking changes, AWS KMS supports both condition keys.

kms:CustomerMasterKeyUsage (deprecated)

The kms:CustomerMasterKeyUsage condition key is deprecated. Instead, use the kms:KeyUsage condition key.

The kms:CustomerMasterKeyUsage and kms:KeyUsage condition keys work the same way. Only the names differ. We recommend that you use kms:KeyUsage. However, to avoid breaking changes, AWS KMS supports both condition keys.

kms:DataKeyPairSpec

You can use this condition key to control access to the GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext operations based on the value of the KeyPairSpec parameter in the request. For example, you can allow users to generate only particular types of data key pairs.

The following example key policy statement uses the kms:DataKeyPairSpec condition key to allow users to use the KMS key to generate only RSA data key pairs.

{
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
  },
  "Action": [
    "kms:GenerateDataKeyPair",
    "kms:GenerateDataKeyPairWithoutPlaintext"
  ],
  "Resource": "*",
  "Condition": {
    "StringLike": {
      "kms:DataKeyPairSpec": "RSA*"
    }
  }
}

See also

kms:EncryptionAlgorithm

You can use the kms:EncryptionAlgorithm condition key to control access to cryptographic operations based on the encryption algorithm that is used in the operation. For the Encrypt, Decrypt, and ReEncrypt operations, it controls access based on the value of the EncryptionAlgorithm parameter in the request. For operations that generate data keys and data key pairs, it controls access based on the encryption algorithm that is used to encrypt the data key.

This condition key has no effect on operations performed outside of AWS KMS, such as encrypting with the public key in an asymmetric KMS key pair outside of AWS KMS.

EncryptionAlgorithm parameter in a request

To allow users to use only a particular encryption algorithm with a KMS key, use a policy statement with a Deny effect and a StringNotEquals condition operator. For example, the following example key policy statement prohibits principals who can assume the ExampleRole role from using this KMS key in the specified cryptographic operations unless the encryption algorithm in the request is RSAES_OAEP_SHA_256, an asymmetric encryption algorithm used with RSA KMS keys.

Unlike a policy statement that allows a user to use a particular encryption algorithm, a policy statement with a double-negative like this one prevents other policies and grants for this KMS key from allowing this role to use other encryption algorithms. The Deny in this key policy statement takes precedence over any key policy or IAM policy with an Allow effect, and it takes precedence over all grants for this KMS key and its principals.

{
  "Sid": "Allow only one encryption algorithm with this asymmetric KMS key",
  "Effect": "Deny",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:role/ExampleRole"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*"
  ],
  "Resource": "*",
  "Condition": {
    "StringNotEquals": {
      "kms:EncryptionAlgorithm": "RSAES_OAEP_SHA_256"
    }
  }
}

Encryption algorithm used for the operation

You can also use the kms:EncryptionAlgorithm condition key to control access to operations based on the encryption algorithm used in the operation, even when the algorithm isn't specified in the request. This allows you to require or forbid the SYMMETRIC_DEFAULT algorithm, which might not be specified in a request because it's the default value.

This feature lets you use the kms:EncryptionAlgorithm condition key to control access to the operations that generate data keys and data key pairs. These operations use only symmetric encryption KMS keys and the SYMMETRIC_DEFAULT algorithm.

For example, this IAM policy limits its principals to symmetric encryption. It denies access to any KMS key in the example account for cryptographic operations unless the encryption algorithm specified in the request or used in the operation is SYMMETRIC_DEFAULT. Including GenerateDataKey* adds GenerateDataKey, GenerateDataKeyWithoutPlaintext, GenerateDataKeyPair, and GenerateDataKeyPairWithoutPlaintext to the permissions. The condition has no effect on these operations because they always use a symmetric encryption algorithm.

{
  "Sid": "AllowOnlySymmetricAlgorithm",
  "Effect": "Deny",
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt",
    "kms:ReEncrypt*",
    "kms:GenerateDataKey*"
  ],
  "Resource": "arn:aws:kms:us-west-2:111122223333:key/*",
  "Condition": {
    "StringNotEquals": {
      "kms:EncryptionAlgorithm": "SYMMETRIC_DEFAULT"
    }
  }
}

See also