docs: apply suggestions from code review

Co-Authored-By: June Blender <juneb@users.noreply.github.com>

Author: mattsb42-aws

examples/README.md

@@ -21,17 +21,17 @@ in the [`examples/src/`](./src) directory.
 
 ## Configuration
 
-To use the library APIs,
+To use the encryption and decryption APIs,
 you need to describe how you want the library to protect your data keys.
-You can do this using
+You can do this by configuring
 [keyrings](#keyrings) or [cryptographic materials managers](#cryptographic-materials-managers),
-or using [master key providers](#master-key-providers).
+or by configuring [master key providers](#master-key-providers).
 These examples will show you how to use the configuration tools that we include for you
-as well as how to create some of your own.
+and how to create some of your own.
 We start with AWS KMS examples, then show how to use other wrapping keys.
 
 * Using AWS Key Management Service (AWS KMS)
-    * How to use a single AWS KMS CMK
+    * How to use one AWS KMS CMK
         * [with keyrings](./src/keyring/aws_kms/single_cmk.py)
     * How to use multiple AWS KMS CMKs in different regions
         * [with keyrings](./src/keyring/aws_kms/multiple_regions.py)

examples/src/keyring/aws_kms/custom_client_supplier.py

@@ -5,8 +5,8 @@
 supplies a client with the same configuration for every region.
 If you need different behavior, you can write your own client supplier.
 
-One use-case where you might need this is
-if you need different credentials to talk to different AWS regions.
+You might use this 
+if you need different credentials in different AWS regions.
 This might be because you are crossing partitions (ex: ``aws`` and ``aws-cn``)
 or if you are working with regions that have separate authentication silos
 like ``ap-east-1`` and ``me-south-1``.
@@ -38,7 +38,7 @@
 try:  # Python 3.5.0 and 3.5.1 have incompatible typing modules
     from typing import Union  # noqa pylint: disable=unused-import
 except ImportError:  # pragma: no cover
-    # We only actually need these imports when running the mypy checks
+    # We only need these imports when running the mypy checks
     pass
 
 

examples/src/keyring/aws_kms/custom_kms_client_config.py

@@ -1,10 +1,10 @@
 # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 """
-By default, the KMS keyring will use the default configurations
-for all KMS clients and will use the default discoverable credentials.
-If you need to change these configurations,
-you can do that using the client supplier.
+By default, the KMS keyring uses the default configurations
+for all KMS clients and uses the default discoverable credentials.
+If you need to change this configuration,
+you can configure the client supplier.
 
 This example shows how to use custom-configured clients with the KMS keyring.
 
@@ -73,8 +73,8 @@ def run(aws_kms_cmk, source_plaintext):
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
     #
-    # We do not need to specify the encryption context on decrypt
-    # because the header message includes the encryption context.
+    # You do not need to specify the encryption context on decrypt
+    # because the header of the encrypted message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
     # Demonstrate that the decrypted plaintext is identical to the original plaintext.

examples/src/keyring/aws_kms/discovery_decrypt.py

@@ -4,12 +4,12 @@
 When you give the KMS keyring specific key IDs it will use those CMKs and nothing else.
 This is true both on encrypt and on decrypt.
 However, sometimes you need more flexibility on decrypt,
-especially if you might not know beforehand which CMK was used to encrypt a message.
+especially when you don't know which CMKs were used to encrypt a message.
 To address this need, you can use a KMS discovery keyring.
-The KMS discovery keyring will do nothing on encrypt
-but will attempt to decrypt *any* data keys that were encrypted under a KMS CMK.
+The KMS discovery keyring does nothing on encrypt,
+but attempts to decrypt *any* data keys that were encrypted under a KMS CMK.
 
-This example shows how to configure and use a KMS keyring in discovery mode.
+This example shows how to configure and use a KMS discovery keyring.
 
 https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html#use-kms-keyring
 
@@ -20,7 +20,7 @@
 see the ``keyring/aws_kms/custom_client_supplier``
 and ``keyring/aws_kms/custom_kms_client_config`` examples.
 
-For examples of how to use the KMS keyring in discovery mode on decrypt,
+For examples of how to use the KMS discovery keyring on decrypt,
 see the ``keyring/aws_kms/discovery_decrypt_in_region_only``
 and ``keyring/aws_kms/discovery_decrypt_with_preferred_region`` examples.
 """
@@ -30,7 +30,7 @@
 
 def run(aws_kms_cmk, source_plaintext):
     # type: (str, bytes) -> None
-    """Demonstrate configuring a KMS keyring to use discovery mode for decryption.
+    """Demonstrate configuring a KMS discovery keyring for decryption.
 
     :param str aws_kms_cmk: The ARN of an AWS KMS CMK that protects data keys
     :param bytes source_plaintext: Plaintext to encrypt
@@ -48,7 +48,7 @@ def run(aws_kms_cmk, source_plaintext):
     # Create the keyring that determines how your data keys are protected.
     encrypt_keyring = KmsKeyring(generator_key_id=aws_kms_cmk)
 
-    # Create the KMS discovery keyring that we will use on decrypt.
+    # Create a KMS discovery keyring to use on decrypt.
     #
     # Because we do not specify any key IDs, this keyring is created in discovery mode.
     decrypt_keyring = KmsKeyring()
@@ -63,8 +63,8 @@ def run(aws_kms_cmk, source_plaintext):
 
     # Decrypt your encrypted data using the KMS discovery keyring.
     #
-    # We do not need to specify the encryption context on decrypt
-    # because the header message includes the encryption context.
+    # You do not need to specify the encryption context on decrypt
+    # because the header of the encrypted message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=decrypt_keyring)
 
     # Demonstrate that the decrypted plaintext is identical to the original plaintext.

examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

@@ -4,13 +4,13 @@
 When you give the KMS keyring specific key IDs it will use those CMKs and nothing else.
 This is true both on encrypt and on decrypt.
 However, sometimes you need more flexibility on decrypt,
-especially if you might not know beforehand which CMK was used to encrypt a message.
+especially if you don't know which CMK was used to encrypt a message.
 To address this need, you can use a KMS discovery keyring.
-The KMS discovery keyring will do nothing on encrypt
-but will attempt to decrypt *any* data keys that were encrypted under a KMS CMK.
+The KMS discovery keyring does nothing on encrypt
+but attempts to decrypt *any* data keys that were encrypted under a KMS CMK.
 
 However, sometimes you need to be a *bit* more restrictive than that.
-To address this need, you can use a client supplier to restrict what regions a KMS keyring can talk to.
+To address this need, you can use a client supplier that restricts the regions a KMS keyring can talk to.
 
 This example shows how to configure and use a KMS regional discovery keyring that is restricted to one region.