General: AWS Encryption SDK
General: AWS Encryption SDK
Asymmetric keys are currently only available in Northern Virginia, Oregon, Sydney, Ireland, and
Tokyo.
• Create symmetric and asymmetric keys where the key material is only ever used within the service
• Create symmetric keys where the key material is generated and used within a custom key store
under your control*
• Import your own symmetric key material for use within the service
• Create both symmetric and asymmetric data key pairs for local use within your applications
• Choose to have keys that were generated by the service to be automatically rotated on an annual
basis
* The use of custom key stores requires CloudHSM resources to be available in your account.
Once you have created a CMK using any of the three supported options, you can submit data
directly to the service AWS KMS to be signed, verified, encrypted, or decrypted using these CMK.
You set usage policies on these keys that determine which users can perform which actions under
which conditions.
AWS services and client-side toolkits that integrate with AWS KMS use a method known as
envelope encryption to protect your data. Under this method, AWS KMS generates data keys which
are used to encrypt data locally in the AWS service or your application. The data keys are
themselves encrypted under a CMK you define. Data keys are not retained or managed by AWS
KMS. AWS services encrypt your data and store an encrypted copy of the data key along with the
encrypted data. When a service needs to decrypt your data, it requests AWS KMS to decrypt the
data key using your CMK. If the user requesting data from the AWS service is authorized to decrypt
under your CMK, the AWS service will receive the decrypted data key from AWS KMS. The AWS
service then decrypts your data and returns it in plaintext. All requests to use your CMKs are logged
in AWS CloudTrail so you can understand who used which key under what context and when they
used it.
Q: Why use envelope encryption? Why not just send data to AWS KMS to encrypt directly?
While AWS KMS does support sending data up to 4 KB to be encrypted directly, envelope
encryption can offer significant performance benefits. When you encrypt data directly with AWS KMS
it must be transferred over the network. Envelope encryption reduces the network load since only
the request and delivery of the much smaller data key go over the network. The data key is used
locally in your application or encrypting AWS service, avoiding the need to send the entire block of
data to AWS KMS and suffer network latency.
Q: What’s the difference between a CMK I create and CMKs created automatically for me by other
AWS services?
You have the option of selecting a specific CMK to use when you want an AWS service to encrypt
data on your behalf. These are known as customer managed CMKs and you have full control over
them. You define the access control and usage policy for each key and you can grant permissions to
other accounts and services to use them. If you don’t specify a CMK, the service in question will
create an AWS managed CMK the first time you try to create an encrypted resource within that
service. AWS will manage the policies associated with AWS managed CMKs on your behalf. You
can track AWS managed keys in your account and all usage is logged in AWS CloudTrail, but you
have no direct control over the keys themselves.
Q: How is the key that I import into AWS KMS protected in transit?
During the import process, your key must be wrapped by an AWS KMS-provided public key using
one of two RSA PKCS#1 schemes. This ensures that your encrypted key can only be decrypted by
AWS KMS.
Q: What’s the difference between a key I import and a key I generate in AWS KMS?
There are two main differences:
1. You are responsible for maintaining a copy of your imported keys in your key management
infrastructure so that you can re-import them at any time. AWS, however, ensures the availability,
security, and durability of keys generated by AWS KMS on your behalf until you schedule the keys
for deletion.
2. You may set an expiration period for an imported key. AWS KMS will automatically delete the key
material after the expiration period. You may also delete imported key material on demand. In both
cases the key material itself is deleted but the CMK reference in AWS KMS and associated
metadata are retained so that the key material can be re-imported in the future. Keys generated by
AWS KMS do not have an expiration time and cannot be deleted immediately; there is a mandatory
7 to 30 day wait period. All customer managed CMKs, irrespective of whether the key material was
imported, can be manually disabled or scheduled for deletion. In this case the CMK itself is deleted,
not just the underlying key material.
If you manually rotate your imported or custom key store keys, you may have to re-encrypt your data
depending on whether you decide to keep old versions of keys available.
For customer master keys with imported key material, you can delete the key material without
deleting the customer master key id or metadata in two ways. First, you can delete your imported
key material on demand without a waiting period. Second, at the time of importing the key material
into the customer master key, you may define an expiration time for how long AWS can use your
imported key material before it is deleted. You can re-import your key material into the customer
master key if you need to use it again.
Q: What should I do if my imported key material has expired or I accidentally deleted it?
You can re-import your copy of the key material with a valid expiration period to AWS KMS under the
original customer master key so it can be used.
Q: Can I be alerted that I need to re-import the key?
Yes. Once you import your key to a customer master key, you will receive an Amazon CloudWatch
Metric every few minutes that counts down the time to expiration of the imported key. You will also
receive an Amazon CloudWatch Event once the imported key under your customer master key
expires. You can build logic that acts on these metrics or events and automatically re-imports the
key with a new expiration period to avoid an availability risk.
Q: Can I use AWS KMS to help manage encryption of data outside of AWS cloud services?
Yes. AWS KMS is supported in AWS SDKs, AWS Encryption SDK, the Amazon DynamoDB Client-
side Encryption, and the Amazon S3 Encryption Client to facilitate encryption of data within your own
applications wherever they run. Visit the AWS Crypto Tools and Developing on AWS website for
more information.
Q: Can data keys and data key pairs be exported out of the HSMs in plain text?
Yes. The symmetric data keys can be exported using either the “GenerateDataKey” API or the
“GenerateDataKeyWithoutPlaintext” API. And the private and public portion of asymmetric data key
pairs can both be exported out of AWS KMS using either the “GenerateDataKeyPair” API or the
“GenerateDataKeypairWithoutPlaintext” API.
Q: How are data keys and data key pairs protected for storage outside the service?
The symmetric data key or the private portion of the asymmetric data key is encrypted under the
symmetric CMK you define when you request AWS KMS to generate the data key.
Q: What is the size limit for data sent to AWS KMS for asymmetric operations?
The size limit is 4KB. If you want to digitally sign data larger than 4KB, you have the option to create
a message digest of the data and send it to AWS KMS. The digital signature is created over the
digest of the data and returned. You specify whether you are sending the full message or a message
digest as a parameter in the Sign API request. Any data submitted to the Encrypt, Decrypt, or Re-
Encrypt APIs that require use of asymmetric operations must also be less than 4KB.
Q: Can a single asymmetric CMK be used for both encryption and signing?
No. When creating a CMK, you must specify whether the key can be used for decrypt or sign
operations. An RSA key type can be used for signing or encryption operations, but not both. Elliptic
curve key types can only be used for signing operations.
Q: Do asymmetric keys work with AWS KMS custom key stores or the Import Key feature?
No. You cannot use the custom key store functionality with asymmetric keys nor can you import
asymmetric keys into AWS KMS.
Q: Can I use asymmetric CMKs for digital signing applications that require digital certificates?
Not directly. AWS KMS doesn’t store or associate digital certificates with asymmetric CMKs it
creates. You could choose to have a certificate authority such as ACM PCA issue a certificate for the
public portion of your asymmetric CMK. This will allow the entities that are consuming your public
key to verify that the public key indeed belongs to you.
Q: For what use scenarios should I use ACM Private Certificate Authority vs. AWS KMS?
The primary reason to use the ACM Private Certificate Authority (CA) service is to provide a public
key infrastructure (PKI) for the purpose of identifying entities and securing network connections. PKI
provides processes and mechanisms, primarily using X.509 certificates, to put structure around
public key cryptographic operations. Certificates provide an association between an identity and a
public key. The certification process in which a certificate authority issues a certificate allows the
trusted certificate authority to assert the identity of another entity by signing a certificate. PKI
provides identity, distributed trust, key lifecycle management, and certificate status vended through
revocation. These functions add important processes and infrastructure to the underlying
asymmetric cryptographic keys and algorithms provided by AWS KMS.
ACM Private CA allows you to issue certificates to identify web and application servers, service
meshes, VPN users, internal API endpoints, and IoT devices. Certificates let you establish the
identity of these resources and create encrypted TLS/SSL communications channels. If you are
considering using asymmetric keys for TLS termination on web or application servers, Elastic Load
Balancers, API Gateway endpoints, EC2 instances or containers, you should consider using ACM
Private CA for issuing certificates and providing a PKI infrastructure.
In contrast, AWS KMS lets you generate, manage, and use asymmetric keys for digital signing
and/or encryption operations that don’t require certificates. While certificates can enable verification
of sender and recipient identity between untrusted parties, the kind of raw asymmetric operations
offered by AWS KMS are typically useful when you have other mechanisms to prove identity or don’t
need to prove it at all to get the security benefit you desire.
Q: Can I use my applications’ cryptographic API providers such as OpenSSL, JCE, Bouncy Castle,
or CNG with AWS KMS?
There is no native integration offered by AWS KMS for any other cryptographic API providers. You
must use AWS KMS APIs directly or through the AWS SDK to integrate signing and encryption
capabilities into your applications.
Additional guidance for deciding if using a custom key store it is right for you can be found in
this blog.
Q: Can I use a custom key store to store an AWS managed customer master key?
No, only customer managed CMKs can be stored and managed in an AWS KMS custom key store.
AWS managed CMKs that are created on your behalf by other AWS services to encrypt your data
are always generated and stored in the AWS KMS default key store.
Q: What impact does using a custom key store have on availability of keys?
The use of an AWS KMS custom key store makes you responsible for ensuring that your keys are
available for use by AWS KMS. Errors in configuration of CloudHSM and accidental deletion of key
material within an AWS CloudHSM cluster could impact availability. The number of HSMs you use
and your choice of availability zones (AZs) can also affect the resilience of your cluster. As in any
key management system, it is important to understand how the availability of keys can impact the
recovery of your encrypted data.
Q: What are the performance limitations associated with a custom key store?
The rate at which keys stored in an AWS KMS custom key store can be used via AWS KMS API
calls are lower than for keys stored in the default AWS KMS key store. See the AWS KMS
Developer Guide for the current performance limits.
Q: What are the costs associated with using a custom key store?
AWS KMS prices are unaffected by the use of a custom key store. However, each custom key store
does require that your AWS CloudHSM cluster contains at least two HSMs. These HSMs are
charged at the standard AWS CloudHSM prices. There are no additional charges for using a custom
key store.
Q: What additional skills and resources are required to configure a custom key stores?
AWS KMS users that wish to use a custom key store will need to set up an AWS CloudHSM
cluster, add HSMs, manage HSMs users and potentially restore HSMs from backup. These are
security sensitive tasks and you should ensure that you have the appropriate resources and
organizational controls in place.
Q: Can I migrate keys between the default AWS KMS keys store and a custom key store?
No, the ability to migrate keys between the different types of AWS KMS key store is not currently
supported. All keys must be created in the key store in which they will be used, except in situations
where you import you own key material into the default AWS KMS key store.
Billing
Q: How will I be charged and billed for my use of AWS KMS?
With AWS KMS, you pay only for what you use, there is no minimum fee. There are no set-up fees
or commitments to begin using the service. At the end of the month, your credit card will
automatically be charged for that month’s usage.
You are charged for all CMKs you create and for API requests made to the service each month
above a free tier.
For current pricing information, please visit the AWS KMS pricing page.
*API requests involving asymmetric CMKs and API requests to the GenerateDataKeyPair and
GenerateDataKeyPairWithoutPlaintext APIs are excluded from the free tier.
Security
Q: Who can use and manage my keys in AWS KMS?
AWS KMS enforces usage and management policies that you define. You choose to allow AWS
Identity and Access Management (IAM) users and roles from your account or other accounts to use
and manage your keys.
More details about these security controls can be found in the AWS KMS Cryptographic Details
whitepaper. You can also review the FIPS 140-2 certificate for AWS KMS HSM along with the
associated Security Policy to get more details about how AWS KMS HSM meets the security
requirements of FIPS 140-2. In addition, you can download a copy of the Service Organization
Controls (SOC) report from AWS Artifact to learn more about security controls used by the service to
protect your CMKs.
Q: What is the difference between the FIPS 140-2 validated endpoints and the FIPS 140-2 validated
HSMs in AWS KMS?
AWS KMS is a two-tier service. The API endpoints receive client requests over an HTTPS
connection using only TLS ciphersuites that support perfect forward secrecy. These API endpoints
authenticate and authorize the request before passing the request for a cryptographic operation to
the AWS KMS HSMs or your AWS CloudHSM cluster if you’re using the KMS custom key store
feature.
Q: How do I make API requests to AWS KMS using the FIPS 140-2 validated endpoints?
You configure your applications to connect to the unique regional FIPS 140-2 validated
HTTPS endpoints. AWS KMS FIPS 140-2 validated HTTPS endpoints are powered by the OpenSSL
FIPS Object Module. You can review the security policy of the OpenSSL module
at https://www.openssl.org/docs/fips/SecurityPolicy-2.0.13.pdf. FIPS 140-2 validated API endpoints
are available in all commercial regions where AWS KMS is available.
Q: Can I use AWS KMS to help me comply with the encryption and key management requirements
in the Payment Card Industry Data Security Standard (PCI DSS 3.2.1)?
Yes. AWS KMS has been validated as having the functionality and security controls to help you
meet the encryption and key management requirements (primarily referenced in sections 3.5 and
3.6) of the PCI DSS 3.2.1.
For more details on PCI DSS compliant services in AWS, you can read the PCI DSS FAQs.
Q: How does AWS KMS secure the data keys I export and use in my application?
You can request that AWS KMS generate data keys and return them for use in your own application.
The data keys are encrypted under a master key you define in AWS KMS so that you can safely
store the encrypted data key along with your encrypted data. Your encrypted data key (and therefore
your source data) can only be decrypted by users with permissions to use the original master key to
decrypt your encrypted data key.
Q: How can I tell who used or changed the configuration of my keys in AWS KMS?
Logs in AWS CloudTrail will show all AWS KMS API requests, including both management requests
(e.g. create, rotate, disable, policy edits) and cryptographic requests (e.g. encrypt/decrypt). Turn on
AWS CloudTrail in your account to view these logs.
AWS KMS allows you to create and control the encryption keys used by your applications and
supported AWS services in multiple regions around the world from a single console. The service
uses an FIPS HSM that has been validated under FIPS 140-2, or are in the process of being
validated, to protect the security of your keys. Centralized management of all your keys in AWS KMS
lets you enforce who can use your keys under which conditions, when they get rotated, and who can
manage them. AWS KMS integration with AWS CloudTrail gives you the ability to audit the use of
your keys to support your regulatory and compliance activities. You interact with AWS KMS from
your applications using the AWS SDK if you want to call the service APIs directly, via other AWS
services that are integrated with AWS KMS or by using the AWS Encryption SDK if you want to
perform client-side encryption.