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