Apply suggestions from code review

Co-Authored-By: June Blender <[email protected]>

Author: mattsb42-aws

examples/README.md

@@ -1,9 +1,9 @@
 # AWS Encryption SDK Examples
 
-Here you can find some examples that show you
+This section features examples that show you
 how to use the AWS Encryption SDK.
-We demonstrate how to use the high-level APIs
-as well as how to set up some common configuration patterns.
+We demonstrate how to use the encryption and decryption APIs
+and how to set up some common configuration patterns.
 
 ## APIs
 
@@ -17,24 +17,24 @@ in the [`examples/src/`](./src) directory root.
 ## Configuration
 
 In order to use the library APIs,
-you must provide some configuration that defines
+you must provide a configuration that defines
 how you want to protect your data keys.
 
 ### Keyrings
 
-Keyrings are the most common way for you to configure that AWS Encryption SDK.
-These let you define how you want the AWS Encryption SDK to protect your data keys.
+Keyrings are the most common way for you to configure the AWS Encryption SDK.
+They determine how the AWS Encryption SDK protects your data.
 You can find these examples in [`examples/src/keyring`](./src/keyring).
 
 ### Cryptographic Materials Managers
 
-Keyrings define how you want to protect your data keys,
-but there is more going on here than just data keys.
+Keyrings define how your data keys are protected,
+but there is more going on here than just protecting data keys.
 
 Cryptographic materials managers give you higher-level controls
 over how the AWS Encryption SDK protects your data.
 This can include things like
-enforcing certain algorithm suites or encryption context settings,
+enforcing the use of certain algorithm suites or encryption context settings,
 reusing data keys across messages,
 or changing how you interact with keyrings.
 You can find these examples in
@@ -53,17 +53,15 @@ you can find these examples in [`examples/src/master_key_provider`](./src/master
 
 ## Legacy
 
-These are any examples that were already defined
-before we started revamping our examples.
-We are keeping them around for anyone who needs them as reference material,
+This section includes older examples, including examples of using master keys and master key providers in Java and Python.
+You can use them as a reference,
 but we recommend looking at the newer examples
-that should provide a clearer picture of how to use this library.
+but we recommend looking at the newer examples, which explain the preferred ways of using this library.
 You can find these examples in [`examples/src/legacy`](./src/legacy).
 
 # Writing Examples
 
-If you want to write a new example, that's awesome!
-There are a couple things you need to keep in mind, though.
+If you want to contribute a new example, that's awesome!
 To make sure that your example is tested in our CI,
 please make sure that it meets the following requirements:
 

examples/src/file_streaming_defaults.py

@@ -3,7 +3,7 @@
 """
 This example shows how to use the streaming encrypt and decrypt APIs when working with files.
 
-For the purposes of this example, we demonstrate using AWS KMS,
+This example uses an AWS KMS CMK,
 but you can use other key management options with the AWS Encryption SDK.
 Look in the ``keyring`` and ``master_key_provider`` directories
 for examples that demonstrate how to use other key management configurations.
@@ -21,7 +21,7 @@ def run(aws_kms_cmk, source_plaintext_filename):
     :param str aws_kms_cmk: AWS KMS CMK ARN to use to protect data keys
     :param str source_plaintext_filename: Path to plaintext file to encrypt
     """
-    # We assume that you can also write in the directory containing the plaintext file,
+    # We assume that you can also write to the directory containing the plaintext file,
     # so that is where we will put all of the results.
     ciphertext_filename = source_plaintext_filename + ".encrypted"
     decrypted_filename = ciphertext_filename + ".decrypted"
@@ -35,13 +35,13 @@ def run(aws_kms_cmk, source_plaintext_filename):
         "the data you are handling": "is what you think it is",
     }
 
-    # Create the keyring that determines how your keys are protected.
+    # Create the keyring that determines how your data keys are protected.
     keyring = KmsKeyring(generator_key_id=aws_kms_cmk)
 
     # Open the files you want to work with.
     with open(source_plaintext_filename, "rb") as plaintext, open(ciphertext_filename, "wb") as ciphertext:
-        # The streaming API provides you with a context manager
-        # that you can read from similar to how you would read from a file.
+        # The streaming API provides a context manager.
+        # You can read from it just as you read from a file.
         with aws_encryption_sdk.stream(
             mode="encrypt", source=plaintext, encryption_context=encryption_context, keyring=keyring
         ) as encryptor:
@@ -63,17 +63,17 @@ def run(aws_kms_cmk, source_plaintext_filename):
             # One benefit of using the streaming API is that
             # we can check the encryption context in the header before we start decrypting.
             #
-            # Verify that the encryption context used in the decrypt operation matches what you expect.
+            # Verify that the encryption context used in the decrypt operation includes the encryption context that you specified when encrypting.
             # The AWS Encryption SDK can add pairs, so don't require an exact match.
             #
             # In production, always use a meaningful encryption context.
             assert set(encryption_context.items()) <= set(decryptor.header.encryption_context.items())
 
-            # Now that we are confident that the message is what we think it should be,
+            # Now that we are more confident that we will decrypt the right message,
             # we can start decrypting.
             for chunk in decryptor:
                 decrypted.write(chunk)
 
-    # Verify that the "cycled" (encrypted then decrypted) plaintext
+    # Verify that the decrypted plaintext
     # is identical to the original plaintext.
     assert filecmp.cmp(source_plaintext_filename, decrypted_filename)