Special-purpose keys - 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 (PDF).

Special-purpose keys

Amazon Key Management Service (Amazon KMS) supports several different types of keys for different uses.

When you create an Amazon KMS key, by default, you get a symmetric encryption KMS key. In Amazon KMS, a symmetric encryption KMS key represents a 256-bit AES-GCM key that is used for encryption and decryption, except in China Regions, where it represents a symmetric a 128-bit symmetric key that uses SM4 encryption. Symmetric key material never leaves Amazon KMS unencrypted. Unless your task explicitly requires asymmetric encryption or HMAC keys, symmetric encryption KMS keys, which never leave Amazon KMS unencrypted, are a good choice. Also, Amazon services that are integrated with Amazon KMS use only symmetric encryption KMS keys to encrypt your data. These services do not support encryption with asymmetric KMS keys.

You can use a symmetric encryption KMS key in Amazon KMS to encrypt, decrypt, and re-encrypt data, generate data keys and data key pairs, and generate random byte strings. 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 Key type reference.

Amazon KMS also supports the following special-purpose KMS key types:

Choosing a KMS key type

Amazon KMS supports several types of KMS keys: symmetric encryption keys, symmetric HMAC keys, asymmetric encryption keys, and asymmetric signing keys.

KMS keys differ because they contain different cryptographic key material.

  • Symmetric encryption KMS key: Represents a single 256-bit AES-GCM encryption key, except in China Regions, where it represents a 128-bit SM4 encryption key. Symmetric key material never leaves Amazon KMS unencrypted. To use your symmetric encryption KMS key, you must call Amazon KMS.

    Symmetric encryption keys, which are the default KMS keys, are ideal for most uses. If you need a KMS key to protect your data in an Amazon Web Service, use a symmetric encryption key unless you are instructed to use another type of key.

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

  • HMAC KMS key (symmetric): Represents a symmetric key of varying length that is used to generate and verify hash-based message authentication codes. The key material in an HMAC KMS key never leaves Amazon KMS unencrypted. To use your HMAC KMS key, you must call 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.

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, an elliptic curve (ECC) key pair, or an SM2 key pair (China Regions only). The key spec you choose is determined by the signing algorithm that you want to use. The ECDSA signing algorithms that ECC key pairs support are recommended over the RSA signing algorithms. However, you might need to use a particular key spec and signing algorithm to support users who verify signatures outside of Amazon.

Perform public key encryption

To perform public key encryption, you must use an asymmetric KMS key with an RSA key spec or an SM2 key spec (China Regions only). To encrypt data in Amazon KMS with the public key of a KMS key pair, 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 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 the key spec you selected. For more information on key specs and supported algorithms, see Asymmetric key specs.

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.

Generate and verify HMAC codes

To generate and verify hash-based message authentication codes, use an HMAC KMS key. When you create an HMAC key in Amazon KMS, Amazon KMS creates and protects your key material and ensures that you use the correct MAC algorithms for your key. HMAC codes can also be used as pseudo-random numbers, and in certain scenarios for symmetric signing and tokenizing.

HMAC KMS keys are symmetric keys. When creating an HMAC KMS key in the Amazon KMS console, choose the Symmetric key type.

Use with 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 encryption KMS key..

In addition to these considerations, cryptographic operations on 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 verifying signatures, or generating and verifying HMAC tags. Each KMS key has only one key usage. Using a KMS key for more than one type of operation makes the product of all operations more vulnerable to attack.

As shown in the following table, symmetric encryption KMS keys can be used only for encryption and decryption. HMAC KMS keys can be used only for generating and verifying HMAC codes. Elliptic curve (ECC) KMS keys can be used only for signing and verification. You need to make a key usage decision only for RSA KMS keys.

Valid key usage for KMS key types
KMS key type Encrypt and decrypt

ENCRYPT_DECRYPT

Sign and verify

SIGN_VERIFY

Generate and verify MAC

GENERATE_VERIFY_MAC

Symmetric encryption KMS keys
HMAC KMS keys (symmetric)
Asymmetric KMS keys with RSA key pairs
Asymmetric KMS keys with ECC key pairs
Asymmetric KMS keys with SM2 key pairs (China Regions only)

In the Amazon KMS console, you first choose the key type (symmetric or asymmetric) and then the key usage. The key type you choose determines which key usage options are displayed. The key usage you choose determines which key specs, if any, are displayed.

To choose a key usage in the Amazon KMS console:

  • For symmetric encryption KMS keys (default), choose Encrypt and decrypt.

  • For HMAC KMS keys, choose Generate and verify MAC.

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

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

  • For asymmetric KMS keys with SM2 key material, choose Encrypt and decrypt or Sign and verify. The SM2 key spec is available only in China Regions.

To allow principals to create KMS keys only for a particular key usage, use the kms:KeyUsage condition key. You can also use the kms:KeyUsage condition key to allow principals to call API operations for a KMS key based on its key usage. For example, you can allow permission to disable a KMS key only if its key usage is SIGN_VERIFY.

Selecting the key spec

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

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 encryption key spec (default)
  • SYMMETRIC_DEFAULT

HMAC key specs
  • HMAC_224

  • HMAC_256

  • HMAC_384

  • HMAC_512

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.

SM2 key spec (encryption and decryption -or- signing and verification)
  • SM2 (China Regions only)