Using Policy Conditions with AWS KMS
You can specify conditions in the key policies and AWS Identity and Access Management policies (IAM policies) that control access to AWS KMS resources. The policy statement is effective only when the conditions are true. For example, you might want a policy statement to take effect only after a specific date. Or, you might want a policy statement to control access only when a specific value appears in an API request.
To specify conditions, you use predefined condition keys in the
Condition
element of a policy statement with IAM condition
policy operators. Some condition keys apply generally to AWS; others are specific to
AWS KMS.
AWS Global Condition Keys
AWS provides global condition
keys, a set of predefined condition keys for all AWS services that use IAM for
access control. For example, you can use the aws:PrincipalArn
condition key to
allow access only when the principal in the request is represented by the Amazon Resource
Name
(ARN) that you specify.
In addition to global conditions keys that are supported by every AWS service, IAM defines conditions keys that AWS services can choose to support. AWS KMS supports the following optional global condition keys.
-
aws:PrincipalTag
-
aws:PrincipalType
-
aws:RequestTag
-
aws:SourceIp (see Using the IP Address Condition in Policies with AWS KMS Permissions)
-
aws:SourceVpc (see Using VPC Endpoint Conditions in Policies with AWS KMS Permissions)
-
aws:SourceVpce (see Using VPC Endpoint Conditions in Policies with AWS KMS Permissions)
-
aws:TagKeys
-
aws:TokenIssueTime
-
aws:userid
-
aws:username
For a list and descriptions of all optional global condition keys, see Keys Available for Some Services in the AWS Identity and Access Management User Guide. For examples of using these condition keys in IAM policies, see Controlling Access to Requests and Controlling Tag Keys in the IAM User Guide.
Topics
Using the IP Address Condition in Policies with AWS KMS Permissions
You can use AWS KMS to protect your data in an integrated AWS service. But use caution when specifying the IP address condition operators or the aws:SourceIp
condition key in
the same policy statement that allows or denies access to AWS KMS. For example, the
policy in
AWS: Denies
Access to AWS Based on the Source IP restricts AWS actions to requests from the
specified IP range.
Consider this scenario:
-
You attach a policy like the one shown at AWS: Denies Access to AWS Based on the Source IP to an IAM user. You set the value of the
aws:SourceIp
condition key to the range of IP addresses for the user's company. This IAM user has other policies attached that allow it to use Amazon EBS, Amazon EC2, and AWS KMS. -
The user attempts to attach an encrypted EBS volume to an EC2 instance. This action fails with an authorization error even though the user has permission to use all the relevant services.
Step 2 fails because the request to AWS KMS to decrypt the volume's encrypted data key comes from an IP address that is associated with the Amazon EC2 infrastructure. To succeed, the request must come from the IP address of the originating user. Because the policy in step 1 explicitly denies all requests from IP addresses other than those specified, Amazon EC2 is denied permission to decrypt the EBS volume's encrypted data key.
Also, the aws:sourceIP
condition key is not effective when the request
comes from an Amazon VPC endpoint. To
restrict requests to a VPC endpoint, including an AWS KMS VPC
endpoint, use the aws:sourceVpce
or aws:sourceVpc
condition keys. For more information, see VPC Endpoints -
Controlling the Use of Endpoints in the Amazon VPC User
Guide.
Using VPC Endpoint Conditions in Policies with AWS KMS Permissions
AWS KMS supports Amazon Virtual Private Cloud (Amazon VPC) endpoints that are powered by AWS PrivateLink. You can use the following global condition keys in IAM policies to allow or deny access to a particular VPC or VPC endpoint. You can also use these global condition keys in AWS KMS key policies to restrict access to AWS KMS CMKs to requests from the VPC or VPC endpoint.
-
aws:SourceVpc
limits access to requests from the specified VPC. -
aws:SourceVpce
limits access to requests from the specified VPC endpoint.
If you use these condition keys in a key policy statement that allows or denies access to AWS KMS CMKs, you might inadvertently deny access to services that use AWS KMS on your behalf.
Take care to avoid a situation like the IP address condition keys example. If you restrict requests for a CMK to a VPC or VPC endpoint, calls to AWS KMS from an integrated service, such as Amazon S3 or Amazon EBS, might fail. This can happen even if the source request ultimately originates in the VPC or from the VPC endpoint.
AWS KMS Condition Keys
AWS KMS provides an additional set of predefined 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
condition key to require a particular encryption context when controlling access to an AWS KMS symmetric
customer master key (CMK).
Conditions for an API operation request
Many of the AWS KMS condition keys control access to a CMK based on the value of a
parameter
in the request for an API operation. For example, you can use the kms:CustomerMasterKeySpec condition key in
an IAM policy to allow use of the CreateKey operation only when the value of the CustomerMasterKeySpec
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:CustomerMasterKeySpec condition key to
allow users to use the CreateKey
operation only when the value of the
CustomerMasterKeySpec
parameter is SYMMETRIC_DEFAULT
, which is the
default value. This condition allows requests that have the CustomerMasterKeySpec
parameter with the SYMMETRIC_DEFAULT
value and requests that have no
CustomerMasterKeySpec
parameter.
Conditions for CMKs used in API operations
Some of the AWS KMS condition keys control access to operations based on a property
of the
CMK that is used in the operation. For example, you can use the kms:KeyOrigin condition to allow principals to
call GenerateDataKey on a CMK only
when the Origin
of the CMK 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 CMK resource operation, that is, an operation that is authorized for a particular CMK. To identify the CMK
resource operations, in the Actions
and Resources Table, look for a value of CMK
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 CMK resource, like ListKeys, the permission is not effective
because the condition can never be satisfied. There is no CMK resource involved in
authorizing
the ListKeys
operation and no CustomerMasterKeySpec
property.
The following topics describe each AWS KMS condition key and include example policy statements that demonstrate policy syntax.
Topics
- kms:BypassPolicyLockoutSafetyCheck
- kms:CallerAccount
- kms:CustomerMasterKeySpec
- kms:CustomerMasterKeyUsage
- kms:DataKeyPairSpec
- kms:EncryptionAlgorithm
- kms:EncryptionContext:
- kms:EncryptionContextKeys
- kms:ExpirationModel
- kms:GrantConstraintType
- kms:GrantIsForAWSResource
- kms:GrantOperations
- kms:GranteePrincipal
- kms:KeyOrigin
- kms:MessageType
- kms:ReEncryptOnSameKey
- kms:RetiringPrincipal
- kms:SigningAlgorithm
- kms:ValidTo
- kms:ViaService
- kms:WrappingAlgorithm
- kms:WrappingKeySpec
kms:BypassPolicyLockoutSafetyCheck
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
Boolean |
|
IAM policies only Key policies and IAM policies |
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 CMKs when the value of the
BypassPolicyLockoutSafetyCheck
parameter in the CreateKey
request is true.
{ "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": "kms:CreateKey", "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 CMK.
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 overriden in the rare case that a bypass is necessary.
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "kms:PutKeyPolicy", "Resource": "*", "Condition": { "Null": { "kms:BypassPolicyLockoutSafetyCheck": true } } } }
See Also
kms:CallerAccount
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
All AWS KMS operations except for |
Key policies only |
You can use this condition key to allow or deny access to all identities (IAM 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.
For example, the following policy statement demonstrates how to use the
kms:CallerAccount
condition key. This policy statement is in the key policy
for the AWS managed CMK 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
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
CMK resource operations |
IAM policies Key policies and IAM policies |
The kms:CustomerMasterKeySpec
condition key controls access to operations
based on the value of the CustomerMasterKeySpec
property of the CMK that is
created by or used in the operation.
You can use this condition key in an IAM policy to control access to the CreateKey operation based on the value of
the CustomerMasterKeySpec parameter in a CreateKey
request. For example,
you can use this condition to allow users to create only symmetric CMKs or only CMKs
with
RSA keys.
The following example IAM policy statement uses the
kms:CustomerMasterKeySpec
condition key to allow the principals to create a
CMK only when the CustomerMasterKeySpec
in the request is
RSA_4096
.
{ "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:CustomerMasterKeySpec": "RSA_4096" } } }
You can also use the kms:CustomerMasterKeySpec
condition key to control
access to operations that use or manage a CMK based on the
CustomerMasterKeySpec
property of the CMK used for the operation.
The operation must be a CMK resource operation, that is, an operation that is authorized for a particular CMK. To identify the CMK
resource operations, in the Actions
and Resources Table, look for a value of CMK
in the Resources
column for the operation.
For example, the following IAM policy allows principals to perform the specified CMK resource operations, but only with the symmetric CMKs in the account.
{ "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:DescribeKey" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringEquals": { "kms:CustomerMasterKeySpec": "SYMMETRIC_DEFAULT" } } }
See Also
kms:CustomerMasterKeyUsage
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
CMK resource operations |
IAM policies Key policies and IAM policies |
The kms:CustomerMasterKeyUsage
condition key controls access to operations
based on the value of the KeyUsage
property of the CMK that is created by or
used in the operation.
You can use this condition key to control access to the CreateKey operation based on the value of
the KeyUsage parameter in the request. Valid values for KeyUsage
are
ENCRYPT_DECRYPT
and SIGN_VERIFY
.
For example, you can allow a user to create a CMK only when the KeyUsage
is
ENCRYPT_DECRYPT
or deny a user permission when the KeyUsage
is
SIGN_VERIFY
.
The following example IAM policy statement uses the
kms:CustomerMasterKeyUsage
condition key to allow a user to create a CMK only
when the KeyUsage
is ENCRYPT_DECRYPT
.
{ "Effect": "Allow", "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:CustomerMasterKeyUsage": "ENCRYPT_DECRYPT" } } }
You can also use the kms:CustomerMasterKeyUsage
condition key to control
access to operations that use or manage a CMK based on the KeyUsage
property of
the CMK used for the operation. The operation must be a CMK resource operation, that is, an operation that is authorized for a particular CMK. To identify the CMK
resource operations, in the Actions
and Resources Table, look for a value of CMK
in the Resources
column for the operation.
For example, the following IAM policy allows principals to perform the specified CMK resource operations, but only with CMKs in the account that are used for signing and verification.
{ "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:DescribeKey", "kms:GetPublicKey", "kms:ScheduleKeyDeletion" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringEquals": { "kms:CustomerMasterKeyUsage": "SIGN_VERIFY" } } }
See Also
kms:DataKeyPairSpec
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
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 a user to
generate only particular types of data key pairs.
The following example key policy statement uses the kms:DataKeyPairSpec
condition key to allow a user to use the CMK to generate only RSA data key pairs.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": [ "kms:GenerateDataKeyPair", "kms:GenerateDataKeyPairWithoutPlaintext" ], "Resource": "*", "Condition": { "StringLike": { "kms:DataKeyPairSpec": "RSA*" } } }
See Also
kms:EncryptionAlgorithm
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
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 CMK pair outside of AWS KMS.
EncryptionAlgorithm parameter in a request
To allow users to use only a particular encryption algorithm with a CMK, 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 symmetric CMK in the specified
cryptographic operations unless the encryption algorithm in the request is
RSAES_OAEP_SHA_256
.
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 CMK from allowing this role to use other encryption algorithms. The Deny
in this policy statement takes precedence over any key policy or IAM policy with an
Allow
effect, and it takes precedence over all grants for this CMK and its
principals.
{ "Sid": "Allow only one encryption algorithm with this asymmetric CMK", "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 the operations that generate data keys and data key pairs. These operations
use
only symmetric CMKs and the SYMMETRIC_DEFAULT
algorithm.
For example, this IAM policy limits its principals to symmetric encryption. It denies access to any CMK in the example account for cryptographic operations unless the encryption algorithm specified in the request or used in the operation is SYMMETRIC_DEFAULT. The addition of GenerateDataKey, GenerateDataKeyWithoutPlaintext, GenerateDataKeyPair, and GenerateDataKeyPairWithoutPlaintext have no immediate practical effect because you can't use an asymmetric CMK or asymmetric encryption algorithm to encrypt a data key or encrypt the private key in a data key pair.
{ "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:GenerateDataKeyPair*" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringNotEquals": { "kms:EncryptionAlgorithm": "SYMMETRIC_DEFAULT" } } }
See Also
kms:EncryptionContext:
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
You can use the kms:EncryptionContext:
condition key prefix to control
access to a symmetric CMK based on the encryption
context in a request for a cryptographic operation. Use this condition key prefix
to
evaluate both the key and the value in the encryption context pair. To evaluate only
the
encryption context keys, use the kms:EncryptionContextKeys condition key.
An encryption context is a set of nonsecret key–value pairs that you can include in a request for any AWS KMS cryptographic operation (Encrypt, Decrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, and ReEncrypt) that uses a symmetric CMK, and the CreateGrant operation. When you specify an encryption context in an encryption operation, you must specify the same encryption context in the decryption operation. Otherwise, the decryption request fails.
You cannot specify an encryption context in a cryptographic operation with an asymmetric CMK. The standard asymmetric encryption algorithms that AWS KMS uses do not support an encryption context.
To use the kms:EncryptionContext:
condition key prefix, replace the
encryption_context_key
placeholder with the encryption context key. Replace
the encryption_context_value
placeholder with the encryption context
value.
"kms:EncryptionContext:
encryption_context_key
": "encryption_context_value
"
For example, the following condition key specifies an encryption context in which
the
key is AppName
and the value is ExampleApp
.
"kms:EncryptionContext:AppName": "ExampleApp"
The following example key policy statement uses this condition key. Because there
can be
multiple encryption context pairs in a request, the condition operator must include ForAnyValue
or
ForAllValues
.
This policy allows the principal to use the CMK in a GenerateDataKey
request only when at least one of the encryption context pairs in the request is
"AppName": "ExampleApp"
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContext:AppName": "ExampleApp" } } }
Requiring multiple encryption context pairs
To require more than one encryption context pair, you can include multiple instances
of the kms:EncryptionContext:
condition. For example, the following example
policy statement uses the ForAllValues
operator to require both of the
following encryption context pairs (and no others). The order in which the pairs are
specified does not matter.
-
"AppName": "ExampleApp"
-
"FilePath": "/var/opt/secrets/"
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "kms:EncryptionContext:AppName": "ExampleApp", "kms:EncryptionContext:FilePath": "/var/opt/secrets/" } } }
Case sensitivity of the encryption context condition
The encryption context that is specified in a decryption operation must be an exact, case-sensitive match for the encryption context that is specified in the encryption operation. Only the order of pairs in an encryption context with multiple pair can vary.
However, in policy conditions, the condition key is not case sensitive. The case
sensitivity of the condition value is determined by the policy condition operator that you use, such as StringEquals
or
StringEqualsIgnoreCase
.
As such, the condition key, which consists of the kms:EncryptionContext:
prefix and the
replacement,
is not case sensitive. A policy that uses this condition does not check the case of
either
element of the condition key. The case sensitivity of the value, that is, the
encryption_context_key
replacement, is
determined by the policy condition operator.
encryption_context_value
For example, the following policy statement allows the operation when the encryption
context includes an Appname
key, regardless of its capitalization. The
StringEquals
condition requires that ExampleApp
be capitalized
as it is specified.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:Decrypt", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContext:Appname": "ExampleApp" } } }
To require a case-sensitive encryption context key, use the kms:EncryptionContextKeys policy
condition with a case-sensitive condition operator, such as StringEquals
. In this
policy condition, because the encryption context key is the policy condition value,
its case
sensitivity is determined by the condition operator.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKey": "AppName" } } }
To require a case-sensitive evaluation of both the encryption context key and value,
use the kms:EncryptionContextKeys
and kms:EncryptionContext:
policy conditions together in the same policy statement. For example, in the following
example policy statement, because the StringEquals
operator is case
sensitive, both the encryption context key and the encryption context value are case
sensitive.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": "kms:GenerateDataKey", "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "AppName", "kms:EncryptionContext:AppName": "ExampleApp" } } }
Using variables in an encryption context condition
The key and value in an encryption context pair must be simple literal strings. They cannot be integers or objects, or any type that is not fully resolved. If you use a different type, such as an integer or float, AWS KMS interprets it as a literal string.
"encryptionContext": { "department": "10103.0" }
However, the value in the kms:EncryptionContext:
condition key pair can
be an IAM policy
variable. These policy variables are resolved at runtime based on values in the
request. For example, aws:CurrentTime
resolves to the time of the request and
aws:username
resolves to the friendly name of the caller.
You can use these policy variables to create a policy statement with a condition that requires very specific information in an encryption context, such as the caller's user name. Because it contains a variable, you can use the same policy statement for all users who can assume the role. You don't have to write a separate policy statement for each user.
Consider a situation where you want to all users who can assume a role to use the
same
CMK to encrypt and decrypt their data. However, you want to allow them to decrypt
only the
data that they encrypted. Start by requiring that every request to AWS KMS include
an
encryption context where the key is user
and the value is the caller's AWS
user name, such as the following one.
"encryptionContext": { "user": "bob" }
Then, to enforce this requirement, you can use a policy statement like the one in
the
following example. This policy statement gives the TestTeam
role permission
to encrypt and decrypt data with the CMK. However, the permission is valid only when
the
encryption context in the request includes a "user":
"
pair. To represent the user name,
the condition uses the <username>
"aws:username
policy variable.
When the request is evaluated, the caller's user name replaces the variable in the
condition. As such, the condition requires an encryption context of "user":
"bob"
for "bob" and "user": "alice"
for "alice."
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/TestTeam" }, "Action": [ "kms:Decrypt", "kms:Encrypt" ] "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContext:user": "${aws:username}" } } }
You can use an IAM policy variable only in the value of the
kms:EncryptionContext:
condition key pair. You cannot use a variable in the
key.
You can also use provider-specific context keys in variables. These context keys uniquely identify users who logged into AWS by using web identity federation.
Like all variables, these variables can be used only in the
kms:EncryptionContext:
policy condition, not in the actual encryption
context. And they can be used only in the value of the condition, not in the key.
For example, the following key policy statement is similar to the previous one.
However, the condition requires an encryption context where the key is sub
and the value uniquely identifies a user logged into a Amazon Cognito user pool. For
details
about identifying users and roles in Amazon Cognito, see IAM Roles in the Amazon Cognito Developer Guide.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/TestTeam" }, "Action": [ "kms:Decrypt", "kms:Encrypt" ] "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContext:sub": "${cognito-identity.amazonaws.com:sub}" } } }
See Also
kms:EncryptionContextKeys
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String (list) |
|
Key policies and IAM policies |
You can use the kms:EncryptionContextKeys
condition key to control access
to a CMK based on the encryption context in a request for a cryptographic operation
that
uses a symmetric CMK. Use this condition key prefix to
evaluate only the key in each encryption context pair. To evaluate both the key and
the
value, use the kms:EncryptionContext: condition key prefix.
You cannot specify an encryption context in a cryptographic operation with an asymmetric CMK. The standard asymmetric encryption algorithms that AWS KMS uses do not support an encryption context.
You can use this condition key to control access based on the encryption context in the AWS KMS API request. Encryption
context is a set of key–value pairs that you can include in AWS KMS cryptographic
operations (Encrypt, Decrypt, GenerateDataKey, GenerateDataKeyWithoutPlaintext, and ReEncrypt) and the CreateGrant operation. Because there can be multiple encryption context pairs in
a request, the condition operator must include ForAnyValue
or
ForAllValues
.
The following example policy statement uses the kms:EncryptionContextKeys
condition key to allow use of a CMK for the specified operations only when at least
one of
the encryption context pairs in the request includes the AppName
key,
regardless of its value.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "ForAnyValue:StringEquals": { "kms:EncryptionContextKeys": "AppName" } } }
Because the StringEquals condition operation is case sensitive, the previous policy statement
requires the spelling and case of the encryption context key. But you can use a condition
operator that ignores the case of the key, such as
StringEqualsIgnoreCase
.
You can specify multiple encryption context keys in each condition. For example, the
following policy statement uses the ForAllValues
and StringEquals
condition operators to allow the specified operations only when the encryption context
in
the request includes both the AppName
and FilePath
keys (and no
others), regardless of their values. The order of keys in the encryption context does
not
matter.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "kms:EncryptionContextKeys": [ "AppName", "FilePath" ] } } }
You can also use the kms:EncryptionContextKeys
condition key to require an
encryption context in cryptographic operations that use the CMK.
The following example key policy statement uses the
kms:EncryptionContextKeys
condition key with the Null condition operator to
allow access to CMK only when the kms:EncryptionContextKeys
condition key
exists (is not null) in the API request. It does not check the keys or values of the
encryption context, only that the encryption context exists.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/RoleForExampleApp" }, "Action": [ "kms:Encrypt", "kms:GenerateDataKey*" ], "Resource": "*", "Condition": { "Null": { "kms:EncryptionContextKeys": false } } }
See Also
kms:ExpirationModel
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
The kms:ExpirationModel
condition key controls access to the ImportKeyMaterial operation based on
the value of the ExpirationModel parameter in the request.
ExpirationModel
is an optional parameter that determines whether the
imported key material expires. Valid values are KEY_MATERIAL_EXPIRES
and
KEY_MATERIAL_DOES_NOT_EXPIRE
. KEY_MATERIAL_EXPIRES
is the
default value.
The expiration date and time is determined by the value of the ValidTo parameter. The ValidTo
parameter is required unless the
value of the ExpirationModel
parameter is
KEY_MATERIAL_DOES_NOT_EXPIRE
. You can also use the kms:ValidTo condition key to require a particular
expiration date as a condition for access.
The following example policy statement uses the kms:ExpirationModel
condition key to allow a user to import key material into a CMK only when the request
includes the ExpirationModel
parameter and its value is
KEY_MATERIAL_DOES_NOT_EXPIRE
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "StringEquals": { "kms:ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE" } } }
You can also use the kms:ExpirationModel
condition key to allow a user to
import key material only when the key material expires, without specifying an expiration date in the condition.
The following example policy statement uses the kms:ExpirationModel
condition
key with the Null condition operator to allow a user to import key material only when the
request does not have an ExpirationModel
parameter.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "Null": { "kms:ExpirationModel": true } } }
See Also
kms:GrantConstraintType
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
You can use this condition key to control access to the CreateGrant operation based on the type of grant constraint in the request.
When you create a grant, you can optionally specify a grant constraint to allow the
operations that the grant permit only when a particular encryption context is present. The grant constraint can be one of two types:
EncryptionContextEquals
or EncryptionContextSubset
. You can use
this condition key to check that the request contains one type or the other.
The following example policy statement uses the kms:GrantConstraintType
condition key to allow a user to create grants only when the request includes an
EncryptionContextEquals
grant constraint. The example shows a policy
statement in a key policy.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:GrantConstraintType": "EncryptionContextEquals" } } }
See Also
kms:GrantIsForAWSResource
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
Boolean |
|
Key policies and IAM policies |
Allows or denies access to the CreateGrant, ListGrants, or RevokeGrant operations when any of the AWS services that is integrated with AWS KMS performs the grant operation on the user's behalf. This condition key does not affect the user's permissions to perform the grant operation directly.
For example, the following key policy statement uses the
kms:GrantIsForAWSResource
condition key. It allows a user to create grants on
this CMK only when the grant is created on the user's behalf by any one of the integrated
services. It does not allow the user to create grants directly.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "Bool": { "kms:GrantIsForAWSResource": true } } }
See Also
kms:GrantOperations
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
You can use this condition key to control access to the CreateGrant operation based on the grant operations in the request. For example, you can allow a user to create grants that delegate permission to encrypt but not decrypt.
The following example policy statement uses the kms:GrantOperations
condition key to allow a user to create grants that delegate permission to encrypt
and
re-encrypt when this CMK is the destination CMK. The example shows a policy statement
in a
key policy.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "ForAllValues:StringEquals": { "kms:GrantOperations": [ "Encrypt", "ReEncryptTo" ] } } }
See Also
kms:GranteePrincipal
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
IAM and key policies |
You can use this condition key to control access to the CreateGrant operation based on the value
of the GranteePrincipal parameter in the request. For example, you can allow a user to
create grants to use a CMK only when the grantee principal in the CreateGrant
request matches the principal specified in the condition statement.
The following example policy statement uses the kms:GranteePrincipal
condition key to allow a user to create grants for a CMK only when the grantee principal
in
the grant is the LimitedAdminRole
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:GranteePrincipal": "arn:aws:iam::111122223333:role/LimitedAdminRole" } } }
See Also
kms:KeyOrigin
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
CMK resource operations |
IAM policies Key policies and IAM policies |
The kms:KeyOrigin
condition key controls access to operations based on the
value of the Origin
property of the CMK that is created by or used in the
operation.
You can use this condition key to control access to the CreateKey operation based on the value of
the Origin
parameter in the request. Valid values for Origin
are AWS_KMS
,
AWS_CLOUDHSM
, and EXTERNAL
.
For example, you can allow a user to create a CMK only when the key material is
generated in KMS (AWS_KMS
), only when the key material is generated in an AWS CloudHSM
cluster that is associated with a custom key
store (AWS_CLOUDHSM
), or only when the key material is imported from an external source (EXTERNAL
).
The following example policy statement uses the kms:KeyOrigin
condition key
to allow a user to create a CMK only when AWS KMS creates the key material.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateKey", "Resource": "*", "Condition": { "StringEquals": { "kms:KeyOrigin": "AWS_KMS" } } }
You can also use the kms:KeyOrigin
condition key to control access to
operations that use or manage a CMK based on the Origin
property of the CMK
used for the operation. The operation must be a CMK resource operation, that is, an operation that is authorized for a particular CMK. To identify the CMK
resource operations, in the Actions
and Resources Table, look for a value of CMK
in the Resources
column for the operation.
For example, the following IAM policy allows principals to perform the specified CMK resource operations, but only with CMKs in the account that were created in a custom key store.
{ "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyWithoutPlaintext", "kms:GenerateDataKeyPair", "kms:GenerateDataKeyPairWithoutPlaintext", "kms:ReEncrypt*" ], "Resource": { "arn:aws:kms:us-west-2:111122223333:key/*" }, "Condition": { "StringEquals": { "kms:KeyOrigin": "AWS_CLOUDHSM" } } }
See Also
kms:MessageType
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
The kms:MessageType
condition key controls access to the Sign and Verify operations based on the value of the
MessageType
parameter in the request. Valid values for
MessageType
are RAW
and DIGEST
.
For example, the following key policy statement uses the kms:MessageType
condition key to allow a user to use an asymmetric CMK to sign a message, but not
a message
digest.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:Sign", "Resource": "*", "Condition": { "StringEquals": { "kms:MessageType": "RAW" } } }
See Also
kms:ReEncryptOnSameKey
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
Boolean |
|
Key policies and IAM policies |
You can use this condition key to control access to the ReEncrypt operation based on whether the
request specifies a destination CMK that is the same one used for the original encryption.
For example, the following policy statement uses the kms:ReEncryptOnSameKey
condition key to allow a user to reencrypt only when the destination CMK is the same
one
used for the original encryption. The example shows a policy statement in a key
policy.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:ReEncrypt*", "Resource": "*", "Condition": { "Bool": { "kms:ReEncryptOnSameKey": true } } }
kms:RetiringPrincipal
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String (list) |
|
Key policies and IAM policies |
You can use this condition key to control access to the CreateGrant operation based on the value
of the RetiringPrincipal parameter in the request. For example, you can allow a user to
create grants to use a CMK only when the RetiringPrincipal
in the
CreateGrant
request matches the RetiringPrincipal
in the
condition statement.
The following example policy statement allows a user to create grants for the CMK.
The
kms:RetiringPrincipal
condition key restricts the permission to
CreateGrant
requests where the retiring principal in the grant is either the
LimitedAdminRole
or the OpsAdmin
user.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:CreateGrant", "Resource": "*", "Condition": { "StringEquals": { "kms:RetiringPrincipal": [ "arn:aws:iam::111122223333:role/LimitedAdminRole", "arn:aws:iam::111122223333:user/OpsAdmin" ] } } }
See Also
kms:SigningAlgorithm
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
You can use the kms:SigningAlgorithm
condition key to control access to the
Sign and Verify operations based on the value of the
SigningAlgorithm parameter in the request. This condition key has no effect on
operations performed outside of AWS KMS, such as verifying signatures with the public
key in
an asymmetric CMK pair outside of AWS KMS.
The following example key policy allows users who can assume the testers
role to use the CMK to sign messages only when the signing algorithm used for the
request is
an RSASSA_PSS algorithm, such as RSASSA_PSS_SHA512
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/testers" }, "Action": "kms:Sign", "Resource": "*", "Condition": { "StringLike": { "kms:SigningAlgorithm": "RSASSA_PSS*" } } }
See Also
kms:ValidTo
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
Timestamp |
|
Key policies and IAM policies |
The kms:ValidTo
condition key controls access to the ImportKeyMaterial operation based on
the value of the ValidTo parameter in the request, which determines when the imported key material
expires. The value is expressed in Unix
time.
By default, the ValidTo
parameter is required in an
ImportKeyMaterial
request. However, if the value of the ExpirationModel parameter is KEY_MATERIAL_DOES_NOT_EXPIRE
, the
ValidTo
parameter is invalid. You can also use the kms:ExpirationModel condition key to
require the ExpirationModel
parameter or a specific parameter value.
The following example policy statement allows a user to import key material into a
CMK.
The kms:ValidTo
condition key limits the permission to
ImportKeyMaterial
requests where the ValidTo
value is less than
or equal to 1546257599.0
(December 31, 2018 11:59:59 PM).
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:ImportKeyMaterial", "Resource": "*", "Condition": { "NumericLessThanEquals": { "kms:ValidTo": "1546257599.0" } } }
See Also
kms:ViaService
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
The |
Key policies and IAM policies |
The kms:ViaService
condition key limits use of an AWS KMS customer master key (CMK) to requests from specified AWS
services. You can specify one or more services in each kms:ViaService
condition
key.
For example, the following statement from a key policy uses the
kms:ViaService
condition key to allow a customer
managed CMK to be used for the specified actions only when the request comes from
Amazon EC2 or Amazon RDS in the US West (Oregon) region on behalf of
ExampleUser
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:CreateGrant", "kms:ListGrants", "kms:DescribeKey" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "ec2.us-west-2.amazonaws.com", "rds.us-west-2.amazonaws.com" ] } } }
You can also use a kms:ViaService
condition key to deny permission to use a
CMK when the request comes from particular services. For example, the following policy
statement from a key policy uses a kms:ViaService
condition key to prevent a
customer managed CMK from being used for Encrypt
operations when the request
comes from AWS Lambda on behalf of ExampleUser
.
{ "Effect": "Deny", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": [ "kms:Encrypt" ], "Resource": "*", "Condition": { "StringEquals": { "kms:ViaService": [ "lambda.us-west-2.amazonaws.com" ] } } }
Important
When you use the kms:ViaService
condition key, the service makes the
request on behalf of a principal in the AWS account. These principals must have the
following permissions:
-
Permission to use the CMK. The principal needs to grant these permissions to the integrated service so the service can use the customer managed CMK on behalf of the principal. For more information, see How AWS Services use AWS KMS.
-
Permission to use the integrated service. For details about giving users access to an AWS service that integrates with AWS KMS, consult the documentation for the integrated service.
All AWS managed CMKs use a
kms:ViaService
condition key in their key policy document. This condition
allows the CMK to be used only for requests that come from the service that created
the CMK.
To see the key policy for an AWS managed CMK, use the GetKeyPolicy operation.
The kms:ViaService
condition key is valid in IAM and key policy statements.
The services that you specify must be integrated
with AWS KMS and support the kms:ViaService
condition key.
The following table lists AWS services that are integrated with AWS KMS, support
customer managed CMKs, and support the use of the kms:ViaService
condition key
in customer managed CMKs. The services in this table might not be available in all
regions.
Services that support the kms:ViaService
condition
key in customer managed CMKs
Service Name | KMS ViaService Name |
---|---|
AWS Backup | backup.AWS_region .amazonaws.com
|
Amazon Connect | connect.AWS_region .amazonaws.com
|
AWS Database Migration Service (AWS DMS) | dms.AWS_region .amazonaws.com
|
AWS Directory Service | directoryservice.AWS_region .amazonaws.com
|
Amazon EC2 Systems Manager | ssm.AWS_region .amazonaws.com
|
Amazon Elastic Block Store (Amazon EBS) | ec2.AWS_region .amazonaws.com (EBS only)
|
Amazon Elastic File System | elasticfilesystem.AWS_region .amazonaws.com
|
Amazon Elasticsearch Service | es.AWS_region .amazonaws.com
|
Amazon FSx | fsx.AWS_region .amazonaws.com
|
AWS Glue | glue.AWS_region .amazonaws.com
|
Amazon Kinesis | kinesis.AWS_region .amazonaws.com
|
Amazon Kinesis Video Streams | kinesisvideo.AWS_region .amazonaws.com
|
AWS Lambda | lambda.AWS_region .amazonaws.com
|
Amazon Lex | lex.AWS_region .amazonaws.com
|
Amazon Managed Streaming for Apache Kafka | kafka.AWS_region .amazonaws.com
|
Amazon Neptune | rds.AWS_region .amazonaws.com
|
Amazon Redshift | redshift.AWS_region .amazonaws.com
|
Amazon Relational Database Service (Amazon RDS) | rds.AWS_region .amazonaws.com
|
Amazon RDS Performance Insights | rds.AWS_region .amazonaws.com
|
AWS Secrets Manager (Secrets Manager) | secretsmanager.AWS_region .amazonaws.com
|
Amazon Simple Email Service (Amazon SES) | ses.AWS_region .amazonaws.com
|
Amazon Simple Notification Service (Amazon SNS) | sns.AWS_region .amazonaws.com
|
Amazon Simple Storage Service (Amazon S3) | s3.AWS_region .amazonaws.com
|
AWS Snowball | importexport.AWS_region .amazonaws.com
|
Amazon SQS | sqs.AWS_region .amazonaws.com
|
Amazon WorkMail | workmail.AWS_region .amazonaws.com
|
Amazon WorkSpaces | workspaces.AWS_region .amazonaws.com
|
AWS X-Ray | xray.AWS_region .amazonaws.com
|
kms:WrappingAlgorithm
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
This condition key controls access to the GetParametersForImport operation based on the value of the WrappingAlgorithm parameter in the request. You can use this condition to require principals to use a particular algorithm to encrypt key material during the import process. Requests for the required public key and import token fail when they specify a different wrapping algorithm.
The following example policy statement uses the kms:WrappingAlgorithm
condition key to give the example user permission to call the
GetParametersForImport
operation, but prevents them from using the
RSAES_OAEP_SHA_1
wrapping algorithm. When the WrappingAlgorithm
in the GetParametersForImport
request is RSAES_OAEP_SHA_1
, the
operation fails.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:GetParametersForImport", "Resource": "*", "Condition": { "StringNotEquals": { "kms:WrappingAlgorithm": "RSAES_OAEP_SHA_1" } } }
See Also
kms:WrappingKeySpec
AWS KMS Condition Keys | Condition Type | API Operations | Policy Type |
---|---|---|---|
|
String |
|
Key policies and IAM policies |
This condition key controls access to the GetParametersForImport operation based on the value of the WrappingKeySpec parameter in the request. You can use this condition to require principals to use a particular type of public key during the import process. If the request specifies a different key type, it fails.
Because the only valid value for the WrappingKeySpec
parameter value is
RSA_2048
, preventing users from using this value effectively prevents them
from using the GetParametersForImport
operation.
The following example policy statement uses the kms:WrappingAlgorithm
condition key to require that the WrappingKeySpec
in the request is
RSA_2048
.
{ "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/ExampleUser" }, "Action": "kms:GetParametersForImport", "Resource": "*", "Condition": { "StringEquals": { "kms:WrappingKeySpec": "RSA_2048" } } }
See Also