AWS Key Management Service

(1)

AWS Key Management Service

API Reference

API Version 2014-11-01

(2)

AWS Key Management Service: API Reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome

AWS Key Management Service (AWS KMS) is an encryption and key management web service. This guide describes the AWS KMS operations that you can call programmatically. For general information about AWS KMS, see the AWS Key Management Service Developer Guide.

NoteAWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term.

AWS provides SDKs that consist of libraries and sample code for various programming languages and platforms (Java, Ruby, .Net, macOS, Android, etc.). The SDKs provide a convenient way to create programmatic access to AWS KMS and other AWS services. For example, the SDKs take care of tasks such as signing requests (see below), managing errors, and retrying requests automatically. For more information about the AWS SDKs, including how to download and install them, see Tools for Amazon Web Services.

We recommend that you use the AWS SDKs to make programmatic API calls to AWS KMS.

If you need to use FIPS 140-2 validated cryptographic modules when communicating with AWS, use the FIPS endpoint in your preferred AWS Region. For more information about the available FIPS endpoints, see Service endpoints in the AWS Key Management Service topic of the Amazon Web Services General Reference.

Clients must support TLS (Transport Layer Security) 1.0. We recommend TLS 1.2. Clients must also support cipher suites with Perfect Forward Secrecy (PFS) such as Ephemeral Diﬃe-Hellman (DHE) or Elliptic Curve Ephemeral Diﬃe-Hellman (ECDHE). Most modern systems such as Java 7 and later support these modes.

Signing Requests

Requests must be signed by using an access key ID and a secret access key. We strongly recommend that you do not use your AWS account (root) access key ID and secret key for everyday work with AWS KMS.

Instead, use the access key ID and secret access key for an IAM user. You can also use the AWS Security Token Service to generate temporary security credentials that you can use to sign requests.

All AWS KMS operations require Signature Version 4.

Logging API Requests

AWS KMS supports AWS CloudTrail, a service that logs AWS API calls and related events for your AWS account and delivers them to an Amazon S3 bucket that you specify. By using the information collected by CloudTrail, you can determine what requests were made to AWS KMS, who made the request, when it was made, and so on. To learn more about CloudTrail, including how to turn it on and ﬁnd your log ﬁles, see the AWS CloudTrail User Guide.

Additional Resources

For more information about credentials and request signing, see the following:

• AWS Security Credentials - This topic provides general information about the types of credentials used to access AWS.

• Temporary Security Credentials - This section of the IAM User Guide describes how to create and use temporary security credentials.

• Signature Version 4 Signing Process - This set of topics walks you through the process of signing a request using an access key ID and a secret access key.

(11)

Commonly Used API Operations

Of the API operations discussed in this guide, the following will prove the most useful for most applications. You will likely perform operations other than these, such as creating keys and assigning policies, by using the console.

• Encrypt (p. 75)

• Decrypt (p. 36)

• GenerateDataKey (p. 81)

• GenerateDataKeyWithoutPlaintext (p. 97)

This document was last published on March 6, 2022.

(12)

Actions

The following actions are supported:

• CancelKeyDeletion (p. 5)

• ConnectCustomKeyStore (p. 8)

• CreateAlias (p. 11)

• CreateCustomKeyStore (p. 15)

• CreateGrant (p. 19)

• CreateKey (p. 26)

• Decrypt (p. 36)

• DeleteAlias (p. 42)

• DeleteCustomKeyStore (p. 45)

• DeleteImportedKeyMaterial (p. 48)

• DescribeCustomKeyStores (p. 51)

• DescribeKey (p. 55)

• DisableKey (p. 60)

• DisableKeyRotation (p. 63)

• DisconnectCustomKeyStore (p. 66)

• EnableKey (p. 69)

• EnableKeyRotation (p. 72)

• Encrypt (p. 75)

• GenerateDataKey (p. 81)

• GenerateDataKeyPair (p. 87)

• GenerateDataKeyPairWithoutPlaintext (p. 92)

• GenerateDataKeyWithoutPlaintext (p. 97)

• GenerateRandom (p. 103)

• GetKeyPolicy (p. 106)

• GetKeyRotationStatus (p. 110)

• GetParametersForImport (p. 114)

• GetPublicKey (p. 119)

• ImportKeyMaterial (p. 124)

• ListAliases (p. 129)

• ListGrants (p. 134)

• ListKeyPolicies (p. 140)

• ListKeys (p. 144)

• ListResourceTags (p. 148)

• ListRetirableGrants (p. 152)

• PutKeyPolicy (p. 157)

• ReEncrypt (p. 162)

• ReplicateKey (p. 170)

• RetireGrant (p. 177)

• RevokeGrant (p. 181)

• ScheduleKeyDeletion (p. 184)

(13)

• Sign (p. 189)

• TagResource (p. 194)

• UntagResource (p. 198)

• UpdateAlias (p. 201)

• UpdateCustomKeyStore (p. 205)

• UpdateKeyDescription (p. 210)

• UpdatePrimaryRegion (p. 213)

• Verify (p. 216)

(14)

CancelKeyDeletion

Cancels the deletion of a KMS key. When this operation succeeds, the key state of the KMS key is Disabled. To enable the KMS key, use EnableKey (p. 69).

For more information about scheduling and canceling deletion of a KMS key, see Deleting KMS keys in the AWS Key Management Service Developer Guide.

The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of AWS KMS keys in the AWS Key Management Service Developer Guide.

Cross-account use: No. You cannot perform this operation on a KMS key in a diﬀerent AWS account.

Required permissions: kms:CancelKeyDeletion (key policy) Related operations: ScheduleKeyDeletion (p. 184)

Request Syntax

{ "KeyId": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 239).

The request accepts the following data in JSON format.

NoteIn the following list, the required parameters are described ﬁrst.

KeyId (p. 5)

Identiﬁes the KMS key whose deletion is being canceled.

Specify the key ID or key ARN of the KMS key.

For example:

• Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

• Key ARN: arn:aws:kms:us-

east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab To get the key ID and key ARN for a KMS key, use ListKeys (p. 144) or DescribeKey (p. 55).

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes

Response Syntax

{

(15)

Response Elements

"KeyId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

KeyId (p. 5)

The Amazon Resource Name (key ARN) of the KMS key whose deletion is canceled.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors (p. 241).

DependencyTimeoutException

The system timed out while trying to fulﬁll the request. The request can be retried.

HTTP Status Code: 500 InvalidArnException

The request was rejected because a speciﬁed ARN, or an ARN in a key policy, is not valid.

HTTP Status Code: 400 KMSInternalException

The request was rejected because an internal exception occurred. The request can be retried.

HTTP Status Code: 500 KMSInvalidStateException

The request was rejected because the state of the speciﬁed resource is not valid for this request.

For more information about how key state aﬀects the use of a KMS key, see Key state: Eﬀect on your KMS key in the AWS Key Management Service Developer Guide .

HTTP Status Code: 400 NotFoundException

The request was rejected because the speciﬁed entity or resource could not be found.

HTTP Status Code: 400

Examples

Example Request

The following example is formatted for legibility.

(16)

See Also

POST / HTTP/1.1

Host: kms.us-east-2.amazonaws.com Content-Length: 48

X-Amz-Target: TrentService.CancelKeyDeletion X-Amz-Date: 20161025T182658Z

Content-Type: application/x-amz-json-1.1 Authorization: AWS4-HMAC-SHA256\

Credential=AKIAI44QH8DHBEXAMPLE/20161025/us-east-2/kms/aws4_request,\

SignedHeaders=content-type;host;x-amz-date;x-amz-target,\

Signature=1a600d3edf52b2c14bd6fb6fa44c6ca591bdcb02931fd9cac2e8aa66bd52e3bf {"KeyId":"1234abcd-12ab-34cd-56ef-1234567890ab"}

Example Response

This example illustrates one usage of CancelKeyDeletion.

HTTP/1.1 200 OK Server: Server

Date: Tue, 25 Oct 2016 18:27:01 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 87

Connection: keep-alive

x-amzn-RequestId: 9f3b3cb8-9ae0-11e6-ac6b-03478315fc57

{"KeyId":"arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"}

ConnectCustomKeyStore

Connects or reconnects a custom key store to its associated AWS CloudHSM cluster.

The custom key store must be connected before you can create KMS keys in the key store or use the KMS keys it contains. You can disconnect and reconnect a custom key store at any time.

To connect a custom key store, its associated AWS CloudHSM cluster must have at least one active HSM.

To get the number of active HSMs in a cluster, use the DescribeClusters operation. To add HSMs to the cluster, use the CreateHsm operation. Also, the kmsuser crypto user (CU) must not be logged into the cluster. This prevents AWS KMS from using this account to log in.

The connection process can take an extended amount of time to complete; up to 20 minutes. This operation starts the connection process, but it does not wait for it to complete. When it succeeds, this operation quickly returns an HTTP 200 response and a JSON object with no properties. However, this response does not indicate that the custom key store is connected. To get the connection state of the custom key store, use the DescribeCustomKeyStores (p. 51) operation.

During the connection process, AWS KMS ﬁnds the AWS CloudHSM cluster that is associated with the custom key store, creates the connection infrastructure, connects to the cluster, logs into the AWS CloudHSM client as the kmsuser CU, and rotates its password.

The ConnectCustomKeyStore operation might fail for various reasons. To ﬁnd the reason, use the DescribeCustomKeyStores (p. 51) operation and see the ConnectionErrorCode in the response. For help interpreting the ConnectionErrorCode, see CustomKeyStoresListEntry (p. 224).

To ﬁx the failure, use the DisconnectCustomKeyStore (p. 66) operation to disconnect the custom key store, correct the error, use the UpdateCustomKeyStore (p. 205) operation if necessary, and then use ConnectCustomKeyStore again.

If you are having trouble connecting or disconnecting a custom key store, see Troubleshooting a Custom Key Store in the AWS Key Management Service Developer Guide.

Cross-account use: No. You cannot perform this operation on a custom key store in a diﬀerent AWS account.

Required permissions: kms:ConnectCustomKeyStore (IAM policy) Related operations

• CreateCustomKeyStore (p. 15)

Request Syntax

{

"CustomKeyStoreId": "string"

}

Request Parameters

(18)

Response Elements

CustomKeyStoreId (p. 8)

Enter the key store ID of the custom key store that you want to connect. To ﬁnd the ID of a custom key store, use the DescribeCustomKeyStores (p. 51) operation.

Type: String

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

CloudHsmClusterInvalidConﬁgurationException

The request was rejected because the associated AWS CloudHSM cluster did not meet the conﬁguration requirements for a custom key store.

• The cluster must be conﬁgured with private subnets in at least two diﬀerent Availability Zones in the Region.

• The security group for the cluster (cloudhsm-cluster-<cluster-id>-sg) must include inbound rules and outbound rules that allow TCP traﬃc on ports 2223-2225. The Source in the inbound rules and the Destination in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them. To get information about a particular security group, use the DescribeSecurityGroups operation.

• The cluster must contain at least as many HSMs as the operation requires. To add HSMs, use the AWS CloudHSM CreateHsm operation.

For the CreateCustomKeyStore (p. 15), UpdateCustomKeyStore (p. 205), and

CreateKey (p. 26) operations, the AWS CloudHSM cluster must have at least two active HSMs, each in a diﬀerent Availability Zone. For the ConnectCustomKeyStore (p. 8) operation, the AWS CloudHSM must contain at least one active HSM.

For information about the requirements for an AWS CloudHSM cluster that is associated with a custom key store, see Assemble the Prerequisites in the AWS Key Management Service Developer Guide. For information about creating a private subnet for an AWS CloudHSM cluster, see Create a Private Subnet in the AWS CloudHSM User Guide. For information about cluster security groups, see Conﬁgure a Default Security Group in the AWS CloudHSM User Guide .

CloudHsmClusterNotActiveException

The request was rejected because the AWS CloudHSM cluster that is associated with the custom key store is not active. Initialize and activate the cluster and try the command again. For detailed instructions, see Getting Started in the AWS CloudHSM User Guide.

(19)

See Also

CustomKeyStoreInvalidStateException

The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores (p. 51) operation.

This exception is thrown under the following conditions:

• You requested the CreateKey (p. 26) or GenerateRandom (p. 103) operation in a custom key store that is not connected. These operations are valid only when the custom key store ConnectionState is CONNECTED.

• You requested the UpdateCustomKeyStore (p. 205) or DeleteCustomKeyStore (p. 45)

operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED.

• You requested the ConnectCustomKeyStore (p. 8) operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values.

CustomKeyStoreNotFoundException

The request was rejected because AWS KMS cannot ﬁnd a custom key store with the speciﬁed key store name or ID.

CreateAlias

Creates a friendly name for a KMS key.

NoteAdding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC in AWS KMS in the AWS Key Management Service Developer Guide.

You can use an alias to identify a KMS key in the AWS KMS console, in the DescribeKey (p. 55) operation and in cryptographic operations, such as Encrypt (p. 75) and GenerateDataKey (p. 81).

You can also change the KMS key that's associated with the alias (UpdateAlias (p. 201)) or delete the alias (DeleteAlias (p. 42)) at any time. These operations don't aﬀect the underlying KMS key.

You can associate the alias with any customer managed key in the same AWS Region. Each alias is associated with only one KMS key at a time, but a KMS key can have multiple aliases. A valid KMS key is required. You can't create an alias without a KMS key.

The alias must be unique in the account and Region, but you can have aliases with the same name in diﬀerent Regions. For detailed information about aliases, see Using aliases in the AWS Key Management Service Developer Guide.

This operation does not return a response. To get the alias that you created, use the ListAliases (p. 129) operation.

Cross-account use: No. You cannot perform this operation on an alias in a diﬀerent AWS account.

Required permissions

• kms:CreateAlias on the alias (IAM policy).

• kms:CreateAlias on the KMS key (key policy).

For details, see Controlling access to aliases in the AWS Key Management Service Developer Guide.

Related operations:

• DeleteAlias (p. 42)

• ListAliases (p. 129)

• UpdateAlias (p. 201)

Request Syntax

{

"AliasName": "string", "TargetKeyId": "string"

}

Request Parameters

(21)

Response Elements

AliasName (p. 11)

Speciﬁes the alias name. This value must begin with alias/ followed by a name, such as alias/

ExampleAlias.

The AliasName value must be string of 1-256 characters. It can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name cannot begin with alias/aws/. The alias/aws/ preﬁx is reserved for AWS managed keys.

Type: String

Pattern: alias/^[a-zA-Z0-9/_-]+$

Required: Yes TargetKeyId (p. 11)

Associates the alias with the speciﬁed customer managed key. The KMS key must be in the same AWS Region.

A valid key ID is required. If you supply a null or empty string value, this operation returns an error.

For help ﬁnding the key ID and ARN, see Finding the Key ID and ARN in the AWS Key Management Service Developer Guide .

Specify the key ID or key ARN of the KMS key.

For example:

Type: String

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

AlreadyExistsException

The request was rejected because it attempted to create a resource that already exists.

(22)

Examples

HTTP Status Code: 500 InvalidAliasNameException

The request was rejected because the speciﬁed alias name is not valid.

HTTP Status Code: 400 LimitExceededException

The request was rejected because a quota was exceeded. For more information, see Quotas in the AWS Key Management Service Developer Guide.

Examples

Example Request

The following example is formatted for legibility.

POST / HTTP/1.1

Host: kms.us-west-2.amazonaws.com Content-Length: 87

X-Amz-Target: TrentService.CreateAlias X-Amz-Date: 20160517T204220Z

Credential=AKIAI44QH8DHBEXAMPLE/20160517/us-west-2/kms/aws4_request,\

Signature=ca7bcf1e8d5364dc3f0d881c05bdadf36f498c6c6a8b576a060142d9b2199123 {

"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "AliasName": "alias/ExampleAlias"

}

(23)

See Also

Example Response

This example illustrates one usage of CreateAlias.

Date: Tue, 17 May 2016 20:42:25 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 0

x-amzn-RequestId: dcb07ca7-1c6f-11e6-8540-77c363708b91

CreateCustomKeyStore

Creates a custom key store that is associated with an AWS CloudHSM cluster that you own and manage.

This operation is part of the Custom Key Store feature feature in AWS KMS, which combines the

convenience and extensive integration of AWS KMS with the isolation and control of a single-tenant key store.

Before you create the custom key store, you must assemble the required elements, including an AWS CloudHSM cluster that fulﬁlls the requirements for a custom key store. For details about the required elements, see Assemble the Prerequisites in the AWS Key Management Service Developer Guide.

When the operation completes successfully, it returns the ID of the new custom key store. Before you can use your new custom key store, you need to use the ConnectCustomKeyStore (p. 8) operation to connect the new key store to its AWS CloudHSM cluster. Even if you are not going to use your custom key store immediately, you might want to connect it to verify that all settings are correct and then disconnect it until you are ready to use it.

For help with failures, see Troubleshooting a Custom Key Store in the AWS Key Management Service Developer Guide.

Cross-account use: No. You cannot perform this operation on a custom key store in a diﬀerent AWS account.

Required permissions: kms:CreateCustomKeyStore (IAM policy).

• ConnectCustomKeyStore (p. 8)

Request Syntax

{ "CloudHsmClusterId": "string", "CustomKeyStoreName": "string", "KeyStorePassword": "string", "TrustAnchorCertificate": "string"

}

Request Parameters

(25)

Response Syntax

CloudHsmClusterId (p. 15)

Identiﬁes the AWS CloudHSM cluster for the custom key store. Enter the cluster ID of any active AWS CloudHSM cluster that is not already associated with a custom key store. To ﬁnd the cluster ID, use the DescribeClusters operation.

Type: String

Required: Yes

CustomKeyStoreName (p. 15)

Speciﬁes a friendly name for the custom key store. The name must be unique in your AWS account.

Type: String

Required: Yes

KeyStorePassword (p. 15)

Enter the password of the kmsuser crypto user (CU) account in the speciﬁed AWS CloudHSM cluster.

AWS KMS logs into the cluster as this user to manage key material on your behalf.

The password must be a string of 7 to 32 characters. Its value is case sensitive.

This parameter tells AWS KMS the kmsuser account password; it does not change the password in the AWS CloudHSM cluster.

Type: String

Required: Yes

TrustAnchorCertiﬁcate (p. 15)

Enter the content of the trust anchor certiﬁcate for the cluster. This is the content of the customerCA.crt ﬁle that you created when you initialized the cluster.

Type: String

Required: Yes

Response Syntax

{

"CustomKeyStoreId": "string"

}

Response Elements

(26)

Errors

A unique identiﬁer for the new custom key store.

Type: String

Errors

CloudHsmClusterInUseException

The request was rejected because the speciﬁed AWS CloudHSM cluster is already associated with a custom key store or it shares a backup history with a cluster that is associated with a custom key store. Each custom key store must be associated with a diﬀerent AWS CloudHSM cluster.

Clusters that share a backup history have the same cluster certiﬁcate. To view the cluster certiﬁcate of a cluster, use the DescribeClusters operation.

CloudHsmClusterInvalidConﬁgurationException

The request was rejected because the associated AWS CloudHSM cluster did not meet the conﬁguration requirements for a custom key store.

• The cluster must be conﬁgured with private subnets in at least two diﬀerent Availability Zones in the Region.

• The security group for the cluster (cloudhsm-cluster-<cluster-id>-sg) must include inbound rules and outbound rules that allow TCP traﬃc on ports 2223-2225. The Source in the inbound rules and the Destination in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them. To get information about a particular security group, use the DescribeSecurityGroups operation.

• The cluster must contain at least as many HSMs as the operation requires. To add HSMs, use the AWS CloudHSM CreateHsm operation.

For the CreateCustomKeyStore (p. 15), UpdateCustomKeyStore (p. 205), and

CreateKey (p. 26) operations, the AWS CloudHSM cluster must have at least two active HSMs, each in a diﬀerent Availability Zone. For the ConnectCustomKeyStore (p. 8) operation, the AWS CloudHSM must contain at least one active HSM.

For information about the requirements for an AWS CloudHSM cluster that is associated with a custom key store, see Assemble the Prerequisites in the AWS Key Management Service Developer Guide. For information about creating a private subnet for an AWS CloudHSM cluster, see Create a Private Subnet in the AWS CloudHSM User Guide. For information about cluster security groups, see Conﬁgure a Default Security Group in the AWS CloudHSM User Guide .

CloudHsmClusterNotActiveException

The request was rejected because the AWS CloudHSM cluster that is associated with the custom key store is not active. Initialize and activate the cluster and try the command again. For detailed instructions, see Getting Started in the AWS CloudHSM User Guide.

(27)

See Also

CloudHsmClusterNotFoundException

The request was rejected because AWS KMS cannot find the AWS CloudHSM cluster with the specified cluster ID. Retry the request with a different cluster ID.

CustomKeyStoreNameInUseException

The request was rejected because the speciﬁed custom key store name is already assigned to another custom key store in the account. Try again with a custom key store name that is unique in the account.

HTTP Status Code: 400 IncorrectTrustAnchorException

The request was rejected because the trust anchor certificate in the request is not the trust anchor certificate for the specified AWS CloudHSM cluster.

When you initialize the cluster, you create the trust anchor certiﬁcate and save it in the customerCA.crt ﬁle.

CreateGrant

Adds a grant to a KMS key.

A grant is a policy instrument that allows AWS principals to use KMS keys in cryptographic operations.

It also can allow them to view a KMS key (DescribeKey (p. 55)) and create and manage grants. When authorizing access to a KMS key, grants are considered along with key policies and IAM policies. Grants are often used for temporary permissions because you can create one, use its permissions, and delete it without changing your key policies or IAM policies.

For detailed information about grants, including grant terminology, see Grants in AWS KMS in the AWS Key Management Service Developer Guide . For examples of working with grants in several programming languages, see Programming grants.

The CreateGrant operation returns a GrantToken and a GrantId.

• When you create, retire, or revoke a grant, there might be a brief delay, usually less than ﬁve minutes, until the grant is available throughout AWS KMS. This state is known as eventual consistency. Once the grant has achieved eventual consistency, the grantee principal can use the permissions in the grant without identifying the grant.

However, to use the permissions in the grant immediately, use the GrantToken that CreateGrant returns. For details, see Using a grant token in the AWS Key Management Service Developer Guide .

• The CreateGrant operation also returns a GrantId. You can use the GrantId and a key identiﬁer to identify the grant in the RetireGrant (p. 177) and RevokeGrant (p. 181) operations. To ﬁnd the grant ID, use the ListGrants (p. 134) or ListRetirableGrants (p. 152) operations.

Cross-account use: Yes. To perform this operation on a KMS key in a diﬀerent AWS account, specify the key ARN in the value of the KeyId parameter.

Required permissions: kms:CreateGrant (key policy) Related operations:

• ListGrants (p. 134)

• ListRetirableGrants (p. 152)

• RetireGrant (p. 177)

• RevokeGrant (p. 181)

Request Syntax

{

"Constraints": {

"EncryptionContextEquals": { "string" : "string"

},

"EncryptionContextSubset": { "string" : "string"

} },

"GranteePrincipal": "string", "GrantTokens": [ "string" ], "KeyId": "string",

(29)

Request Parameters

"Name": "string",

"Operations": [ "string" ], "RetiringPrincipal": "string"

}

Request Parameters

GranteePrincipal (p. 19)

The identity that gets the permissions speciﬁed in the grant.

To specify the principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid AWS principals include AWS accounts (root), IAM users, IAM roles, federated users, and assumed role users. For examples of the ARN syntax to use for specifying a principal, see AWS Identity and Access Management (IAM) in the Example ARNs section of the AWS General Reference.

Type: String

Pattern: ^[\w+=,.@:/-]+$

Required: Yes KeyId (p. 19)

Identiﬁes the KMS key for the grant. The grant gives principals permission to use this KMS key.

Specify the key ID or key ARN of the KMS key. To specify a KMS key in a diﬀerent AWS account, you must use the key ARN.

For example:

Type: String

Required: Yes Operations (p. 19)

A list of operations that the grant permits.

The operation must be supported on the KMS key. For example, you cannot create a grant for a symmetric KMS key that allows the Sign (p. 189) operation, or a grant for an asymmetric KMS key that allows the GenerateDataKey (p. 81) operation. If you try, AWS KMS returns a

ValidationError exception. For details, see Grant operations in the AWS Key Management Service Developer Guide.

(30)

Request Parameters

Type: Array of strings

Valid Values: Decrypt | Encrypt | GenerateDataKey |

GenerateDataKeyWithoutPlaintext | ReEncryptFrom | ReEncryptTo | Sign

Required: Yes Constraints (p. 19)

Speciﬁes a grant constraint.

AWS KMS supports the EncryptionContextEquals and EncryptionContextSubset grant constraints. Each constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters.

These grant constraints allow the permissions in the grant only when the encryption context in the request matches (EncryptionContextEquals) or includes (EncryptionContextSubset) the encryption context speciﬁed in this structure. For information about grant constraints, see Using grant constraints in the AWS Key Management Service Developer Guide. For more information about encryption context, see Encryption Context in the AWS Key Management Service Developer Guide . The encryption context grant constraints are supported only on operations that include an

encryption context. You cannot use an encryption context grant constraint for cryptographic operations with asymmetric KMS keys or for management operations, such as DescribeKey (p. 55) or RetireGrant (p. 177).

Type: GrantConstraints (p. 227) object Required: No

GrantTokens (p. 19) A list of grant tokens.

Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the AWS Key Management Service Developer Guide.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Required: No Name (p. 19)

A friendly name for the grant. Use this value to prevent the unintended creation of duplicate grants when retrying this request.

When this value is absent, all CreateGrant requests result in a new grant with a unique GrantId even if all the supplied parameters are identical. This can result in unintended duplicates when you retry the CreateGrant request.

When this value is present, you can retry a CreateGrant request with identical parameters; if the grant already exists, the original GrantId is returned without creating a new grant. Note that the returned grant token is unique with every CreateGrant request, even when a duplicate GrantId is returned. All grant tokens for the same grant ID can be used interchangeably.

Type: String

(31)

Response Syntax

Pattern: ^[a-zA-Z0-9:/_-]+$

Required: No RetiringPrincipal (p. 19)

The principal that has permission to use the RetireGrant (p. 177) operation to retire the grant.

To specify the principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid AWS principals include AWS accounts (root), IAM users, federated users, and assumed role users.

For examples of the ARN syntax to use for specifying a principal, see AWS Identity and Access Management (IAM) in the Example ARNs section of the AWS General Reference.

The grant determines the retiring principal. Other principals might have permission to retire the grant or revoke the grant. For details, see RevokeGrant (p. 181) and Retiring and revoking grants in the AWS Key Management Service Developer Guide.

Type: String

Pattern: ^[\w+=,.@:/-]+$

Required: No

Response Syntax

{ "GrantId": "string", "GrantToken": "string"

}

Response Elements

GrantId (p. 22)

The unique identiﬁer for the grant.

You can use the GrantId in a ListGrants (p. 134), RetireGrant (p. 177), or RevokeGrant (p. 181) operation.

Type: String

GrantToken (p. 22) The grant token.

Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the AWS Key Management Service Developer Guide.

(32)

Errors

Type: String

Errors

HTTP Status Code: 500 DisabledException

The request was rejected because the speciﬁed KMS key is not enabled.

HTTP Status Code: 400 InvalidArnException

The request was rejected because a speciﬁed ARN, or an ARN in a key policy, is not valid.

HTTP Status Code: 400 InvalidGrantTokenException

The request was rejected because the speciﬁed grant token is not valid.

HTTP Status Code: 400 LimitExceededException

The request was rejected because a quota was exceeded. For more information, see Quotas in the AWS Key Management Service Developer Guide.

Examples

The following examples are formatted for legibility.

(33)

See Also

Example Request

This example illustrates one usage of CreateGrant.

POST / HTTP/1.1

Host: kms.us-east-2.amazonaws.com Content-Length: 176

X-Amz-Target: TrentService.CreateGrant X-Amz-Date: 20161031T202851Z

Credential=AKIAI44QH8DHBEXAMPLE/20161031/us-east-2/kms/aws4_request,\

Signature=84a2b3b8eb50b9bf34ba844cd5e59649fb315a16b447357ae49bf8b87774c8f7 { "Operations": [

"Encrypt", "Decrypt"

], "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",

"KeyId": "arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"

}

Example Response

This example illustrates one usage of CreateGrant.

Date: Mon, 31 Oct 2016 20:28:51 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 585

x-amzn-RequestId: a2d8d452-9fa8-11e6-b30c-dbb8ea4d97c5

{ "GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60", "GrantToken":

"AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNGY3NiKIAgEBAgB4Pa6VDCWW__MSrqnre1HIN0Grt00ViSSuUjhqOC8OT3YAAADfMIHcBgkqhkiG9w0BBwaggc4wgcsCAQAwgcUGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMmqLyBTAegIn9XlK5AgEQgIGXZQjkBcl1dykDdqZBUQ6L1OfUivQy7JVYO2- ZJP7m6f1g8GzV47HX5phdtONAP7K_HQIflcgpkoCqd_fUnE114mSmiagWkbQ5sqAVV3ov-

VeqgrvMe5ZFEWLMSluvBAqdjHEdMIkHMlhlj4ENZbzBfo9Wxk8b8SnwP4kc4gGivedzFXo- dwN8fxjjq_ZZ9JFOj2ijIbj5FyogDCN0drOfi8RORSEuCEmPvjFRMFAwcmwFkN2NPp89amA"

}

CreateKey

Creates a unique customer managed KMS key in your AWS account and Region.

NoteAWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term.

You can use the CreateKey operation to create symmetric or asymmetric KMS keys.

• Symmetric KMS keys contain a 256-bit symmetric key that never leaves AWS KMS unencrypted. To use the KMS key, you must call AWS KMS. You can use a symmetric KMS key to encrypt and decrypt small amounts of data, but they are typically used to generate data keys and data keys pairs. For details, see GenerateDataKey (p. 81) and GenerateDataKeyPair (p. 87).

• Asymmetric KMS keys can contain an RSA key pair or an Elliptic Curve (ECC) key pair. The private key in an asymmetric KMS key never leaves AWS KMS unencrypted. However, you can use the GetPublicKey (p. 119) operation to download the public key so it can be used outside of AWS KMS.

KMS keys with RSA key pairs can be used to encrypt or decrypt data or sign and verify messages (but not both). KMS keys with ECC key pairs can be used only to sign and verify messages.

For information about symmetric and asymmetric KMS keys, see Asymmetric KMS keys in the AWS Key Management Service Developer Guide.

To create diﬀerent types of KMS keys, use the following guidance:

Asymmetric KMS keys

To create an asymmetric KMS key, use the KeySpec parameter to specify the type of key material in the KMS key. Then, use the KeyUsage parameter to determine whether the KMS key will be used to encrypt and decrypt or sign and verify. You can't change these properties after the KMS key is created.

Symmetric KMS keys

When creating a symmetric KMS key, you don't need to specify the KeySpec or KeyUsage parameters. The default value for KeySpec, SYMMETRIC_DEFAULT, and the default value for KeyUsage, ENCRYPT_DECRYPT, are the only valid values for symmetric KMS keys.

Multi-Region primary keys, Imported key material

To create a multi-Region primary key in the local AWS Region, use the MultiRegion parameter with a value of True. To create a multi-Region replica key, that is, a KMS key with the same key ID and key material as a primary key, but in a diﬀerent AWS Region, use the ReplicateKey (p. 170) operation. To change a replica key to a primary key, and its primary key to a replica key, use the UpdatePrimaryRegion (p. 213) operation.

This operation supports multi-Region keys, an AWS KMS feature that lets you create multiple interoperable KMS keys in diﬀerent AWS Regions. Because these KMS keys have the same key ID, key material, and other metadata, you can use them interchangeably to encrypt data in one AWS Region and decrypt it in a diﬀerent AWS Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in AWS KMS in the AWS Key Management Service Developer Guide.

You can create symmetric and asymmetric multi-Region keys and multi-Region keys with imported key material. You cannot create multi-Region keys in a custom key store.

(36)

Request Syntax

To import your own key material, begin by creating a symmetric KMS key with no key material.

To do this, use the Origin parameter of CreateKey with a value of EXTERNAL. Next, use GetParametersForImport (p. 114) operation to get a public key and import token, and use the public key to encrypt your key material. Then, use ImportKeyMaterial (p. 124) with your import token to import the key material. For step-by-step instructions, see Importing Key Material in the AWS Key Management Service Developer Guide . You cannot import the key material into an asymmetric KMS key.

To create a multi-Region primary key with imported key material, use the Origin parameter of CreateKey with a value of EXTERNAL and the MultiRegion parameter with a value of True.

To create replicas of the multi-Region primary key, use the ReplicateKey (p. 170) operation. For more information about multi-Region keys, see Multi-Region keys in AWS KMS in the AWS Key Management Service Developer Guide.

Custom key store

To create a symmetric KMS key in a custom key store, use the CustomKeyStoreId parameter to specify the custom key store. You must also use the Origin parameter with a value of

AWS_CLOUDHSM. The AWS CloudHSM cluster that is associated with the custom key store must have at least two active HSMs in diﬀerent Availability Zones in the AWS Region.

You cannot create an asymmetric KMS key in a custom key store. For information about custom key stores in AWS KMS see Custom key stores in AWS KMS in the AWS Key Management Service Developer Guide .

Cross-account use: No. You cannot use this operation to create a KMS key in a diﬀerent AWS account.

Required permissions: kms:CreateKey (IAM policy). To use the Tags parameter, kms:TagResource (IAM policy). For examples and information about related permissions, see Allow a user to create KMS keys in the AWS Key Management Service Developer Guide.

• DescribeKey (p. 55)

• ListKeys (p. 144)

• ScheduleKeyDeletion (p. 184)

Request Syntax

{ "BypassPolicyLockoutSafetyCheck": boolean, "CustomerMasterKeySpec": "string",

"CustomKeyStoreId": "string", "Description": "string", "KeySpec": "string", "KeyUsage": "string", "MultiRegion": boolean, "Origin": "string", "Policy": "string", "Tags": [

{

"TagKey": "string", "TagValue": "string"

} ]}

(37)

Request Parameters

BypassPolicyLockoutSafetyCheck (p. 27)

A ﬂag to indicate whether to bypass the key policy lockout safety check.

Important

Setting this value to true increases the risk that the KMS key becomes unmanageable. Do not set this value to true indiscriminately.

For more information, refer to the scenario in the Default Key Policy section in the AWS Key Management Service Developer Guide .

Use this parameter only when you include a policy in the request and you intend to prevent the principal that is making the request from making a subsequent PutKeyPolicy (p. 157) request on the KMS key.

The default value is false.

Type: Boolean Required: No

CustomerMasterKeySpec (p. 27) This parameter has been deprecated.

Instead, use the KeySpec parameter.

The KeySpec and CustomerMasterKeySpec parameters work the same way. Only the names diﬀer. We recommend that you use KeySpec parameter in your code. However, to avoid breaking changes, AWS KMS will support both parameters.

Type: String

Required: No

Creates the KMS key in the speciﬁed custom key store and the key material in its associated AWS CloudHSM cluster. To create a KMS key in a custom key store, you must also specify the Origin parameter with a value of AWS_CLOUDHSM. The AWS CloudHSM cluster that is associated with the custom key store must have at least two active HSMs, each in a diﬀerent Availability Zone in the Region.

This parameter is valid only for symmetric KMS keys and regional KMS keys. You cannot create an asymmetric KMS key or a multi-Region key in a custom key store.

To ﬁnd the ID of a custom key store, use the DescribeCustomKeyStores (p. 51) operation.

The response includes the custom key store ID and the ID of the AWS CloudHSM cluster.

(38)

Request Parameters

This operation is part of the Custom Key Store feature feature in AWS KMS, which combines the convenience and extensive integration of AWS KMS with the isolation and control of a single-tenant key store.

Type: String

Required: No Description (p. 27)

A description of the KMS key.

Use a description that helps you decide whether the KMS key is appropriate for a task. The default value is an empty string (no description).

To set or change the description after the key is created, use UpdateKeyDescription (p. 210).

Type: String

Required: No KeySpec (p. 27)

Speciﬁes the type of KMS key to create. The default value, SYMMETRIC_DEFAULT, creates a KMS key with a 256-bit symmetric key for encryption and decryption. For help choosing a key spec for your KMS key, see How to Choose Your KMS key Conﬁguration in the AWS Key Management Service Developer Guide .

The KeySpec determines whether the KMS key contains a symmetric key or an asymmetric key pair.

It also determines the encryption algorithms or signing algorithms that the KMS key supports. You can't change the KeySpec after the KMS key is created. To further restrict the algorithms that can be used with the KMS key, use a condition key in its key policy or IAM policy. For more information, see kms:EncryptionAlgorithm or kms:Signing Algorithm in the AWS Key Management Service Developer Guide .

Important

AWS services that are integrated with AWS KMS use symmetric KMS keys to protect your data. These services do not support asymmetric KMS keys. For help determining whether a KMS key is symmetric or asymmetric, see Identifying Symmetric and Asymmetric KMS keys in the AWS Key Management Service Developer Guide.

AWS KMS supports the following key specs for KMS keys:

• Symmetric key (default)

• SYMMETRIC_DEFAULT (AES-256-GCM)

• Asymmetric RSA key pairs

• RSA_2048

• RSA_3072

• RSA_4096

• Asymmetric NIST-recommended elliptic curve key pairs

• ECC_NIST_P256 (secp256r1)

• Other asymmetric elliptic curve key pairs

• ECC_SECG_P256K1 (secp256k1), commonly used for cryptocurrencies.

(39)

Request Parameters

Type: String

Required: No KeyUsage (p. 27)

Determines the cryptographic operations for which you can use the KMS key. The default value is ENCRYPT_DECRYPT. This parameter is required only for asymmetric KMS keys. You can't change the KeyUsage value after the KMS key is created.

Select only one valid value.

• For symmetric KMS keys, omit the parameter or specify ENCRYPT_DECRYPT.

• For asymmetric KMS keys with RSA key material, specify ENCRYPT_DECRYPT or SIGN_VERIFY.

• For asymmetric KMS keys with ECC key material, specify SIGN_VERIFY.

Type: String

Valid Values: SIGN_VERIFY | ENCRYPT_DECRYPT Required: No

MultiRegion (p. 27)

Creates a multi-Region primary key that you can replicate into other AWS Regions. You cannot change this value after you create the KMS key.

For a multi-Region key, set this parameter to True. For a single-Region KMS key, omit this parameter or set it to False. The default value is False.

This operation supports multi-Region keys, an AWS KMS feature that lets you create multiple interoperable KMS keys in diﬀerent AWS Regions. Because these KMS keys have the same key ID, key material, and other metadata, you can use them interchangeably to encrypt data in one AWS Region and decrypt it in a diﬀerent AWS Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in AWS KMS in the AWS Key Management Service Developer Guide.

This value creates a primary key, not a replica. To create a replica key, use the ReplicateKey (p. 170) operation.

You can create a symmetric or asymmetric multi-Region key, and you can create a multi-Region key with imported key material. However, you cannot create a multi-Region key in a custom key store.

Type: Boolean Required: No Origin (p. 27)

The source of the key material for the KMS key. You cannot change the origin after you create the KMS key. The default is AWS_KMS, which means that AWS KMS creates the key material.

To create a KMS key with no key material (for imported key material), set the value to EXTERNAL. For more information about importing key material into AWS KMS, see Importing Key Material in the AWS Key Management Service Developer Guide. This value is valid only for symmetric KMS keys.

To create a KMS key in an AWS KMS custom key store and create its key material in the associated AWS CloudHSM cluster, set this value to AWS_CLOUDHSM. You must also use the CustomKeyStoreId parameter to identify the custom key store. This value is valid only for symmetric KMS keys.

AWS Key Management Service

AWS Key Management Service

API Reference

API Version 2014-11-01

AWS Key Management Service: API Reference

Table of Contents

Welcome

Actions

CancelKeyDeletion

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example Request

Example Response

See Also

ConnectCustomKeyStore

Request Syntax

Request Parameters

Response Elements

Errors

See Also

CreateAlias

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Example Request

Example Response

See Also

CreateCustomKeyStore

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

See Also

CreateGrant

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example Request

Example Response

See Also

CreateKey

Request Syntax

Request Parameters