Key spec reference

When you create an asymmetric KMS key or an HMAC KMS key, you select its key spec. The key spec, which is a property of every AWS 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 a 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, signing algorithms, or message authentication code (MAC) algorithms that AWS KMS supports for the KMS key. The key spec that you choose is typically determined by your use case and regulatory requirements. However, cryptographic operations on KMS keys with different key specs are priced differently and are subject to different quotas. For pricing details, see AWS Key Management Service Pricing. For information about request quotas, see Request quotas.

To limit the key specs that principals can use when creating KMS keys, use the kms:KeySpec condition key. You can also use the kms:KeySpec condition key to allow principals to call AWS KMS operations only on KMS keys with a particular key spec. For example, you can deny permission to schedule deletion of any KMS key with an RSA_4096 key spec.

AWS KMS supports the following key specs for KMS keys:

Symmetric encryption key spec (default)

• 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 -or- deriving shared secrets)

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

SM2 key spec (encryption and decryption -or- signing and verification -or- deriving shared secrets)

• SM2 (China Regions only)

HMAC key specs

• HMAC_224

• HMAC_256

• HMAC_384

• HMAC_512

SYMMETRIC_DEFAULT key spec

The default key spec, SYMMETRIC_DEFAULT, is the key spec for symmetric encryption KMS keys. When you select the Symmetric key type and the Encrypt and decrypt key usage in the AWS 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 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.

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 AWS KMS ciphertexts infeasible.

The only exception in China Regions, where SYMMETRIC_DEFAULT represents a 128-bit symmetric key that uses SM4 encryption. You can only create a 128-bit SM4 key within China Regions. You cannot create a 256-bit AES-GCM KMS key in China Regions.

You can use a symmetric encryption KMS key in AWS KMS to encrypt, decrypt, and re-encrypt data, and to protect generated data keys and data key pairs. AWS services that are integrated with AWS KMS use symmetric encryption KMS keys to encrypt your data at rest. You can import your own key material into a symmetric encryption KMS key and create symmetric encryption 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.

You can use a symmetric encryption KMS key in AWS KMS to encrypt, decrypt, and re-encrypt data, and generate data keys and data key pairs. You can create multi-Region symmetric encryption KMS keys, import your own key material into a symmetric encryption KMS key, and create symmetric encryption KMS keys in custom key stores. For a table comparing the operations that you can perform on KMS keys of different types, see Key type reference.

RSA key specs

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

Warning

When you encrypt data outside of AWS KMS, be sure that you can decrypt your ciphertext. If you use the public key from a KMS key that has been deleted from AWS 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 AWS 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.

AWS 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. Cryptographic operations on KMS keys with different RSA key specs are priced differently. For information about AWS KMS pricing, see AWS 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 AWS KMS for an RSA KMS key, AWS 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. AWS 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 AWS KMS. Be sure to use an encryption algorithm that AWS KMS supports for RSA KMS keys. To decrypt the ciphertext, call the Decrypt function with the same KMS key and encryption algorithm.

AWS 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 AWS 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 AWS KMS console or use the DescribeKey operation. AWS KMS also provides the key spec and encryption algorithms when you download your public key, either in the AWS 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 encryption 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 AWS KMS for an asymmetric KMS key, AWS 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. AWS 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 AWS KMS.

AWS KMS supports the following signing algorithms for all KMS keys with an RSA key spec. You are required to specify a signing algorithm when you call the Sign and Verify operations. You can choose a different algorithm for each request. When signing with RSA key pairs, RSASSA-PSS algorithms are preferred. We include RSASSA-PKCS1-v1_5 algorithms for compatibility with existing applications.

Supported signing algorithms for RSA key specs
Signing algorithm	Algorithm description
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
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

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 AWS KMS console or by using the DescribeKey operation. AWS KMS also provides the key spec and signing algorithms when you download your public key, either in the AWS KMS console or by using the GetPublicKey operation.

Elliptic curve key specs

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

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

• Asymmetric NIST-recommended elliptic curve key pairs (signing and verification -or- deriving shared secrets)

  • 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 derive shared secrets, use one of the NIST-recommended elliptic curve key specs. The only supported key agreement algorithm for deriving shared secrets is the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive (ECDH). For an example of how to derive shared secrets offline, see Deriving shared secrets offline.

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 AWS KMS pricing, see AWS Key Management Service Pricing. For information about request quotas, see Request quotas.

The following table shows the signing algorithms that AWS 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.

SM2 key spec (China Regions only)

The SM2 key spec is an elliptic curve key spec defined within the GM/T series of specifications published by China's Office of State Commercial Cryptography Administration (OSCCA). The SM2 key spec is available only in China Regions. When you use the SM2 key spec, AWS KMS creates an asymmetric KMS key with an SM2 key pair. You can use your SM2 key pair within AWS KMS, or download the public key for use outside of AWS KMS. For more information, see Offline verification with SM2 key pairs (China Regions only).

Each KMS key can have only one key usage. You can use an SM2 KMS key for signing and verification, encryption and decryption, or deriving shared secrets. You must specify the key usage when you create the KMS key, and you cannot change it after the key is created.

If you're creating an asymmetric KMS key to derive shared secrets, use the SM2 key spec. The only supported key agreement algorithm for deriving shared secrets is the Elliptic Curve Cryptography Cofactor Diffie-Hellman Primitive (ECDH).

AWS KMS supports the following SM2 encryption and signing algorithms:

• SM2PKE encryption algorithm

  SM2PKE is an elliptic curve based encryption algorithm defined by OSCCA in GM/T 0003.4-2012.

• SM2DSA signing algorithm

  SM2DSA is an elliptic curve based signing algorithm defined by OSCCA in GM/T 0003.2-2012. SM2DSA requires a distinguishing ID that is hashed with the SM3 hashing algorithm and then combined with the message, or message digest, that you passed to AWS KMS. This concatenated value is then hashed and signed by AWS KMS.

Key specs for HMAC KMS keys

AWS KMS supports symmetric HMAC keys in varying lengths. The key spec that you select can depend on your security, regulatory, or business requirements. The length of the key determines the MAC algorithm that is used in GenerateMac and VerifyMac operations. In general, longer keys are more secure. Use the longest key that is practical for your use case.

HMAC key spec	MAC algorithm
HMAC_224	HMAC_SHA_224
HMAC_256	HMAC_SHA_256
HMAC_384	HMAC_SHA_384
HMAC_512	HMAC_SHA_512