Choosing your KMS key configuration - Amazon Key Management Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Choosing your KMS key configuration

Amazon KMS supports symmetric and asymmetric KMS keys.

  • Symmetric KMS key: Represents a single 256-bit secret encryption key that never leaves Amazon KMS unencrypted. To use your symmetric KMS key, you must call Amazon KMS.

  • Asymmetric KMS key: Represents a mathematically related public key and private key pair that you can use for encryption and decryption or signing and verification, but not both. The private key never leaves Amazon KMS unencrypted. You can use the public key within Amazon KMS by calling the Amazon KMS API operations, or download the public key and use it outside of Amazon KMS.

The type of KMS key that you create depends largely on how you plan to use the KMS key, your security requirements, and your authorization requirements. When creating your KMS key, remember that the cryptographic configuration of the KMS key, including its key spec and key usage, are established when you create the KMS key and cannot be changed. For help with creating symmetric and asymmetric KMS key, see Creating keys.

Use the following guidance to determine which type of KMS key you need based on your use case.

Encrypt and decrypt data

Use a symmetric KMS key for most use cases that require encrypting and decrypting data. The symmetric encryption algorithm that Amazon KMS uses is fast, efficient, and assures the confidentiality and authenticity of data. It supports authenticated encryption with additional authenticated data (AAD), defined as an encryption context. This type of KMS key requires both the sender and recipient of encrypted data to have valid Amazon credentials to call Amazon KMS.

If your use case requires encryption outside of Amazon by users who cannot call Amazon KMS, asymmetric KMS keys are a good choice. You can distribute the public key of the asymmetric KMS key to allow these users to encrypt data. And your applications that need to decrypt that data can use the private key of the asymmetric KMS key within Amazon KMS.

Sign messages and verify signatures

To sign messages and verify signatures, you must use an asymmetric KMS key. You can use a KMS key with a key spec that represents an RSA key pair or an elliptic curve (ECC) key pair. The key spec you choose is determined by the signing algorithm that you want to use. In some cases, the users who will verify signatures are outside of Amazon and can’t call the Verify operation. In that case, choose a key spec associated with a signing algorithm that these users can support in their local applications.

Perform public key encryption

To perform public key encryption, you must use an asymmetric KMS key with an RSA key spec. Elliptic curve (ECC) key specs cannot be used for public key encryption. To encrypt data in Amazon KMS with the public key of an RSA KMS key, use the Encrypt operation. You can also download the public key and share it with the parties that need to encrypt data outside of Amazon KMS.

When you download the public key of an asymmetric KMS key, you can use it outside of Amazon KMS. But it is no longer subject to the security controls that protect the KMS key in Amazon KMS. For example, you cannot use Amazon KMS key policies or grants to control use of the public key. Nor can you control whether the key is used only for encryption and decryption using the RSA encryption algorithms that Amazon KMS supports. For more details, see Special Considerations for Downloading Public Keys.

To decrypt data that was encrypted with the public key outside of Amazon KMS, call the Decrypt operation. The Decrypt operation fails if the data was encrypted under a public key from a KMS key with a key usage of SIGN_VERIFY. It will also fail if it was encrypted by using an algorithm that Amazon KMS does not support for RSA KMS keys.

To avoid these errors, anyone using a public key outside of Amazon KMS must store the key configuration. The Amazon KMS console and the GetPublicKey response provide the information that you must include when you share the public key.

Use with integrated Amazon services

To create a KMS key for use with an Amazon service that is integrated with Amazon KMS, consult the documentation for the service. Amazon services that encrypt your data require a symmetric KMS key..

In addition to these considerations, KMS keys with different key specs have different prices and different request quotas. For information about Amazon KMS pricing, see Amazon Key Management Service Pricing. For information about request quotas, see Request quotas.

Selecting the key usage

The key usage of a KMS key determines whether the KMS key is used for encryption and decryption -or- signing and verification. You cannot choose both. Using a KMS key for more than one type of operations makes the product of both operations more vulnerable to attack.

As shown in the following table, symmetric KMS keys can be used only for encryption and decryption. Elliptic curve (ECC) KMS keys can be used only for signing and verification. Key usage decisions are really made only for RSA KMS keys.

Valid key usage for KMS key types
KMS key type Encrypt and decrypt Sign and verify
Symmetric KMS keys
Asymmetric KMS keys with RSA key pairs
Asymmetric KMS keys with ECC key pairs

In the Amazon KMS console, you first choose the key type (symmetric or asymmetric), and then, for asymmetric KMS keys, the key usage. If you select a symmetric key type, the key usage options do not appear, because symmetric KMS keys only support encryption and decryption. The key usage that you choose determines which key specs are displayed.

To choose a key usage in the Amazon KMS console:

  • For KMS keys with elliptic curve (ECC) key material, choose Sign and verify.

  • For KMS keys with RSA key material, choose Encrypt and decrypt or Sign and verify.

To determine the key usage that principals in your account are permitted to use for KMS keys, use the kms:KeyUsage; condition key.

Selecting the key spec

When you create an asymmetric KMS key, you select its key spec. The key spec, which is a property of every Amazon KMS key, represents the cryptographic configuration of your KMS key. You choose the key spec when you create the KMS key, and you cannot change it. If you've selected the wrong key spec, delete the KMS key, and create a new one.

Note

The key spec for an KMS key was known as a "customer master key spec." The CustomerMasterKeySpec parameter of the CreateKey operation is deprecated. Instead, use the KeySpec parameter. The response of the CreateKey and DescribeKey operations includes a KeySpec and CustomerMasterKeySpec member with the same value.

The key spec determines whether the KMS key is symmetric or asymmetric, the type of key material in the KMS key, and the encryption algorithms or signing algorithms that Amazon KMS supports for the KMS key. The key spec that you choose is typically determined by your use case and regulatory requirements.

To determine the key specs that principals in your account are permitted to use for KMS keys, use the kms:KeySpec condition key.

Amazon KMS supports the following key specs for KMS keys:

  • Symmetric KMS keys (default; encryption and decryption)

    • SYMMETRIC_DEFAULT

  • RSA key specs (encryption and decryption -or- signing and verification)

    • RSA_2048

    • RSA_3072

    • RSA_4096

  • Elliptic curve key specs

    • Asymmetric NIST-recommended elliptic curve key pairs (signing and verification)

      • ECC_NIST_P256 (secp256r1)

      • ECC_NIST_P384 (secp384r1)

      • ECC_NIST_P521 (secp521r1)

    • Other asymmetric elliptic curve key pairs (signing and verification)

      • ECC_SECG_P256K1 (secp256k1), commonly used for cryptocurrency.

Topics

The following topics provide technical information about the key specs.

SYMMETRIC_DEFAULT key spec

The default key spec, SYMMETRIC_DEFAULT, is the key spec for symmetric KMS keys. When you select the Symmetric key type in the Amazon KMS console, it selects the SYMMETRIC_DEFAULT key spec. In the CreateKey operation, if you don't specify a KeySpec value, SYMMETRIC_DEFAULT is selected. If you don't have a reason to use a different key spec, SYMMETRIC_DEFAULT is a good choice.

SYMMETRIC_DEFAULT currently represents AES-256-GCM, a symmetric algorithm based on Advanced Encryption Standard (AES) in Galois Counter Mode (GCM) with 256-bit keys, an industry standard for secure encryption. The ciphertext that this algorithm generates supports additional authenticated data (AAD), such as an encryption context, and GCM provides an additional integrity check on the ciphertext. For technical details, see Amazon Key Management Service Cryptographic Details.

Data encrypted under AES-256-GCM is protected now and in the future. Cryptographers consider this algorithm to be quantum resistant. Theoretical future, large-scale quantum computing attacks on ciphertexts created under 256-bit AES-GCM keys reduce the effective security of the key to 128 bits. But, this security level is sufficient to make brute force attacks on Amazon KMS ciphertexts infeasible.

You can use a symmetric KMS key in Amazon KMS to encrypt, decrypt, and re-encrypt data, and generate data keys and data key pairs. Amazon services that are integrated with Amazon KMS use symmetric KMS keys to encrypt your data at rest. You can import your own key material into a symmetric KMS key and create symmetric KMS keys in custom key stores. For a table comparing the operations that you can perform on symmetric and asymmetric KMS keys, see Comparing Symmetric and Asymmetric KMS keys.

RSA key specs

When you use an RSA key spec, Amazon KMS creates an asymmetric KMS key with an RSA key pair. The private key never leaves Amazon KMS unencrypted. You can use the public key within Amazon KMS, or download the public key for use outside of Amazon KMS.

Warning

When you encrypt data outside of Amazon KMS, be sure that you can decrypt your ciphertext. If you use the public key from a KMS key that has been deleted from Amazon KMS, the public key from a KMS key configured for signing and verification, or an encryption algorithm that is not supported by the KMS key, the data is unrecoverable.

In Amazon KMS, you can use asymmetric KMS keys with RSA key pairs for encryption and decryption, or signing and verification, but not both. This property, known as key usage, is determined separately from the key spec, but you should make that decision before you select a key spec.

Amazon KMS supports the following RSA key specs for encryption and decryption or signing and verification:

  • RSA_2048

  • RSA_3072

  • RSA_4096

RSA key specs differ by the length of the RSA key in bits. The RSA key spec that you choose might be determined by your security standards or the requirements of your task. In general, use the largest key that is practical and affordable for your task. KMS keys with different RSA key specs are priced differently and are subject to different request quotas. For information about Amazon KMS pricing, see Amazon Key Management Service Pricing. For information about request quotas, see Request quotas.

RSA key specs for encryption and decryption

When an RSA asymmetric KMS key is used for encryption and decryption, you encrypt with the public key and decrypt with the private key. When you call the Encrypt operation in Amazon KMS for an RSA KMS key, Amazon KMS uses the public key in the RSA key pair and the encryption algorithm you specify to encrypt your data. To decrypt the ciphertext, call the Decrypt operation and specify the same KMS key and encryption algorithm. Amazon KMS then uses the private key in the RSA key pair to decrypt your data.

You can also download the public key and use it to encrypt data outside of Amazon KMS. Be sure to use an encryption algorithm that Amazon KMS supports for RSA KMS keys. To decrypt the ciphertext, call the Decrypt function with the same KMS key and encryption algorithm.

Amazon KMS supports two encryption algorithms for KMS keys with RSA key specs. These algorithms, which are defined in PKCS #1 v2.2, differ in the hash function they use internally. In Amazon KMS, the RSAES_OAEP algorithms always use the same hash function for both hashing purposes and for the mask generation function (MGF1). You are required to specify an encryption algorithm when you call the Encrypt and Decrypt operations. You can choose a different algorithm for each request.

Supported encryption algorithms for RSA key specs
Encryption algorithm Algorithm description
RSAES_OAEP_SHA_1 PKCS #1 v2.2, Section 7.1. RSA encryption with OAEP Padding using SHA-1 for both the hash and in the MGF1 mask generation function along with an empty label.
RSAES_OAEP_SHA_256 PKCS #1, Section 7.1. RSA encryption with OAEP Padding using SHA-256 for both the hash and in the MGF1 mask generation function along with an empty label.

You cannot configure a KMS key to use a particular encryption algorithm. However, you can use the kms:EncryptionAlgorithm policy condition to specify the encryption algorithms that principals are allowed to use with the KMS key.

To get the encryption algorithms for a KMS key, view the cryptographic configuration of the KMS key in the Amazon KMS console or use the DescribeKey operation. Amazon KMS also provides the key spec and encryption algorithms when you download your public key, either in the Amazon KMS console or by using the GetPublicKey operation.

You might choose an RSA key spec based on the length of the plaintext data that you can encrypt in each request. The following table shows the maximum size, in bytes, of the plaintext that you can encrypt in a single call to the Encrypt operation. The values differ with the key spec and encryption algorithm. To compare, you can use a symmetric KMS key to encrypt up to 4096 bytes at one time.

To compute the maximum plaintext length in bytes for these algorithms, use the following formula: (key_size_in_bits / 8) - (2 * hash_length_in_bits/8) - 2. For example, for RSA_2048 with SHA-256, the maximum plaintext size in bytes is (2048/8) - (2 * 256/8) -2 = 190.

Maximum plaintext size (in bytes) in an Encrypt operation
Encryption algorithm
Key spec RSAES_OAEP_SHA_1 RSAES_OAEP_SHA_256
RSA_2048 214 190
RSA_3072 342 318
RSA_4096 470 446

RSA key specs for signing and verification

When an RSA asymmetric KMS key is used for signing and verification, you generate the signature for a message with the private key and verify the signature with the public key.

When you call the Sign operation in Amazon KMS for an asymmetric KMS key, Amazon KMS uses the private key in the RSA key pair, the message, and the signing algorithm you specify, to generate a signature. To verify the signature, call the Verify operation. Specify the signature, plus the same KMS key, message, and signing algorithm. Amazon KMS then uses the public key in the RSA key pair to verify the signature. You can also download the public key and use it to verify the signature outside of Amazon KMS.

Amazon KMS supports the following signing algorithms for KMS keys with RSA key spec. You are required to specify an signing algorithm when you call the Sign and Verify operations. You can choose a different algorithm for each request.

Supported signing algorithms for RSA key specs
Signing algorithm Algorithm description
RSASSA_PKCS1_V1_5_SHA_256 PKCS #1 v2.2, Section 8.2, RSA signature with PKCS #1v1.5 Padding and SHA-256
RSASSA_PKCS1_V1_5_SHA_384 PKCS #1 v2.2, Section 8.2, RSA signature with PKCS #1v1.5 Padding and SHA-384
RSASSA_PKCS1_V1_5_SHA_512 PKCS #1 v2.2, Section 8.2, RSA signature with PKCS #1v1.5 Padding and SHA-512
RSASSA_PSS_SHA_256 PKCS #1 v2.2, Section 8.1, RSA signature with PSS padding using SHA-256 for both the message digest and the MGF1 mask generation function along with a 256-bit salt
RSASSA_PSS_SHA_384 PKCS #1 v2.2, Section 8.1, RSA signature with PSS padding using SHA-384 for both the message digest and the MGF1 mask generation function along with a 384-bit salt
RSASSA_PSS_SHA_512 PKCS #1 v2.2, Section 8.1, RSA signature with PSS padding using SHA-512 for both the message digest and the MGF1 mask generation function along with a 512-bit salt

You cannot configure a KMS key to use particular signing algorithms. However, you can use the kms:SigningAlgorithm policy condition to specify the signing algorithms that principals are allowed to use with the KMS key.

To get the signing algorithms for a KMS key, view the cryptographic configuration of the KMS key in the Amazon KMS console or by using the DescribeKey operation. Amazon KMS also provides the key spec and signing algorithms when you download your public key, either in the Amazon KMS console or by using the GetPublicKey operation.

Elliptic curve key specs

When you use an elliptic curve (ECC) key spec, Amazon KMS creates an asymmetric KMS key with an ECC key pair for signing and verification. The private key that generates signature never leaves Amazon KMS unencrypted. You can use the public key to verify signatures within Amazon KMS, or download the public key for use outside of Amazon KMS.

Amazon KMS supports the following ECC key specs for asymmetric KMS keys.

  • Asymmetric NIST-recommended elliptic curve key pairs (signing and verification)

    • ECC_NIST_P256 (secp256r1)

    • ECC_NIST_P384 (secp384r1)

    • ECC_NIST_P521 (secp521r1)

  • Other asymmetric elliptic curve key pairs (signing and verification)

    • ECC_SECG_P256K1 (secp256k1), commonly used for cryptocurrencies.

The ECC key spec that you choose might be determined by your security standards or the requirements of your task. In general, use the curve with the most points that is practical and affordable for your task.

If you're creating an asymmetric KMS key to use with cryptocurrencies, use the ECC_SECG_P256K1 key spec. You can also use this key spec for other purposes, but it is required for Bitcoin, and other cryptocurrencies.

KMS keys with different ECC key specs are priced differently and are subject to different request quotas. For information about Amazon KMS pricing, see Amazon Key Management Service Pricing. For information about request quotas, see Request quotas.

The following table shows the signing algorithms that Amazon KMS supports for each of the ECC key specs. You cannot configure a KMS key to use particular signing algorithms. However, you can use the kms:SigningAlgorithm policy condition to specify the signing algorithms that principals are allowed to use with the KMS key.

Supported signing algorithms for ECC key specs
Key spec Signing algorithm Algorithm description
ECC_NIST_P256 ECDSA_SHA_256 NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and SHA-256 for the message digest.
ECC_NIST_P384 ECDSA_SHA_384 NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and SHA-384 for the message digest.
ECC_NIST_P521 ECDSA_SHA_512 NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and SHA-512 for the message digest.
ECC_SECG_P256K1 ECDSA_SHA_256 NIST FIPS 186-4, Section 6.4, ECDSA signature using the curve specified by the key and SHA-256 for the message digest.