Recovers the shared secret that was encapsulated with the public key of an ML-KEM KMS key. 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 Decapsulate operation is not available in China Regions.
Decapsulate returns the shared secret as a 32-byte value. You can use it directly as key material, or run it through a key derivation function to derive multiple keys and nonces.
Decapsulate returns an InvalidCiphertextException when the length of the SharedSecretCiphertextBlob is inconsistent with the ML-KEM key spec. In all other cases, Decapsulate returns a 32-byte pseudo-random value. This is true even when the SharedSecretCiphertextBlob was created using a different ML-KEM key or altered from its original value. This behavior is a security feature called implicit rejection that helps protect against chosen-ciphertext attacks. Because a response does not indicate that the ciphertext and key are valid, confirm the two parties derived the same shared secret before using it. 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:Decapsulate (key policy)
Related operations:Eventual consistency: The KMS API follows an eventual consistency model. For more information, see
KMS eventual consistency.