feat!: Updates to the AWS Encryption SDK.

This change includes fixes for issues that were reported by Thai Duong from Google's Security team, and
for issues that were identified by AWS Cryptography.

BREAKING CHANGE: AWS KMS KeyIDs must be specified explicitly or Discovery mode explicitly chosen.
Key committing suites are now default. CommitmentPolicy requires commitment by default.

See: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/migration.html

Author: farleyb-amazon

README.rst

@@ -96,8 +96,11 @@ Usage
 EncryptionSDKClient
 ===================
 To use this module, you (the caller) must first create an instance of the ``EncryptionSDKClient`` class.
-The constructor to this class requires a single keyword argument, ``commitment_policy``. There is
-currently only one valid value for this argument: ``FORBID_ENCRYPT_ALLOW_DECRYPT``.
+The constructor to this class accepts an optional keyword argument, ``commitment_policy``, that controls
+which algorithm suites can be used for encryption and decryption. If no value
+is provided for this argument, a default value of ``REQUIRE_ENCRYPT_REQUIRE_DECRYPT`` is used. Unless
+you have specialized performance requirements or are in the process of migrating from an older
+version of the AWS Encryption SDK, we recommend using the default value.
 
 .. code:: python
 
@@ -106,7 +109,7 @@ currently only one valid value for this argument: ``FORBID_ENCRYPT_ALLOW_DECRYPT
 
 
     client = aws_encryption_sdk.EncryptionSDKClient(
-        commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT
+        commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
     )
 
 

examples/src/basic_encryption.py

@@ -23,8 +23,9 @@ def cycle_string(key_arn, source_plaintext, botocore_session=None):
     :param botocore_session: existing botocore session instance
     :type botocore_session: botocore.session.Session
     """
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create a KMS master key provider
     kms_kwargs = dict(key_ids=[key_arn])

examples/src/basic_file_encryption_with_multiple_providers.py

@@ -76,8 +76,9 @@ def cycle_file(key_arn, source_plaintext_filename, botocore_session=None):
     cycled_kms_plaintext_filename = source_plaintext_filename + ".kms.decrypted"
     cycled_static_plaintext_filename = source_plaintext_filename + ".static.decrypted"
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create a KMS master key provider
     kms_kwargs = dict(key_ids=[key_arn])

examples/src/basic_file_encryption_with_raw_key_provider.py

@@ -53,8 +53,9 @@ def cycle_file(source_plaintext_filename):
 
     :param str source_plaintext_filename: Filename of file to encrypt
     """
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create a static random master key provider
     key_id = os.urandom(8)

examples/src/data_key_caching_basic.py

@@ -32,8 +32,9 @@ def encrypt_with_caching(kms_cmk_arn, max_age_in_cache, cache_capacity):
     # Create an encryption context
     encryption_context = {"purpose": "test"}
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create a master key provider for the KMS customer master key (CMK)
     key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(key_ids=[kms_cmk_arn])

examples/src/discovery_kms_provider.py

@@ -11,7 +11,7 @@
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
 """Example showing encryption of a value already in memory using one KMS CMK, then decryption of the ciphertext using
-a DiscoveryKMSMasterKeyProvider.
+a DiscoveryAwsKmsMasterKeyProvider.
 """
 import aws_encryption_sdk
 from aws_encryption_sdk import CommitmentPolicy
@@ -32,8 +32,9 @@ def encrypt_decrypt(key_arn, source_plaintext, botocore_session=None):
     if botocore_session is not None:
         encrypt_kwargs["botocore_session"] = botocore_session
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create strict master key provider that is only allowed to encrypt and decrypt using the ARN of the provided key.
     strict_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(**encrypt_kwargs)

examples/src/multiple_kms_cmk.py

@@ -28,8 +28,9 @@ def encrypt_decrypt(key_arns, source_plaintext, botocore_session=None):
     if botocore_session is not None:
         encrypt_kwargs["botocore_session"] = botocore_session
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create strict master key provider that is only allowed to encrypt and decrypt using the ARN of the provided key.
     strict_encrypt_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(**encrypt_kwargs)

examples/src/one_kms_cmk.py

@@ -28,8 +28,9 @@ def encrypt_decrypt(key_arn, source_plaintext, botocore_session=None):
     if botocore_session is not None:
         kwargs["botocore_session"] = botocore_session
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create master key provider using the ARN of the key and the session (botocore_session)
     kms_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(**kwargs)

examples/src/one_kms_cmk_streaming_data.py

@@ -32,8 +32,9 @@ def encrypt_decrypt_stream(key_arn, source_plaintext_filename, botocore_session=
     if botocore_session is not None:
         kwargs["botocore_session"] = botocore_session
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create master key provider using the ARN of the key and the session (botocore_session)
     kms_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(**kwargs)

examples/src/one_kms_cmk_unsigned.py

@@ -12,6 +12,8 @@
 # language governing permissions and limitations under the License.
 """Example showing basic encryption and decryption of a value already in memory
 using one AWS KMS CMK with an unsigned algorithm.
+
+Note: We recommend using an algorithm with signing as an AWS Encryption SDK best practice.
 """
 import aws_encryption_sdk
 from aws_encryption_sdk import StrictAwsKmsMasterKeyProvider
@@ -31,15 +33,16 @@ def encrypt_decrypt(key_arn, source_plaintext, botocore_session=None):
     if botocore_session is not None:
         kwargs["botocore_session"] = botocore_session
 
-    # Set up an encryption client with an explicit commitment policy
-    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
+    # Set up an encryption client with an explicit commitment policy. Note that if you do not explicitly choose a
+    # commitment policy, REQUIRE_ENCRYPT_REQUIRE_DECRYPT is used by default.
+    client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
 
     # Create master key provider using the ARN of the key and the session (botocore_session)
     kms_key_provider = StrictAwsKmsMasterKeyProvider(**kwargs)
 
     # Encrypt the plaintext using the AWS Encryption SDK. It returns the encrypted message and the header
     ciphertext, encrypted_message_header = client.encrypt(
-        algorithm=Algorithm.AES_256_GCM_IV12_TAG16_HKDF_SHA256, source=source_plaintext, key_provider=kms_key_provider
+        algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
     )
 
     # Decrypt the encrypted message using the AWS Encryption SDK. It returns the decrypted message and the header