Add support for recipient for KMS Decrypt #13343

mboorstin-circle · 2025-11-06T03:48:20Z

Motivation

Add support for the KMS Decrypt Recipient field. This is used by Nitro Enclaves to decrypt sensitive without their host being able to read it, by KMS re-encrypting the decrypted data to the provided RSA key before it is returned to the caller. This flow is described here.

Changes

I've added basic support to the KMS Decrypt command for the Recipient field by looking for the attestation, parsing it to extract the recipient public key, and returning CiphertextForRecipient instead of Plaintext. It's not clear to me how to simulate verifying the attestation (which involves a signature from AWS that the PCR values are correct) without a significant effort to add proper support for Nitro to Localstack, and I think this PR as-is provides valuable functionality by allowing systems that use Nitro and KMS to be tested against Localstack without having to special-case their calls to Localstack's KMS implementation. So, I don't attempt to do any validation on the provided attestation document beyond what is required to extract the recipient public key.

I've unfortunately had to do a significant amount of manual crypto operations here with asn1crypto and PyCryptoDome because cryptography.hazmat doesn't appear to support the exact algorithms that AWS uses; I apologize for the verbosity and am happy to change it to cryptography.hazmat if there is a way to use it.

I've taken a compromise approach to ensuring that this change is backwards-compatible; if callers pass in a nonsense value to Recipient it will be logged and ignored and Plaintext will be returned, but if an attestation with a valid public key is passed in then CiphertextForRecipient instead of Plaintext will be returned. It is more to spec to error if a nonsense value is passed in for Recipient but that feels a bit more breaking. I'm happy to change to erroring if the maintainers would prefer that now, or it could be done as part of the next major release or similar.

Tests

I've added basic tests for the functionality. I've had to mark them as only_localstack because it is quite complex to call AWS to set up an actual Nitro Enclave, and until Localstack has broader Nitro support I think this will suffice to test. They do test that the flow works end to end. In addition, I have manually tested that this implementation produces a PKCS7 envelope similar to what actual AWS produces for an actual Nitro Enclave, and I have manually tested that my application that works on actual Nitro and KMS works against this PR.

Welcome to LocalStack! Thanks for raising your first Pull Request and landing in your contributions. Our team will reach out with any reviews or feedbacks that we have shortly. We recommend joining our Slack Community and share your PR on the #community channel to share your contributions with us. Please make sure you are following our contributing guidelines and our Code of Conduct.

mboorstin-circle · 2025-11-06T05:29:54Z

(I know that I need to sign the CLA; I just need to consult with my employer's legal department before doing so).

mboorstin-circle · 2025-11-06T14:37:49Z

I have read the CLA Document and I hereby sign the CLA

mboorstin-circle · 2025-11-06T14:37:59Z

recheck

mboorstin-circle · 2025-11-06T14:40:07Z

recheck

mboorstin-circle · 2025-11-06T19:29:29Z

@sannya-singal @alexrashed @bentsku (tagging some of the automatically selected reviewers) I believe this should be ready for review. Thank you in advance!

sannya-singal

Awesome! Thanks for adding this functionality 🚀 The implementation looks good and the approach of gracefully handling invalid attestations is really great. I just have a few suggestions to improve it, please let me know if you require some help or have questions.

sannya-singal · 2025-11-10T06:47:27Z

localstack-core/localstack/services/kms/provider.py

 import logging
 import os

+from cbor2._decoder import loads as cbor2_loads


Rather than using an internal method _decoder here we should use the following from cbor2 import loads.

Done, thanks.

sannya-singal · 2025-11-10T06:47:45Z

localstack-core/localstack/services/kms/provider.py

                    f" constraint: [Member must satisfy enum value set: {VALID_OPERATIONS}]"
                )

+    def _extract_attestation_pubkey(self, attestation_document: bytes):


A return type hint needs to be added to this function.

done, thanks.

sannya-singal · 2025-11-10T06:51:13Z

localstack-core/localstack/utils/crypto.py

+from Crypto.Cipher import AES, PKCS1_OAEP
+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA as CryptoRSA


In my opinion we could eliminate the use of Crypto here and use dependencies from cryptography.hazmat.primitives.

So something like:

encrypted_session_key = recipient_pubkey.encrypt( session_key, padding.OAEP( mgf=padding.MGF1(algorithm=hashes.SHA256()), algorithm=hashes.SHA256(), label=None ) ) cipher = Cipher(algorithms.AES(session_key), modes.CBC(iv), backend=default_backend()) encryptor = cipher.encryptor() padder = sym_padding.PKCS7(algorithms.AES.block_size).padder() padded_plaintext = padder.update(plaintext) + padder.finalize() encrypted_content = encryptor.update(padded_plaintext) + encryptor.finalize()

Please let me know if you would like to know more context here.

Yes, thank you! This all makes sense. I went down this path because Hazmat's one-shot PKCS7 only supports RSA-PKCS1.5 rather than the RSA-OAEP that AWS provides, but yes, I can still do the individual encryption operations with Hazmat and then just use the asn1crypto library to build them into a PKCS7 envelope. So I've updated things to follow your example and remove the PyCryptoDome usage here and in the test file. Let me know if things now look better. Thank you!

sannya-singal · 2025-11-10T06:51:18Z

localstack-core/localstack/utils/crypto.py

+from Crypto.Cipher import AES, PKCS1_OAEP
+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA as CryptoRSA
+from Crypto.Random import get_random_bytes


Can we use os.urandom here instead?

Yes, thank you. Updated.

sannya-singal · 2025-11-10T06:51:54Z

localstack-core/localstack/utils/crypto.py

+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA as CryptoRSA
+from Crypto.Random import get_random_bytes
+from Crypto.Util.Padding import pad as crypto_pad


using from cryptography.hazmat.primitives.asymmetric import padding should suffice the purpose here as well.

Yes, updated to use it as per your example. Thank you!

sannya-singal · 2025-11-10T06:52:36Z

localstack-core/localstack/utils/crypto.py

    return decrypted
+
+
+def pkcs7_envelope_encrypt(plaintext: bytes, recipient_pubkey) -> bytes:


Parameter recipient_pubkey lacks type hint here, can you please add it?

Yes, added.

sannya-singal · 2025-11-10T06:53:20Z

tests/aws/services/kms/test_kms.py

+from Crypto.Cipher import AES, PKCS1_OAEP
+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA as CryptoRSA
+from Crypto.Util.Padding import unpad as crypto_unpad


Same as suggested in the crypto.py most of this can be done with cryptography library.

Yes, thank you! I've updated it in the same way of still using as1ncrypto to deserialize the envelope, but then using the normal Hazmat methods to do the actual decryption. Thanks!

sannya-singal · 2025-11-10T06:53:26Z

tests/aws/services/kms/test_kms.py

+        assert base64.b64decode(plaintext) == message
+
+    @markers.aws.only_localstack
+    def test_decrypt_recipient_invalid_attestation(self, kms_create_key, snapshot, aws_client):


We can safely remove snapshot fixture as its not being used in this test.

Fixed, thanks.

sannya-singal · 2025-11-10T06:53:29Z

tests/aws/services/kms/test_kms.py

        snapshot.match("decrypt_response_with_invalid_ciphertext", e.value.response)

+    @markers.aws.only_localstack
+    def test_decrypt_recipient(self, kms_create_key, snapshot, aws_client):


We can safely remove snapshot fixture as its not being used in this test.

Fixed, thanks.

mboorstin-circle · 2025-11-10T16:51:36Z

Thanks @sannya-singal ! All of your comments make sense and I have updated the diff appropriately. As you requested, I changed back to using cryptography.hazmat for the individual encryption / decryption operations (I think I still need asn1crypto to do the envelope serialization / deserialization, as like I said Hazmat's one-stop PKCS7 doesn't support RSA-OAEP). Let me know if things now look better. Thanks!

sannya-singal

Thanks @mboorstin-circle for addressing all the comments so quickly 🚀 🎉 Changes LGTM, tagging @k-a-il for a quick sanity check on the dependency file changes.

Add support for recipient for KMS Decrypt

05d6765

mboorstin-circle requested review from alexrashed, bentsku, k-a-il, sannya-singal and silv-io as code owners November 6, 2025 03:48

localstack-bot reviewed Nov 6, 2025

View reviewed changes

localstack-bot added a commit that referenced this pull request Nov 6, 2025

@mboorstin-circle has signed the CLA in #13343

947390b

alexrashed assigned sannya-singal Nov 7, 2025

alexrashed added semver: minor Non-breaking changes which can be included in minor releases, but not in patch releases docs: skip Pull request does not require documentation changes notes: needed Pull request should be mentioned in the release notes labels Nov 7, 2025

alexrashed added this to the 4.11 milestone Nov 7, 2025

sannya-singal requested changes Nov 10, 2025

View reviewed changes

Update for code review comments

6d5101d

mboorstin-circle requested a review from sannya-singal November 10, 2025 16:52

sannya-singal approved these changes Nov 11, 2025

View reviewed changes

		return decrypted


		def pkcs7_envelope_encrypt(plaintext: bytes, recipient_pubkey) -> bytes:

Uh oh!

Add support for recipient for KMS Decrypt #13343

Are you sure you want to change the base?

Add support for recipient for KMS Decrypt #13343

Conversation

mboorstin-circle commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Changes

Tests

Related

Uh oh!

localstack-bot commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

localstack-bot left a comment

Choose a reason for hiding this comment

Uh oh!

mboorstin-circle commented Nov 6, 2025

Uh oh!

mboorstin-circle commented Nov 6, 2025

Uh oh!

mboorstin-circle commented Nov 6, 2025

Uh oh!

mboorstin-circle commented Nov 6, 2025

Uh oh!

mboorstin-circle commented Nov 6, 2025

Uh oh!

sannya-singal left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mboorstin-circle commented Nov 10, 2025

Uh oh!

sannya-singal left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mboorstin-circle commented Nov 6, 2025 •

edited

Loading

localstack-bot commented Nov 6, 2025 •

edited

Loading