chore(migration examples): added KMS, raw AES and raw RSA keyring/MKP…

examples/src/migration/README.rst

@@ -0,0 +1,19 @@
+##################
+Migration Examples
+##################
+
+The `Encryption SDK for Python`_ now uses the `AWS Cryptographic Material Providers Library`_,
+which introduces keyrings in place of Master Key Providers. The MPL abstracts lower
+level cryptographic materials management of encryption and decryption materials.
+
+This directory contains some examples to migrate from the old version of the ESDK.
+If you have messages encrypted in the older versions using Master Key Providers,
+these examples can guide you on how to decrypt those messages using the new version
+of the ESDK. Here is the list of examples:
+1. Migration example for AWS KMS keys
+2. Migration example for Raw AES keys
+3. Migration example for Raw RSA keys
+4. Setting a 'CommitmentPolicy' during migration
+
+.. _AWS Cryptographic Material Providers Library: https://github.com/aws/aws-cryptographic-material-providers-library
+.. _Encryption SDK for Python: https://github.com/aws/aws-encryption-sdk-python/tree/9c34aad60fc918c1a9186ec5215a451e8bfd0f65

examples/src/migration/migration_aws_kms_key_example.py

@@ -0,0 +1,166 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+This is a migration example for moving to the AWS KMS Keyring from AWS KMS master key provider (MKP)
+
+The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
+decrypt data keys. This example creates a KMS Keyring and KMS MKP and
+then encrypts a custom input EXAMPLE_DATA with the same encryption context using both
+the keyring and MKP. The example then decrypts the ciphertexts using both keyring and MKPs.
+This example also includes some sanity checks for demonstration:
+1. Decryption of these ciphertexts encrypted using keyring and MKP
+   is possible using both KMS keyring and KMS MKP
+2. Both decrypted plaintexts are same and match EXAMPLE_DATA
+These sanity checks are for demonstration in the example only. You do not need these in your code.
+
+Note: The ciphertexts obtained by encrypting EXAMPLE_DATA using keyring and MKP are not
+the same because the ESDK generates different data keys each time for encryption of the data.
+But both ciphertexts when decrypted using keyring and MKP should give the same plaintext result.
+
+For more information on how to use KMS keyrings, see
+https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/use-kms-keyring.html
+"""
+import boto3
+from aws_cryptographic_materialproviders.mpl import AwsCryptographicMaterialProviders
+from aws_cryptographic_materialproviders.mpl.config import MaterialProvidersConfig
+from aws_cryptographic_materialproviders.mpl.models import CreateAwsKmsKeyringInput
+from aws_cryptographic_materialproviders.mpl.references import IKeyring
+from typing import Dict  # noqa pylint: disable=wrong-import-order
+
+import aws_encryption_sdk
+
+EXAMPLE_DATA: bytes = b"Hello World"
+
+DEFAULT_ENCRYPTION_CONTEXT : Dict[str, str] = {
+    "encryption": "context",
+    "is not": "secret",
+    "but adds": "useful metadata",
+    "that can help you": "be confident that",
+    "the data you are handling": "is what you think it is",
+}
+
+
+def create_keyring(
+    kms_key_id: str,
+    aws_region="us-west-2"
+):
+    """Demonstrate how to create an AWS KMS keyring.
+
+    Usage: create_keyring(kms_key_id)
+    :param kms_key_id: KMS Key identifier for the KMS key you want to use.
+    :type kms_key_id: string
+
+    For more information on KMS Key identifiers, see
+    https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id
+    """
+    # Create a boto3 client for KMS.
+    kms_client = boto3.client('kms', region_name=aws_region)
+
+    # Create a KMS keyring
+    mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
+        config=MaterialProvidersConfig()
+    )
+
+    keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
+        kms_key_id=kms_key_id,
+        kms_client=kms_client
+    )
+
+    keyring: IKeyring = mat_prov.create_aws_kms_keyring(
+        input=keyring_input
+    )
+
+    return keyring
+
+
+def create_key_provider(
+    kms_key_id: str
+):
+    """Demonstrate how to create an AWS KMS master key provider.
+
+    Usage: create_key_provider(kms_key_id)
+    :param kms_key_id: KMS Key identifier for the KMS key you want to use.
+    :type kms_key_id: string
+
+    For more information on KMS Key identifiers, see
+    https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id
+    """
+    # Create a KMS master key provider.
+    key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(key_ids=[
+        kms_key_id,
+    ])
+
+    return key_provider
+
+
+def migration_aws_kms_key(
+    kms_key_id: str
+):
+    """Demonstrate a migration example for moving to an AWS KMS keyring from AWS KMS MKP.
+
+    Usage: migration_aws_kms_key(kms_key_id)
+    :param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
+    decryption of your data keys.
+    :type kms_key_id: string
+
+    For more information on KMS Key identifiers, see
+    https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id
+    """
+    client = aws_encryption_sdk.EncryptionSDKClient()
+
+    # 1a. Create a AWS KMS Keyring
+    aws_kms_keyring = create_keyring(kms_key_id=kms_key_id)
+
+    # 1b. Create a AWS KMS Master Key Provider
+    aws_kms_master_key_provider = create_key_provider(kms_key_id=kms_key_id)
+
+    # 2a. Encrypt EXAMPLE_DATA using AWS KMS Keyring
+    ciphertext_keyring, _ = client.encrypt(
+        source=EXAMPLE_DATA,
+        keyring=aws_kms_keyring,
+        encryption_context=DEFAULT_ENCRYPTION_CONTEXT
+    )
+
+    # 2b. Encrypt EXAMPLE_DATA using AWS KMS Master Key Provider
+    ciphertext_mkp, _ = client.encrypt(
+        source=EXAMPLE_DATA,
+        key_provider=aws_kms_master_key_provider,
+        encryption_context=DEFAULT_ENCRYPTION_CONTEXT
+    )
+
+    # Note: The ciphertexts obtained by encrypting EXAMPLE_DATA using keyring and MKP
+    # (that is ciphertext_keyring and ciphertext_mkp) are not the same because the ESDK
+    # generates different data keys each time for encryption of the data. But both
+    # ciphertexts when decrypted using keyring and MKP should give the same plaintext result.
+
+    # 3. Decrypt the ciphertext_keyring using both the keyring and MKP and ensure the
+    # resulting plaintext is the same and also equal to EXAMPLE_DATA
+    decrypted_ciphertext_keyring_using_keyring, _ = client.decrypt(
+        source=ciphertext_keyring,
+        keyring=aws_kms_keyring
+    )
+
+    decrypted_ciphertext_keyring_using_mkp, _ = client.decrypt(
+        source=ciphertext_keyring,
+        key_provider=aws_kms_master_key_provider
+    )
+
+    assert decrypted_ciphertext_keyring_using_keyring == decrypted_ciphertext_keyring_using_mkp \
+        and decrypted_ciphertext_keyring_using_keyring == EXAMPLE_DATA, \
+        "Decrypted outputs using keyring and master key provider are not the same"
+
+    # 4. Decrypt the ciphertext_mkp using both the keyring and MKP and ensure the
+    # resulting plaintext is the same and also equal to EXAMPLE_DATA
+    decrypted_ciphertext_mkp_using_keyring, _ = client.decrypt(
+        source=ciphertext_mkp,
+        keyring=aws_kms_keyring
+    )
+
+    decrypted_ciphertext_mkp_using_mkp, _ = client.decrypt(
+        source=ciphertext_mkp,
+        key_provider=aws_kms_master_key_provider
+    )
+
+    assert decrypted_ciphertext_mkp_using_keyring == decrypted_ciphertext_mkp_using_mkp \
+        and decrypted_ciphertext_mkp_using_keyring == EXAMPLE_DATA, \
+        "Decrypted outputs using keyring and master key provider are not the same"

examples/src/migration/migration_raw_aes_key_example.py

@@ -0,0 +1,193 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+This is a migration example for moving to the Raw AES Keyring from Raw AES master key provider (MKP)
+
+The Raw AES keyring lets you use an AES symmetric key that you provide as a wrapping key that
+protects your data key. You need to generate, store, and protect the key material,
+preferably in a hardware security module (HSM) or key management system. Use a Raw AES keyring
+when you need to provide the wrapping key and encrypt the data keys locally or offline.
+
+This example creates a Raw AES Keyring and Raw AES MKP and
+then encrypts a custom input EXAMPLE_DATA with the same encryption context using both
+the keyring and MKP. The example then decrypts the ciphertexts using both keyring and MKPs.
+This example also includes some sanity checks for demonstration:
+1. Decryption of these ciphertexts encrypted using keyring and MKP
+   is possible using both Raw AES keyring and Raw AES MKP
+2. Both decrypted plaintexts are same and match EXAMPLE_DATA
+These sanity checks are for demonstration in the example only. You do not need these in your code.
+
+Note: The ciphertexts obtained by encrypting EXAMPLE_DATA using keyring and MKP are not
+the same because the ESDK generates different data keys each time for encryption of the data.
+But both ciphertexts when decrypted using keyring and MKP should give the same plaintext result.
+
+For more information on how to use Raw AES keyrings, see
+https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/use-raw-aes-keyring.html
+"""
+import secrets
+
+from aws_cryptographic_materialproviders.mpl import AwsCryptographicMaterialProviders
+from aws_cryptographic_materialproviders.mpl.config import MaterialProvidersConfig
+from aws_cryptographic_materialproviders.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
+from aws_cryptographic_materialproviders.mpl.references import IKeyring
+from typing import Dict  # noqa pylint: disable=wrong-import-order
+
+import aws_encryption_sdk
+from aws_encryption_sdk.identifiers import EncryptionKeyType, WrappingAlgorithm
+from aws_encryption_sdk.internal.crypto.wrapping_keys import WrappingKey
+from aws_encryption_sdk.key_providers.raw import RawMasterKeyProvider
+
+EXAMPLE_DATA: bytes = b"Hello World"
+
+DEFAULT_ENCRYPTION_CONTEXT : Dict[str, str] = {
+    "encryption": "context",
+    "is not": "secret",
+    "but adds": "useful metadata",
+    "that can help you": "be confident that",
+    "the data you are handling": "is what you think it is",
+}
+
+DEFAULT_AES_256_STATIC_KEY = secrets.token_bytes(32)
+
+DEFAULT_KEY_NAME_SPACE = "Some managed raw keys"
+
+DEFAULT_KEY_NAME = "My 256-bit AES wrapping key"
+
+
+def create_keyring():
+    """Demonstrate how to create a Raw AES keyring.
+
+    Usage: create_keyring()
+    """
+    # We fix the static key in order to make the test deterministic
+    static_key = DEFAULT_AES_256_STATIC_KEY
+
+    mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
+        config=MaterialProvidersConfig()
+    )
+
+    keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
+        key_namespace=DEFAULT_KEY_NAME_SPACE,
+        key_name=DEFAULT_KEY_NAME,
+        wrapping_key=static_key,
+        wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
+    )
+
+    keyring: IKeyring = mat_prov.create_raw_aes_keyring(
+        input=keyring_input
+    )
+
+    return keyring
+
+
+# This is a helper class necessary for the Raw AES master key provider
+class StaticRandomMasterKeyProvider(RawMasterKeyProvider):
+    """Generates 256-bit keys for each unique key ID."""
+
+    # The Provider ID (or Provider) field in the JceMasterKey and RawMasterKey is
+    # equivalent to key namespace in the Raw keyrings
+    provider_id = DEFAULT_KEY_NAME_SPACE
+
+    def __init__(self, **kwargs):  # pylint: disable=unused-argument
+        """Initialize empty map of keys."""
+        self._static_keys = {}
+
+    def _get_raw_key(self, key_id):
+        """Returns a static, randomly-generated symmetric key for the specified key ID.
+
+        :param str key_id: Key ID
+        :returns: Wrapping key that contains the specified static key
+        :rtype: :class:`aws_encryption_sdk.internal.crypto.WrappingKey`
+        """
+        try:
+            static_key = self._static_keys[key_id]
+        except KeyError:
+            # We fix the static key in order to make the test deterministic
+            # In practice, you should get this key from a secure key management system such as an HSM.
+            static_key = DEFAULT_AES_256_STATIC_KEY
+            self._static_keys[key_id] = static_key
+        return WrappingKey(
+            wrapping_algorithm=WrappingAlgorithm.AES_256_GCM_IV12_TAG16_NO_PADDING,
+            wrapping_key=static_key,
+            wrapping_key_type=EncryptionKeyType.SYMMETRIC,
+        )
+
+
+def create_key_provider():
+    """Demonstrate how to create a Raw AES master key provider.
+
+    Usage: create_key_provider()
+    """
+    # Create a Raw AES master key provider.
+
+    # The Key ID field in the JceMasterKey and RawMasterKey is equivalent to key name in the Raw keyrings
+    key_id = DEFAULT_KEY_NAME
+    key_provider = StaticRandomMasterKeyProvider()
+    key_provider.add_master_key(key_id)
+
+    return key_provider
+
+
+def migration_raw_aes_key():
+    """Demonstrate a migration example for moving to a Raw AES keyring from Raw AES MKP.
+
+    Usage: migration_raw_aes_key()
+    """
+    client = aws_encryption_sdk.EncryptionSDKClient()
+
+    # 1a. Create a Raw AES Keyring
+    raw_aes_keyring = create_keyring()
+
+    # 1b. Create a Raw AES Master Key Provider
+    raw_aes_master_key_provider = create_key_provider()
+
+    # 2a. Encrypt EXAMPLE_DATA using Raw AES Keyring
+    ciphertext_keyring, _ = client.encrypt(
+        source=EXAMPLE_DATA,
+        keyring=raw_aes_keyring,
+        encryption_context=DEFAULT_ENCRYPTION_CONTEXT
+    )
+
+    # 2b. Encrypt EXAMPLE_DATA using Raw AES Master Key Provider
+    ciphertext_mkp, _ = client.encrypt(
+        source=EXAMPLE_DATA,
+        key_provider=raw_aes_master_key_provider,
+        encryption_context=DEFAULT_ENCRYPTION_CONTEXT
+    )
+
+    # Note: The ciphertexts obtained by encrypting EXAMPLE_DATA using keyring and MKP
+    # (that is ciphertext_keyring and ciphertext_mkp) are not the same because the ESDK
+    # generates different data keys each time for encryption of the data. But both
+    # ciphertexts when decrypted using keyring and MKP should give the same plaintext result.
+
+    # 3. Decrypt the ciphertext_keyring using both the keyring and MKP and ensure the
+    # resulting plaintext is the same and also equal to EXAMPLE_DATA
+    decrypted_ciphertext_keyring_using_keyring, _ = client.decrypt(
+        source=ciphertext_keyring,
+        keyring=raw_aes_keyring
+    )
+
+    decrypted_ciphertext_keyring_using_mkp, _ = client.decrypt(
+        source=ciphertext_keyring,
+        key_provider=raw_aes_master_key_provider
+    )
+
+    assert decrypted_ciphertext_keyring_using_keyring == decrypted_ciphertext_keyring_using_mkp \
+        and decrypted_ciphertext_keyring_using_keyring == EXAMPLE_DATA, \
+        "Decrypted outputs using keyring and master key provider are not the same"
+
+    # 4. Decrypt the ciphertext_mkp using both the keyring and MKP and ensure the
+    # resulting plaintext is the same and also equal to EXAMPLE_DATA
+    decrypted_ciphertext_mkp_using_keyring, _ = client.decrypt(
+        source=ciphertext_mkp,
+        keyring=raw_aes_keyring
+    )
+
+    decrypted_ciphertext_mkp_using_mkp, _ = client.decrypt(
+        source=ciphertext_mkp,
+        key_provider=raw_aes_master_key_provider
+    )
+
+    assert decrypted_ciphertext_mkp_using_keyring == decrypted_ciphertext_mkp_using_mkp \
+        and decrypted_ciphertext_mkp_using_keyring == EXAMPLE_DATA, \
+        "Decrypted outputs using keyring and master key provider are not the same"