Kms Api Reference

AWS Key Management Service
API Reference
API Version 2014-11-01
AWS Key Management Service API Reference
AWS Key Management Service: API Reference

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
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 affiliated with, connected to, or sponsored by Amazon.
Table of Contents
Welcome ........................................................................................................................................... 1
Actions ............................................................................................................................................. 3
CancelKeyDeletion ...................................................................................................................... 5
Request Syntax .................................................................................................................. 5
Request Parameters ............................................................................................................ 5
Response Syntax ................................................................................................................ 5
Response Elements ............................................................................................................. 6
Errors ............................................................................................................................... 6
Examples ........................................................................................................................... 6
See Also ............................................................................................................................ 7
ConnectCustomKeyStore ............................................................................................................. 8
Request Syntax .................................................................................................................. 8
Request Parameters ............................................................................................................ 8
Response Elements ............................................................................................................. 9
Errors ............................................................................................................................... 9
See Also .......................................................................................................................... 10
CreateAlias .............................................................................................................................. 11
Request Syntax ................................................................................................................ 11
Request Parameters .......................................................................................................... 11
Response Elements ........................................................................................................... 12
Errors .............................................................................................................................. 12
Examples ......................................................................................................................... 13
See Also .......................................................................................................................... 13
CreateCustomKeyStore .............................................................................................................. 14
Request Syntax ................................................................................................................ 14
Response Syntax .............................................................................................................. 15
Errors .............................................................................................................................. 15
See Also .......................................................................................................................... 17
CreateGrant ............................................................................................................................. 18
Request Syntax ................................................................................................................ 18
Response Syntax .............................................................................................................. 20
Errors .............................................................................................................................. 21
Examples ......................................................................................................................... 21
See Also .......................................................................................................................... 22
CreateKey ................................................................................................................................ 23
Request Syntax ................................................................................................................ 23
Response Syntax .............................................................................................................. 25
Errors .............................................................................................................................. 26
Examples ......................................................................................................................... 28
See Also .......................................................................................................................... 28
Decrypt ................................................................................................................................... 30
Request Syntax ................................................................................................................ 30
Response Syntax .............................................................................................................. 31
Errors .............................................................................................................................. 31
Examples ......................................................................................................................... 32
See Also .......................................................................................................................... 33

iii
DeleteAlias .............................................................................................................................. 34
Request Syntax ................................................................................................................ 34
Errors .............................................................................................................................. 34
Examples ......................................................................................................................... 35
See Also .......................................................................................................................... 35
DeleteCustomKeyStore .............................................................................................................. 37
Request Syntax ................................................................................................................ 37
Errors .............................................................................................................................. 38
See Also .......................................................................................................................... 38
DeleteImportedKeyMaterial ....................................................................................................... 40
Request Syntax ................................................................................................................ 40
Errors .............................................................................................................................. 41
Examples ......................................................................................................................... 41
See Also .......................................................................................................................... 42
DescribeCustomKeyStores .......................................................................................................... 43
Request Syntax ................................................................................................................ 43
Response Syntax .............................................................................................................. 44
Errors .............................................................................................................................. 45
See Also .......................................................................................................................... 45
DescribeKey ............................................................................................................................. 47
Request Syntax ................................................................................................................ 47
Response Syntax .............................................................................................................. 48
Errors .............................................................................................................................. 48
Examples ......................................................................................................................... 49
See Also .......................................................................................................................... 49
DisableKey ............................................................................................................................... 51
Request Syntax ................................................................................................................ 51
Errors .............................................................................................................................. 51
Examples ......................................................................................................................... 52
See Also .......................................................................................................................... 53
DisableKeyRotation ................................................................................................................... 54
Request Syntax ................................................................................................................ 54
Errors .............................................................................................................................. 54
Examples ......................................................................................................................... 55
See Also .......................................................................................................................... 56
DisconnectCustomKeyStore ........................................................................................................ 57
Request Syntax ................................................................................................................ 57
Errors .............................................................................................................................. 57
See Also .......................................................................................................................... 58
EnableKey ............................................................................................................................... 59
Request Syntax ................................................................................................................ 59

iv

Errors .............................................................................................................................. 59
Examples ......................................................................................................................... 60
See Also .......................................................................................................................... 61
EnableKeyRotation ................................................................................................................... 62
Request Syntax ................................................................................................................ 62
Errors .............................................................................................................................. 62
Examples ......................................................................................................................... 63
See Also .......................................................................................................................... 64
Encrypt ................................................................................................................................... 65
Request Syntax ................................................................................................................ 65
Response Syntax .............................................................................................................. 66
Errors .............................................................................................................................. 67
Examples ......................................................................................................................... 68
See Also .......................................................................................................................... 68
GenerateDataKey ...................................................................................................................... 70
Request Syntax ................................................................................................................ 70
Response Syntax .............................................................................................................. 72
Errors .............................................................................................................................. 73
Examples ......................................................................................................................... 73
See Also .......................................................................................................................... 74
GenerateDataKeyWithoutPlaintext .............................................................................................. 75
Request Syntax ................................................................................................................ 75
Response Syntax .............................................................................................................. 76
Errors .............................................................................................................................. 77
Examples ......................................................................................................................... 78
See Also .......................................................................................................................... 78
GenerateRandom ...................................................................................................................... 80
Request Syntax ................................................................................................................ 80
Response Syntax .............................................................................................................. 80
Errors .............................................................................................................................. 81
Examples ......................................................................................................................... 81
See Also .......................................................................................................................... 82
GetKeyPolicy ............................................................................................................................ 83
Request Syntax ................................................................................................................ 83
Response Syntax .............................................................................................................. 83
Errors .............................................................................................................................. 84
Examples ......................................................................................................................... 84
See Also .......................................................................................................................... 85
GetKeyRotationStatus ............................................................................................................... 86
Request Syntax ................................................................................................................ 86
Response Syntax .............................................................................................................. 86

v
Errors .............................................................................................................................. 87
Examples ......................................................................................................................... 88
See Also .......................................................................................................................... 88
GetParametersForImport ........................................................................................................... 89
Request Syntax ................................................................................................................ 89
Response Syntax .............................................................................................................. 90
Errors .............................................................................................................................. 91
Examples ......................................................................................................................... 91
See Also .......................................................................................................................... 93
ImportKeyMaterial .................................................................................................................... 94
Request Syntax ................................................................................................................ 94
Errors .............................................................................................................................. 96
Examples ......................................................................................................................... 97
See Also .......................................................................................................................... 98
ListAliases ................................................................................................................................ 99
Request Syntax ................................................................................................................ 99
Response Syntax ............................................................................................................ 100
Response Elements ......................................................................................................... 100
Errors ............................................................................................................................ 101
Examples ....................................................................................................................... 101
See Also ........................................................................................................................ 102
ListGrants .............................................................................................................................. 104
Request Syntax .............................................................................................................. 104
Request Parameters ........................................................................................................ 104
Response Syntax ............................................................................................................ 105
Errors ............................................................................................................................ 106
Examples ....................................................................................................................... 106
See Also ........................................................................................................................ 108
ListKeyPolicies ........................................................................................................................ 109
Request Syntax .............................................................................................................. 109
Response Syntax ............................................................................................................ 110
Errors ............................................................................................................................ 110
Examples ....................................................................................................................... 111
See Also ........................................................................................................................ 112
ListKeys ................................................................................................................................. 113
Request Syntax .............................................................................................................. 113
Response Syntax ............................................................................................................ 113
Errors ............................................................................................................................ 114
Examples ....................................................................................................................... 115
See Also ........................................................................................................................ 116
ListResourceTags .................................................................................................................... 117
Request Syntax .............................................................................................................. 117
Response Syntax ............................................................................................................ 118
Errors ............................................................................................................................ 119
Examples ....................................................................................................................... 119

vi
See Also ........................................................................................................................ 120

ListRetirableGrants .................................................................................................................. 121
Request Syntax .............................................................................................................. 121
Response Syntax ............................................................................................................ 122
Errors ............................................................................................................................ 123
Examples ....................................................................................................................... 123
See Also ........................................................................................................................ 124
PutKeyPolicy .......................................................................................................................... 125
Request Syntax .............................................................................................................. 125
Errors ............................................................................................................................ 126
Examples ....................................................................................................................... 127
See Also ........................................................................................................................ 129
ReEncrypt .............................................................................................................................. 130
Request Syntax .............................................................................................................. 130
Response Syntax ............................................................................................................ 131
Errors ............................................................................................................................ 132
Examples ....................................................................................................................... 133
See Also ........................................................................................................................ 134
RetireGrant ............................................................................................................................ 135
Request Syntax .............................................................................................................. 135
Errors ............................................................................................................................ 136
Examples ....................................................................................................................... 137
See Also ........................................................................................................................ 137
RevokeGrant .......................................................................................................................... 138
Request Syntax .............................................................................................................. 138
Errors ............................................................................................................................ 139
Examples ....................................................................................................................... 139
See Also ........................................................................................................................ 140
ScheduleKeyDeletion ............................................................................................................... 141
Request Syntax .............................................................................................................. 141
Response Syntax ............................................................................................................ 142
Errors ............................................................................................................................ 142
Examples ....................................................................................................................... 143
See Also ........................................................................................................................ 144
TagResource ........................................................................................................................... 145
Request Syntax .............................................................................................................. 145
Errors ............................................................................................................................ 146
Examples ....................................................................................................................... 146
See Also ........................................................................................................................ 147
UntagResource ....................................................................................................................... 148
Request Syntax .............................................................................................................. 148

vii
Errors ............................................................................................................................ 149

Examples ....................................................................................................................... 149
See Also ........................................................................................................................ 150
UpdateAlias ........................................................................................................................... 151
Request Syntax .............................................................................................................. 151
Errors ............................................................................................................................ 152
Examples ....................................................................................................................... 152
See Also ........................................................................................................................ 153
UpdateCustomKeyStore ........................................................................................................... 154
Request Syntax .............................................................................................................. 154
Errors ............................................................................................................................ 155
See Also ........................................................................................................................ 157
UpdateKeyDescription ............................................................................................................. 158
Request Syntax .............................................................................................................. 158
Errors ............................................................................................................................ 159
Examples ....................................................................................................................... 159
See Also ........................................................................................................................ 160
Data Types .................................................................................................................................... 161
AliasListEntry ......................................................................................................................... 162
Contents ........................................................................................................................ 162
See Also ........................................................................................................................ 162
CustomKeyStoresListEntry ....................................................................................................... 163
Contents ........................................................................................................................ 163
See Also ........................................................................................................................ 164
GrantConstraints .................................................................................................................... 165
Contents ........................................................................................................................ 165
See Also ........................................................................................................................ 165
GrantListEntry ........................................................................................................................ 167
Contents ........................................................................................................................ 167
See Also ........................................................................................................................ 168
KeyListEntry ........................................................................................................................... 169
Contents ........................................................................................................................ 169
See Also ........................................................................................................................ 169
KeyMetadata .......................................................................................................................... 170
Contents ........................................................................................................................ 170
See Also ........................................................................................................................ 172
Tag ....................................................................................................................................... 173
Contents ........................................................................................................................ 173
See Also ........................................................................................................................ 173
Common Parameters ...................................................................................................................... 174
Common Errors .............................................................................................................................. 176

viii
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 .
Note
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.
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 Diffie-Hellman (DHE) or
Elliptic Curve Ephemeral Diffie-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 find your log files,
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
for accessing 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.
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.

1
• Encrypt (p. 65)

• Decrypt (p. 30)
• GenerateDataKey (p. 70)
• GenerateDataKeyWithoutPlaintext (p. 75)
This document was last published on November 21, 2019.

2
Actions
The following actions are supported:
• CancelKeyDeletion (p. 5)
• ConnectCustomKeyStore (p. 8)
• CreateAlias (p. 11)
• CreateCustomKeyStore (p. 14)
• CreateGrant (p. 18)
• CreateKey (p. 23)
• Decrypt (p. 30)
• DeleteAlias (p. 34)
• DeleteCustomKeyStore (p. 37)
• DeleteImportedKeyMaterial (p. 40)
• DescribeCustomKeyStores (p. 43)
• DescribeKey (p. 47)
• DisableKey (p. 51)
• DisableKeyRotation (p. 54)
• DisconnectCustomKeyStore (p. 57)
• EnableKey (p. 59)
• EnableKeyRotation (p. 62)
• Encrypt (p. 65)
• GenerateRandom (p. 80)
• GetKeyPolicy (p. 83)
• GetKeyRotationStatus (p. 86)
• GetParametersForImport (p. 89)
• ImportKeyMaterial (p. 94)
• ListAliases (p. 99)
• ListGrants (p. 104)
• ListKeyPolicies (p. 109)
• ListKeys (p. 113)
• ListResourceTags (p. 117)
• ListRetirableGrants (p. 121)
• PutKeyPolicy (p. 125)
• ReEncrypt (p. 130)
• RetireGrant (p. 135)
• RevokeGrant (p. 138)
• ScheduleKeyDeletion (p. 141)
• TagResource (p. 145)
• UntagResource (p. 148)
• UpdateAlias (p. 151)
• UpdateCustomKeyStore (p. 154)

3
• UpdateKeyDescription (p. 158)

4
CancelKeyDeletion
CancelKeyDeletion
Cancels the deletion of a customer master key (CMK). When this operation is successful, the CMK is set to
the Disabled state. To enable a CMK, use EnableKey (p. 59). You cannot perform this operation on a
CMK in a different AWS account.
For more information about scheduling and canceling deletion of a CMK, see Deleting Customer Master
Keys in the AWS Key Management Service Developer Guide.
The result of this operation varies with the key state of the CMK. For details, see How Key State Affects
Use of a Customer Master Key in the AWS Key Management Service Developer Guide.
Request Syntax
{
"KeyId": "string"
}
Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 174).
The request accepts the following data in JSON format.

Note
In the following list, the required parameters are described first.
KeyId (p. 5)
The unique identifier for the customer master key (CMK) for which to cancel deletion.
Specify the key ID or the Amazon Resource Name (ARN) of the CMK.
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 CMK, use ListKeys (p. 113) or DescribeKey (p. 47).
Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Required: Yes
Response Syntax
{
"KeyId": "string"
}

5
Response Elements
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 unique identifier of the master key for which deletion is canceled.
Type: String
Errors
For information about the errors that are common to all actions, see Common Errors (p. 176).
DependencyTimeoutException
The system timed out while trying to fulfill the request. The request can be retried.
HTTP Status Code: 500

InvalidArnException
The request was rejected because a specified ARN, or an ARN in a key policy, is not valid.

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

KMSInvalidStateException
The request was rejected because the state of the specified resource is not valid for this request.
For more information about how key state affects the use of a CMK, see How Key State Affects Use
of a Customer Master Key in the AWS Key Management Service Developer Guide.

NotFoundException
The request was rejected because the specified entity or resource could not be found.
Examples
Example Request
The following example is formatted for legibility.
POST / HTTP/1.1
Host: kms.us-east-2.amazonaws.com

6
See Also
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
HTTP/1.1 200 OK
Server: Server
Date: Tue, 25 Oct 2016 18:27:01 GMT
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"}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:
• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

7
ConnectCustomKeyStore
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 customer master keys (CMKs) in the key
store or use the CMKs 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.
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. 43) operation.
During the connection process, AWS KMS finds 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 crypto user (CU), and rotates its password.
The ConnectCustomKeyStore operation might fail for various reasons. To find the reason, use the
DescribeCustomKeyStores (p. 43) operation and see the ConnectionErrorCode in the response. For
help interpreting the ConnectionErrorCode, see CustomKeyStoresListEntry (p. 163).
To fix the failure, use the DisconnectCustomKeyStore (p. 57) operation to disconnect the custom key
store, correct the error, use the UpdateCustomKeyStore (p. 154) 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.
Request Syntax
{
"CustomKeyStoreId": "string"
}
Request Parameters

Note
CustomKeyStoreId (p. 8)
Enter the key store ID of the custom key store that you want to connect. To find the ID of a custom
key store, use the DescribeCustomKeyStores (p. 43) operation.
Type: String

8
Response Elements
Required: Yes
Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.
Errors
CloudHsmClusterInvalidConfigurationException
The request was rejected because the associated AWS CloudHSM cluster did not meet the
configuration requirements for a custom key store.
• The cluster must be configured with private subnets in at least two different 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 traffic 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. 14), UpdateCustomKeyStore (p. 154), and

CreateKey (p. 23) operations, the AWS CloudHSM cluster must have at least two active HSMs,
each in a different 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
Configure 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.

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. 43) operation.
This exception is thrown under the following conditions:

• You requested the CreateKey (p. 23) or GenerateRandom (p. 80) 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. 154) or DeleteCustomKeyStore (p. 37)
operation on a custom key store that is not disconnected. This operation is valid only when the
custom key store ConnectionState is DISCONNECTED.

9
See Also
• 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 find a custom key store with the specified key
store name or ID.

See Also

• AWS SDK for C++
• AWS SDK for Go

10
CreateAlias
CreateAlias
Creates a display name for a customer managed customer master key (CMK). You can use an alias to
identify a CMK in selected operations, such as Encrypt (p. 65) and GenerateDataKey (p. 70).
Each CMK can have multiple aliases, but each alias points to only one CMK. The alias name must be
unique in the AWS account and region. To simplify code that runs in multiple regions, use the same alias
name, but point it to a different CMK in each region.
Because an alias is not a property of a CMK, you can delete and change the aliases of a CMK without
affecting the CMK. Also, aliases do not appear in the response from the DescribeKey (p. 47) operation.
To get the aliases of all CMKs, use the ListAliases (p. 99) operation.
The alias name must begin with alias/ followed by a name, such as alias/ExampleAlias. It can
contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name
cannot begin with alias/aws/. The alias/aws/ prefix is reserved for AWS managed CMKs.
The alias and the CMK it is mapped to must be in the same AWS account and the same region. You
cannot perform this operation on an alias in a different AWS account.
To map an existing alias to a different CMK, call UpdateAlias (p. 151).
Request Syntax
{
"AliasName": "string",
"TargetKeyId": "string"
}
Request Parameters

Note
AliasName (p. 11)
Specifies the alias name. This value must begin with alias/ followed by a name, such as alias/
ExampleAlias. The alias name cannot begin with alias/aws/. The alias/aws/ prefix is reserved
for AWS managed CMKs.
Type: String
Pattern: ^[a-zA-Z0-9:/_-]+$
Required: Yes
TargetKeyId (p. 11)
Identifies the CMK to which the alias refers.

11
Response Elements
For example:
Type: String
Required: Yes
Response Elements
Errors
AlreadyExistsException
The request was rejected because it attempted to create a resource that already exists.


InvalidAliasNameException
The request was rejected because the specified alias name is not valid.



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

12
Examples
NotFoundException
Examples
Example Request
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"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 17 May 2016 20:42:25 GMT
Content-Length: 0
x-amzn-RequestId: dcb07ca7-1c6f-11e6-8540-77c363708b91
See Also

• AWS SDK for C++
• AWS SDK for Go

13
CreateCustomKeyStore
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 fulfills 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.
Request Syntax
{
"CloudHsmClusterId": "string",
"CustomKeyStoreName": "string",
"KeyStorePassword": "string",
"TrustAnchorCertificate": "string"
}
Request Parameters

Note
CloudHsmClusterId (p. 14)
Identifies 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 find the cluster ID, use
the DescribeClusters operation.
Type: String
Required: Yes
CustomKeyStoreName (p. 14)
Specifies a friendly name for the custom key store. The name must be unique in your AWS account.
Type: String

14
Response Syntax
Required: Yes
KeyStorePassword (p. 14)
Enter the password of the kmsuser crypto user (CU) account in the specified AWS CloudHSM
cluster. AWS KMS logs into the cluster as this user to manage key material on your behalf.
This parameter tells AWS KMS the kmsuser account password; it does not change the password in
the AWS CloudHSM cluster.
Type: String
Length Constraints: Minimum length of 1.
Required: Yes
TrustAnchorCertificate (p. 14)
Enter the content of the trust anchor certificate for the cluster. This is the content of the
customerCA.crt file that you created when you initialized the cluster.
Type: String
Required: Yes
Response Syntax
{
}
Response Elements
A unique identifier for the new custom key store.
Type: String
Errors
CloudHsmClusterInUseException
The request was rejected because the specified 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 different AWS CloudHSM cluster.

15
Errors
Clusters that share a backup history have the same cluster certificate. To view the cluster certificate
of a cluster, use the DescribeClusters operation.

the Region.
For the CreateCustomKeyStore (p. 14), UpdateCustomKeyStore (p. 154), and

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


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 specified 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.

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 certificate and save it in the
customerCA.crt file.

16
See Also

See Also

• AWS SDK for C++
• AWS SDK for Go

17
CreateGrant
CreateGrant
Adds a grant to a customer master key (CMK). The grant allows the grantee principal to use the CMK
when the conditions specified in the grant are met. When setting permissions, grants are an alternative
to key policies.
To create a grant that allows a cryptographic operation only when the encryption context in the
operation request matches or includes a specified encryption context, use the Constraints parameter.
For details, see GrantConstraints (p. 165).
To perform this operation on a CMK in a different AWS account, specify the key ARN in the value of the
KeyId parameter. For more information about grants, see Grants in the AWS Key Management Service
Developer Guide .
Request Syntax
{
"Constraints": {
"EncryptionContextEquals": {
"string" : "string"
},
"EncryptionContextSubset": {
"string" : "string"
}
},
"GranteePrincipal": "string",
"GrantTokens": [ "string" ],
"KeyId": "string",
"Name": "string",
"Operations": [ "string" ],
"RetiringPrincipal": "string"
}
Request Parameters

Note
GranteePrincipal (p. 18)
The principal that is given permission to perform the operations that the grant permits.
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

18
Request Parameters
Pattern: ^[\w+=,.@:/-]+$
Required: Yes
KeyId (p. 18)
The unique identifier for the customer master key (CMK) that the grant applies to.
Specify the key ID or the Amazon Resource Name (ARN) of the CMK. To specify a CMK in a different
AWS account, you must use the key ARN.
For example:
Type: String
Required: Yes
Operations (p. 18)
A list of operations that the grant permits.
Type: Array of strings
Valid Values: Decrypt | Encrypt | GenerateDataKey |

GenerateDataKeyWithoutPlaintext | ReEncryptFrom | ReEncryptTo | CreateGrant
| RetireGrant | DescribeKey
Required: Yes
Constraints (p. 18)
Allows a cryptographic operation only when the encryption context matches or includes the
encryption context specified in this structure. For more information about encryption context, see
Encryption Context in the AWS Key Management Service Developer Guide .
Type: GrantConstraints (p. 165) object
Required: No
GrantTokens (p. 18)
A list of grant tokens.
For more information, see Grant Tokens in the AWS Key Management Service Developer Guide.
Array Members: Minimum number of 0 items. Maximum number of 10 items.
Required: No
Name (p. 18)
A friendly name for identifying the grant. Use this value to prevent the unintended creation of
duplicate grants when retrying this request.

19
Response Syntax
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 obtained in this way can be used interchangeably.
Type: String
Required: No
RetiringPrincipal (p. 18)
The principal that is given permission to retire the grant by using RetireGrant (p. 135) operation.
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.
Type: String
Pattern: ^[\w+=,.@:/-]+$
Required: No
Response Syntax
{
"GrantId": "string",
"GrantToken": "string"
}
Response Elements
GrantId (p. 20)
The unique identifier for the grant.
You can use the GrantId in a subsequent RetireGrant (p. 135) or RevokeGrant (p. 138) operation.
Type: String

GrantToken (p. 20)
The grant token.

20
Errors
Type: String
Errors

DisabledException
The request was rejected because the specified CMK is not enabled.

InvalidArnException

InvalidGrantTokenException
The request was rejected because the specified grant token is not valid.




NotFoundException
Examples
The following examples are formatted for legibility.

21
See Also
Example Request
POST / HTTP/1.1
Content-Length: 176
X-Amz-Target: TrentService.CreateGrant
X-Amz-Date: 20161031T202851Z
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
HTTP/1.1 200 OK
Server: Server
Date: Mon, 31 Oct 2016 20:28:51 GMT
Content-Length: 585
x-amzn-RequestId: a2d8d452-9fa8-11e6-b30c-dbb8ea4d97c5
{
"GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60",
"GrantToken":
"AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNGY3NiKIAgEBAgB4P
ZJP7m6f1g8GzV47HX5phdtONAP7K_HQIflcgpkoCqd_fUnE114mSmiagWkbQ5sqAVV3ov-
VeqgrvMe5ZFEWLMSluvBAqdjHEdMIkHMlhlj4ENZbzBfo9Wxk8b8SnwP4kc4gGivedzFXo-
dwN8fxjjq_ZZ9JFOj2ijIbj5FyogDCN0drOfi8RORSEuCEmPvjFRMFAwcmwFkN2NPp89amA"
}
See Also

• AWS SDK for C++
• AWS SDK for Go

22
CreateKey
CreateKey
Creates a customer managed customer master key (CMK) in your AWS account.
You can use a CMK to encrypt small amounts of data (up to 4096 bytes) directly. But CMKs are more
commonly used to encrypt the data keys that are used to encrypt data.
To create a CMK for imported key material, use the Origin parameter with a value of EXTERNAL.
To create a CMK 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 different
Availability Zones in the AWS Region.
You cannot use this operation to create a CMK in a different AWS account.
Request Syntax
{
"BypassPolicyLockoutSafetyCheck": boolean,
"CustomKeyStoreId": "string",
"Description": "string",
"KeyUsage": "string",
"Origin": "string",
"Policy": "string",
"Tags": [
{
"TagKey": "string",
"TagValue": "string"
}
]
}
Request Parameters

Note
BypassPolicyLockoutSafetyCheck (p. 23)
A flag to indicate whether to bypass the key policy lockout safety check.
Important
Setting this value to true increases the risk that the CMK 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. 125) request on
the CMK.
The default value is false.

23
Request Parameters
Type: Boolean
Required: No
Creates the CMK in the specified custom key store and the key material in its associated AWS
CloudHSM cluster. To create a CMK 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 different Availability Zone in the
Region.
To find the ID of a custom key store, use the DescribeCustomKeyStores (p. 43) operation.
The response includes the custom key store ID and the ID of the AWS CloudHSM cluster.
convenience and extensive integration of AWS KMS with the isolation and control of a single-tenant
key store.
Type: String
Required: No
Description (p. 23)
A description of the CMK.
Enter a description that explains the type of data you plan to protect or the application you plan to
use with the CMK. The Default master key that protects my ... when no other key is defined description
format is reserved for AWS managed CMKs.
You can add a description now or update it at any time unless its key state is PendingDeletion.
To add, change, or delete the description of an existing customer managed CMK, use the
UpdateKeyDescription (p. 158) operation.
Type: String
Required: No
KeyUsage (p. 23)
The cryptographic operations for which you can use the CMK. The only valid value is
ENCRYPT_DECRYPT, which means you can use the CMK to encrypt and decrypt data.
Type: String
Valid Values: ENCRYPT_DECRYPT
Required: No
Origin (p. 23)
The source of the key material for the CMK. You cannot change the origin after you create the CMK.
The default is AWS_KMS, which means AWS KMS creates the key material in its own key store.
When the parameter value is EXTERNAL, AWS KMS creates a CMK without key material so
that you can import key material from your existing key management infrastructure. For more
information about importing key material into AWS KMS, see Importing Key Material in the AWS Key
Management Service Developer Guide.

24
Response Syntax
When the parameter value is AWS_CLOUDHSM, AWS KMS creates the CMK in an AWS KMS custom key
store and creates its key material in the associated AWS CloudHSM cluster. You must also use the
CustomKeyStoreId parameter to identify the custom key store.
Type: String
Valid Values: AWS_KMS | EXTERNAL | AWS_CLOUDHSM
Required: No
Policy (p. 23)
The key policy to attach to the CMK.
If you provide a key policy, it must meet the following criteria:

• If you don't set BypassPolicyLockoutSafetyCheck to true, the key policy must allow the
principal that is making the CreateKey request to make a subsequent PutKeyPolicy (p. 125)
request on the CMK. This reduces the risk that the CMK becomes unmanageable. For more
information, refer to the scenario in the Default Key Policy section of the AWS Key Management
Service Developer Guide .
• Each statement in the key policy must contain one or more principals. The principals in the key
policy must exist and be visible to AWS KMS. When you create a new AWS principal (for example,
an IAM user or role), you might need to enforce a delay before including the new principal in a
key policy because the new principal might not be immediately visible to AWS KMS. For more
information, see Changes that I make are not always immediately visible in the AWS Identity and
Access Management User Guide.
If you do not provide a key policy, AWS KMS attaches a default key policy to the CMK. For more
information, see Default Key Policy in the AWS Key Management Service Developer Guide.
The key policy size limit is 32 kilobytes (32768 bytes).
Type: String
Pattern: [\u0009\u000A\u000D\u0020-\u00FF]+
Required: No
Tags (p. 23)
One or more tags. Each tag consists of a tag key and a tag value. Tag keys and tag values are both
required, but tag values can be empty (null) strings.
Use this parameter to tag the CMK when it is created. Alternately, you can omit this parameter and
instead tag the CMK after it is created using TagResource (p. 145).
Type: Array of Tag (p. 173) objects
Required: No
Response Syntax
{
"KeyMetadata": {
"Arn": "string",
"AWSAccountId": "string",

25
Response Elements
"CreationDate": number,
"DeletionDate": number,
"Enabled": boolean,
"ExpirationModel": "string",
"KeyId": "string",
"KeyManager": "string",
"KeyState": "string",
"Origin": "string",
"ValidTo": number
}
}
Response Elements
KeyMetadata (p. 25)
Metadata associated with the CMK.
Type: KeyMetadata (p. 170) object
Errors
the Region.
For the CreateCustomKeyStore (p. 14), UpdateCustomKeyStore (p. 154), and CreateKey (p. 23)
operations, the AWS CloudHSM cluster must have at least two active HSMs, each in a different
Availability Zone. For the ConnectCustomKeyStore (p. 8) operation, the AWS CloudHSM must
contain at least one active HSM.

26
Errors


store name or ID.


InvalidArnException



MalformedPolicyDocumentException
The request was rejected because the specified policy is not syntactically or semantically correct.

TagException
The request was rejected because one or more tags are not valid.

UnsupportedOperationException
The request was rejected because a specified parameter is not supported or a specified resource is
not valid for this operation.

27
Examples
Examples
Example Request
POST / HTTP/1.1
Signature=8fb59aa17854a97df47aae69f560b66178ed0b5e1ebe334be516c4f3f59acedc
X-Amz-Target: TrentService.CreateKey
X-Amz-Date: 20170705T210455Z
Content-Length: 62
{
"Tags": [{
"TagValue": "ExampleUser",
"TagKey": "CreatedBy"
}]
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 05 Jul 2017 21:04:55 GMT
Content-Length: 335
x-amzn-RequestId: 98b2de61-61c5-11e7-bd87-9fc4a74e147b
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1.499288695918E9,
"Description": "",
"Enabled": true,
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS"
}
}
See Also


28
See Also
• AWS SDK for C++

• AWS SDK for Go

29
Decrypt
Decrypt
Decrypts ciphertext. Ciphertext is plaintext that has been previously encrypted by using any of the
following operations:

• Encrypt (p. 65)
Whenever possible, use key policies to give users permission to call the Decrypt operation on the CMK,
instead of IAM policies. Otherwise, you might create an IAM user policy that gives the user Decrypt
permission on all CMKs. This user could decrypt ciphertext that was encrypted by CMKs in other accounts
if the key policy for the cross-account CMK permits it. If you must use an IAM policy for Decrypt
permissions, limit the user to particular CMKs or particular trusted accounts.
Request Syntax
{
"CiphertextBlob": blob,
"EncryptionContext": {
"string" : "string"
},
"GrantTokens": [ "string" ]
}
Request Parameters

Note
CiphertextBlob (p. 30)
Ciphertext to be decrypted. The blob includes metadata.
Type: Base64-encoded binary data object
Required: Yes
EncryptionContext (p. 30)
The encryption context. If this was specified in the Encrypt (p. 65) function, it must be specified
here or the decryption operation will fail. For more information, see Encryption Context.
Type: String to string map
Required: No

30
Response Syntax
GrantTokens (p. 30)
Required: No
Response Syntax
{
"KeyId": "string",
"Plaintext": blob
}
Response Elements
KeyId (p. 31)
ARN of the key used to perform the decryption. This value is returned if no errors are encountered
during the operation.
Type: String

Plaintext (p. 31)
Decrypted plaintext data. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.
Otherwise, it is not encoded.
Errors

DisabledException

31
Examples

InvalidCiphertextException
The request was rejected because the specified ciphertext, or additional authenticated data
incorporated into the ciphertext, such as the encryption context, is corrupted, missing, or otherwise
invalid.


KeyUnavailableException
The request was rejected because the specified CMK was not available. The request can be retried.



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 293
X-Amz-Target: TrentService.Decrypt
X-Amz-Date: 20160517T204035Z
Signature=545b0c3bfd9223b8ef7e6293ef3ccac37a83d415ee3112d2e5c70727d2a49c46
{"CiphertextBlob": "CiDPoCH188S65r5Cy7pAhIFJMXDlU7mewhSlYUpuQIVBrhKmAQEBAgB4z6Ah9fPEuua
+Qsu6QISBSTFw5VO5nsIUpWFKbkCFQa4AAAB9MHsGCSqGSIb3DQEHBqBuMGwCAQAwZwYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBA
ZjYCARCAOt8la8qXLO5wB3JH2NlwWWzWRU2RKqpO9A/0psE5UWwkK6CnwoeC3Zj9Q0A66apZkbRglFfY1lTY+Tc="}

32
See Also
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 17 May 2016 20:40:40 GMT
Content-Length: 146
x-amzn-RequestId: 9e02f41f-1c6f-11e6-af63-ab8791945da7
{
"KeyId": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Plaintext": "VGhpcyBpcyBEYXkgMSBmb3IgdGhlIEludGVybmV0Cg=="
}
See Also

• AWS SDK for C++
• AWS SDK for Go

33
DeleteAlias
DeleteAlias
Deletes the specified alias. You cannot perform this operation on an alias in a different AWS account.
Because an alias is not a property of a CMK, you can delete and change the aliases of a CMK without
affecting the CMK. Also, aliases do not appear in the response from the DescribeKey (p. 47) operation.
To get the aliases of all CMKs, use the ListAliases (p. 99) operation.
Each CMK can have multiple aliases. To change the alias of a CMK, use DeleteAlias (p. 34) to delete the
current alias and CreateAlias (p. 11) to create a new alias. To associate an existing alias with a different
customer master key (CMK), call UpdateAlias (p. 151).
Request Syntax
{
"AliasName": "string"
}
Request Parameters

Note
AliasName (p. 34)
The alias to be deleted. The alias name must begin with alias/ followed by the alias name, such as
alias/ExampleAlias.
Type: String
Required: Yes
Response Elements
Errors

34
Examples


NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 34
X-Amz-Target: TrentService.DeleteAlias
X-Amz-Date: 20161104T183415Z
Signature=a57d9c76f60733ea93fe92ac4fa90ca82058a72913e4b8e52c262ffc96704d53
{"AliasName": "alias/ExampleAlias"}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Fri, 04 Nov 2016 18:34:15 GMT
Content-Length: 0
x-amzn-RequestId: 4a2313ae-a2bd-11e6-aea3-9bf897a0ae69
See Also

• AWS SDK for C++

35
See Also
• AWS SDK for Go


36
DeleteCustomKeyStore
DeleteCustomKeyStore
Deletes a custom key store. This operation does not delete the AWS CloudHSM cluster that is associated
with the custom key store, or affect any users or keys in the cluster.
The custom key store that you delete cannot contain any AWS KMS customer master keys (CMKs).
Before deleting the key store, verify that you will never need to use any of the CMKs in the key store
for any cryptographic operations. Then, use ScheduleKeyDeletion (p. 141) to delete the AWS KMS
customer master keys (CMKs) from the key store. When the scheduled waiting period expires, the
ScheduleKeyDeletion operation deletes the CMKs. Then it makes a best effort to delete the key
material from the associated cluster. However, you might need to manually delete the orphaned key
material from the cluster and its backups.
After all CMKs are deleted from AWS KMS, use DisconnectCustomKeyStore (p. 57) to disconnect the
key store from AWS KMS. Then, you can delete the custom key store.
Instead of deleting the custom key store, consider using DisconnectCustomKeyStore (p. 57) to
disconnect it from AWS KMS. While the key store is disconnected, you cannot create or use the CMKs in
the key store. But, you do not need to delete CMKs and you can reconnect a disconnected custom key
store at any time.
If the operation succeeds, it returns a JSON object with no properties.
store.
Request Syntax
{
}
Request Parameters

Note
Enter the ID of the custom key store you want to delete. To find the ID of a custom key store, use the
DescribeCustomKeyStores (p. 43) operation.
Type: String
Required: Yes
Response Elements

37
Errors
Errors
CustomKeyStoreHasCMKsException
The request was rejected because the custom key store contains AWS KMS customer
master keys (CMKs). After verifying that you do not need to use the CMKs, use the
ScheduleKeyDeletion (p. 141) operation to delete the CMKs. After they are deleted, you can delete
the custom key store.



store name or ID.

See Also

• AWS SDK for C++
• AWS SDK for Go

38
See Also

39
DeleteImportedKeyMaterial
DeleteImportedKeyMaterial
Deletes key material that you previously imported. This operation makes the specified customer master
key (CMK) unusable. For more information about importing key material into AWS KMS, see Importing
Key Material in the AWS Key Management Service Developer Guide. You cannot perform this operation on
a CMK in a different AWS account.
When the specified CMK is in the PendingDeletion state, this operation does not change the CMK's
state. Otherwise, it changes the CMK's state to PendingImport.
After you delete key material, you can use ImportKeyMaterial (p. 94) to reimport the same key
material into the CMK.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 40)
Identifies the CMK from which you are deleting imported key material. The Origin of the CMK must
be EXTERNAL.
For example:
Type: String
Required: Yes
Response Elements

40
Errors
Errors

InvalidArnException



NotFoundException

Examples
Example Request
POST / HTTP/1.1
Content-Length: 48
X-Amz-Target: TrentService.DeleteImportedKeyMaterial
X-Amz-Date: 20161107T213532Z
Signature=2cea34fe55d5858295a377448a1e053d0edd45ce571da7cf69b202905759f272
{"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"}

41
See Also
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 07 Nov 2016 21:35:35 GMT
Content-Length: 0
x-amzn-RequestId: 1e76aa81-a532-11e6-a265-d3aef78e1a90
See Also

• AWS SDK for C++
• AWS SDK for Go

42
DescribeCustomKeyStores
DescribeCustomKeyStores
Gets information about custom key stores in the account and region.
store.
By default, this operation returns information about all custom key stores in the account and region.
To get only information about a particular custom key store, use either the CustomKeyStoreName or
CustomKeyStoreId parameter (but not both).
To determine whether the custom key store is connected to its AWS CloudHSM cluster, use the
ConnectionState element in the response. If an attempt to connect the custom key store
failed, the ConnectionState value is FAILED and the ConnectionErrorCode element in the
response indicates the cause of the failure. For help interpreting the ConnectionErrorCode, see
CustomKeyStoresListEntry (p. 163).
Custom key stores have a DISCONNECTED connection state if the key store has never been connected or
you use the DisconnectCustomKeyStore (p. 57) operation to disconnect it. If your custom key store
state is CONNECTED but you are having trouble using it, make sure that its associated AWS CloudHSM
cluster is active and contains the minimum number of HSMs required for the operation, if any.
For help repairing your custom key store, see the Troubleshooting Custom Key Stores topic in the AWS
Request Syntax
{
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
Gets only information about the specified custom key store. Enter the key store ID.
By default, this operation gets information about all custom key stores in the account and region.
To limit the output to a particular custom key store, you can use either the CustomKeyStoreId or
CustomKeyStoreName parameter, but not both.
Type: String
Required: No

43
Response Syntax
CustomKeyStoreName (p. 43)
Gets only information about the specified custom key store. Enter the friendly name of the custom
key store.
By default, this operation gets information about all custom key stores in the account and region.
To limit the output to a particular custom key store, you can use either the CustomKeyStoreId or
CustomKeyStoreName parameter, but not both.
Type: String
Required: No
Limit (p. 43)
Use this parameter to specify the maximum number of items to return. When this value is present,
AWS KMS does not return more than the specified number of items, but it might return fewer.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 1000.
Required: No
Marker (p. 43)
Use this parameter in a subsequent request after you receive a response with truncated results. Set it
to the value of NextMarker from the truncated response you just received.
Type: String
Pattern: [\u0020-\u00FF]*
Required: No
Response Syntax
{
"CustomKeyStores": [
{
"ConnectionErrorCode": "string",
"ConnectionState": "string",
"TrustAnchorCertificate": "string"
}
],
"NextMarker": "string",
"Truncated": boolean
}
Response Elements

44
Errors
CustomKeyStores (p. 44)
Contains metadata about each custom key store.
Type: Array of CustomKeyStoresListEntry (p. 163) objects

NextMarker (p. 44)
When Truncated is true, this element is present and contains the value to use for the Marker
parameter in a subsequent request.
Type: String
Truncated (p. 44)
A flag that indicates whether there are more items in the list. When this value is true, the list in this
response is truncated. To get more items, pass the value of the NextMarker element in thisresponse
to the Marker parameter in a subsequent request.
Type: Boolean
Errors
store name or ID.

See Also

• AWS SDK for C++
• AWS SDK for Go

45
See Also

46
DescribeKey
DescribeKey
Provides detailed information about the specified customer master key (CMK).
You can use DescribeKey on a predefined AWS alias, that is, an AWS alias with no key ID. When you do,
AWS KMS associates the alias with an AWS managed CMK and returns its KeyId and Arn in the response.
To perform this operation on a CMK in a different AWS account, specify the key ARN or alias ARN in the
value of the KeyId parameter.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 47)
Describes the specified customer master key (CMK).
If you specify a predefined AWS alias (an AWS alias with no key ID), KMS associates the alias with an
AWS managed CMK and returns its KeyId and Arn in the response.
To specify a CMK, use its key ID, Amazon Resource Name (ARN), alias name, or alias ARN. When using
an alias name, prefix it with "alias/". To specify a CMK in a different AWS account, you must use
the key ARN or alias ARN.
For example:
• Alias name: alias/ExampleAlias
• Alias ARN: arn:aws:kms:us-east-2:111122223333:alias/ExampleAlias
To get the key ID and key ARN for a CMK, use ListKeys (p. 113) or DescribeKey (p. 47). To get the
alias name and alias ARN, use ListAliases (p. 99).
Type: String
Required: Yes
GrantTokens (p. 47)

47
Response Syntax
Required: No
Response Syntax
{
"KeyMetadata": {
"Arn": "string",
"AWSAccountId": "string",
"Enabled": boolean,
"KeyId": "string",
"KeyManager": "string",
"KeyState": "string",
"Origin": "string",
"ValidTo": number
}
}
Response Elements
KeyMetadata (p. 48)
Metadata associated with the key.
Type: KeyMetadata (p. 170) object
Errors

InvalidArnException

48
Examples

NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 49
X-Amz-Target: TrentService.DescribeKey
X-Amz-Date: 20170705T211529Z
Signature=6bcb6a5ef9ee7585d83955e8a5c3f6d47cf581596208fc0e436fa1de26ef3f6a
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 05 Jul 2017 21:15:30 GMT
Content-Length: 335
x-amzn-RequestId: 13230ddb-61c7-11e7-af6f-c5b105d7a982
{
"KeyMetadata": {
"AWSAccountId": "111122223333",
"Arn": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"CreationDate": 1.499288695918E9,
"Description": "",
"Enabled": true,
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "AWS_KMS"
}
}
See Also

49
See Also

• AWS SDK for C++
• AWS SDK for Go

50
DisableKey
DisableKey
Sets the state of a customer master key (CMK) to disabled, thereby preventing its use for cryptographic
operations. You cannot perform this operation on a CMK in a different AWS account.
For more information about how key state affects the use of a CMK, see How Key State Affects the Use of
a Customer Master Key in the AWS Key Management Service Developer Guide .
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 51)
A unique identifier for the customer master key (CMK).
For example:
Type: String
Required: Yes
Response Elements
Errors

51
Examples

InvalidArnException



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 48
X-Amz-Target: TrentService.DisableKey
X-Amz-Date: 20161107T221459Z
Signature=de4ddbea732953d60c07d835a5dde9037c484ee3bec9313cbecd1d9420b41a7a
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 07 Nov 2016 22:14:59 GMT
Content-Length: 0
x-amzn-RequestId: 9f5f3560-a537-11e6-8185-8df6f2682323

52
See Also
See Also

• AWS SDK for C++
• AWS SDK for Go

53
DisableKeyRotation
DisableKeyRotation
Disables automatic rotation of the key material for the specified customer master key (CMK). You cannot
perform this operation on a CMK in a different AWS account.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 54)
For example:
Type: String
Required: Yes
Response Elements
Errors

54
Examples

DisabledException

InvalidArnException



NotFoundException

Examples
Example Request
POST / HTTP/1.1
Content-Length: 48
X-Amz-Target: TrentService.DisableKeyRotation
X-Amz-Date: 20161107T222236Z
Signature=2304622be05af2afa8c75bf784fb87b280c194746418b05d7af947c8c2bd8f04
Example Response
55
See Also
HTTP/1.1 200 OK
Server: Server
Date: Mon, 07 Nov 2016 22:22:36 GMT
Content-Length: 0
x-amzn-RequestId: afd1c328-a538-11e6-861b-ad130425efbf
See Also

• AWS SDK for C++
• AWS SDK for Go

56
DisconnectCustomKeyStore
DisconnectCustomKeyStore
Disconnects the custom key store from its associated AWS CloudHSM cluster. While a custom key store
is disconnected, you can manage the custom key store and its customer master keys (CMKs), but you
cannot create or use CMKs in the custom key store. You can reconnect the custom key store at any time.
Note
While a custom key store is disconnected, all attempts to create customer master keys (CMKs)
in the custom key store or to use existing CMKs in cryptographic operations will fail. This action
can prevent users from storing and accessing sensitive data.
To find the connection state of a custom key store, use the DescribeCustomKeyStores (p. 43) operation.
To reconnect a custom key store, use the ConnectCustomKeyStore (p. 8) operation.
store.
Request Syntax
{
}
Request Parameters

Note
Enter the ID of the custom key store you want to disconnect. To find the ID of a custom key store,
use the DescribeCustomKeyStores (p. 43) operation.
Type: String
Required: Yes
Response Elements
Errors

57
See Also

• You requested the UpdateCustomKeyStore (p. 154) or DeleteCustomKeyStore (p. 37) operation
on a custom key store that is not disconnected. This operation is valid only when the custom key
store ConnectionState is DISCONNECTED.

store name or ID.

See Also

• AWS SDK for C++
• AWS SDK for Go

58
EnableKey
EnableKey
Sets the key state of a customer master key (CMK) to enabled. This allows you to use the CMK for
cryptographic operations. You cannot perform this operation on a CMK in a different AWS account.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 59)
For example:
Type: String
Required: Yes
Response Elements
Errors

59
Examples

InvalidArnException




NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 48
X-Amz-Target: TrentService.EnableKey
X-Amz-Date: 20161107T221800Z
Signature=74d02e36580c1759255dfef66f1e51f3542e469de8c7c8fa5fb21c042e518295
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 07 Nov 2016 22:18:00 GMT

60
See Also
Content-Length: 0
x-amzn-RequestId: 0b588162-a538-11e6-b4ed-059c103e7a90
See Also

• AWS SDK for C++
• AWS SDK for Go

61
EnableKeyRotation
EnableKeyRotation
Enables automatic rotation of the key material for the specified customer master key (CMK). You cannot
perform this operation on a CMK in a different AWS account.
You cannot enable automatic rotation of CMKs with imported key material or CMKs in a custom key
store.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 62)
For example:
Type: String
Required: Yes
Response Elements
Errors

62
Examples

DisabledException

InvalidArnException



NotFoundException

Examples
Example Request
POST / HTTP/1.1
Content-Length: 48
X-Amz-Target: TrentService.EnableKeyRotation
X-Amz-Date: 20161107T221835Z
Signature=4783e177036ca78627fe0cda9dcfdaf4ad7c8312d0e7c3d71d814b0c4cff1c0b

63
See Also
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 07 Nov 2016 22:18:36 GMT
Content-Length: 0
x-amzn-RequestId: 2077c3bf-a538-11e6-b6fb-794e83344f84
See Also

• AWS SDK for C++
• AWS SDK for Go

64
Encrypt
Encrypt
Encrypts plaintext into ciphertext by using a customer master key (CMK). The Encrypt operation has
two primary use cases:
• You can encrypt up to 4 kilobytes (4096 bytes) of arbitrary data such as an RSA key, a database
password, or other sensitive information.
• You can use the Encrypt operation to move encrypted data from one AWS region to another. In the
first region, generate a data key and use the plaintext key to encrypt the data. Then, in the new region,
call the Encrypt method on same plaintext data key. Now, you can safely move the encrypted data
and encrypted data key to the new region, and decrypt in the new region when necessary.
You don't need use this operation to encrypt a data key within a region. The GenerateDataKey (p. 70)
and GenerateDataKeyWithoutPlaintext (p. 75) operations return an encrypted data key.
Also, you don't need to use this operation to encrypt data in your application. You can use the plaintext
and encrypted data keys that the GenerateDataKey operation returns.
To perform this operation on a CMK in a different AWS account, specify the key ARN or alias ARN in the
value of the KeyId parameter.
Request Syntax
{
"string" : "string"
},
"KeyId": "string",
"Plaintext": blob
}
Request Parameters

Note
KeyId (p. 65)
For example:

65
Response Syntax

Type: String
Required: Yes
Plaintext (p. 65)
Data to be encrypted.
Required: Yes
Name-value pair that specifies the encryption context to be used for authenticated encryption. If
used here, the same value must be supplied to the Decrypt API or decryption will fail. For more
information, see Encryption Context.
Required: No
GrantTokens (p. 65)
Required: No
Response Syntax
{
"KeyId": "string"
}
Response Elements

66
Errors
The encrypted plaintext. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.

KeyId (p. 66)
The ID of the key used during encryption.
Type: String
Errors

DisabledException


InvalidKeyUsageException
The request was rejected because the specified KeySpec value is not valid.




67
Examples
NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 107
X-Amz-Target: TrentService.Encrypt
X-Amz-Date: 20160517T203825Z
Signature=67ccaa73c1af7fe83973ce8139104d55f3bdcebee323d2f2e65996d99015ace2
{
"Plaintext": "VGhpcyBpcyBEYXkgMSBmb3IgdGhlIEludGVybmV0Cg==",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 17 May 2016 20:38:30 GMT
Content-Length: 379
x-amzn-RequestId: 50a0c603-1c6f-11e6-bb9e-3fadde80ce75
{
"CiphertextBlob": "CiDPoCH188S65r5Cy7pAhIFJMXDlU7mewhSlYUpuQIVBrhKmAQEBAgB4z6Ah9fPEuua
+Qsu6QISBSTFw5VO5nsIUpWFKbkCFQa4AAAB9MHsGCSqGSIb3DQEHBqBuMGwCAQAwZwYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBA
ZjYCARCAOt8la8qXLO5wB3JH2NlwWWzWRU2RKqpO9A/0psE5UWwkK6CnwoeC3Zj9Q0A66apZkbRglFfY1lTY+Tc=",
}
See Also

• AWS SDK for C++
• AWS SDK for Go

68
See Also


69
GenerateDataKey
GenerateDataKey
Generates a unique data key. This operation returns a plaintext copy of the data key and a copy that is
encrypted under a customer master key (CMK) that you specify. You can use the plaintext key to encrypt
your data outside of KMS and store the encrypted data key with the encrypted data.
GenerateDataKey returns a unique data key for each request. The bytes in the key are not related to
the caller or CMK that is used to encrypt the data key.
To generate a data key, you need to specify the customer master key (CMK) that will be used to
encrypt the data key. You must also specify the length of the data key using either the KeySpec or
NumberOfBytes field (but not both). For common key lengths (128-bit and 256-bit symmetric keys), use
the KeySpec parameter. To perform this operation on a CMK in a different AWS account, specify the key
ARN or alias ARN in the value of the KeyId parameter.
You will find the plaintext copy of the data key in the Plaintext field of the response, and the
encrypted copy of the data key in the CiphertextBlob field.
We recommend that you use the following pattern to encrypt data locally in your application:
1. Use the GenerateDataKey operation to get a data encryption key.

2. Use the plaintext data key (returned in the Plaintext field of the response) to encrypt data locally,
then erase the plaintext data key from memory.
3. Store the encrypted data key (returned in the CiphertextBlob field of the response) alongside the
locally encrypted data.
To decrypt data locally:
1. Use the Decrypt (p. 30) operation to decrypt the encrypted data key. The operation returns a plaintext
copy of the data key.
2. Use the plaintext data key to decrypt data locally, then erase the plaintext data key from memory.
To get only an encrypted copy of the data key, use GenerateDataKeyWithoutPlaintext (p. 75). To get a
cryptographically secure random byte string, use GenerateRandom (p. 80).
You can use the optional encryption context to add additional security to your encryption operation.
When you specify an EncryptionContext in the GenerateDataKey operation, you must specify the
same encryption context (a case-sensitive exact match) in your request to Decrypt (p. 30) the data key.
Otherwise, the request to decrypt fails with an InvalidCiphertextException. For more information,
see Encryption Context in the AWS Key Management Service Developer Guide .
Request Syntax
{
"string" : "string"
},
"KeyId": "string",
"KeySpec": "string",
"NumberOfBytes": number
}

70
Request Parameters
Request Parameters

Note
KeyId (p. 70)
An identifier for the CMK that encrypts the data key.
For example:
Type: String
Required: Yes
A set of key-value pairs that represents additional authenticated data.
For more information, see Encryption Context in the AWS Key Management Service Developer Guide.
Required: No
GrantTokens (p. 70)
Required: No
KeySpec (p. 70)
The length of the data key. Use AES_128 to generate a 128-bit symmetric key, or AES_256 to
generate a 256-bit symmetric key.

71
Response Syntax
You must specify either the KeySpec or the NumberOfBytes parameter (but not both) in every
GenerateDataKey request.
Type: String
Valid Values: AES_256 | AES_128
Required: No
NumberOfBytes (p. 70)
The length of the data key in bytes. For example, use the value 64 to generate a 512-bit data key
(64 bytes is 512 bits). For 128-bit (16-byte) and 256-bit (32-byte) symmetric keys, use the KeySpec
parameter.
You must specify either the KeySpec or the NumberOfBytes parameter (but not both) in every
GenerateDataKey request.
Type: Integer
Required: No
Response Syntax
{
"KeyId": "string",
"Plaintext": blob
}
Response Elements
The encrypted copy of the data key. When you use the HTTP API or the AWS CLI, the value is
Base64-encoded. Otherwise, it is not encoded.

KeyId (p. 72)
The identifier of the CMK that encrypted the data key.
Type: String

Plaintext (p. 72)
The plaintext data key. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.
Otherwise, it is not encoded. Use this data key to encrypt your data outside of KMS. Then, remove it
from memory as soon as possible.

72
Errors
Errors

DisabledException






NotFoundException
Examples

73
See Also
Example Request
POST / HTTP/1.1
Content-Length: 50
X-Amz-Target: TrentService.GenerateDataKey
X-Amz-Date: 20161112T000940Z
Signature=815ac4ccbb5c53b8ca015f979704c7953bb0068bf53f4e0b7c6886ed5b0a8fe4
{
"KeyId": "alias/ExampleAlias",
"KeySpec": "AES_256"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Sat, 12 Nov 2016 00:09:40 GMT
Content-Length: 390
x-amzn-RequestId: 4e6fc242-a86c-11e6-aff0-8333261e2fbd
{
"CiphertextBlob":
"AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwH
+YdhV8MrkBQPeac0ReRVNDt9qleAt+SHgIRF8P0H+7U=",
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Plaintext": "VdzKNHGzUAzJeRBVY+uUmofUGGiDzyB3+i9fVkh3piw="
}
See Also

• AWS SDK for C++
• AWS SDK for Go

74
GenerateDataKeyWithoutPlaintext
GenerateDataKeyWithoutPlaintext
Generates a unique data key. This operation returns a data key that is encrypted under a customer
master key (CMK) that you specify. GenerateDataKeyWithoutPlaintext is identical to
GenerateDataKey (p. 70) except that returns only the encrypted copy of the data key.
Like GenerateDataKey, GenerateDataKeyWithoutPlaintext returns a unique data key for each

request. The bytes in the key are not related to the caller or CMK that is used to encrypt the data key.
This operation is useful for systems that need to encrypt data at some point, but not immediately. When
you need to encrypt the data, you call the Decrypt (p. 30) operation on the encrypted copy of the key.
It's also useful in distributed systems with different levels of trust. For example, you might store
encrypted data in containers. One component of your system creates new containers and stores an
encrypted data key with each container. Then, a different component puts the data into the containers.
That component first decrypts the data key, uses the plaintext data key to encrypt data, puts the
encrypted data into the container, and then destroys the plaintext data key. In this system, the
component that creates the containers never sees the plaintext data key.
Request Syntax
{
"string" : "string"
},
"KeyId": "string",
"KeySpec": "string",
}
Request Parameters

Note
KeyId (p. 75)
The identifier of the customer master key (CMK) that encrypts the data key.
For example:

75
Response Syntax
Type: String
Required: Yes
A set of key-value pairs that represents additional authenticated data.
For more information, see Encryption Context in the AWS Key Management Service Developer Guide.
Required: No
GrantTokens (p. 75)
Required: No
KeySpec (p. 75)
The length of the data key. Use AES_128 to generate a 128-bit symmetric key, or AES_256 to
generate a 256-bit symmetric key.
Type: String
Valid Values: AES_256 | AES_128
Required: No
The length of the data key in bytes. For example, use the value 64 to generate a 512-bit data key (64
bytes is 512 bits). For common key lengths (128-bit and 256-bit symmetric keys), we recommend
that you use the KeySpec field instead of this one.
Type: Integer
Required: No
Response Syntax
{
"KeyId": "string"

76
Response Elements
Response Elements
The encrypted data key. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.

KeyId (p. 76)
The identifier of the CMK that encrypted the data key.
Type: String
Errors

DisabledException





77
Examples

NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 50
X-Amz-Target: TrentService.GenerateDataKeyWithoutPlaintext
X-Amz-Date: 20161112T001941Z
Signature=c86e7fc0218461e537c0d06ac29d865d94dba6fbfad00a844f61200e651df483
{
"KeyId": "alias/ExampleAlias",
"KeySpec": "AES_256"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Sat, 12 Nov 2016 00:19:41 GMT
Content-Length: 331
x-amzn-RequestId: b4ca7ee7-a86d-11e6-8a4e-2f341b963ed6
{
"CiphertextBlob":
"AQEDAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH4wfAYJKoZIhvcNAQcGoG8wbQIBADBoBgkqhkiG9w0BBwEwH
ntdQTL16wQIBEIA7BE/3LB7F1meU8z4e1vEKBGZgXPwMvkZXbKnf3wxCD9lB4hU29lii4euOqxp8pESb
+7oCN9f1R75ac3s=",
}
See Also

78
See Also

• AWS SDK for C++
• AWS SDK for Go

79
GenerateRandom
GenerateRandom
Returns a random byte string that is cryptographically secure.
By default, the random byte string is generated in AWS KMS. To generate the byte string in the AWS
CloudHSM cluster that is associated with a custom key store, specify the custom key store ID.
For more information about entropy and random number generation, see the AWS Key Management
Service Cryptographic Details whitepaper.
Request Syntax
{
}
Request Parameters

Note
Generates the random byte string in the AWS CloudHSM cluster that is associated with the specified
custom key store. To find the ID of a custom key store, use the DescribeCustomKeyStores (p. 43)
operation.
Type: String
Required: No
The length of the byte string.
Type: Integer
Required: No
Response Syntax
{
"Plaintext": blob
}
Response Elements

80
Errors
Plaintext (p. 80)
The random byte string. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.
Errors


store name or ID.


Examples
Example Request

81
See Also
POST / HTTP/1.1
Content-Length: 21
X-Amz-Target: TrentService.GenerateRandom
X-Amz-Date: 20161114T215101Z
Signature=e3a0cfdbfb71fae5c89e422ad8322b6a44aed85bf68e3d11f3f315bbaa82ad22
{"NumberOfBytes": 32}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 14 Nov 2016 21:51:02 GMT
Content-Length: 60
x-amzn-RequestId: 6f79b0ad-aab4-11e6-971f-0f7b7e5b6782
{"Plaintext":"+Q2hxK6OBuU6K6ZIIBucFMCW2NJkhiSWDySSQyWp9zA="}
See Also

• AWS SDK for C++
• AWS SDK for Go

82
GetKeyPolicy
GetKeyPolicy
Gets a key policy attached to the specified customer master key (CMK). You cannot perform this
operation on a CMK in a different AWS account.
Request Syntax
{
"KeyId": "string",
"PolicyName": "string"
}
Request Parameters

Note
KeyId (p. 83)
For example:
Type: String
Required: Yes
PolicyName (p. 83)
Specifies the name of the key policy. The only valid name is default. To get the names of key
policies, use ListKeyPolicies (p. 109).
Type: String
Pattern: [\w]+
Required: Yes
Response Syntax
{

83
Response Elements
"Policy": "string"
}
Response Elements
Policy (p. 83)
A key policy document in JSON format.
Type: String
Errors

InvalidArnException



NotFoundException
Examples

84
See Also
Example Request
POST / HTTP/1.1
Content-Length: 74
X-Amz-Target: TrentService.GetKeyPolicy
X-Amz-Date: 20161114T225546Z
Signature=a88e20eebfbea3bf62d1512d0d2987e2d233becc7631a442237d3661df623a40
{
"PolicyName": "default",
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 14 Nov 2016 22:55:47 GMT
Content-Length: 326
x-amzn-RequestId: 7b105e7b-aabd-11e6-8039-3123b558b719
{"Policy":"{\n
\"Version\" : \"2012-10-17\",\n
\"Id\" : \"key-default-1\",\n
\"Statement\" : [ {\n
\"Sid\" : \"Enable IAM User Permissions\",\n
\"Effect\" : \"Allow\",\n
\"Principal\" : {\n
\"AWS\" : \"arn:aws:iam::111122223333:root\"\n
},\n
\"Action\" : \"kms:*\",\n
\"Resource\" : \"*\"\n
} ]\n
}"}
See Also

• AWS SDK for C++
• AWS SDK for Go

85
GetKeyRotationStatus
GetKeyRotationStatus
Gets a Boolean value that indicates whether automatic rotation of the key material is enabled for the
specified customer master key (CMK).
• Disabled: The key rotation status does not change when you disable a CMK. However, while the CMK is
disabled, AWS KMS does not rotate the backing key.
• Pending deletion: While a CMK is pending deletion, its key rotation status is false and AWS KMS does
not rotate the backing key. If you cancel the deletion, the original key rotation status is restored.
KeyId parameter.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
KeyId (p. 86)
For example:
Type: String
Required: Yes
Response Syntax
{

86
Response Elements
"KeyRotationEnabled": boolean
}
Response Elements
KeyRotationEnabled (p. 86)
A Boolean value that specifies whether key rotation is enabled.
Type: Boolean
Errors

InvalidArnException



NotFoundException


87
Examples
Examples
Example Request
POST / HTTP/1.1
Content-Length: 49
X-Amz-Target: TrentService.GetKeyRotationStatus
X-Amz-Date: 20161115T005817Z
Signature=282cb3a4a5d10684ff6c363300c34569a0707c4d503b88778e78cc51ea52f9be
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 15 Nov 2016 00:58:18 GMT
Content-Length: 28
x-amzn-RequestId: 98b59330-aace-11e6-aff0-8333261e2fbd
{"KeyRotationEnabled":false}
See Also

• AWS SDK for C++
• AWS SDK for Go

88
GetParametersForImport
GetParametersForImport
Returns the items you need in order to import key material into AWS KMS from your existing key
management infrastructure. For more information about importing key material into AWS KMS, see
Importing Key Material in the AWS Key Management Service Developer Guide.
You must specify the key ID of the customer master key (CMK) into which you will import key material.
This CMK's Origin must be EXTERNAL. You must also specify the wrapping algorithm and type of
wrapping key (public key) that you will use to encrypt the key material. You cannot perform this
This operation returns a public key and an import token. Use the public key to encrypt the key material.
Store the import token to send with a subsequent ImportKeyMaterial (p. 94) request. The public key
and import token from the same response must be used together. These items are valid for 24 hours.
When they expire, they cannot be used for a subsequent ImportKeyMaterial (p. 94) request. To get
new ones, send another GetParametersForImport request.
Request Syntax
{
"KeyId": "string",
"WrappingAlgorithm": "string",
"WrappingKeySpec": "string"
}
Request Parameters

Note
KeyId (p. 89)
The identifier of the CMK into which you will import key material. The CMK's Origin must be
EXTERNAL.
For example:
Type: String
Required: Yes

89
Response Syntax
WrappingAlgorithm (p. 89)
The algorithm you will use to encrypt the key material before importing it with
ImportKeyMaterial (p. 94). For more information, see Encrypt the Key Material in the AWS Key
Type: String
Valid Values: RSAES_PKCS1_V1_5 | RSAES_OAEP_SHA_1 | RSAES_OAEP_SHA_256
Required: Yes
WrappingKeySpec (p. 89)
The type of wrapping key (public key) to return in the response. Only 2048-bit RSA public keys are
supported.
Type: String
Valid Values: RSA_2048
Required: Yes
Response Syntax
{
"ImportToken": blob,
"KeyId": "string",
"ParametersValidTo": number,
"PublicKey": blob
}
Response Elements
ImportToken (p. 90)
The import token to send in a subsequent ImportKeyMaterial (p. 94) request.

KeyId (p. 90)
The identifier of the CMK to use in a subsequent ImportKeyMaterial (p. 94) request. This is the
same CMK specified in the GetParametersForImport request.
Type: String

ParametersValidTo (p. 90)
The time at which the import token and public key are no longer valid. After this time, you
cannot use them to make an ImportKeyMaterial (p. 94) request and you must send another
GetParametersForImport request to get new ones.

90
Errors
Type: Timestamp
PublicKey (p. 90)
The public key to use to encrypt the key material before importing it with
ImportKeyMaterial (p. 94).
Errors

InvalidArnException



NotFoundException

Examples
Example Request
POST / HTTP/1.1

91
Examples
Content-Length: 121
X-Amz-Target: TrentService.GetParametersForImport
X-Amz-Date: 20161130T225216Z
Signature=5bcc8e7669b6de719091ad27ae0145daa319f881010958208e960329341421d5
{
"WrappingAlgorithm": "RSAES_OAEP_SHA_1",
"WrappingKeySpec": "RSA_2048"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 30 Nov 2016 22:52:17 GMT
Content-Length: 2892
x-amzn-RequestId: a46d61e0-b74f-11e6-b0c0-3343f53dee45
{
"ImportToken": "AQECAHgybIx2X9LNs5ADpvmFm5Sv//
daUB9ZeCKoiJxmiw09YQAABrQwggawBgkqhkiG9w0BBwagggahMIIGnQIBADCCBpYGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMv
U4Wg2Vw+RMAgEQgIIGZ/wOYGszlrjopP6BW63jlYYn
+gd7jpdpx0dxPmPC5Ka6uuUomx1yMKVdgtMiX85jHr8or7RoLISwsyQH+CRD33V
+pQs+Rm0+XkinHj5Zl371ibHytqM1DwhCs5FdQJM+8kLau7EXTcar7XLQj86DWJRj/
dQW0nDdkQXgXvz7GFWkbYs3IELvTAc5lHOLHgkXeoXom3NtHMvbR2V34tYwaT86gdira9Qj0FDouNaTesEOJN/
QjBedXcnuWumwOzK+w/OL+MD4tR8/
B1jDjeafRv7YSMxiADr2FsfDL0ELhgXhFVC0Wz42oM0jYnoYjZuXx6fQxEmADjBMPjk6W
+SFs4sWOuHs0U8npsWBNOnLAZPqXskqSuPZzb3XMG59s+2ZUcbeARQjYv97861ohWgwzjxur2+wSlaGNYAb
+Xh7EV34n2KSLuJ1lSrZrEWlU1Pato6zzN1x0VHJgU3sMCJMQz1uch8ZGHbI7vvBvvvqTJT/
+087IA8thTTCRLAYTjr81sSEofug71twBrhct3pzKswaNQVmWMptBe54HWiWWZz1peNuIAIJtX9qtNzeuYEJyqfVBera0B5tK1vCOrw
+E4AQcSin0AWERUK9LY3BNM2svFrrl2tPWURtUPokMVI0i4NLw2fsHtLw1CXqwjGuzEGKvRfiaat3WGzAtMao5sSFQz/
XSCB9Ab5OsddOTArBr/ShuX1WYuPIL2+zQP+gadWjAfTgmx9Q4K2MxQUpS72bqUJmfzXqpVi63sKL43tOwJ
+2Bt8Z5JA9xaPkPwiYE5q7dWL4J57cr+Ty/GLXAhat9xIUsTjG5E3FIHLywKiBwlVjH/T5FXxk
+T0TXV/61UPGaxPX2HkFTirq/D2Uhz45pFwwH46nbhJe9NoRodjot+uAblfuAqxz0YElCRt/
gIMr87l4AF7X48JHfvqmZAYGdhJ1bUhSw8VfTOPkHpUV2k6Eq9DvcSRDsww1FI5+fVf0ZpDEf0W2itRz5Hq
+cRkQL9EZqLICNF0QrhEuEJNBXf3oSckvS1tqPnHaRIRmG71BONqwc7fSU7zmXa
+O95GV3gIgfvnQ3HJy5EHR2dgkjQdP
+hfdw7BcC9NT7ZyO9XefAI5GEr623hrzn6yom4JIiyUjjCQPK8mS75rIgazvyTp0WQKpSSKeJOZswYLNgip8Xv/
UBcehAKwRL0QhbOGhUbZvoRNS8c1FbrCUlcBc4W4aWzA4e7cepqy38/jfwRoh0UvN/
bbaDh8FC+jZyXhyXSTIPvM25HVVrxsDbsN8LkCabokXFlkhiawm3PqVm6QgWWKcpR2Td+ty
+Bdl2tRmGHDsPcHN0WaUEq2AjE7kzL0dv7Jd9OemBNTZSlEoQ8U5+sKbvmSrtFvPIj7zWDpDT9bkZFHcCvwlIE6AflbgBS8z0+xllVg
phBgaiRlDQdDmJmGD1yl+dxnIcoPs14xlcIwBdpw/M
+lvUuX8K4tqLMKzi1MOE0heBhGL0uEebYSkSQSUXUTTCk9hEkqslw0VXgwpgnGBXAOnVtYdUaqFMx5RIVxW471bnU0CYW5MrTTJ7o2j
H4KrdRPdvevc8kTG6I8fdK/ArYCvTk/yYL3L6YZbeqbActUTADX0iBijX/T5QYz/
Dd4H1eX4abHV70CnxftxCHuLMnwR8DpJVnkouQAqb4N7Ap6JIYkvNKFWb8HBlygq5kKcg5dTMAMiPRz80qsQm/
IwGG9JVbKeyhqlKtQOIerspm8J99lcn5s0aB180LKrtXAaFD1AyO3nDZxB3I71QKvOulr1BZ6K4meBKkEw3VqW4PpmxmBKnQVUK1jqw
+2ytZAdDox9zLT7YW457esjUQC6zibfBwb8G97leh704m37Stq6Z752u46frBNSPQlypGuSbqCw1peKeqf/
AVehk+j8RKBegOQSCvEja4KPmQrayXVzu3h1tDktA1/Wj21ercJaW20fcZ1KQG/
GPHuScFgBsWawQf1spqKwZyHAHPaWZCymD9Fo2yHBHi+/ARPwM02iuqDLi9Tqv/g0=",
"ParametersValidTo": 1.480632737044E9,
"PublicKey":
"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvH3Yj0wbkLEpUl95Cv1cJVjsVNSjwGq3tCLnzXfhVwVvmzGN8pYj3U8nK
+iSK341kr2kFTpINN7T1ZaX9vfXBdGR+VtkRKMWoHQeWzHrPZ+3irvpXNCKxGUxmPNsJSjPUhuSXT5+0VrY/
LEYLQ5lUTrhU6z5/OK0kzaCc66DXc5ipSloS4Xyg
+QcYSMxe9xuqO5HtzFImUSKBm1W6eDT6lHnSbpi7vXzNbIX7pWxKw9nmQvQIDAQAB"

92
See Also
See Also

• AWS SDK for C++
• AWS SDK for Go

93
ImportKeyMaterial
ImportKeyMaterial
Imports key material into an existing AWS KMS customer master key (CMK) that was created without key
material. You cannot perform this operation on a CMK in a different AWS account. For more information
about creating CMKs with no key material and then importing key material, see Importing Key Material
in the AWS Key Management Service Developer Guide.
Before using this operation, call GetParametersForImport (p. 89). Its response includes a public key and
an import token. Use the public key to encrypt the key material. Then, submit the import token from the
same GetParametersForImport response.
When calling this operation, you must specify the following values:
• The key ID or key ARN of a CMK with no key material. Its Origin must be EXTERNAL.
To create a CMK with no key material, call CreateKey (p. 23) and set the value of its Origin parameter
to EXTERNAL. To get the Origin of a CMK, call DescribeKey (p. 47).)
• The encrypted key material. To get the public key to encrypt the key material, call
GetParametersForImport (p. 89).
• The import token that GetParametersForImport (p. 89) returned. This token and the public key used to
encrypt the key material must have come from the same response.
• Whether the key material expires and if so, when. If you set an expiration date, you can change it only
by reimporting the same key material and specifying a new expiration date. If the key material expires,
AWS KMS deletes the key material and the CMK becomes unusable. To use the CMK again, you must
reimport the same key material.
When this operation is successful, the key state of the CMK changes from PendingImport to Enabled,
and you can use the CMK. After you successfully import key material into a CMK, you can reimport the
same key material into that CMK, but you cannot import different key material.
Request Syntax
{
"EncryptedKeyMaterial": blob,
"ImportToken": blob,
"KeyId": "string",
"ValidTo": number
}
Request Parameters

Note

94
Request Parameters
EncryptedKeyMaterial (p. 94)
The encrypted key material to import. It must be encrypted with the public key that you received in
the response to a previous GetParametersForImport (p. 89) request, using the wrapping algorithm
that you specified in that request.
Required: Yes
ImportToken (p. 94)
The import token that you received in the response to a previous GetParametersForImport (p. 89)
request. It must be from the same response that contained the public key that you used to encrypt
the key material.
Required: Yes
KeyId (p. 94)
The identifier of the CMK to import the key material into. The CMK's Origin must be EXTERNAL.
For example:
Type: String
Required: Yes
ExpirationModel (p. 94)
Specifies whether the key material expires. The default is KEY_MATERIAL_EXPIRES,

in which case you must include the ValidTo parameter. When this parameter is set to
KEY_MATERIAL_DOES_NOT_EXPIRE, you must omit the ValidTo parameter.
Type: String
Valid Values: KEY_MATERIAL_EXPIRES | KEY_MATERIAL_DOES_NOT_EXPIRE
Required: No
ValidTo (p. 94)
The time at which the imported key material expires. When the key material expires, AWS KMS
deletes the key material and the CMK becomes unusable. You must omit this parameter when
the ExpirationModel parameter is set to KEY_MATERIAL_DOES_NOT_EXPIRE. Otherwise it is
required.
Type: Timestamp

95
Response Elements
Required: No
Response Elements
Errors

ExpiredImportTokenException
The request was rejected because the provided import token is expired. Use
GetParametersForImport (p. 89) to get a new import token and public key, use the new public key to
encrypt the key material, and then try the request again.

IncorrectKeyMaterialException
The request was rejected because the provided key material is invalid or is not the same key material
that was previously imported into this customer master key (CMK).

InvalidArnException

invalid.

InvalidImportTokenException
The request was rejected because the provided import token is invalid or is associated with a
different customer master key (CMK).



96
Examples

NotFoundException

Examples
Example Request
POST / HTTP/1.1
X-Amz-Target: TrentService.ImportKeyMaterial
X-Amz-Date: 20161201T212609Z
Signature=dda4e269d4fd93decf1401aeb651e49c206c412c609141f6c743f146e1afb4e3
{
"ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE",
"ImportToken": "AQECAHgybIx2X9LNs5ADpvmFm5Sv//
daUB9ZeCKoiJxmiw09YQAABrQwggawBgkqhkiG9w0BBwagggahMIIGnQIBADCCBpYGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMv
U4Wg2Vw+RMAgEQgIIGZ/wOYGszlrjopP6BW63jlYYn
+gd7jpdpx0dxPmPC5Ka6uuUomx1yMKVdgtMiX85jHr8or7RoLISwsyQH+CRD33V
+pQs+Rm0+XkinHj5Zl371ibHytqM1DwhCs5FdQJM+8kLau7EXTcar7XLQj86DWJRj/
dQW0nDdkQXgXvz7GFWkbYs3IELvTAc5lHOLHgkXeoXom3NtHMvbR2V34tYwaT86gdira9Qj0FDouNaTesEOJN/
QjBedXcnuWumwOzK+w/OL+MD4tR8/
B1jDjeafRv7YSMxiADr2FsfDL0ELhgXhFVC0Wz42oM0jYnoYjZuXx6fQxEmADjBMPjk6W
+SFs4sWOuHs0U8npsWBNOnLAZPqXskqSuPZzb3XMG59s+2ZUcbeARQjYv97861ohWgwzjxur2+wSlaGNYAb
+Xh7EV34n2KSLuJ1lSrZrEWlU1Pato6zzN1x0VHJgU3sMCJMQz1uch8ZGHbI7vvBvvvqTJT/
+087IA8thTTCRLAYTjr81sSEofug71twBrhct3pzKswaNQVmWMptBe54HWiWWZz1peNuIAIJtX9qtNzeuYEJyqfVBera0B5tK1vCOrw
+E4AQcSin0AWERUK9LY3BNM2svFrrl2tPWURtUPokMVI0i4NLw2fsHtLw1CXqwjGuzEGKvRfiaat3WGzAtMao5sSFQz/
XSCB9Ab5OsddOTArBr/ShuX1WYuPIL2+zQP+gadWjAfTgmx9Q4K2MxQUpS72bqUJmfzXqpVi63sKL43tOwJ
+2Bt8Z5JA9xaPkPwiYE5q7dWL4J57cr+Ty/GLXAhat9xIUsTjG5E3FIHLywKiBwlVjH/T5FXxk
+T0TXV/61UPGaxPX2HkFTirq/D2Uhz45pFwwH46nbhJe9NoRodjot+uAblfuAqxz0YElCRt/
gIMr87l4AF7X48JHfvqmZAYGdhJ1bUhSw8VfTOPkHpUV2k6Eq9DvcSRDsww1FI5+fVf0ZpDEf0W2itRz5Hq
+cRkQL9EZqLICNF0QrhEuEJNBXf3oSckvS1tqPnHaRIRmG71BONqwc7fSU7zmXa
+O95GV3gIgfvnQ3HJy5EHR2dgkjQdP
+hfdw7BcC9NT7ZyO9XefAI5GEr623hrzn6yom4JIiyUjjCQPK8mS75rIgazvyTp0WQKpSSKeJOZswYLNgip8Xv/
UBcehAKwRL0QhbOGhUbZvoRNS8c1FbrCUlcBc4W4aWzA4e7cepqy38/jfwRoh0UvN/
bbaDh8FC+jZyXhyXSTIPvM25HVVrxsDbsN8LkCabokXFlkhiawm3PqVm6QgWWKcpR2Td+ty
+Bdl2tRmGHDsPcHN0WaUEq2AjE7kzL0dv7Jd9OemBNTZSlEoQ8U5+sKbvmSrtFvPIj7zWDpDT9bkZFHcCvwlIE6AflbgBS8z0+xllVg
phBgaiRlDQdDmJmGD1yl+dxnIcoPs14xlcIwBdpw/M
+lvUuX8K4tqLMKzi1MOE0heBhGL0uEebYSkSQSUXUTTCk9hEkqslw0VXgwpgnGBXAOnVtYdUaqFMx5RIVxW471bnU0CYW5MrTTJ7o2j
H4KrdRPdvevc8kTG6I8fdK/ArYCvTk/yYL3L6YZbeqbActUTADX0iBijX/T5QYz/
Dd4H1eX4abHV70CnxftxCHuLMnwR8DpJVnkouQAqb4N7Ap6JIYkvNKFWb8HBlygq5kKcg5dTMAMiPRz80qsQm/
IwGG9JVbKeyhqlKtQOIerspm8J99lcn5s0aB180LKrtXAaFD1AyO3nDZxB3I71QKvOulr1BZ6K4meBKkEw3VqW4PpmxmBKnQVUK1jqw
+2ytZAdDox9zLT7YW457esjUQC6zibfBwb8G97leh704m37Stq6Z752u46frBNSPQlypGuSbqCw1peKeqf/

97
See Also
AVehk+j8RKBegOQSCvEja4KPmQrayXVzu3h1tDktA1/Wj21ercJaW20fcZ1KQG/
GPHuScFgBsWawQf1spqKwZyHAHPaWZCymD9Fo2yHBHi+/ARPwM02iuqDLi9Tqv/g0=",
"EncryptedKeyMaterial": "CubeyZ4cm/xMEA0UG5jP1iBzh/0E+uUg407JDcXhIC+iuMm
+wPgITaEby+Y3nM/e6gjUls5vy9TdBRFv4+JtksvB5hW4Znb2lUQhTUv+SSAZpaI14kAgTq/
jC2GTLkaC6Vf5zJx2xaLrOKGV2Xu4YgONIGslubHNffTC3aL/YBJ/FXTXaVu7rS2phOFCrZ
+ATittS03w4DiCVoNwo2v0QE0+dVoUNjXNQC1veWxhPlC7FezfK7AIsBSSXotJfANxRkybg8KcmkSoYdzr3N0L0v7oMorgbTgaTvdrL
PzphK6RWJGJig4tk+lxUT8hV7xiLkFskGjIHFmp6Xbon8w=="
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Thu, 01 Dec 2016 21:26:10 GMT
Content-Length: 2
x-amzn-RequestId: c72fb6ff-b80c-11e6-ae07-61b14fe11739
{}
See Also

• AWS SDK for C++
• AWS SDK for Go

98
ListAliases
ListAliases
Gets a list of aliases in the caller's AWS account and region. You cannot list aliases in other accounts. For
more information about aliases, see CreateAlias (p. 11).
By default, the ListAliases command returns all aliases in the account and region. To get only the aliases
that point to a particular customer master key (CMK), use the KeyId parameter.
The ListAliases response can include aliases that you created and associated with your customer
managed CMKs, and aliases that AWS created and associated with AWS managed CMKs in your account.
You can recognize AWS aliases because their names have the format aws/<service-name>, such as
aws/dynamodb.
The response might also include aliases that have no TargetKeyId field. These are predefined aliases
that AWS has created but has not yet associated with a CMK. Aliases that AWS creates in your account,
including predefined aliases, do not count against your AWS KMS aliases limit.
Request Syntax
{
"KeyId": "string",
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
KeyId (p. 99)
Lists only aliases that refer to the specified CMK. The value of this parameter can be the ID or
Amazon Resource Name (ARN) of a CMK in the caller's account and region. You cannot use an alias
name or alias ARN in this value.
This parameter is optional. If you omit it, ListAliases returns all aliases in the account and region.
Type: String
Required: No
Limit (p. 99)
This value is optional. If you include a value, it must be between 1 and 100, inclusive. If you do not
include a value, it defaults to 50.
Type: Integer

99
Response Syntax
Required: No
Marker (p. 99)
Type: String
Required: No
Response Syntax
{
"Aliases": [
{
"AliasArn": "string",
}
],
}
Response Elements
Aliases (p. 100)
A list of aliases.
Type: Array of AliasListEntry (p. 162) objects

NextMarker (p. 100)
Type: String
Truncated (p. 100)
Type: Boolean

100
Errors
Errors

InvalidArnException

InvalidMarkerException
The request was rejected because the marker that specifies where pagination should next begin is
not valid.


NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 2
X-Amz-Target: TrentService.ListAliases
X-Amz-Date: 20161203T011453Z
Signature=c2867e5f45167bf713e8f2c9998772ad72a20958db2cc0ef46bfba1632ca4d62
{}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Sat, 03 Dec 2016 01:14:55 GMT

101
See Also
x-amzn-RequestId: e6196175-b8f5-11e6-b404-15dcd0a7add5
{
"Aliases": [
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/aws/acm",
"AliasName": "alias/aws/acm",
"TargetKeyId": "da03f6f7-d279-427a-9cae-de48d07e5b66"
},
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/aws/ebs",
"AliasName": "alias/aws/ebs",
"TargetKeyId": "25a217e7-7170-4b8c-8bf6-045ea5f70e5b"
},
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/aws/rds",
"AliasName": "alias/aws/rds",
"TargetKeyId": "7ec3104e-c3f2-4b5c-bf42-bfc4772c6685"
},
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/aws/redshift",
"AliasName": "alias/aws/redshift"
},
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/aws/s3",
"AliasName": "alias/aws/s3",
"TargetKeyId": "d2b0f1a3-580d-4f79-b836-bc983be8cfa5"
},
{
"AliasArn": "arn:aws:kms:us-east-2:111122223333:alias/example1",
"AliasName": "alias/example1",
"TargetKeyId": "4da1e216-62d0-46c5-a7c0-5f3a3d2f8046"
},
{
"TargetKeyId": "f32fef59-2cc2-445b-8573-2d73328acbee"
},
{
"TargetKeyId": "1374ef38-d34e-4d5f-b2c9-4e0daee38855"
}
],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

102
See Also


103
ListGrants
ListGrants
Gets a list of all grants for the specified customer master key (CMK).
KeyId parameter.
Request Syntax
{
"KeyId": "string",
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
KeyId (p. 104)
For example:
Type: String
Required: Yes
Limit (p. 104)
Type: Integer
Required: No

104
Response Syntax
Marker (p. 104)
Type: String
Required: No
Response Syntax
{
"Grants": [
{
"Constraints": {
"string" : "string"
},
"string" : "string"
}
},
"IssuingAccount": "string",
"KeyId": "string",
"Name": "string",
}
],
}
Response Elements
Grants (p. 105)
A list of grants.
Type: Array of GrantListEntry (p. 167) objects

NextMarker (p. 105)
Type: String

105
Errors
Truncated (p. 105)
Type: Boolean
Errors

InvalidArnException

not valid.



NotFoundException
Examples
Example Request
POST / HTTP/1.1

106
Examples
Content-Length: 49
X-Amz-Target: TrentService.ListGrants
X-Amz-Date: 20161206T231134Z
Signature=157e1dd2ef1992e70e403e96c9f7122c5eb18bf82e4e5a71a83d63dcbc1c681b
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 06 Dec 2016 23:11:34 GMT
x-amzn-RequestId: 54ee4e2f-bc09-11e6-8073-89d6c33fcd1f
{
"Grants": [
{
"CreationDate": 1.477431461E9,
"GrantId": "91ad875e49b04a9d1f3bdeb84d821f9db6ea95e1098813f6d47f0c65fbe2a172",
"GranteePrincipal": "acm.us-east-2.amazonaws.com",
"IssuingAccount": "arn:aws:iam::111122223333:root",
"KeyId": "arn:aws:kms:us-
east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Name": "",
"Operations": [
"Encrypt",
"ReEncryptFrom",
"ReEncryptTo"
],
"RetiringPrincipal": "acm.us-east-2.amazonaws.com"
},
{
"GrantId": "a5d67d3e207a8fc1f4928749ee3e52eb0440493a8b9cf05bbfad91655b056200",
"Name": "",
"Operations": [
"ReEncryptFrom",
"ReEncryptTo"
],
},
{
"GrantId": "c541aaf05d90cb78846a73b346fc43e65be28b7163129488c738e0c9e0628f4f",
"Name": "",
"Operations": [
"Encrypt",
"ReEncryptFrom",

107
See Also
"ReEncryptTo"
],
},
{
"GrantId": "dd2052c67b4c76ee45caf1dc6a1e2d24e8dc744a51b36ae2f067dc540ce0105c",
"Name": "",
"Operations": [
"Encrypt",
"ReEncryptFrom",
"ReEncryptTo"
],
}
],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

108
ListKeyPolicies
ListKeyPolicies
Gets the names of the key policies that are attached to a customer master key (CMK). This operation is
designed to get policy names that you can use in a GetKeyPolicy (p. 83) operation. However, the only
valid policy name is default. You cannot perform this operation on a CMK in a different AWS account.
Request Syntax
{
"KeyId": "string",
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
KeyId (p. 109)
For example:
Type: String
Required: Yes
Limit (p. 109)
Only one policy can be attached to a key.
Type: Integer
Required: No

109
Response Syntax
Marker (p. 109)
Type: String
Required: No
Response Syntax
{
"PolicyNames": [ "string" ],
}
Response Elements
NextMarker (p. 110)
Type: String
PolicyNames (p. 110)
A list of key policy names. The only valid value is default.
Pattern: [\w]+
Truncated (p. 110)
Type: Boolean
Errors

110
Examples

InvalidArnException



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 49
X-Amz-Target: TrentService.ListKeyPolicies
X-Amz-Date: 20161206T235923Z
Signature=82fe067c53d0dfff36793b8b6ef2d82d8adf0f1c05016bf4b4d6c50563ec7033
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Tue, 06 Dec 2016 23:59:24 GMT
Content-Length: 45
x-amzn-RequestId: 036f8e4b-bc10-11e6-b60b-ffb5eb2d1d15

111
See Also
{
"PolicyNames": ["default"],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

112
ListKeys
ListKeys
Gets a list of all customer master keys (CMKs) in the caller's AWS account and region.
Request Syntax
{
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
Limit (p. 113)
Type: Integer
Required: No
Marker (p. 113)
Type: String
Required: No
Response Syntax
{
"Keys": [
{
"KeyArn": "string",
"KeyId": "string"

113
Response Elements
}
],
}
Response Elements
Keys (p. 113)
A list of customer master keys (CMKs).
Type: Array of KeyListEntry (p. 169) objects

NextMarker (p. 113)
Type: String
Truncated (p. 113)
Type: Boolean
Errors

not valid.


114
Examples
Examples
Example Request
POST / HTTP/1.1
Content-Length: 2
X-Amz-Target: TrentService.ListKeys
X-Amz-Date: 20161207T003550Z
Signature=2196a20c1a139ae8f6fe070881f41954616c775bb5a484814c35f8ee35cfa448
{}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 07 Dec 2016 00:35:50 GMT
Content-Length: 980
x-amzn-RequestId: 1a5f0a53-bc15-11e6-82b3-e9e4af764a06
{
"Keys": [
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/0d990263-018e-4e65-a703-
eff731de951e",
"KeyId": "0d990263-018e-4e65-a703-eff731de951e"
},
{
"KeyArn": "arn:aws:kms:us-
east-2:111122223333:key/144be297-0ae1-44ac-9c8f-93cd8c82f841",
"KeyId": "144be297-0ae1-44ac-9c8f-93cd8c82f841"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/21184251-b765-428e-
b852-2c7353e72571",
"KeyId": "21184251-b765-428e-b852-2c7353e72571"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/214fe92f-5b03-4ae1-b350-
db2a45dbe10c",
"KeyId": "214fe92f-5b03-4ae1-b350-db2a45dbe10c"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/339963f2-e523-49d3-af24-
a0fe752aa458",
"KeyId": "339963f2-e523-49d3-af24-a0fe752aa458"
},
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/b776a44b-df37-4438-9be4-
a27494e4271a",
"KeyId": "b776a44b-df37-4438-9be4-a27494e4271a"
},

115
See Also
{
"KeyArn": "arn:aws:kms:us-east-2:111122223333:key/deaf6c9e-cf2c-46a6-
bf6d-0b6d487cffbb",
"KeyId": "deaf6c9e-cf2c-46a6-bf6d-0b6d487cffbb"
}
],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

116
ListResourceTags
ListResourceTags
Returns a list of all tags for the specified customer master key (CMK).
You cannot perform this operation on a CMK in a different AWS account.
Request Syntax
{
"KeyId": "string",
"Limit": number,
"Marker": "string"
}
Request Parameters

Note
KeyId (p. 117)
For example:
Type: String
Required: Yes
Limit (p. 117)
Type: Integer
Required: No

117
Response Syntax
Marker (p. 117)
Do not attempt to construct this value. Use only the value of NextMarker from the truncated
response you just received.
Type: String
Required: No
Response Syntax
{
"Tags": [
{
"TagKey": "string",
}
],
}
Response Elements
NextMarker (p. 118)
Do not assume or infer any information from this value.
Type: String
Tags (p. 118)
A list of tags. Each tag consists of a tag key and a tag value.

Truncated (p. 118)

118
Errors
Type: Boolean
Errors
InvalidArnException

not valid.


NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 49
X-Amz-Target: TrentService.ListResourceTags
X-Amz-Date: 20170109T200421Z
Signature=17706fce40fda00c6768b3297355c353490c1dfdf3b3a9591193612961cd2cb4
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 09 Jan 2017 20:04:22 GMT
Content-Length: 158

119
See Also
x-amzn-RequestId: cfb46544-d6a6-11e6-a164-b5365990e84e
{
"Tags": [{
"TagKey": "CostCenter",
"TagValue": "87654"
}, {
"TagKey": "CreatedBy",
"TagValue": "ExampleUser"
}, {
"TagKey": "Purpose",
"TagValue": "Test"
}],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

120
ListRetirableGrants
ListRetirableGrants
Returns a list of all grants for which the grant's RetiringPrincipal matches the one specified.
A typical use is to list all grants that you are able to retire. To retire a grant, use RetireGrant (p. 135).
Request Syntax
{
"Limit": number,
"Marker": "string",
}
Request Parameters

Note
RetiringPrincipal (p. 121)
The retiring principal for which to list grants.
To specify the retiring 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 for specifying a principal, see AWS Identity and Access Management
(IAM) in the Example ARNs section of the Amazon Web Services General Reference.
Type: String
Pattern: ^[\w+=,.@:/-]+$
Required: Yes
Limit (p. 121)
Type: Integer
Required: No
Marker (p. 121)
Type: String

121
Response Syntax
Required: No
Response Syntax
{
"Grants": [
{
"Constraints": {
"string" : "string"
},
"string" : "string"
}
},
"IssuingAccount": "string",
"KeyId": "string",
"Name": "string",
}
],
}
Response Elements
Grants (p. 122)
A list of grants.
Type: Array of GrantListEntry (p. 167) objects

NextMarker (p. 122)
Type: String
Truncated (p. 122)

122
Errors
Type: Boolean
Errors

InvalidArnException

not valid.


NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 61
X-Amz-Target: TrentService.ListRetirableGrants
X-Amz-Date: 20161207T191040Z
Signature=d5e43f0cfd75a3251f40bc27e76f83b3110b33e3d972142ae118b2b3c0f67b39
{"RetiringPrincipal": "arn:aws:iam::111122223333:role/ExampleRole"}
Example Response
HTTP/1.1 200 OK

123
See Also
Server: Server
Date: Wed, 07 Dec 2016 19:10:41 GMT
Content-Length: 436
x-amzn-RequestId: d86125dc-bcb0-11e6-82b3-e9e4af764a06
{
"Grants": [
{
"GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60",
"GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",
"Name": "",
"Operations": [
"Decrypt",
"Encrypt"
],
"RetiringPrincipal": "arn:aws:iam::111122223333:role/ExampleRole"
}
],
"Truncated": false
}
See Also

• AWS SDK for C++
• AWS SDK for Go

124
PutKeyPolicy
PutKeyPolicy
Attaches a key policy to the specified customer master key (CMK). You cannot perform this operation on
a CMK in a different AWS account.
For more information about key policies, see Key Policies in the AWS Key Management Service Developer
Guide.
Request Syntax
{
"BypassPolicyLockoutSafetyCheck": boolean,
"KeyId": "string",
"Policy": "string",
"PolicyName": "string"
}
Request Parameters

Note
KeyId (p. 125)
For example:
Type: String
Required: Yes
Policy (p. 125)
The key policy to attach to the CMK.
The key policy must meet the following criteria:

• If you don't set BypassPolicyLockoutSafetyCheck to true, the key policy must allow the
principal that is making the PutKeyPolicy request to make a subsequent PutKeyPolicy
request on the CMK. This reduces the risk that the CMK becomes unmanageable. For more
information, refer to the scenario in the Default Key Policy section of the AWS Key Management
Service Developer Guide.

125
Response Elements
• Each statement in the key policy must contain one or more principals. The principals in the key
policy must exist and be visible to AWS KMS. When you create a new AWS principal (for example,
an IAM user or role), you might need to enforce a delay before including the new principal in a
key policy because the new principal might not be immediately visible to AWS KMS. For more
information, see Changes that I make are not always immediately visible in the AWS Identity and
Access Management User Guide.
The key policy size limit is 32 kilobytes (32768 bytes).
Type: String
Required: Yes
PolicyName (p. 125)
The name of the key policy. The only valid value is default.
Type: String
Pattern: [\w]+
Required: Yes
BypassPolicyLockoutSafetyCheck (p. 125)
A flag to indicate whether to bypass the key policy lockout safety check.
Important
Setting this value to true increases the risk that the CMK 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
Use this parameter only when you intend to prevent the principal that is making the request from
making a subsequent PutKeyPolicy request on the CMK.
The default value is false.
Type: Boolean
Required: No
Response Elements
Errors

126
Examples
InvalidArnException




MalformedPolicyDocumentException
The request was rejected because the specified policy is not syntactically or semantically correct.

NotFoundException

Examples
Example Request
POST / HTTP/1.1
X-Amz-Target: TrentService.PutKeyPolicy
X-Amz-Date: 20161207T203023Z
Signature=e58ea91db06afc1bc7a1f204769cf6bc4d003ee090095a13caef361c69739ede

127
Examples
{
"Policy": "{
\"Version\": \"2012-10-17\",
\"Id\": \"custom-policy-2016-12-07\",
\"Statement\": [
{
\"Sid\": \"Enable IAM User Permissions\",
\"Effect\": \"Allow\",
\"Principal\": {
\"AWS\": \"arn:aws:iam::111122223333:root\"
},
\"Action\": \"kms:*\",
\"Resource\": \"*\"
},
{
\"Sid\": \"Allow access for Key Administrators\",
\"Principal\": {
\"AWS\": [
\"arn:aws:iam::111122223333:user/ExampleAdminUser\",
\"arn:aws:iam::111122223333:role/ExampleAdminRole\"
]
},
\"Action\": [
\"kms:Create*\",
\"kms:Describe*\",
\"kms:Enable*\",
\"kms:List*\",
\"kms:Put*\",
\"kms:Update*\",
\"kms:Revoke*\",
\"kms:Disable*\",
\"kms:Get*\",
\"kms:Delete*\",
\"kms:ScheduleKeyDeletion\",
\"kms:CancelKeyDeletion\"
],
\"Resource\": \"*\"
},
{
\"Sid\": \"Allow use of the key\",
\"Principal\": {
\"AWS\": \"arn:aws:iam::111122223333:role/ExamplePowerUserRole\"
},
\"Action\": [
\"kms:Encrypt\",
\"kms:Decrypt\",
\"kms:ReEncrypt*\",
\"kms:GenerateDataKey*\",
\"kms:DescribeKey\"
],
\"Resource\": \"*\"
},
{
\"Sid\": \"Allow attachment of persistent resources\",
\"Principal\": {
\"AWS\": \"arn:aws:iam::111122223333:role/ExamplePowerUserRole\"
},
\"Action\": [
\"kms:CreateGrant\",
\"kms:ListGrants\",
\"kms:RevokeGrant\"
],

128
See Also
\"Resource\": \"*\",
\"Condition\": {
\"Bool\": {
\"kms:GrantIsForAWSResource\": \"true\"
}
}
}
]
}",
"PolicyName": "default",
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 07 Dec 2016 20:30:23 GMT
Content-Length: 0
x-amzn-RequestId: fb114d4c-bcbb-11e6-82b3-e9e4af764a06
See Also

• AWS SDK for C++
• AWS SDK for Go

129
ReEncrypt
ReEncrypt
Encrypts data on the server side with a new customer master key (CMK) without exposing the plaintext
of the data on the client side. The data is first decrypted and then reencrypted. You can also use this
operation to change the encryption context of a ciphertext.
You can reencrypt data using CMKs in different AWS accounts.
Unlike other operations, ReEncrypt is authorized twice, once as ReEncryptFrom on the source
CMK and once as ReEncryptTo on the destination CMK. We recommend that you include the
"kms:ReEncrypt*" permission in your key policies to permit reencryption from or to the CMK. This
permission is automatically included in the key policy when you create a CMK through the console. But
you must include it manually when you create a CMK programmatically or when you set a key policy with
the PutKeyPolicy (p. 125) operation.
Request Syntax
{
"DestinationEncryptionContext": {
"string" : "string"
},
"DestinationKeyId": "string",
"SourceEncryptionContext": {
"string" : "string"
}
}
Request Parameters

Note
Ciphertext of the data to reencrypt.
Required: Yes
DestinationKeyId (p. 130)
A unique identifier for the CMK that is used to reencrypt the data.

130
Response Syntax
For example:
To get the key ID and key ARN for a CMK, use ListKeys (p. 113) or DescribeKey (p. 47). To get the alias
name and alias ARN, use ListAliases (p. 99).
Type: String
Required: Yes
DestinationEncryptionContext (p. 130)
Encryption context to use when the data is reencrypted.
Required: No
GrantTokens (p. 130)
Required: No
SourceEncryptionContext (p. 130)
Encryption context used to encrypt and decrypt the data specified in the CiphertextBlob
parameter.
Required: No
Response Syntax
{
"KeyId": "string",
"SourceKeyId": "string"
}
Response Elements

131
Errors
The reencrypted data. When you use the HTTP API or the AWS CLI, the value is Base64-encoded.

KeyId (p. 131)
Unique identifier of the CMK used to reencrypt the data.
Type: String

SourceKeyId (p. 131)
Unique identifier of the CMK used to originally encrypt the data.
Type: String
Errors

DisabledException

invalid.




132
Examples


NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 306
X-Amz-Target: TrentService.ReEncrypt
X-Amz-Date: 20161207T225816Z
Signature=7afd339e2a680e0726592ddf687aabe48e1d8a7933a60ebbdc0154b8e2936ef2
{
"DestinationKeyId": "0987dcba-09fe-87dc-65ba-ab0987654321",
"CiphertextBlob": "AQECAHj/M9MyvNsMT8kW
+K5DVkMfunTHr0w6V6crnuAGw80uRwAAAH0wewYJKoZIhvcNAQcGoG4wbAIBADBnBgkqhkiG9w0BBwEwHgYJYIZIAWUDBAEuMBEEDPX
+FSkUmNmmE0H0aHHRYRD6XqUnaCNnzAuhhq4VTGBfii6oWtjVU83pGmradvUawxE/tbCg=="
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Wed, 07 Dec 2016 22:58:17 GMT
Content-Length: 423
x-amzn-RequestId: a434eca2-bcd0-11e6-b60b-ffb5eb2d1d15
{
"CiphertextBlob":
"AQECAHjRYf5WytIc0C857tFSnBaPn2F8DgfmThbJlGfR8P3WlwAAAH0wewYJKoZIhvcNAQcGoG4wbAIBADBnBgkqhkiG9w0BBwEwH
vwjXjPBhQIBEIA6wjfzufQPhuU
+nVqa3Kj4nqSTdhDw1PTkImKCUEuvQDui6qsooyB4Qxe8OOBqciRNC7ENQN8lKaEijg==",

133
See Also
"KeyId": "arn:aws:kms:us-east-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321",
"SourceKeyId": "arn:aws:kms:us-
east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
See Also

• AWS SDK for C++
• AWS SDK for Go

134
RetireGrant
RetireGrant
Retires a grant. To clean up, you can retire a grant when you're done using it. You should revoke a grant
when you intend to actively deny operations that depend on it. The following are permitted to call this
API:
• The AWS account (root user) under which the grant was created
• The RetiringPrincipal, if present in the grant
• The GranteePrincipal, if RetireGrant is an operation specified in the grant
You must identify the grant to retire by its grant token or by a combination of the grant ID and
the Amazon Resource Name (ARN) of the customer master key (CMK). A grant token is a unique
variable-length base64-encoded string. A grant ID is a 64 character unique identifier of a grant. The
CreateGrant (p. 18) operation returns both.
Request Syntax
{
"GrantToken": "string",
"KeyId": "string"
}
Request Parameters

Note
GrantId (p. 135)
Unique identifier of the grant to retire. The grant ID is returned in the response to a CreateGrant
operation.
• Grant ID Example -
0123456789012345678901234567890123456789012345678901234567890123
Type: String
Required: No
GrantToken (p. 135)
Token that identifies the grant to be retired.
Type: String
Required: No

135
Response Elements
KeyId (p. 135)
The Amazon Resource Name (ARN) of the CMK associated with the grant.
For example: arn:aws:kms:us-

Type: String
Required: No
Response Elements
Errors

InvalidArnException

InvalidGrantIdException
The request was rejected because the specified GrantId is not valid.




NotFoundException

136
Examples
Examples
Example Request
POST / HTTP/1.1
Content-Length: 167
X-Amz-Target: TrentService.RetireGrant
X-Amz-Date: 20161208T233237Z
Signature=e463f010eb7d997b4f89ae836288a67f362b0afd762fcf242a3f76ba282448dc
{
"GrantId": "1ea8e6c7d4d49ecf7e4461c792f6a27651d7ff0ee13a724c19e730337faa26b1"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Thu, 08 Dec 2016 23:32:38 GMT
Content-Length: 0
x-amzn-RequestId: 9ad2b038-bd9e-11e6-ace2-6fb96f685e31
See Also

• AWS SDK for C++
• AWS SDK for Go

137
RevokeGrant
RevokeGrant
Revokes the specified grant for the specified customer master key (CMK). You can revoke a grant to
actively deny operations that depend on it.
KeyId parameter.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
GrantId (p. 138)
Identifier of the grant to be revoked.
Type: String
Required: Yes
KeyId (p. 138)
A unique identifier for the customer master key associated with the grant.
For example:
Type: String
Required: Yes
Response Elements

138
Errors
Errors

InvalidArnException

InvalidGrantIdException
The request was rejected because the specified GrantId is not valid.



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 128
X-Amz-Target: TrentService.RevokeGrant
X-Amz-Date: 20161210T000739Z
Signature=3f4073c96c38c8bc006b3a74a67fb2108cfe2d6ff23f96f09047924919806a7d
{

139
See Also
"GrantId": "f271e8328717f8bde5d03f4981f06a6b3fc18bcae2da12ac38bd9186e7925d11"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Sat, 10 Dec 2016 00:07:40 GMT
Content-Length: 0
x-amzn-RequestId: aa49887b-be6c-11e6-b749-7394871b1b43
See Also

• AWS SDK for C++
• AWS SDK for Go

140
ScheduleKeyDeletion
ScheduleKeyDeletion
Schedules the deletion of a customer master key (CMK). You may provide a waiting period, specified in
days, before deletion occurs. If you do not provide a waiting period, the default period of 30 days is used.
When this operation is successful, the key state of the CMK changes to PendingDeletion. Before the
waiting period ends, you can use CancelKeyDeletion (p. 5) to cancel the deletion of the CMK. After the
waiting period ends, AWS KMS deletes the CMK and all AWS KMS data associated with it, including all
aliases that refer to it.
Important
Deleting a CMK is a destructive and potentially dangerous operation. When a CMK is deleted, all
data that was encrypted under the CMK is unrecoverable. To prevent the use of a CMK without
deleting it, use DisableKey (p. 51).
If you schedule deletion of a CMK from a custom key store, when the waiting period expires,
ScheduleKeyDeletion deletes the CMK from AWS KMS. Then AWS KMS makes a best effort to delete
the key material from the associated AWS CloudHSM cluster. However, you might need to manually
delete the orphaned key material from the cluster and its backups.
For more information about scheduling a CMK for deletion, see Deleting Customer Master Keys in the
AWS Key Management Service Developer Guide.
Request Syntax
{
"KeyId": "string",
"PendingWindowInDays": number
}
Request Parameters

Note
KeyId (p. 141)
The unique identifier of the customer master key (CMK) to delete.
For example:

141
Response Syntax
Type: String
Required: Yes
PendingWindowInDays (p. 141)
The waiting period, specified in number of days. After the waiting period ends, AWS KMS deletes the
customer master key (CMK).
Type: Integer
Required: No
Response Syntax
{
"KeyId": "string"
}
Response Elements
DeletionDate (p. 142)
The date and time after which AWS KMS deletes the customer master key (CMK).
Type: Timestamp
KeyId (p. 142)
The unique identifier of the customer master key (CMK) for which deletion is scheduled.
Type: String
Errors

142
Examples
InvalidArnException



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 75
X-Amz-Target: TrentService.ScheduleKeyDeletion
X-Amz-Date: 20161210T003358Z
Signature=c42c52cf0e4057e004b73a905b0e5da215f63dd33117e7316f760e6223433abb
{
"PendingWindowInDays": 7,
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Sat, 10 Dec 2016 00:33:58 GMT
Content-Length: 114
x-amzn-RequestId: 5704ddf7-be70-11e6-b0c0-3343f53dee45
{
"DeletionDate": 1.4820192E9,

143
See Also
}
See Also

• AWS SDK for C++
• AWS SDK for Go

144
TagResource
TagResource
Adds or edits tags for a customer master key (CMK). You cannot perform this operation on a CMK in a
different AWS account.
Each tag consists of a tag key and a tag value. Tag keys and tag values are both required, but tag values
can be empty (null) strings.
You can only use a tag key once for each CMK. If you use the tag key again, AWS KMS replaces the
current tag value with the specified value.
For information about the rules that apply to tag keys and tag values, see User-Defined Tag Restrictions
in the AWS Billing and Cost Management User Guide.
Request Syntax
{
"KeyId": "string",
"Tags": [
{
"TagKey": "string",
}
]
}
Request Parameters

Note
KeyId (p. 145)
A unique identifier for the CMK you are tagging.
For example:
Type: String
Required: Yes

145
Response Elements
Tags (p. 145)
One or more tags. Each tag consists of a tag key and a tag value.
Required: Yes
Response Elements
Errors
InvalidArnException




NotFoundException

TagException
Examples
Example Request

146
See Also
POST / HTTP/1.1
Content-Length: 102
X-Amz-Target: TrentService.TagResource
X-Amz-Date: 20170109T200202Z
Signature=5a5e6b9950567ea2b9ead41df706fd8f3e4a900553957c5c7f1992daaa67b8ff
{
"Tags": [{
"TagKey": "Purpose",
"TagValue": "Test"
}]
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 09 Jan 2017 20:02:03 GMT
Content-Length: 0
x-amzn-RequestId: 7ce02bcb-d6a6-11e6-bfed-ebe31947a596
See Also

• AWS SDK for C++
• AWS SDK for Go

147
UntagResource
UntagResource
Removes the specified tags from the specified customer master key (CMK). You cannot perform this
To remove a tag, specify the tag key. To change the tag value of an existing tag key, use
TagResource (p. 145).
Request Syntax
{
"KeyId": "string",
"TagKeys": [ "string" ]
}
Request Parameters

Note
KeyId (p. 148)
A unique identifier for the CMK from which you are removing tags.
For example:
Type: String
Required: Yes
TagKeys (p. 148)
One or more tag keys. Specify only the tag keys, not the tag values.
Required: Yes

148
Response Elements
Response Elements
Errors
InvalidArnException



NotFoundException

TagException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 87
X-Amz-Target: TrentService.UntagResource
X-Amz-Date: 20170109T200704Z
Signature=f1c9c01e545fa02e2dba096b66d5f697800a1b8e06a1776058206dc393b8d1b4
{

149
See Also
"TagKeys": [
"Purpose",
"CostCenter"
]
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 09 Jan 2017 20:07:04 GMT
Content-Length: 0
x-amzn-RequestId: 30b417a1-d6a7-11e6-a164-b5365990e84e
See Also

• AWS SDK for C++
• AWS SDK for Go

150
UpdateAlias
UpdateAlias
Associates an existing alias with a different customer master key (CMK). Each CMK can have multiple
aliases, but the aliases must be unique within the account and region. You cannot perform this operation
on an alias in a different AWS account.
This operation works only on existing aliases. To change the alias of a CMK to a new value, use
CreateAlias (p. 11) to create a new alias and DeleteAlias (p. 34) to delete the old alias.
Because an alias is not a property of a CMK, you can create, update, and delete the aliases of a CMK
without affecting the CMK. Also, aliases do not appear in the response from the DescribeKey (p. 47)
operation. To get the aliases of all CMKs in the account, use the ListAliases (p. 99) operation.
The alias name must begin with alias/ followed by a name, such as alias/ExampleAlias. It can
contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). The alias name
cannot begin with alias/aws/. The alias/aws/ prefix is reserved for AWS managed CMKs.
Request Syntax
{
}
Request Parameters

Note
AliasName (p. 151)
Specifies the name of the alias to change. This value must begin with alias/ followed by the alias
name, such as alias/ExampleAlias.
Type: String
Required: Yes
TargetKeyId (p. 151)
Unique identifier of the customer master key (CMK) to be mapped to the alias. When the update
operation completes, the alias will point to this CMK.
For example:

151
Response Elements

To verify that the alias is mapped to the correct CMK, use ListAliases (p. 99).
Type: String
Required: Yes
Response Elements
Errors



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 90

152
See Also
X-Amz-Target: TrentService.UpdateAlias
X-Amz-Date: 20161212T193252Z
Signature=3d6375048a5917aff38f25b92e66bceb16b29562193f7ab7f869b4c53f115c20
{
"TargetKeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"AliasName": "alias/ExampleAlias"
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 12 Dec 2016 19:32:53 GMT
Content-Length: 0
x-amzn-RequestId: c64706c8-c0a1-11e6-b0c0-3343f53dee45
See Also

• AWS SDK for C++
• AWS SDK for Go

153
UpdateCustomKeyStore
UpdateCustomKeyStore
Changes the properties of a custom key store. Use the CustomKeyStoreId parameter to identify the
custom key store you want to edit. Use the remaining parameters to change the properties of the custom
key store.
You can only update a custom key store that is disconnected. To disconnect the custom key store, use
DisconnectCustomKeyStore (p. 57). To reconnect the custom key store after the update completes,
use ConnectCustomKeyStore (p. 8). To find the connection state of a custom key store, use the
DescribeCustomKeyStores (p. 43) operation.
Use the parameters of UpdateCustomKeyStore to edit your keystore settings.
• Use the NewCustomKeyStoreName parameter to change the friendly name of the custom key store to
the value that you specify.
• Use the KeyStorePassword parameter tell AWS KMS the current password of the kmsuser crypto
user (CU) in the associated AWS CloudHSM cluster. You can use this parameter to fix connection
failures that occur when AWS KMS cannot log into the associated cluster because the kmsuser
password has changed. This value does not change the password in the AWS CloudHSM cluster.
• Use the CloudHsmClusterId parameter to associate the custom key store with a different, but related,
AWS CloudHSM cluster. You can use this parameter to repair a custom key store if its AWS CloudHSM
cluster becomes corrupted or is deleted, or when you need to create or restore a cluster from a backup.
store.
Request Syntax
{
"KeyStorePassword": "string",
"NewCustomKeyStoreName": "string"
}
Request Parameters

Note
Identifies the custom key store that you want to update. Enter the ID of the custom key store. To
find the ID of a custom key store, use the DescribeCustomKeyStores (p. 43) operation.
Type: String

154
Response Elements
Required: Yes
CloudHsmClusterId (p. 154)
Associates the custom key store with a related AWS CloudHSM cluster.
Enter the cluster ID of the cluster that you used to create the custom key store or a cluster that
shares a backup history and has the same cluster certificate as the original cluster. You cannot
use this parameter to associate a custom key store with an unrelated cluster. In addition, the
replacement cluster must fulfill the requirements for a cluster associated with a custom key store. To
view the cluster certificate of a cluster, use the DescribeClusters operation.
Type: String
Required: No
KeyStorePassword (p. 154)
Enter the current password of the kmsuser crypto user (CU) in the AWS CloudHSM cluster that is
associated with the custom key store.
This parameter tells AWS KMS the current password of the kmsuser crypto user (CU). It does not set
or change the password of any users in the AWS CloudHSM cluster.
Type: String
Length Constraints: Minimum length of 1.
Required: No
NewCustomKeyStoreName (p. 154)
Changes the friendly name of the custom key store to the value that you specify. The custom key
store name must be unique in the AWS account.
Type: String
Required: No
Response Elements
Errors
the Region.

155
Errors
For the CreateCustomKeyStore (p. 14), UpdateCustomKeyStore (p. 154), and CreateKey (p. 23)
operations, the AWS CloudHSM cluster must have at least two active HSMs, each in a different
Availability Zone. For the ConnectCustomKeyStore (p. 8) operation, the AWS CloudHSM must
contain at least one active HSM.


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.

CloudHsmClusterNotRelatedException
The request was rejected because the specified AWS CloudHSM cluster has a different cluster
certificate than the original cluster. You cannot use the operation to specify an unrelated cluster.
Specify a cluster that shares a backup history with the original cluster. This includes clusters that
were created from a backup of the current cluster, and clusters that were created from the same
backup that produced the current cluster.
Clusters that share a backup history have the same cluster certificate. To view the cluster certificate
of a cluster, use the DescribeClusters operation.


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

156
See Also

CustomKeyStoreNameInUseException
The request was rejected because the specified 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.

store name or ID.

See Also

• AWS SDK for C++
• AWS SDK for Go

157
UpdateKeyDescription
UpdateKeyDescription
Replaces the description of a customer managed CMK with one that you specify. You can use this
operation to add, change, or delete the CMK description. You cannot update the description of a CMK
when its key state is PendingDeletion.
A CMK description is optional. To see the description of a CMK, use the DescribeKey (p. 47) operation.
Request Syntax
{
"KeyId": "string"
}
Request Parameters

Note
Description (p. 158)
New description for the CMK.
Enter a description that explains the type of data you plan to protect or the application you plan to
use with the CMK. The Default master key that protects my ... when no other key is defined description
format is reserved for AWS managed CMKs.
To delete an existing description, enter an empty string.
Type: String
Required: Yes
KeyId (p. 158)
For example:

158
Response Elements
Type: String
Required: Yes
Response Elements
Errors

InvalidArnException



NotFoundException
Examples
Example Request
POST / HTTP/1.1
Content-Length: 150
X-Amz-Target: TrentService.UpdateKeyDescription
X-Amz-Date: 20161212T201249Z

159
See Also
Signature=cd81d09965e5df1156eb0416ec8b2e3f9dea9dbc4ca9285b472c319bcbbaec71
{
"Description": "Example description that explains what this CMK is used for."
}
Example Response
HTTP/1.1 200 OK
Server: Server
Date: Mon, 12 Dec 2016 20:12:50 GMT
Content-Length: 0
x-amzn-RequestId: 5b089880-c0a7-11e6-89c4-3d6791a06780
See Also

• AWS SDK for C++
• AWS SDK for Go

160
Data Types
The AWS Key Management Service API contains several data types that various actions use. This section
describes each data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not
assume a particular order.
The following data types are supported:
• AliasListEntry (p. 162)

• CustomKeyStoresListEntry (p. 163)
• GrantConstraints (p. 165)
• GrantListEntry (p. 167)
• KeyListEntry (p. 169)
• KeyMetadata (p. 170)
• Tag (p. 173)

161
AliasListEntry
AliasListEntry
Contains information about an alias.
Contents
Note
AliasArn
String that contains the key ARN.
Type: String
Required: No
AliasName
String that contains the alias. This value begins with alias/.
Type: String
Required: No
TargetKeyId
String that contains the key identifier referred to by the alias.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

162
CustomKeyStoresListEntry
CustomKeyStoresListEntry
Contains information about each custom key store in the custom key store list.
Contents
Note
CloudHsmClusterId
A unique identifier for the AWS CloudHSM cluster that is associated with the custom key store.
Type: String
Required: No
ConnectionErrorCode
Describes the connection error. Valid values are:

• CLUSTER_NOT_FOUND - AWS KMS cannot find the AWS CloudHSM cluster with the specified
cluster ID.
• INSUFFICIENT_CLOUDHSM_HSMS - The associated AWS CloudHSM cluster does not contain any
active HSMs. To connect a custom key store to its AWS CloudHSM cluster, the cluster must contain
at least one active HSM.
• INTERNAL_ERROR - AWS KMS could not complete the request due to an internal error. Retry the
request. For ConnectCustomKeyStore requests, disconnect the custom key store before trying
to connect again.
• INVALID_CREDENTIALS - AWS KMS does not have the correct password for the kmsuser crypto
user in the AWS CloudHSM cluster.
• NETWORK_ERRORS - Network errors are preventing AWS KMS from connecting to the custom key
store.
• USER_LOCKED_OUT - The kmsuser CU account is locked out of the associated AWS CloudHSM
cluster due to too many failed password attempts. Before you can connect your custom key store
to its AWS CloudHSM cluster, you must change the kmsuser account password and update the
password value for the custom key store.
For help with connection failures, see Troubleshooting Custom Key Stores in the AWS Key
Type: String
Valid Values: INVALID_CREDENTIALS | CLUSTER_NOT_FOUND | NETWORK_ERRORS |

INTERNAL_ERROR | INSUFFICIENT_CLOUDHSM_HSMS | USER_LOCKED_OUT
Required: No
ConnectionState
Indicates whether the custom key store is connected to its AWS CloudHSM cluster.
You can create and use CMKs in your custom key stores only when its connection state is
CONNECTED.
The value is DISCONNECTED if the key store has never been connected or you use the
DisconnectCustomKeyStore (p. 57) operation to disconnect it. If the value is CONNECTED but you are

163
See Also
having trouble using the custom key store, make sure that its associated AWS CloudHSM cluster is
active and contains at least one active HSM.
A value of FAILED indicates that an attempt to connect was unsuccessful. For help resolving a
connection failure, see Troubleshooting a Custom Key Store in the AWS Key Management Service
Developer Guide.
Type: String
Valid Values: CONNECTED | CONNECTING | FAILED | DISCONNECTED | DISCONNECTING
Required: No
CreationDate
The date and time when the custom key store was created.
Type: Timestamp
Required: No
CustomKeyStoreId
A unique identifier for the custom key store.
Type: String
Required: No
CustomKeyStoreName
The user-specified friendly name for the custom key store.
Type: String
Required: No
TrustAnchorCertificate
The trust anchor certificate of the associated AWS CloudHSM cluster. When you initialize the cluster,
you create this certificate and save it in the customerCA.crt file.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

164
GrantConstraints
GrantConstraints
Use this structure to allow cryptographic operations in the grant only when the operation request
includes the specified encryption context.
AWS KMS applies the grant constraints only when the grant allows a cryptographic operation that
accepts an encryption context as input, such as the following.
• Encrypt (p. 65)

• Decrypt (p. 30)
• ReEncrypt (p. 130)
AWS KMS does not apply the grant constraints to other operations, such as DescribeKey (p. 47) or
ScheduleKeyDeletion (p. 141).
Important
In a cryptographic operation, the encryption context in the decryption operation must be an
exact, case-sensitive match for the keys and values in the encryption context of the encryption
operation. Only the order of the pairs can vary.
However, in a grant constraint, the key in each key-value pair is not case sensitive, but the value
is case sensitive.
To avoid confusion, do not use multiple encryption context pairs that differ only by case.
To require a fully case-sensitive encryption context, use the kms:EncryptionContext:
and kms:EncryptionContextKeys conditions in an IAM or key policy. For details, see
kms:EncryptionContext: in the AWS Key Management Service Developer Guide .
Contents
Note
EncryptionContextEquals
A list of key-value pairs that must match the encryption context in the cryptographic operation
request. The grant allows the operation only when the encryption context in the request is the same
as the encryption context specified in this constraint.
Required: No
EncryptionContextSubset
A list of key-value pairs that must be included in the encryption context of the cryptographic
operation request. The grant allows the cryptographic operation only when the encryption context
in the request includes the key-value pairs specified in this constraint, although it can include
additional key-value pairs.
Required: No
See Also

165
See Also
• AWS SDK for C++

• AWS SDK for Go

166
GrantListEntry
GrantListEntry
Contains information about an entry in a list of grants.
Contents
Note
Constraints
A list of key-value pairs that must be present in the encryption context of certain subsequent
operations that the grant allows.
Type: GrantConstraints (p. 165) object
Required: No
CreationDate
The date and time when the grant was created.
Type: Timestamp
Required: No
GranteePrincipal
The principal that receives the grant's permissions.
Type: String
Pattern: ^[\w+=,.@:/-]+$
Required: No
GrantId
The unique identifier for the grant.
Type: String
Required: No
IssuingAccount
The AWS account under which the grant was issued.
Type: String
Pattern: ^[\w+=,.@:/-]+$
Required: No
KeyId
The unique identifier for the customer master key (CMK) to which the grant applies.

167
See Also
Type: String
Required: No
Name
The friendly name that identifies the grant. If a name was provided in the CreateGrant (p. 18)
request, that name is returned. Otherwise this value is null.
Type: String
Required: No
Operations
The list of operations permitted by the grant.
Valid Values: Decrypt | Encrypt | GenerateDataKey |

GenerateDataKeyWithoutPlaintext | ReEncryptFrom | ReEncryptTo | CreateGrant
| RetireGrant | DescribeKey
Required: No
RetiringPrincipal
The principal that can retire the grant.
Type: String
Pattern: ^[\w+=,.@:/-]+$
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

168
KeyListEntry
KeyListEntry
Contains information about each entry in the key list.
Contents
Note
KeyArn
ARN of the key.
Type: String
Required: No
KeyId
Unique identifier of the key.
Type: String
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

169
KeyMetadata
KeyMetadata
Contains metadata about a customer master key (CMK).
This data type is used as a response element for the CreateKey (p. 23) and DescribeKey (p. 47)
operations.
Contents
Note
KeyId
The globally unique identifier for the CMK.
Type: String
Required: Yes
Arn
The Amazon Resource Name (ARN) of the CMK. For examples, see AWS Key Management Service
(AWS KMS) in the Example ARNs section of the AWS General Reference.
Type: String
Required: No
AWSAccountId
The twelve-digit account ID of the AWS account that owns the CMK.
Type: String
Required: No
CloudHsmClusterId
The cluster ID of the AWS CloudHSM cluster that contains the key material for the CMK. When you
create a CMK in a custom key store, AWS KMS creates the key material for the CMK in the associated
AWS CloudHSM cluster. This value is present only when the CMK is created in a custom key store.
Type: String
Required: No
CreationDate
The date and time when the CMK was created.
Type: Timestamp
Required: No
CustomKeyStoreId
A unique identifier for the custom key store that contains the CMK. This value is present only when
the CMK is created in a custom key store.

170
Contents
Type: String
Required: No
DeletionDate
The date and time after which AWS KMS deletes the CMK. This value is present only when KeyState
is PendingDeletion.
Type: Timestamp
Required: No
Description
The description of the CMK.
Type: String
Required: No
Enabled
Specifies whether the CMK is enabled. When KeyState is Enabled this value is true, otherwise it is
false.
Type: Boolean
Required: No
ExpirationModel
Specifies whether the CMK's key material expires. This value is present only when Origin is
EXTERNAL, otherwise this value is omitted.
Type: String
Valid Values: KEY_MATERIAL_EXPIRES | KEY_MATERIAL_DOES_NOT_EXPIRE
Required: No
KeyManager
The manager of the CMK. CMKs in your AWS account are either customer managed or AWS
managed. For more information about the difference, see Customer Master Keys in the AWS Key
Type: String
Valid Values: AWS | CUSTOMER
Required: No
KeyState
The state of the CMK.
For more information about how key state affects the use of a CMK, see How Key State Affects the
Type: String

171
See Also
Valid Values: Enabled | Disabled | PendingDeletion | PendingImport |

Unavailable
Required: No
KeyUsage
The cryptographic operations for which you can use the CMK. The only valid value is
ENCRYPT_DECRYPT, which means you can use the CMK to encrypt and decrypt data.
Type: String
Valid Values: ENCRYPT_DECRYPT
Required: No
Origin
The source of the CMK's key material. When this value is AWS_KMS, AWS KMS created the key
material. When this value is EXTERNAL, the key material was imported from your existing key
management infrastructure or the CMK lacks key material. When this value is AWS_CLOUDHSM, the
key material was created in the AWS CloudHSM cluster associated with a custom key store.
Type: String
Valid Values: AWS_KMS | EXTERNAL | AWS_CLOUDHSM
Required: No
ValidTo
The time at which the imported key material expires. When the key material expires, AWS KMS
deletes the key material and the CMK becomes unusable. This value is present only for CMKs whose
Origin is EXTERNAL and whose ExpirationModel is KEY_MATERIAL_EXPIRES, otherwise this
value is omitted.
Type: Timestamp
Required: No
See Also
• AWS SDK for C++

• AWS SDK for Go

172
Tag
Tag
A key-value pair. A tag consists of a tag key and a tag value. Tag keys and tag values are both required,
but tag values can be empty (null) strings.
For information about the rules that apply to tag keys and tag values, see User-Defined Tag Restrictions
in the AWS Billing and Cost Management User Guide.
Contents
Note
TagKey
The key of the tag.
Type: String
Required: Yes
TagValue
The value of the tag.
Type: String
Required: Yes
See Also
• AWS SDK for C++

• AWS SDK for Go

173
Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.
Action
The action to be performed.
Type: string
Required: Yes
Version
The API version that the request is written for, expressed in the format YYYY-MM-DD.
Type: string
Required: Yes
X-Amz-Algorithm
The hash algorithm that you used to create the request signature.
Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.
Type: string
Valid Values: AWS4-HMAC-SHA256
Required: Conditional
X-Amz-Credential
The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.
For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.
Type: string
X-Amz-Date
The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.
Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

174
not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.
Type: string
X-Amz-Security-Token
The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.
Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.
Type: string
X-Amz-Signature
Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.
Type: string
X-Amz-SignedHeaders
Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.
Type: string

175
Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.
AccessDeniedException
You do not have sufficient access to perform this action.

IncompleteSignature
The request signature does not conform to AWS standards.

InternalFailure
The request processing has failed because of an unknown error, exception or failure.

InvalidAction
The action or operation requested is invalid. Verify that the action is typed correctly.

InvalidClientTokenId
The X.509 certificate or AWS access key ID provided does not exist in our records.

InvalidParameterCombination
Parameters that must not be used together were used together.

InvalidParameterValue
An invalid or out-of-range value was supplied for the input parameter.

InvalidQueryParameter
The AWS query string is malformed or does not adhere to AWS standards.

MalformedQueryString
The query string contains a syntax error.

MissingAction
The request is missing an action or a required parameter.

176
MissingAuthenticationToken
The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

MissingParameter
A required parameter for the specified action is not supplied.

OptInRequired
The AWS access key ID needs a subscription for the service.

RequestExpired
The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp
on the request is more than 15 minutes in the future.

ServiceUnavailable
The request has failed due to a temporary failure of the server.

ThrottlingException
The request was denied due to request throttling.

ValidationError
The input fails to satisfy the constraints specified by an AWS service.

177

Kms Api Reference

Uploaded by

Copyright:

Available Formats

Kms Api Reference

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Kms Api Reference

Uploaded by

Copyright:

Available Formats

AWS Key Management Service

AWS Key Management Service: API Reference

API Version 2014-11-01

API Version 2014-11-01

Request Parameters .......................................................................................................... 59

API Version 2014-11-01

API Version 2014-11-01

See Also ........................................................................................................................ 120

API Version 2014-11-01

Errors ............................................................................................................................ 149

API Version 2014-11-01

All AWS KMS operations require Signature Version 4.

Logging API Requests

Commonly Used API Operations

API Version 2014-11-01

• Encrypt (p. 65)

This document was last published on November 21, 2019.

API Version 2014-11-01

API Version 2014-11-01

• UpdateKeyDescription (p. 158)

API Version 2014-11-01

The request accepts the following data in JSON format.

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

API Version 2014-11-01

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

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

HTTP Status Code: 500

HTTP Status Code: 400

HTTP Status Code: 500

HTTP Status Code: 400

HTTP Status Code: 400

API Version 2014-11-01

• AWS Command Line Interface

API Version 2014-11-01

The request accepts the following data in JSON format.

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

API Version 2014-11-01

For the CreateCustomKeyStore (p. 14), UpdateCustomKeyStore (p. 154), and

HTTP Status Code: 400

HTTP Status Code: 400

This exception is thrown under the following conditions:

API Version 2014-11-01

HTTP Status Code: 400

HTTP Status Code: 400

HTTP Status Code: 500

• AWS Command Line Interface

API Version 2014-11-01

To map an existing alias to a diﬀerent CMK, call UpdateAlias (p. 151).

The request accepts the following data in JSON format.

AliasName (p. 11)

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

Identiﬁes the CMK to which the alias refers.

API Version 2014-11-01

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

HTTP Status Code: 400

HTTP Status Code: 500

HTTP Status Code: 400

HTTP Status Code: 500

HTTP Status Code: 400