feat: Required encryption context CMM

examples/src/keyrings/hierarchical_keyring.py

@@ -1,6 +1,36 @@
 # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
-"""Example showing basic encryption and decryption of a value already in memory."""
+"""
+This example sets up the Hierarchical Keyring, which establishes a key hierarchy where "branch"
+keys are persisted in DynamoDb. These branch keys are used to protect your data keys, and these
+branch keys are themselves protected by a KMS Key.
+
+Establishing a key hierarchy like this has two benefits:
+First, by caching the branch key material, and only calling KMS to re-establish authentication
+regularly according to your configured TTL, you limit how often you need to call KMS to protect
+your data. This is a performance security tradeoff, where your authentication, audit, and logging
+from KMS is no longer one-to-one with every encrypt or decrypt call. Additionally, KMS Cloudtrail
+cannot be used to distinguish Encrypt and Decrypt calls, and you cannot restrict who has
+Encryption rights from who has Decryption rights since they both ONLY need KMS:Decrypt. However,
+the benefit is that you no longer have to make a network call to KMS for every encrypt or
+decrypt.
+
+Second, this key hierarchy facilitates cryptographic isolation of a tenant's data in a
+multi-tenant data store. Each tenant can have a unique Branch Key, that is only used to protect
+the tenant's data. You can either statically configure a single branch key to ensure you are
+restricting access to a single tenant, or you can implement an interface that selects the Branch
+Key based on the Encryption Context.
+
+This example demonstrates configuring a Hierarchical Keyring with a Branch Key ID Supplier to
+encrypt and decrypt data for two separate tenants.
+
+This example requires access to the DDB Table where you are storing the Branch Keys. This
+table must be configured with the following primary key configuration: - Partition key is named
+"partition_key" with type (S) - Sort key is named "sort_key" with type (S).
+
+This example also requires using a KMS Key. You need the following access on this key: -
+GenerateDataKeyWithoutPlaintext - Decrypt
+"""
 import sys
 
 import boto3
@@ -25,6 +55,7 @@
 
 from .example_branch_key_id_supplier import ExampleBranchKeyIdSupplier
 
+# TODO-MPL: Remove this as part of removing PYTHONPATH hacks.
 module_root_dir = '/'.join(__file__.split("/")[:-1])
 
 sys.path.append(module_root_dir)

examples/src/keyrings/required_encryption_context_cmm.py

@@ -0,0 +1,158 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Demonstrate an encrypt/decrypt cycle using a Required Encryption Context CMM.
+A required encryption context CMM asks for required keys in the encryption context field
+on encrypt such that they will not be stored on the message, but WILL be included in the header signature.
+On decrypt, the client MUST supply the key/value pair(s) that were not stored to successfully decrypt the message.
+"""
+import sys
+
+import boto3
+# Ignore missing MPL for pylint, but the MPL is required for this example
+# noqa pylint: disable=import-error
+from aws_cryptographic_materialproviders.mpl import AwsCryptographicMaterialProviders
+from aws_cryptographic_materialproviders.mpl.config import MaterialProvidersConfig
+from aws_cryptographic_materialproviders.mpl.models import (
+    CreateAwsKmsKeyringInput,
+    CreateDefaultCryptographicMaterialsManagerInput,
+    CreateRequiredEncryptionContextCMMInput,
+)
+from aws_cryptographic_materialproviders.mpl.references import ICryptographicMaterialsManager, IKeyring
+from typing import Dict, List
+
+import aws_encryption_sdk
+from aws_encryption_sdk import CommitmentPolicy
+from aws_encryption_sdk.exceptions import AWSEncryptionSDKClientError
+
+# TODO-MPL: Remove this as part of removing PYTHONPATH hacks
+module_root_dir = '/'.join(__file__.split("/")[:-1])
+
+sys.path.append(module_root_dir)
+
+EXAMPLE_DATA: bytes = b"Hello World"
+
+
+def encrypt_and_decrypt_with_keyring(
+    kms_key_id: str
+):
+    """Creates a hierarchical keyring using the provided resources, then encrypts and decrypts a string with it."""
+    # 1. Instantiate the encryption SDK client.
+    #    This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
+    #    which enforces that this client only encrypts using committing algorithm suites and enforces
+    #    that this client will only decrypt encrypted messages that were created with a committing
+    #    algorithm suite.
+    #    This is the default commitment policy if you were to build the client as
+    #    `client = aws_encryption_sdk.EncryptionSDKClient()`.
+
+    client = aws_encryption_sdk.EncryptionSDKClient(
+        commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
+    )
+
+    # 2. Create an encryption context.
+    #    Most encrypted data should have an associated encryption context
+    #    to protect integrity. This sample uses placeholder values.
+    #    For more information see:
+    #    blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management  # noqa: E501
+    encryption_context: Dict[str, str] = {
+        "key1": "value1",
+        "key2": "value2",
+        "requiredKey1": "requiredValue1",
+        "requiredKey2": "requiredValue2",
+    }
+
+    # 3. Create list of required encryption context keys.
+    #    This is a list of keys that must be present in the encryption context.
+    required_encryption_context_keys: List[str] = ["requiredKey1", "requiredKey2"]
+
+    # 4. Create the AWS KMS keyring.
+    mpl: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
+        config=MaterialProvidersConfig()
+    )
+    keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
+        kms_key_id=kms_key_id,
+        kms_client=boto3.client('kms', region_name="us-west-2")
+    )
+    kms_keyring: IKeyring = mpl.create_aws_kms_keyring(keyring_input)
+
+    # 5. Create the required encryption context CMM.
+    underlying_cmm: ICryptographicMaterialsManager = \
+        mpl.create_default_cryptographic_materials_manager(
+            CreateDefaultCryptographicMaterialsManagerInput(
+                keyring=kms_keyring
+            )
+        )
+
+    required_ec_cmm: ICryptographicMaterialsManager = \
+        mpl.create_required_encryption_context_cmm(
+            CreateRequiredEncryptionContextCMMInput(
+                required_encryption_context_keys=required_encryption_context_keys,
+                underlying_cmm=underlying_cmm,
+            )
+        )
+
+    # 6. Encrypt the data
+    ciphertext, _ = client.encrypt(
+        source=EXAMPLE_DATA,
+        materials_manager=required_ec_cmm,
+        encryption_context=encryption_context
+    )
+
+    # 7. Reproduce the encryption context.
+    #    The reproduced encryption context MUST contain a value for
+    #    every key in the configured required encryption context keys during encryption with
+    #    Required Encryption Context CMM.
+    reproduced_encryption_context: Dict[str, str] = {
+        "requiredKey1": "requiredValue1",
+        "requiredKey2": "requiredValue2",
+    }
+
+    # 8. Decrypt the data
+    plaintext_bytes_A, _ = client.decrypt(
+        source=ciphertext,
+        materials_manager=required_ec_cmm,
+        encryption_context=reproduced_encryption_context
+    )
+    assert plaintext_bytes_A == EXAMPLE_DATA
+
+    # We can also decrypt using the underlying CMM,
+    # but must also provide the reproduced encryption context
+    plaintext_bytes_A, _ = client.decrypt(
+        source=ciphertext,
+        materials_manager=underlying_cmm,
+        encryption_context=reproduced_encryption_context
+    )
+    assert plaintext_bytes_A == EXAMPLE_DATA
+
+    # 9. Extra: Demonstrate that if we don't provide the reproduced encryption context,
+    #    decryption will fail.
+    try:
+        plaintext_bytes_A, _ = client.decrypt(
+            source=ciphertext,
+            materials_manager=required_ec_cmm,
+            # No reproduced encryption context for required EC CMM-produced message makes decryption fail.
+        )
+        raise Exception("If this exception is raised, decryption somehow succeeded!")
+    except AWSEncryptionSDKClientError:
+        # Swallow specific expected exception.
+        # We expect decryption to fail with an AWSEncryptionSDKClientError
+        # since we did not provide reproduced encryption context when decrypting
+        # a message encrypted with the requried encryption context CMM.
+        pass
+
+    # Same for the default CMM;
+    # If we don't provide the reproduced encryption context, decryption will fail.
+    try:
+        plaintext_bytes_A, _ = client.decrypt(
+            source=ciphertext,
+            materials_manager=required_ec_cmm,
+            # No reproduced encryption context for required EC CMM-produced message makes decryption fail.
+        )
+        raise Exception("If this exception is raised, decryption somehow succeeded!")
+    except AWSEncryptionSDKClientError:
+        # Swallow specific expected exception.
+        # We expect decryption to fail with an AWSEncryptionSDKClientError
+        # since we did not provide reproduced encryption context when decrypting
+        # a message encrypted with the requried encryption context CMM,
+        # even though we are using a default CMM on decrypt.
+        pass

examples/test/keyrings/test_i_hierarchical_keyring.py

@@ -1,6 +1,6 @@
 # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
-"""Unit test suite for the hierarchical keyring example."""
+"""Test suite for the hierarchical keyring example."""
 import pytest
 
 from ...src.keyrings.hierarchical_keyring import encrypt_and_decrypt_with_keyring

examples/test/keyrings/test_i_required_encryption_context_cmm.py

@@ -0,0 +1,13 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Test suite for the required encryption context CMM example."""
+import pytest
+
+from ...src.keyrings.required_encryption_context_cmm import encrypt_and_decrypt_with_keyring
+
+pytestmark = [pytest.mark.examples]
+
+
+def test_encrypt_and_decrypt_with_keyring():
+    key_arn = "arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f"
+    encrypt_and_decrypt_with_keyring(key_arn)

setup.py

@@ -40,7 +40,7 @@ def get_requirements():
     license="Apache License 2.0",
     install_requires=get_requirements(),
     # pylint: disable=fixme
-    # TODO: Point at PyPI once MPL is released.
+    # TODO-MPL: Point at PyPI once MPL is released.
     # This blocks releasing ESDK-Python MPL integration.
     extras_require={
         "MPL": ["aws-cryptographic-material-providers @" \

src/aws_encryption_sdk/__init__.py

@@ -185,6 +185,9 @@ def decrypt(self, **kwargs):
                 If source_length is not provided and read() is called, will attempt to seek()
                 to the end of the stream and tell() to find the length of source data.
 
+        :param dict encryption_context: Dictionary defining encryption context to validate
+            on decrypt. This is ONLY validated on decrypt if using a CMM from the
+            aws-cryptographic-material-providers library.
         :param int max_body_length: Maximum frame size (or content length for non-framed messages)
             in bytes to read from ciphertext message.
         :returns: Tuple containing the decrypted plaintext and the message header object