KMS.
Client
¶A low-level client representing AWS Key Management Service (KMS):
import boto3
client = boto3.client('kms')
These are the available methods:
can_paginate()
create_alias()
create_grant()
create_key()
decrypt()
delete_alias()
describe_key()
disable_key()
disable_key_rotation()
enable_key()
enable_key_rotation()
encrypt()
generate_data_key()
generate_data_key_without_plaintext()
generate_presigned_url()
generate_random()
get_key_policy()
get_key_rotation_status()
get_paginator()
get_waiter()
list_aliases()
list_grants()
list_key_policies()
list_keys()
put_key_policy()
re_encrypt()
retire_grant()
revoke_grant()
update_alias()
update_key_description()
can_paginate
(operation_name)¶Check if an operation can be paginated.
Parameters: | operation_name (string) -- The operation name. This is the same name
as the method name on the client. For example, if the
method name is create_foo , and you'd normally invoke the
operation as client.create_foo(**kwargs) , if the
create_foo operation can be paginated, you can use the
call client.get_paginator("create_foo") . |
---|---|
Returns: | True if the operation can be paginated,
False otherwise. |
create_alias
(**kwargs)¶Creates a display name for a customer master key. An alias can be used to identify a key and should be unique. The console enforces a one-to-one mapping between the alias and a key. An alias name can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). An alias must start with the word "alias" followed by a forward slash (alias/). An alias that begins with "aws" after the forward slash (alias/aws...) is reserved by Amazon Web Services (AWS).
To associate an alias with a different key, call UpdateAlias .
Note that you cannot create or update an alias that represents a key in another account.
Request Syntax
response = client.create_alias(
AliasName='string',
TargetKeyId='string'
)
Parameters: |
|
---|---|
Returns: | None |
create_grant
(**kwargs)¶Adds a grant to a key to specify who can access the key and under what conditions. Grants are alternate permission mechanisms to key policies. For more information about grants, see Grants in the developer guide. If a grant is absent, access to the key is evaluated based on IAM policies attached to the user.
Request Syntax
response = client.create_grant(
KeyId='string',
GranteePrincipal='string',
RetiringPrincipal='string',
Operations=[
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant',
],
Constraints={
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
},
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'GrantToken': 'string',
'GrantId': 'string'
}
Response Structure
|
create_key
(**kwargs)¶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
response = client.create_key(
Policy='string',
Description='string',
KeyUsage='ENCRYPT_DECRYPT'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'ENCRYPT_DECRYPT'
}
}
Response Structure
|
decrypt
(**kwargs)¶Decrypts ciphertext. Ciphertext is plaintext that has been previously encrypted by using any of the following functions:
Note that if a caller has been granted access permissions to all keys (through, for example, IAM user policies that grant Decrypt
permission on all resources), then ciphertext encrypted by using keys in other accounts where the key grants access to the caller can be decrypted. To remedy this, we recommend that you do not grant Decrypt
access in an IAM user policy. Instead grant Decrypt
access only in key policies. If you must grant Decrypt
access in an IAM user policy, you should scope the resource to specific keys or to specific trusted accounts.
Request Syntax
response = client.decrypt(
CiphertextBlob=b'bytes',
EncryptionContext={
'string': 'string'
},
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'KeyId': 'string',
'Plaintext': b'bytes'
}
Response Structure
|
delete_alias
(**kwargs)¶Deletes the specified alias. To associate an alias with a different key, call UpdateAlias .
Request Syntax
response = client.delete_alias(
AliasName='string'
)
Parameters: | AliasName (string) -- [REQUIRED] The alias to be deleted. The name must start with the word "alias" followed by a forward slash (alias/). Aliases that begin with "alias/AWS" are reserved. |
---|---|
Returns: | None |
describe_key
(**kwargs)¶Provides detailed information about the specified customer master key.
Request Syntax
response = client.describe_key(
KeyId='string'
)
Parameters: | KeyId (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/".
|
---|---|
Return type: | dict |
Returns: | Response Syntax{
'KeyMetadata': {
'AWSAccountId': 'string',
'KeyId': 'string',
'Arn': 'string',
'CreationDate': datetime(2015, 1, 1),
'Enabled': True|False,
'Description': 'string',
'KeyUsage': 'ENCRYPT_DECRYPT'
}
}
Response Structure
|
disable_key
(**kwargs)¶Marks a key as disabled, thereby preventing its use.
Request Syntax
response = client.disable_key(
KeyId='string'
)
Parameters: | KeyId (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.
|
---|---|
Returns: | None |
disable_key_rotation
(**kwargs)¶Disables rotation of the specified key.
Request Syntax
response = client.disable_key_rotation(
KeyId='string'
)
Parameters: | KeyId (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.
|
---|---|
Returns: | None |
enable_key
(**kwargs)¶Marks a key as enabled, thereby permitting its use. You can have up to 25 enabled keys at one time.
Request Syntax
response = client.enable_key(
KeyId='string'
)
Parameters: | KeyId (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.
|
---|---|
Returns: | None |
enable_key_rotation
(**kwargs)¶Enables rotation of the specified customer master key.
Request Syntax
response = client.enable_key_rotation(
KeyId='string'
)
Parameters: | KeyId (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.
|
---|---|
Returns: | None |
encrypt
(**kwargs)¶Encrypts plaintext into ciphertext by using a customer master key. The Encrypt
function has two primary use cases:
Unless you are moving encrypted data from one region to another, you don't use this function to encrypt a generated data key within a region. You retrieve data keys already encrypted by calling the GenerateDataKey or GenerateDataKeyWithoutPlaintext function. Data keys don't need to be encrypted again by calling Encrypt
.
If you want to encrypt data locally in your application, you can use the GenerateDataKey
function to return a plaintext data encryption key and a copy of the key encrypted under the customer master key (CMK) of your choosing.
Request Syntax
response = client.encrypt(
KeyId='string',
Plaintext=b'bytes',
EncryptionContext={
'string': 'string'
},
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'CiphertextBlob': b'bytes',
'KeyId': 'string'
}
Response Structure
|
generate_data_key
(**kwargs)¶Generates a data key that you can use in your application to locally encrypt data. This call returns a plaintext version of the key in the Plaintext
field of the response object and an encrypted copy of the key in the CiphertextBlob
field. The key is encrypted by using the master key specified by the KeyId
field. To decrypt the encrypted key, pass it to the Decrypt
API.
We recommend that you use the following pattern to locally encrypt data: call the GenerateDataKey
API, use the key returned in the Plaintext
response field to locally encrypt data, and then erase the plaintext data key from memory. Store the encrypted data key (contained in the CiphertextBlob
field) alongside of the locally encrypted data.
Note
You should not call the Encrypt
function to re-encrypt your data keys within a region. GenerateDataKey
always returns the data key encrypted and tied to the customer master key that will be used to decrypt it. There is no need to decrypt it twice.
If you decide to use the optional EncryptionContext
parameter, you must also store the context in full or at least store enough information along with the encrypted data to be able to reconstruct the context when submitting the ciphertext to the Decrypt
API. It is a good practice to choose a context that you can reconstruct on the fly to better secure the ciphertext. For more information about how this parameter is used, see Encryption Context .
To decrypt data, pass the encrypted data key to the Decrypt
API. Decrypt
uses the associated master key to decrypt the encrypted data key and returns it as plaintext. Use the plaintext data key to locally decrypt your data and then erase the key from memory. You must specify the encryption context, if any, that you specified when you generated the key. The encryption context is logged by CloudTrail, and you can use this log to help track the use of particular data.
Request Syntax
response = client.generate_data_key(
KeyId='string',
EncryptionContext={
'string': 'string'
},
NumberOfBytes=123,
KeySpec='AES_256'|'AES_128',
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'CiphertextBlob': b'bytes',
'Plaintext': b'bytes',
'KeyId': 'string'
}
Response Structure
|
generate_data_key_without_plaintext
(**kwargs)¶Returns a data key encrypted by a customer master key without the plaintext copy of that key. Otherwise, this API functions exactly like GenerateDataKey . You can use this API to, for example, satisfy an audit requirement that an encrypted key be made available without exposing the plaintext copy of that key.
Request Syntax
response = client.generate_data_key_without_plaintext(
KeyId='string',
EncryptionContext={
'string': 'string'
},
KeySpec='AES_256'|'AES_128',
NumberOfBytes=123,
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'CiphertextBlob': b'bytes',
'KeyId': 'string'
}
Response Structure
|
generate_presigned_url
(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)¶Generate a presigned url given a client, its method, and arguments
Parameters: |
|
---|---|
Returns: | The presigned url |
generate_random
(**kwargs)¶Generates an unpredictable byte string.
Request Syntax
response = client.generate_random(
NumberOfBytes=123
)
Parameters: | NumberOfBytes (integer) -- Integer that contains the number of bytes to generate. Common values are 128, 256, 512, 1024 and so on. The current limit is 1024 bytes. |
---|---|
Return type: | dict |
Returns: | Response Syntax{
'Plaintext': b'bytes'
}
Response Structure
|
get_key_policy
(**kwargs)¶Retrieves a policy attached to the specified key.
Request Syntax
response = client.get_key_policy(
KeyId='string',
PolicyName='string'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'Policy': 'string'
}
Response Structure
|
get_key_rotation_status
(**kwargs)¶Retrieves a Boolean value that indicates whether key rotation is enabled for the specified key.
Request Syntax
response = client.get_key_rotation_status(
KeyId='string'
)
Parameters: | KeyId (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.
|
---|---|
Return type: | dict |
Returns: | Response Syntax{
'KeyRotationEnabled': True|False
}
Response Structure
|
get_paginator
(operation_name)¶Create a paginator for an operation.
Parameters: | operation_name (string) -- The operation name. This is the same name
as the method name on the client. For example, if the
method name is create_foo , and you'd normally invoke the
operation as client.create_foo(**kwargs) , if the
create_foo operation can be paginated, you can use the
call client.get_paginator("create_foo") . |
---|---|
Raises OperationNotPageableError: | |
Raised if the operation is not
pageable. You can use the client.can_paginate method to
check if an operation is pageable. |
|
Return type: | L{botocore.paginate.Paginator} |
Returns: | A paginator object. |
get_waiter
(waiter_name)¶list_aliases
(**kwargs)¶Lists all of the key aliases in the account.
Request Syntax
response = client.list_aliases(
Limit=123,
Marker='string'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'Aliases': [
{
'AliasName': 'string',
'AliasArn': 'string',
'TargetKeyId': 'string'
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
|
list_grants
(**kwargs)¶List the grants for a specified key.
Request Syntax
response = client.list_grants(
KeyId='string',
Limit=123,
Marker='string'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'Grants': [
{
'GrantId': 'string',
'GranteePrincipal': 'string',
'RetiringPrincipal': 'string',
'IssuingAccount': 'string',
'Operations': [
'Decrypt'|'Encrypt'|'GenerateDataKey'|'GenerateDataKeyWithoutPlaintext'|'ReEncryptFrom'|'ReEncryptTo'|'CreateGrant'|'RetireGrant',
],
'Constraints': {
'EncryptionContextSubset': {
'string': 'string'
},
'EncryptionContextEquals': {
'string': 'string'
}
}
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
|
list_key_policies
(**kwargs)¶Retrieves a list of policies attached to a key.
Request Syntax
response = client.list_key_policies(
KeyId='string',
Limit=123,
Marker='string'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'PolicyNames': [
'string',
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
|
list_keys
(**kwargs)¶Lists the customer master keys.
Request Syntax
response = client.list_keys(
Limit=123,
Marker='string'
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'Keys': [
{
'KeyId': 'string',
'KeyArn': 'string'
},
],
'NextMarker': 'string',
'Truncated': True|False
}
Response Structure
|
put_key_policy
(**kwargs)¶Attaches a policy to the specified key.
Request Syntax
response = client.put_key_policy(
KeyId='string',
PolicyName='string',
Policy='string'
)
Parameters: |
|
---|---|
Returns: | None |
re_encrypt
(**kwargs)¶Encrypts data on the server side with a new customer master key without exposing the plaintext of the data on the client side. The data is first decrypted and then encrypted. This operation can also be used to change the encryption context of a ciphertext.
Unlike other actions, ReEncrypt
is authorized twice - once as ReEncryptFrom
on the source key and once as ReEncryptTo
on the destination key. We therefore recommend that you include the "action":"kms:ReEncrypt*"
statement in your key policies to permit re-encryption from or to the key. The statement is included automatically when you authorize use of the key through the console but must be included manually when you set a policy by using the PutKeyPolicy function.
Request Syntax
response = client.re_encrypt(
CiphertextBlob=b'bytes',
SourceEncryptionContext={
'string': 'string'
},
DestinationKeyId='string',
DestinationEncryptionContext={
'string': 'string'
},
GrantTokens=[
'string',
]
)
Parameters: |
|
---|---|
Return type: | dict |
Returns: | Response Syntax {
'CiphertextBlob': b'bytes',
'SourceKeyId': 'string',
'KeyId': 'string'
}
Response Structure
|
retire_grant
(**kwargs)¶Retires a grant. You can retire a grant when you're done using it to clean up. You should revoke a grant when you intend to actively deny operations that depend on it. The following are permitted to call this API:
RetiringPrincipal
, if presentGranteePrincipal
, if RetireGrant
is a grantee operationThe grant to retire must be identified by its grant token or by a combination of the key ARN and the grant ID. A grant token is a unique variable-length base64-encoded string. A grant ID is a 64 character unique identifier of a grant. Both are returned by the CreateGrant
function.
Request Syntax
response = client.retire_grant(
GrantToken='string',
KeyId='string',
GrantId='string'
)
Parameters: |
|
---|---|
Returns: | None |
revoke_grant
(**kwargs)¶Revokes a grant. You can revoke a grant to actively deny operations that depend on it.
Request Syntax
response = client.revoke_grant(
KeyId='string',
GrantId='string'
)
Parameters: |
|
---|---|
Returns: | None |
update_alias
(**kwargs)¶Updates an alias to associate it with a different key.
An alias name can contain only alphanumeric characters, forward slashes (/), underscores (_), and dashes (-). An alias must start with the word "alias" followed by a forward slash (alias/). An alias that begins with "aws" after the forward slash (alias/aws...) is reserved by Amazon Web Services (AWS).
An alias is not a property of a key. Therefore, an alias can be associated with and disassociated from an existing key without changing the properties of the key.
Note that you cannot create or update an alias that represents a key in another account.
Request Syntax
response = client.update_alias(
AliasName='string',
TargetKeyId='string'
)
Parameters: |
|
---|---|
Returns: | None |
update_key_description
(**kwargs)¶Updates the description of a key.
Request Syntax
response = client.update_key_description(
KeyId='string',
Description='string'
)
Parameters: |
|
---|---|
Returns: | None |