2015/10/15 - AWS Key Management Service - 3 new 5 updated api methods
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 state of the CMK changes to PendingDeletion . Before the waiting period ends, you can use CancelKeyDeletion 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 point to it.
Warning
Deleting a CMK is a destructive and potentially dangerous operation. When a CMK is deleted, all data that was encrypted under the CMK is rendered unrecoverable. To restrict the use of a CMK without deleting it, use DisableKey.
For more information about scheduling a CMK for deletion, go to Deleting Customer Master Keys in the AWS Key Management Service Developer Guide .
Request Syntax
client.schedule_key_deletion(
KeyId='string',
PendingWindowInDays=123
)
string
[REQUIRED]
The unique identifier for the customer master key (CMK) to delete.
To specify this value, use the unique key ID or the Amazon Resource Name (ARN) of the CMK. Examples:
Unique key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To obtain the unique key ID and key ARN for a given CMK, use ListKeys or DescribeKey.
integer
The waiting period, specified in number of days. After the waiting period ends, AWS KMS deletes the customer master key (CMK).
This value is optional. If you include a value, it must be between 7 and 30, inclusive. If you do not include a value, it defaults to 30.
dict
Response Syntax
{
'KeyId': 'string',
'DeletionDate': datetime(2015, 1, 1)
}
Response Structure
(dict) --
KeyId (string) --
The unique identifier of the customer master key (CMK) for which deletion is scheduled.
DeletionDate (datetime) --
The date and time after which AWS KMS deletes the customer master key (CMK).
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.
For more information about scheduling and canceling deletion of a CMK, go to Deleting Customer Master Keys in the AWS Key Management Service Developer Guide .
Request Syntax
client.cancel_key_deletion(
KeyId='string'
)
string
[REQUIRED]
The unique identifier for the customer master key (CMK) for which to cancel deletion.
To specify this value, use the unique key ID or the Amazon Resource Name (ARN) of the CMK. Examples:
Unique key ID: 1234abcd-12ab-34cd-56ef-1234567890ab
Key ARN: arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
To obtain the unique key ID and key ARN for a given CMK, use ListKeys or DescribeKey.
dict
Response Syntax
{
'KeyId': 'string'
}
Response Structure
(dict) --
KeyId (string) --
The unique identifier of the master key for which deletion is canceled.
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.
Request Syntax
client.list_retirable_grants(
Limit=123,
Marker='string',
RetiringPrincipal='string'
)
integer
When paginating results, specify the maximum number of items to return in the response. If additional items exist beyond the number you specify, the Truncated element in the response is set to true.
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.
string
Use this parameter only when paginating results and only in a subsequent request after you've received a response with truncated results. Set it to the value of NextMarker from the response you just received.
string
[REQUIRED]
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, go to AWS Identity and Access Management (IAM) in the Example ARNs section of the Amazon Web Services General Reference .
dict
Response Syntax
{
'Grants': [
{
'KeyId': 'string',
'GrantId': 'string',
'Name': 'string',
'CreationDate': datetime(2015, 1, 1),
'GranteePrincipal': 'string',
'RetiringPrincipal': 'string',
'IssuingAccount': 'string',
'Operations': [
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant'|'DescribeKey',
],
'Constraints': {
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
}
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
(dict) --
Grants (list) --
A list of grants.
(dict) --
Contains information about an entry in a list of grants.
KeyId (string) --
The unique identifier for the customer master key (CMK) to which the grant applies.
GrantId (string) --
The unique identifier for the grant.
Name (string) --
The friendly name that identifies the grant. If a name was provided in the CreateGrant request, that name is returned. Otherwise this value is null.
CreationDate (datetime) --
The date and time when the grant was created.
GranteePrincipal (string) --
The principal that receives the grant's permissions.
RetiringPrincipal (string) --
The principal that can retire the grant.
IssuingAccount (string) --
The AWS account under which the grant was issued.
Operations (list) --
The list of operations permitted by the grant.
(string) --
Constraints (dict) --
The conditions under which the grant's operations are allowed.
EncryptionContextSubset (dict) --
Contains a list of key-value pairs, a subset of which must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list or is a subset of this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
EncryptionContextEquals (dict) --
Contains a list of key-value pairs that must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
NextMarker (string) --
When Truncated is true, this value is present and contains the value to use for the Marker parameter in a subsequent pagination request.
Truncated (boolean) --
A flag that indicates whether there are more items in the list. If your results were truncated, you can use the Marker parameter to make a subsequent pagination request to retrieve more items in the list.
{'Name': 'string', 'Operations': {'DescribeKey'}}
Adds a grant to a key to specify who can use the key and under what conditions. Grants are alternate permission mechanisms to key policies.
For more information about grants, see Grants in the AWS Key Management Service Developer Guide .
Request Syntax
client.create_grant(
KeyId='string',
GranteePrincipal='string',
RetiringPrincipal='string',
Operations=[
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant'|'DescribeKey',
],
Constraints={
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
},
GrantTokens=[
'string',
],
Name='string'
)
string
[REQUIRED]
The unique identifier for the customer master key (CMK) that the grant applies to.
To specify this value, use the globally unique key ID or the Amazon Resource Name (ARN) of the key. Examples:
Globally unique key ID: 12345678-1234-1234-1234-123456789012
Key ARN: arn:aws:kms:us-west-2:123456789012:key/12345678-1234-1234-1234-123456789012
string
[REQUIRED]
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, 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 .
string
The principal that is given permission to retire the grant by using RetireGrant 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 .
list
A list of operations that the grant permits. The list can contain any combination of one or more of the following values:
Decrypt
Encrypt
GenerateDataKey
GenerateDataKeyWithoutPlaintext
ReEncryptFrom
ReEncryptTo
CreateGrant
RetireGrant
(string) --
dict
The conditions under which the operations permitted by the grant are allowed.
You can use this value to allow the operations permitted by the grant only when a specified encryption context is present. For more information, see Encryption Context in the AWS Key Management Service Developer Guide .
EncryptionContextSubset (dict) --
Contains a list of key-value pairs, a subset of which must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list or is a subset of this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
EncryptionContextEquals (dict) --
Contains a list of key-value pairs that must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
list
A list of grant tokens.
For more information, go to Grant Tokens in the AWS Key Management Service Developer Guide .
(string) --
string
A friendly name for identifying the grant. Use this value to prevent unintended creation of duplicate grants when retrying this request.
When this value is absent, all CreateGrant requests result in a new grant with a unique GrantId even if all the supplied parameters are identical. This can result in unintended duplicates when you retry the CreateGrant request.
When this value is present, you can retry a CreateGrant request with identical parameters; if the grant already exists, the original GrantId is returned without creating a new grant. Note that the returned grant token is unique with every CreateGrant request, even when a duplicate GrantId is returned. All grant tokens obtained in this way can be used interchangeably.
dict
Response Syntax
{
'GrantToken': 'string',
'GrantId': 'string'
}
Response Structure
(dict) --
GrantToken (string) --
The grant token.
For more information about using grant tokens, see Grant Tokens in the AWS Key Management Service Developer Guide .
GrantId (string) --
The unique identifier for the grant.
You can use the GrantId in a subsequent RetireGrant or RevokeGrant operation.
{'KeyMetadata': {'DeletionDate': 'timestamp',
'KeyState': 'Enabled | Disabled | PendingDeletion'}}
Creates a customer master key. Customer master keys can be used to encrypt small amounts of data (less than 4K) directly, but they are most commonly used to encrypt or envelope data keys that are then used to encrypt customer data. For more information about data keys, see GenerateDataKey and GenerateDataKeyWithoutPlaintext.
Request Syntax
client.create_key(
Policy='string',
Description='string',
KeyUsage='ENCRYPT_DECRYPT'
)
string
Policy to attach to the key. This is required and delegates back to the account. The key is the root of trust. The policy size limit is 32 KiB (32768 bytes).
string
Description of the key. We recommend that you choose a description that helps your customer decide whether the key is appropriate for a task.
string
Specifies the intended use of the key. Currently this defaults to ENCRYPT/DECRYPT, and only symmetric encryption and decryption are supported.
dict
Response Syntax
{
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'ENCRYPT_DECRYPT',
'KeyState': 'Enabled'|'Disabled'|'PendingDeletion',
'DeletionDate': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
KeyMetadata (dict) --
Metadata associated with the key.
AWSAccountId (string) --
The twelve-digit account ID of the AWS account that owns the key.
KeyId (string) --
The globally unique identifier for the key.
Arn (string) --
The Amazon Resource Name (ARN) of the key. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .
CreationDate (datetime) --
The date and time when the key was created.
Enabled (boolean) --
Specifies whether the key is enabled. When KeyState is Enabled this value is true, otherwise it is false.
Description (string) --
The friendly description of the key.
KeyUsage (string) --
The cryptographic operations for which you can use the key. Currently the only allowed value is ENCRYPT_DECRYPT , which means you can use the key for the Encrypt and Decrypt operations.
KeyState (string) --
The state of the customer master key (CMK).
For more information about how key state affects the use of a CMK, go to How Key State Affects the Use of a Customer Master Key in the AWS Key Management Service Developer Guide .
DeletionDate (datetime) --
The date and time after which AWS KMS deletes the customer master key (CMK). This value is present only when KeyState is PendingDeletion , otherwise this value is null.
{'GrantTokens': ['string']}
Response {'KeyMetadata': {'DeletionDate': 'timestamp',
'KeyState': 'Enabled | Disabled | PendingDeletion'}}
Provides detailed information about the specified customer master key.
Request Syntax
client.describe_key(
KeyId='string',
GrantTokens=[
'string',
]
)
string
[REQUIRED]
A unique identifier for the customer master key. This value can be a globally unique identifier, a fully specified ARN to either an alias or a key, or an alias name prefixed by "alias/".
Key ARN Example - arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
Alias ARN Example - arn:aws:kms:us-east-1:123456789012:alias/MyAliasName
Globally Unique Key ID Example - 12345678-1234-1234-1234-123456789012
Alias Name Example - alias/MyAliasName
list
A list of grant tokens.
For more information, go to Grant Tokens in the AWS Key Management Service Developer Guide .
(string) --
dict
Response Syntax
{
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'ENCRYPT_DECRYPT',
'KeyState': 'Enabled'|'Disabled'|'PendingDeletion',
'DeletionDate': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
KeyMetadata (dict) --
Metadata associated with the key.
AWSAccountId (string) --
The twelve-digit account ID of the AWS account that owns the key.
KeyId (string) --
The globally unique identifier for the key.
Arn (string) --
The Amazon Resource Name (ARN) of the key. For examples, see AWS Key Management Service (AWS KMS) in the Example ARNs section of the AWS General Reference .
CreationDate (datetime) --
The date and time when the key was created.
Enabled (boolean) --
Specifies whether the key is enabled. When KeyState is Enabled this value is true, otherwise it is false.
Description (string) --
The friendly description of the key.
KeyUsage (string) --
The cryptographic operations for which you can use the key. Currently the only allowed value is ENCRYPT_DECRYPT , which means you can use the key for the Encrypt and Decrypt operations.
KeyState (string) --
The state of the customer master key (CMK).
For more information about how key state affects the use of a CMK, go to How Key State Affects the Use of a Customer Master Key in the AWS Key Management Service Developer Guide .
DeletionDate (datetime) --
The date and time after which AWS KMS deletes the customer master key (CMK). This value is present only when KeyState is PendingDeletion , otherwise this value is null.
{'Grants': {'CreationDate': 'timestamp',
'KeyId': 'string',
'Name': 'string',
'Operations': {'DescribeKey'}}}
List the grants for a specified key.
Request Syntax
client.list_grants(
Limit=123,
Marker='string',
KeyId='string'
)
integer
When paginating results, specify the maximum number of items to return in the response. If additional items exist beyond the number you specify, the Truncated element in the response is set to true.
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.
string
Use this parameter only when paginating results and only in a subsequent request after you've received a response with truncated results. Set it to the value of NextMarker from the response you just received.
string
[REQUIRED]
A unique identifier for the customer master key. This value can be a globally unique identifier or the fully specified ARN to a key.
Key ARN Example - arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012
Globally Unique Key ID Example - 12345678-1234-1234-1234-123456789012
dict
Response Syntax
{
'Grants': [
{
'KeyId': 'string',
'GrantId': 'string',
'Name': 'string',
'CreationDate': datetime(2015, 1, 1),
'GranteePrincipal': 'string',
'RetiringPrincipal': 'string',
'IssuingAccount': 'string',
'Operations': [
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant'|'DescribeKey',
],
'Constraints': {
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
}
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
(dict) --
Grants (list) --
A list of grants.
(dict) --
Contains information about an entry in a list of grants.
KeyId (string) --
The unique identifier for the customer master key (CMK) to which the grant applies.
GrantId (string) --
The unique identifier for the grant.
Name (string) --
The friendly name that identifies the grant. If a name was provided in the CreateGrant request, that name is returned. Otherwise this value is null.
CreationDate (datetime) --
The date and time when the grant was created.
GranteePrincipal (string) --
The principal that receives the grant's permissions.
RetiringPrincipal (string) --
The principal that can retire the grant.
IssuingAccount (string) --
The AWS account under which the grant was issued.
Operations (list) --
The list of operations permitted by the grant.
(string) --
Constraints (dict) --
The conditions under which the grant's operations are allowed.
EncryptionContextSubset (dict) --
Contains a list of key-value pairs, a subset of which must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list or is a subset of this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
EncryptionContextEquals (dict) --
Contains a list of key-value pairs that must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
NextMarker (string) --
When Truncated is true, this value is present and contains the value to use for the Marker parameter in a subsequent pagination request.
Truncated (boolean) --
A flag that indicates whether there are more items in the list. If your results were truncated, you can use the Marker parameter to make a subsequent pagination request to retrieve more items in the list.
{'Grants': {'CreationDate': 'timestamp',
'KeyId': 'string',
'Name': 'string',
'Operations': {'DescribeKey'}}}
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.
Request Syntax
client.list_retirable_grants(
Limit=123,
Marker='string',
RetiringPrincipal='string'
)
integer
When paginating results, specify the maximum number of items to return in the response. If additional items exist beyond the number you specify, the Truncated element in the response is set to true.
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.
string
Use this parameter only when paginating results and only in a subsequent request after you've received a response with truncated results. Set it to the value of NextMarker from the response you just received.
string
[REQUIRED]
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, go to AWS Identity and Access Management (IAM) in the Example ARNs section of the Amazon Web Services General Reference .
dict
Response Syntax
{
'Grants': [
{
'KeyId': 'string',
'GrantId': 'string',
'Name': 'string',
'CreationDate': datetime(2015, 1, 1),
'GranteePrincipal': 'string',
'RetiringPrincipal': 'string',
'IssuingAccount': 'string',
'Operations': [
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant'|'DescribeKey',
],
'Constraints': {
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
}
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
(dict) --
Grants (list) --
A list of grants.
(dict) --
Contains information about an entry in a list of grants.
KeyId (string) --
The unique identifier for the customer master key (CMK) to which the grant applies.
GrantId (string) --
The unique identifier for the grant.
Name (string) --
The friendly name that identifies the grant. If a name was provided in the CreateGrant request, that name is returned. Otherwise this value is null.
CreationDate (datetime) --
The date and time when the grant was created.
GranteePrincipal (string) --
The principal that receives the grant's permissions.
RetiringPrincipal (string) --
The principal that can retire the grant.
IssuingAccount (string) --
The AWS account under which the grant was issued.
Operations (list) --
The list of operations permitted by the grant.
(string) --
Constraints (dict) --
The conditions under which the grant's operations are allowed.
EncryptionContextSubset (dict) --
Contains a list of key-value pairs, a subset of which must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list or is a subset of this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
EncryptionContextEquals (dict) --
Contains a list of key-value pairs that must be present in the encryption context of a subsequent operation permitted by the grant. When a subsequent operation permitted by the grant includes an encryption context that matches this list, the grant allows the operation. Otherwise, the operation is not allowed.
(string) --
(string) --
NextMarker (string) --
When Truncated is true, this value is present and contains the value to use for the Marker parameter in a subsequent pagination request.
Truncated (boolean) --
A flag that indicates whether there are more items in the list. If your results were truncated, you can use the Marker parameter to make a subsequent pagination request to retrieve more items in the list.