

# Generate data key pairs
<a name="data-key-pairs"></a>

An asymmetric KMS key represents a *data key pair*. Data key pairs are asymmetric data keys consisting of a mathematically-related public key and private key. They are designed for use in client-side encryption and decryption, signing and verification outside of AWS KMS, or to establish a shared secret between two peers. 

Unlike the data key pairs that tools like OpenSSL generate, AWS KMS protects the private key in each data key pair under a symmetric encryption KMS key in AWS KMS that you specify. However, AWS KMS does not store, manage, or track your data key pairs, or perform cryptographic operations with data key pairs. You must use and manage data key pairs outside of AWS KMS.

**Topics**
+ [Create a data key pair](#data-keys-pairs-create)
+ [How cryptographic operations with data key pairs work](#use-data-key-pairs)

## Create a data key pair
<a name="data-keys-pairs-create"></a>

To create a data key pair, call the [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) or [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) operations. Specify the [symmetric encryption KMS key](symm-asymm-choose-key-spec.md#symmetric-cmks) you want to use to encrypt the private key.

`GenerateDataKeyPair` returns a plaintext public key, a plaintext private key, and an encrypted private key. Use this operation when you need a plaintext private key immediately, such as to generate a digital signature.

`GenerateDataKeyPairWithoutPlaintext` returns a plaintext public key and an encrypted private key, but not a plaintext private key. Use this operation when you don't need a plaintext private key immediately, such as when you're encrypting with a public key. Later, when you need a plaintext private key to decrypt the data, you can call the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation.

You can generate RSA, ECC, and ML-KEM data key pairs. In China Regions, you can also generate SM2 data key pairs. If your applications rely on the long-term confidentiality of the plaintext private key returned by `GenerateDataKeyPair`, we recommend that you [use post-quantum TLS with AWS KMS](pqtls.md).

The following image shows the `GenerateDataKeyPair` operation. The `GenerateDataKeyPairWithoutPlaintext` operation omits the plaintext private key.

![Generate a data key pair](https://docs.aws.amazon.com/kms/latest/developerguide/images/generate-data-key-pair.png)


## How cryptographic operations with data key pairs work
<a name="use-data-key-pairs"></a>

The following topics explain what cryptographic operations you can perform with data key pairs generated by a [GenerateDataKeyPair](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPair.html) or [GenerateDataKeyPairWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyPairWithoutPlaintext.html) operation and how they work.

### Encrypt data with a data key pair
<a name="data-key-pairs-encrypt"></a>

When you encrypt with a data key pair, you use the public key of the pair to encrypt the data and the private key of the same pair to decrypt the data. Typically, you use data key pairs when many parties need to encrypt data that only the party with the private key can decrypt.

The parties with the public key use that key to encrypt data, as shown in the following diagram.

![Encrypt user data with the public key of a data key pair outside of AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/images/encrypt-with-data-key-pair.png)


### Decrypt data with a data key pair
<a name="data-key-pairs-decrypt"></a>

To decrypt your data, use the private key in the data key pair. For the operation to succeed, the public and private keys must be from the same data key pair, and you must use the same encryption algorithm.

To decrypt the encrypted private key, pass it to the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. Use the plaintext private key to decrypt the data. Then remove the plaintext private key from memory as soon as possible.

The following diagram shows how to use the private key in a data key pair to decrypt ciphertext.

![Decrypt the data with the private key in a data key pair outside of AWS KMS.](https://docs.aws.amazon.com/kms/latest/developerguide/images/decrypt-with-data-key-pair.png)


### Sign messages with a data key pair
<a name="data-key-pairs-sign"></a>

To generate a cryptographic signature for a message, use the private key in the data key pair. Anyone with the public key can use it to verify that the message was signed with your private key and that it has not changed since it was signed.

If you encrypt your private key, pass the encrypted private key to the [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) operation. AWS KMS uses your KMS key to decrypt the data key and then it returns the plaintext private key. Use the plaintext private key to generate the signature. Then remove the plaintext private key from memory as soon as possible.

To sign a message, create a message digest using a cryptographic hash function, such as the [`dgst`](https://www.openssl.org/docs/man1.0.2/man1/openssl-dgst.html) command in OpenSSL. Then, pass your plaintext private key to the signing algorithm. The result is a signature that represents the contents of the message. (You might be able to sign shorter messages without first creating a digest. The maximum message size varies with the signing tool you use.)

The following diagram shows how to use the private key in a data key pair to sign a message.

![Generate a cryptographic signature with the private key in a data key pair outside of AWS KMS.](https://docs.aws.amazon.com/kms/latest/developerguide/images/sign-with-data-key-pair.png)


### Verify a signature with a data key pair
<a name="data-key-pairs-verify"></a>

Anyone who has the public key in your data key pair can use it to verify the signature that you generated with your private key. Verification confirms that an authorized user signed the message with the specified private key and signing algorithm, and the message hasn't changed since it was signed. 

To be successful, the party verifying the signature must generate the same type of digest, use the same algorithm, and use the public key that corresponds to the private key used to sign the message.

The following diagram shows how to use the public key in a data key pair to verify a message signature.

![Verify a cryptographic signature with the public key in a data key pair outside of AWS KMS.](https://docs.aws.amazon.com/kms/latest/developerguide/images/verify-with-data-key-pair.png)


### Establish a shared secret with data key pairs
<a name="data-key-pairs-derive-shared-secret"></a>

Key agreement enables two peers, each having an elliptic-curve public–private key pair, to establish a shared secret over an insecure channel. To derive a shared secret, the two peers must exchange their public keys. Then, each party uses their *private key* and their peer's *public key* to calculate the same shared secret using a key agreement algorithm. You can use the shared secret value to derive a symmetric key that can encrypt and decrypt data that is sent between the two peers, or that can generate and verify HMACs.

You can also establish a shared secret with a post-quantum ML-KEM data key pair through key encapsulation. Unlike key agreement, which derives a shared secret from a key contributed by each party, key encapsulation generates the shared secret using only the recipient's public key. The sender uses the encapsulate operation on the recipient's public key to generate a shared secret and its encapsulated (ciphertext). It sends the encapsulated shared secret to the recipient. The recipient uses the decapsulate operation to recover the shared secret using their private key.

**Note**  
AWS KMS strongly recommends verifying that the public key you receive came from the expected party before using it to derive or encapsulate a shared secret.