encapsulate

Generates a shared secret and its encapsulated (ciphertext) form using the public key of an ML-KEM KMS key pair. Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM), specified in FIPS 203 on the NIST website, is a post-quantum algorithm for establishing a shared secret between two parties.

For an example of how two parties establish a shared secret over an insecure channel using ML-KEM, see ML-KEM keys in KMS in the Key Management Service Developer Guide.

The Encapsulate operation is not available in China Regions.

The KMS key that you use for this operation must be in a compatible key state. For details, see Key states of KMS keys in the Key Management Service Developer Guide.

Cross-account use: Yes. To perform this operation with a KMS key in a different Amazon Web Services account, specify the key ARN or alias ARN in the value of the KeyId parameter.

Required permissions: kms:Encapsulate (key policy)

Related operations:

• Decapsulate

• DeriveSharedSecret

• CreateKey

• GetPublicKey

• DescribeKey

Eventual consistency: The KMS API follows an eventual consistency model. For more information, see KMS eventual consistency.

Samples

// Generates a shared secret and its encapsulated ciphertext (SharedSecretCiphertextBlob) using the
// public key in an asymmetric ML KEM KMS key. Send the ciphertext to your peer, who calls Decapsulate to
// recover the same shared secret.
val resp = kmsClient.encapsulate {
    keyId = "1234abcd-12ab-34cd-56ef-1234567890ab"
    encapsulationAlgorithm = EncapsulationAlgorithmSpec.fromValue("ML_KEM")
}