Special-purpose keys - AWS Key Management Service

Special-purpose keys

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

When you create a AWS KMS key in KMS, by default, you get a symmetric encryption KMS key. In AWS KMS, a symmetric encryption KMS key represents a 256-bit key that is used for encryption and decryption. Symmetric key material never leaves AWS KMS unencrypted. Unless your task explicitly requires asymmetric encryption or HMAC keys, symmetric encryption KMS keys, which never leave AWS KMS unencrypted, are a good choice. Also, AWS services that are integrated with AWS 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 AWS 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.

AWS KMS also support the following special-purpose KMS key types:

Choosing a KMS key type

AWS 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 secret encryption key that never leaves AWS KMS unencrypted. To use your symmetric encryption KMS key, you must call AWS 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 AWS 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 AWS KMS unencrypted. You can use the public key within AWS KMS by calling the AWS KMS API operations, or download the public key and use it outside of AWS 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 AWS KMS unencrypted. To use your HMAC KMS key, you must call AWS 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 AWS 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 AWS credentials to call AWS KMS.

If your use case requires encryption outside of AWS by users who cannot call AWS 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 AWS 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 AWS 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 AWS 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 AWS KMS.

When you download the public key of an asymmetric KMS key, you can use it outside of AWS KMS. But it is no longer subject to the security controls that protect the KMS key in AWS KMS. For example, you cannot use AWS 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 AWS KMS supports. For more details, see Special Considerations for Downloading Public Keys.

To decrypt data that was encrypted with the public key outside of AWS 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 AWS KMS does not support for RSA KMS keys.

To avoid these errors, anyone using a public key outside of AWS KMS must store the key configuration. The AWS 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 AWS KMS, AWS 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 AWS KMS console, choose the Symmetric key type.

Note

HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

Use with AWS services

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

In addition to these considerations, KMS keys with different key specs have different prices and different request quotas. For information about AWS KMS pricing, see AWS 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

In the AWS 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 AWS KMS console:

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

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

    Note

    HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

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

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

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

AWS KMS supports the following key specs for KMS keys:

Note

HMAC KMS keys are not supported in all AWS Regions. For a list of Regions in which HMAC KMS keys are supported, see HMAC Regions.

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.