Network.AWS.KMS

AWS Key Management Service

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.

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 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 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, or you can 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.
• AWS Security Token Service
• This guide describes how to create and use temporary security credentials.
• Signing AWS API Requests
• 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 APIs

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

• Encrypt
• Decrypt
• GenerateDataKey
• GenerateDataKeyWithoutPlaintext

See: AWS API Reference

Service Configuration

kMS :: Service

API version '2014-11-01' of the Amazon Key Management Service SDK configuration.

Errors

Error matchers are designed for use with the functions provided by Control.Exception.Lens. This allows catching (and rethrowing) service specific errors returned by KMS.

InvalidMarkerException

_InvalidMarkerException :: AsError a => Getting (First ServiceError) a ServiceError

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

KMSInvalidStateException

_KMSInvalidStateException :: AsError a => Getting (First ServiceError) a ServiceError

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 customer master key (CMK), go to How Key State Affects the Use of a Customer Master Key in the AWS Key Management Service Developer Guide.

InvalidKeyUsageException

_InvalidKeyUsageException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because the specified KeySpec parameter is not valid. The currently supported value is ENCRYPT/DECRYPT.

MalformedPolicyDocumentException

_MalformedPolicyDocumentException :: AsError a => Getting (First ServiceError) a ServiceError

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

UnsupportedOperationException

_UnsupportedOperationException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because a specified parameter is not supported.

DisabledException

_DisabledException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because the specified key was marked as disabled.

KeyUnavailableException

_KeyUnavailableException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because the key was not available. The request can be retried.

KMSInternalException

_KMSInternalException :: AsError a => Getting (First ServiceError) a ServiceError

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

NotFoundException

_NotFoundException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because the specified entity or resource could not be found.

InvalidAliasNameException

_InvalidAliasNameException :: AsError a => Getting (First ServiceError) a ServiceError

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

InvalidGrantIdException

_InvalidGrantIdException :: AsError a => Getting (First ServiceError) a ServiceError

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

InvalidGrantTokenException

_InvalidGrantTokenException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because a grant token provided as part of the request is invalid.

InvalidARNException

_InvalidARNException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because a specified ARN was not valid.

DependencyTimeoutException

_DependencyTimeoutException :: AsError a => Getting (First ServiceError) a ServiceError

The system timed out while trying to fulfill the request. The request can be retried.

InvalidCiphertextException

_InvalidCiphertextException :: AsError a => Getting (First ServiceError) a ServiceError

The request was rejected because the specified ciphertext has been corrupted or is otherwise invalid.

AlreadyExistsException

_AlreadyExistsException :: AsError a => Getting (First ServiceError) a ServiceError

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

LimitExceededException

_LimitExceededException :: AsError a => Getting (First ServiceError) a ServiceError

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

Waiters

Waiters poll by repeatedly sending a request until some remote success condition configured by the Wait specification is fulfilled. The Wait specification determines how many attempts should be made, in addition to delay and retry strategies.

Operations

Some AWS operations return results that are incomplete and require subsequent requests in order to obtain the entire result set. The process of sending subsequent requests to continue where a previous request left off is called pagination. For example, the ListObjects operation of Amazon S3 returns up to 1000 objects at a time, and you must send subsequent requests with the appropriate Marker in order to retrieve the next page of results.

Operations that have an AWSPager instance can transparently perform subsequent requests, correctly setting Markers and other request facets to iterate through the entire result set of a truncated API operation. Operations which support this have an additional note in the documentation.

Many operations have the ability to filter results on the server side. See the individual operation parameters for details.

Encrypt

module Network.AWS.KMS.Encrypt

ListGrants

module Network.AWS.KMS.ListGrants

DisableKeyRotation

module Network.AWS.KMS.DisableKeyRotation

GenerateDataKeyWithoutPlaintext

module Network.AWS.KMS.GenerateDataKeyWithoutPlaintext

EnableKeyRotation

module Network.AWS.KMS.EnableKeyRotation

CreateAlias

module Network.AWS.KMS.CreateAlias

CreateGrant

module Network.AWS.KMS.CreateGrant

ListAliases

module Network.AWS.KMS.ListAliases

ListRetirableGrants

module Network.AWS.KMS.ListRetirableGrants

GenerateRandom

module Network.AWS.KMS.GenerateRandom

CreateKey

module Network.AWS.KMS.CreateKey

DisableKey

module Network.AWS.KMS.DisableKey

RetireGrant

module Network.AWS.KMS.RetireGrant

ListKeys

module Network.AWS.KMS.ListKeys

GetKeyRotationStatus

module Network.AWS.KMS.GetKeyRotationStatus

GenerateDataKey

module Network.AWS.KMS.GenerateDataKey

DeleteAlias

module Network.AWS.KMS.DeleteAlias

UpdateAlias

module Network.AWS.KMS.UpdateAlias

DescribeKey

module Network.AWS.KMS.DescribeKey

CancelKeyDeletion

module Network.AWS.KMS.CancelKeyDeletion

Decrypt

module Network.AWS.KMS.Decrypt

UpdateKeyDescription

module Network.AWS.KMS.UpdateKeyDescription

ReEncrypt

module Network.AWS.KMS.ReEncrypt

ListKeyPolicies

module Network.AWS.KMS.ListKeyPolicies

ScheduleKeyDeletion

module Network.AWS.KMS.ScheduleKeyDeletion

PutKeyPolicy

module Network.AWS.KMS.PutKeyPolicy

EnableKey

module Network.AWS.KMS.EnableKey

RevokeGrant

module Network.AWS.KMS.RevokeGrant

GetKeyPolicy

module Network.AWS.KMS.GetKeyPolicy

Types

DataKeySpec

data DataKeySpec

Constructors

AES128

AES256

Instances

Enum DataKeySpec

Eq DataKeySpec

Data DataKeySpec

Ord DataKeySpec

Read DataKeySpec

Show DataKeySpec

Generic DataKeySpec

ToJSON DataKeySpec

Hashable DataKeySpec

ToHeader DataKeySpec

ToQuery DataKeySpec

ToByteString DataKeySpec

FromText DataKeySpec

ToText DataKeySpec

type Rep DataKeySpec

GrantOperation

data GrantOperation

Constructors

CreateGrant

Decrypt

DescribeKey

Encrypt

GenerateDataKey

GenerateDataKeyWithoutPlaintext

ReEncryptFrom

ReEncryptTo

RetireGrant

Instances

Enum GrantOperation

Eq GrantOperation

Data GrantOperation

Ord GrantOperation

Read GrantOperation

Show GrantOperation

Generic GrantOperation

ToJSON GrantOperation

FromJSON GrantOperation

Hashable GrantOperation

ToHeader GrantOperation

ToQuery GrantOperation

ToByteString GrantOperation

FromText GrantOperation

ToText GrantOperation

type Rep GrantOperation

KeyState

data KeyState

Constructors

Disabled

Enabled

PendingDeletion

Instances

Enum KeyState

Eq KeyState

Data KeyState

Ord KeyState

Read KeyState

Show KeyState

Generic KeyState

FromJSON KeyState

Hashable KeyState

ToHeader KeyState

ToQuery KeyState

ToByteString KeyState

FromText KeyState

ToText KeyState

type Rep KeyState

KeyUsageType

data KeyUsageType

Constructors

EncryptDecrypt

Instances

Enum KeyUsageType

Eq KeyUsageType

Data KeyUsageType

Ord KeyUsageType

Read KeyUsageType

Show KeyUsageType

Generic KeyUsageType

ToJSON KeyUsageType

FromJSON KeyUsageType

Hashable KeyUsageType

ToHeader KeyUsageType

ToQuery KeyUsageType

ToByteString KeyUsageType

FromText KeyUsageType

ToText KeyUsageType

type Rep KeyUsageType

AliasListEntry

data AliasListEntry

Contains information about an alias.

See: aliasListEntry smart constructor.

Instances

Eq AliasListEntry

Data AliasListEntry

Read AliasListEntry

Show AliasListEntry

Generic AliasListEntry

FromJSON AliasListEntry

type Rep AliasListEntry

aliasListEntry :: AliasListEntry

Creates a value of AliasListEntry with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• aleTargetKeyId
• aleAliasName
• aleAliasARN

aleTargetKeyId :: Lens' AliasListEntry (Maybe Text)

String that contains the key identifier pointed to by the alias.

aleAliasName :: Lens' AliasListEntry (Maybe Text)

String that contains the alias.

aleAliasARN :: Lens' AliasListEntry (Maybe Text)

String that contains the key ARN.

GrantConstraints

data GrantConstraints

A structure for specifying the conditions under which the operations permitted by the grant are allowed.

You can use this structure to allow the operations permitted by the grant only when a specified encryption context is present. For more information about encryption context, see Encryption Context in the AWS Key Management Service Developer Guide.

See: grantConstraints smart constructor.

Instances

Eq GrantConstraints

Data GrantConstraints

Read GrantConstraints

Show GrantConstraints

Generic GrantConstraints

ToJSON GrantConstraints

FromJSON GrantConstraints

type Rep GrantConstraints

grantConstraints :: GrantConstraints

Creates a value of GrantConstraints with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• gcEncryptionContextEquals
• gcEncryptionContextSubset

gcEncryptionContextEquals :: Lens' GrantConstraints (HashMap Text Text)

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.

gcEncryptionContextSubset :: Lens' GrantConstraints (HashMap Text Text)

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.

GrantListEntry

data GrantListEntry

Contains information about an entry in a list of grants.

See: grantListEntry smart constructor.

Instances

Eq GrantListEntry

Data GrantListEntry

Read GrantListEntry

Show GrantListEntry

Generic GrantListEntry

FromJSON GrantListEntry

type Rep GrantListEntry

grantListEntry :: GrantListEntry

Creates a value of GrantListEntry with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• gleKeyId
• gleRetiringPrincipal
• gleIssuingAccount
• gleGrantId
• gleConstraints
• gleGranteePrincipal
• gleName
• gleCreationDate
• gleOperations

gleKeyId :: Lens' GrantListEntry (Maybe Text)

The unique identifier for the customer master key (CMK) to which the grant applies.

gleRetiringPrincipal :: Lens' GrantListEntry (Maybe Text)

The principal that can retire the grant.

gleIssuingAccount :: Lens' GrantListEntry (Maybe Text)

The AWS account under which the grant was issued.

gleGrantId :: Lens' GrantListEntry (Maybe Text)

The unique identifier for the grant.

gleConstraints :: Lens' GrantListEntry (Maybe GrantConstraints)

The conditions under which the grant's operations are allowed.

gleGranteePrincipal :: Lens' GrantListEntry (Maybe Text)

The principal that receives the grant's permissions.

gleName :: Lens' GrantListEntry (Maybe Text)

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.

gleCreationDate :: Lens' GrantListEntry (Maybe UTCTime)

The date and time when the grant was created.

gleOperations :: Lens' GrantListEntry [GrantOperation]

The list of operations permitted by the grant.

KeyListEntry

data KeyListEntry

Contains information about each entry in the key list.

See: keyListEntry smart constructor.

Instances

Eq KeyListEntry

Data KeyListEntry

Read KeyListEntry

Show KeyListEntry

Generic KeyListEntry

FromJSON KeyListEntry

type Rep KeyListEntry

keyListEntry :: KeyListEntry

Creates a value of KeyListEntry with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• kleKeyId
• kleKeyARN

kleKeyId :: Lens' KeyListEntry (Maybe Text)

Unique identifier of the key.

kleKeyARN :: Lens' KeyListEntry (Maybe Text)

ARN of the key.

KeyMetadata

data KeyMetadata

Contains metadata about a customer master key (CMK).

This data type is used as a response element for the CreateKey and DescribeKey operations.

See: keyMetadata smart constructor.

Instances

Eq KeyMetadata

Data KeyMetadata

Read KeyMetadata

Show KeyMetadata

Generic KeyMetadata

FromJSON KeyMetadata

type Rep KeyMetadata

keyMetadata

Arguments

:: Text

kmKeyId

-> KeyMetadata

Creates a value of KeyMetadata with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• kmEnabled
• kmARN
• kmKeyState
• kmAWSAccountId
• kmKeyUsage
• kmCreationDate
• kmDeletionDate
• kmDescription
• kmKeyId

kmEnabled :: Lens' KeyMetadata (Maybe Bool)

Specifies whether the key is enabled. When KeyState is Enabled this value is true, otherwise it is false.

kmARN :: Lens' KeyMetadata (Maybe Text)

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.

kmKeyState :: Lens' KeyMetadata (Maybe KeyState)

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.

kmAWSAccountId :: Lens' KeyMetadata (Maybe Text)

The twelve-digit account ID of the AWS account that owns the key.

kmKeyUsage :: Lens' KeyMetadata (Maybe KeyUsageType)

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.

kmCreationDate :: Lens' KeyMetadata (Maybe UTCTime)

The date and time when the key was created.

kmDeletionDate :: Lens' KeyMetadata (Maybe UTCTime)

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.

kmDescription :: Lens' KeyMetadata (Maybe Text)

The friendly description of the key.

kmKeyId :: Lens' KeyMetadata Text

The globally unique identifier for the key.

ListGrantsResponse

data ListGrantsResponse

See: listGrantsResponse smart constructor.

Instances

Eq ListGrantsResponse

Data ListGrantsResponse

Read ListGrantsResponse

Show ListGrantsResponse

Generic ListGrantsResponse

FromJSON ListGrantsResponse

type Rep ListGrantsResponse

listGrantsResponse :: ListGrantsResponse

Creates a value of ListGrantsResponse with the minimum fields required to make a request.

Use one of the following lenses to modify other fields as desired:

• lgTruncated
• lgGrants
• lgNextMarker

lgTruncated :: Lens' ListGrantsResponse (Maybe Bool)

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.

lgGrants :: Lens' ListGrantsResponse [GrantListEntry]

A list of grants.

lgNextMarker :: Lens' ListGrantsResponse (Maybe Text)

When Truncated is true, this value is present and contains the value to use for the Marker parameter in a subsequent pagination request.