Note

You are viewing the documentation for an older version of boto (boto2).

Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.

For more information, see the documentation for boto3.

KMS

boto.kms

boto.kms.connect_to_region(region_name, **kw_params)
boto.kms.regions()

Get all available regions for the AWS Key Management Service.

Return type:list
Returns:A list of boto.regioninfo.RegionInfo

boto.kms.layer1

class boto.kms.layer1.KMSConnection(**kwargs)

AWS Key Management Service AWS Key Management Service (KMS) is an encryption and key management web service. This guide describes the KMS actions that you can call programmatically. For general information about KMS, see (need an address here). For the KMS developer guide, see (need address here).

AWS provides SDKs that consist of libraries and sample code for various programming languages and platforms (Java, Ruby, .Net, iOS, Android, etc.). The SDKs provide a convenient way to create programmatic access to KMS and AWS. 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 KMS. However, you can also use the KMS Query API to make to make direct calls to the KMS web service.

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 access key ID and secret key for everyday work with KMS. Instead, use the access key ID and secret access key for an IAM user, or you can use the AWS Security Token Service to generate temporary security credentials that you can use to sign requests.

All KMS operations require `Signature Version 4`_.

Recording API Requests

KMS supports AWS CloudTrail, a service that records 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 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:

APIVersion = '2014-11-01'
DefaultRegionEndpoint = 'kms.us-east-1.amazonaws.com'
DefaultRegionName = 'us-east-1'
ResponseError

alias of boto.exception.JSONResponseError

ServiceName = 'KMS'
TargetPrefix = 'TrentService'
create_alias(alias_name, target_key_id)

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

Parameters:
  • alias_name (string) – String that contains the display name. Aliases that begin with AWS are reserved.
  • target_key_id (string) – An identifier of the key for which you are creating the alias. This value cannot be another alias.
create_grant(key_id, grantee_principal, retiring_principal=None, operations=None, constraints=None, grant_tokens=None)

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. If absent, access to the key is evaluated based on IAM policies attached to the user. By default, grants do not expire. Grants can be listed, retired, or revoked as indicated by the following APIs. Typically, when you are finished using a grant, you retire it. When you want to end a grant immediately, revoke it. For more information about grants, see `Grants`_.

  1. ListGrants
  2. RetireGrant
  3. RevokeGrant
Parameters:
  • key_id (string) – A unique key identifier for a customer master key. This value can be a globally unique identifier, an ARN, or an alias.
  • grantee_principal (string) – Principal given permission by the grant to use the key identified by the keyId parameter.
  • retiring_principal (string) – Principal given permission to retire the grant. For more information, see RetireGrant.
  • operations (list) – List of operations permitted by the grant. This can be any combination of one or more of the following values:
  1. Decrypt
  2. Encrypt
  3. GenerateDataKey
  4. GenerateDataKeyWithoutPlaintext
  5. ReEncryptFrom
  6. ReEncryptTo
  7. CreateGrant
Parameters:
  • constraints (dict) – Specifies the conditions under which the actions specified by the Operations parameter are allowed.
  • grant_tokens (list) – List of grant tokens.
create_key(policy=None, description=None, key_usage=None)

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.

Parameters:
  • policy (string) – Policy to be attached to the key. This is required and delegates back to the account. The key is the root of trust.
  • description (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.
  • key_usage (string) – Specifies the intended use of the key. Currently this defaults to ENCRYPT/DECRYPT, and only symmetric encryption and decryption are supported.
decrypt(ciphertext_blob, encryption_context=None, grant_tokens=None)

Decrypts ciphertext. Ciphertext is plaintext that has been previously encrypted by using the Encrypt function.

Parameters:
  • ciphertext_blob (blob) – Ciphertext including metadata.
  • encryption_context (map) – The encryption context. If this was specified in the Encrypt function, it must be specified here or the decryption operation will fail. For more information, see `Encryption Context`_.
  • grant_tokens (list) – A list of grant tokens that represent grants which can be used to provide long term permissions to perform decryption.
delete_alias(alias_name)

Deletes the specified alias.

Parameters:alias_name (string) – The alias to be deleted.
describe_key(key_id)

Provides detailed information about the specified customer master key.

Parameters:key_id (string) – Unique identifier of the customer master key to be described. This can be an ARN, an alias, or a globally unique identifier.
disable_key(key_id)

Marks a key as disabled, thereby preventing its use.

Parameters:key_id (string) – Unique identifier of the customer master key to be disabled. This can be an ARN, an alias, or a globally unique identifier.
disable_key_rotation(key_id)

Disables rotation of the specified key.

Parameters:key_id (string) – Unique identifier of the customer master key for which rotation is to be disabled. This can be an ARN, an alias, or a globally unique identifier.
enable_key(key_id)

Marks a key as enabled, thereby permitting its use. You can have up to 25 enabled keys at one time.

Parameters:key_id (string) – Unique identifier of the customer master key to be enabled. This can be an ARN, an alias, or a globally unique identifier.
enable_key_rotation(key_id)

Enables rotation of the specified customer master key.

Parameters:key_id (string) – Unique identifier of the customer master key for which rotation is to be enabled. This can be an ARN, an alias, or a globally unique identifier.
encrypt(key_id, plaintext, encryption_context=None, grant_tokens=None)

Encrypts plaintext into ciphertext by using a customer master key.

Parameters:
  • key_id (string) – Unique identifier of the customer master. This can be an ARN, an alias, or the Key ID.
  • plaintext (blob) – Data to be encrypted.
  • encryption_context (map) – Name:value pair that specifies the encryption context to be used for authenticated encryption. For more information, see `Authenticated Encryption`_.
  • grant_tokens (list) – A list of grant tokens that represent grants which can be used to provide long term permissions to perform encryption.
generate_data_key(key_id, encryption_context=None, number_of_bytes=None, key_spec=None, grant_tokens=None)

Generates a secure data key. Data keys are used to encrypt and decrypt data. They are wrapped by customer master keys.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • encryption_context (map) – Name/value pair that contains additional data to be authenticated during the encryption and decryption processes that use the key. This value is logged by AWS CloudTrail to provide context around the data encrypted by the key.
  • number_of_bytes (integer) – Integer that contains the number of bytes to generate. Common values are 128, 256, 512, 1024 and so on. 1024 is the current limit.
  • key_spec (string) – Value that identifies the encryption algorithm and key size to generate a data key for. Currently this can be AES_128 or AES_256.
  • grant_tokens (list) – A list of grant tokens that represent grants which can be used to provide long term permissions to generate a key.
generate_data_key_without_plaintext(key_id, encryption_context=None, key_spec=None, number_of_bytes=None, grant_tokens=None)

Returns a key wrapped by a customer master key without the plaintext copy of that key. To retrieve the plaintext, see GenerateDataKey.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • encryption_context (map) – Name:value pair that contains additional data to be authenticated during the encryption and decryption processes.
  • key_spec (string) – Value that identifies the encryption algorithm and key size. Currently this can be AES_128 or AES_256.
  • number_of_bytes (integer) – Integer that contains the number of bytes to generate. Common values are 128, 256, 512, 1024 and so on.
  • grant_tokens (list) – A list of grant tokens that represent grants which can be used to provide long term permissions to generate a key.
generate_random(number_of_bytes=None)

Generates an unpredictable byte string.

Parameters:number_of_bytes (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.
get_key_policy(key_id, policy_name)

Retrieves a policy attached to the specified key.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • policy_name (string) – String that contains the name of the policy. Currently, this must be “default”. Policy names can be discovered by calling ListKeyPolicies.
get_key_rotation_status(key_id)

Retrieves a Boolean value that indicates whether key rotation is enabled for the specified key.

Parameters:key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
list_aliases(limit=None, marker=None)

Lists all of the key aliases in the account.

Parameters:
  • limit (integer) – Specify this parameter when paginating results to indicate the maximum number of aliases you want in each response. If there are additional aliases beyond the maximum you specify, the Truncated response element will be set to true.
  • marker (string) – Use this parameter when paginating results, and only in a subsequent request after you’ve received a response where the results are truncated. Set it to the value of the NextMarker element in the response you just received.
list_grants(key_id, limit=None, marker=None)

List the grants for a specified key.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • limit (integer) – Specify this parameter only when paginating results to indicate the maximum number of grants you want listed in the response. If there are additional grants beyond the maximum you specify, the Truncated response element will be set to true.
  • marker (string) – Use this parameter only when paginating results, and only in a subsequent request after you’ve received a response where the results are truncated. Set it to the value of the NextMarker in the response you just received.
list_key_policies(key_id, limit=None, marker=None)

Retrieves a list of policies attached to a key.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • limit (integer) – Specify this parameter only when paginating results to indicate the maximum number of policies you want listed in the response. If there are additional policies beyond the maximum you specify, the Truncated response element will be set to true.
  • marker (string) – Use this parameter only when paginating results, and only in a subsequent request after you’ve received a response where the results are truncated. Set it to the value of the NextMarker in the response you just received.
list_keys(limit=None, marker=None)

Lists the customer master keys.

Parameters:
  • limit (integer) – Specify this parameter only when paginating results to indicate the maximum number of keys you want listed in the response. If there are additional keys beyond the maximum you specify, the Truncated response element will be set to true.
  • marker (string) – Use this parameter only when paginating results, and only in a subsequent request after you’ve received a response where the results are truncated. Set it to the value of the NextMarker in the response you just received.
make_request(action, body)

Makes a request to the server, with stock multiple-retry logic.

put_key_policy(key_id, policy_name, policy)

Attaches a policy to the specified key.

Parameters:
  • key_id (string) – Unique identifier of the key. This can be an ARN, an alias, or a globally unique identifier.
  • policy_name (string) – Name of the policy to be attached. Currently, the only supported name is “default”.
  • policy (string) – The policy, in JSON format, to be attached to the key.
re_encrypt(ciphertext_blob, destination_key_id, source_encryption_context=None, destination_encryption_context=None, grant_tokens=None)

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.

Parameters:
  • ciphertext_blob (blob) – Ciphertext of the data to re-encrypt.
  • source_encryption_context (map) – Encryption context used to encrypt and decrypt the data specified in the CiphertextBlob parameter.
  • destination_key_id (string) – Key identifier of the key used to re-encrypt the data.
  • destination_encryption_context (map) – Encryption context to be used when the data is re-encrypted.
  • grant_tokens (list) – Grant tokens that identify the grants that have permissions for the encryption and decryption process.
retire_grant(grant_token)

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.

Parameters:grant_token (string) – Token that identifies the grant to be retired.
revoke_grant(key_id, grant_id)

Revokes a grant. You can revoke a grant to actively deny operations that depend on it.

Parameters:
  • key_id (string) – Unique identifier of the key associated with the grant.
  • grant_id (string) – Identifier of the grant to be revoked.
update_key_description(key_id, description)
Parameters:
  • key_id (string) –
  • description (string) –

boto.kms.exceptions

exception boto.kms.exceptions.AlreadyExistsException(status, reason, body=None, *args)
exception boto.kms.exceptions.DependencyTimeoutException(status, reason, body=None, *args)
exception boto.kms.exceptions.DisabledException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidAliasNameException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidArnException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidCiphertextException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidGrantTokenException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidKeyUsageException(status, reason, body=None, *args)
exception boto.kms.exceptions.InvalidMarkerException(status, reason, body=None, *args)
exception boto.kms.exceptions.KMSInternalException(status, reason, body=None, *args)
exception boto.kms.exceptions.KeyUnavailableException(status, reason, body=None, *args)
exception boto.kms.exceptions.LimitExceededException(status, reason, body=None, *args)
exception boto.kms.exceptions.MalformedPolicyDocumentException(status, reason, body=None, *args)
exception boto.kms.exceptions.NotFoundException(status, reason, body=None, *args)
exception boto.kms.exceptions.UnsupportedOperationException(status, reason, body=None, *args)