Wording changes based on feedback

Author: WesleyRosenblum

src/examples/README.md

@@ -16,17 +16,17 @@ in the [`examples`](./java/com/amazonaws/crypto/examples) 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](./java/com/amazonaws/crypto/examples/keyring/awskms/SingleCmk.java)
     * How to use multiple AWS KMS CMKs in different regions
         * [with keyrings](./java/com/amazonaws/crypto/examples/keyring/awskms/MultipleRegions.java)

src/examples/java/com/amazonaws/crypto/examples/InMemoryStreamingDefaults.java

@@ -73,8 +73,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoInputStream decryptingStream = awsEncryptionSdk.createDecryptingInputStream(
                 CreateDecryptingInputStreamRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/OneStepDefaults.java

@@ -60,8 +60,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/OneStepUnsigned.java

@@ -74,8 +74,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/CustomClientSupplier.java

@@ -24,8 +24,8 @@
  * supplies a client with the same configuration for every region.
  * If you need different behavior, you can write your own client supplier.
  * <p>
- * 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".
@@ -116,8 +116,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/CustomKmsClientConfig.java

@@ -20,10 +20,10 @@
 import java.util.Map;
 
 /**
- * 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.
  * <p>
  * This example shows how to use custom-configured clients with the KMS keyring.
  * <p>
@@ -95,8 +95,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecrypt.java

@@ -19,10 +19,10 @@
  * 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.
  * <p>
  * This example shows how to configure and use a KMS discovery keyring.
  * <p>
@@ -63,7 +63,7 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
         // Create the keyring that determines how your data keys are protected.
         final Keyring encryptKeyring = StandardKeyrings.awsKms(awsKmsCmk);
 
-        // Create the KMS discovery keyring that we will use on decrypt.
+        // Create a KMS discovery keyring to use on decrypt.
         final Keyring decryptKeyring = StandardKeyrings.awsKmsDiscoveryBuilder().build();
 
         // Encrypt your plaintext data.
@@ -79,8 +79,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(decryptKeyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptInRegionOnly.java

@@ -23,13 +23,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.
  * <p>
  * 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.
  * <p>
  * This example shows how to configure and use a KMS regional discovery keyring that is restricted to one region.
  * <p>
@@ -95,8 +95,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(decryptKeyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/DiscoveryDecryptWithPreferredRegions.java

@@ -111,8 +111,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // Decrypt your encrypted data using the multi-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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(decryptKeyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/MultipleRegions.java

@@ -92,8 +92,8 @@ public static void run(final AwsKmsCmkId awsKmsGeneratorCmk, final List<AwsKmsCm
 
         // Decrypt your encrypted data separately using the single-CMK keyrings.
         //
-        // 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.
         final AwsCryptoResult<byte[]> decryptResult1 = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(singleCmkKeyringThatGenerated)

src/examples/java/com/amazonaws/crypto/examples/keyring/awskms/SingleCmk.java

@@ -69,8 +69,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/multi/AwsKmsWithEscrow.java

@@ -119,8 +119,8 @@ public static void run(final AwsKmsCmkId awsKmsCmk, final byte[] sourcePlaintext
 
         // Decrypt your encrypted data separately using the KMS keyring and the escrow decrypt 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.
         final AwsCryptoResult<byte[]> decryptedKmsResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(kmsKeyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/rawaes/RawAes.java

@@ -78,8 +78,8 @@ public static void run(final byte[] sourcePlaintext) {
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/rawrsa/PublicPrivateKeySeparate.java

@@ -124,8 +124,8 @@ public static void run(final byte[] sourcePlaintext) throws GeneralSecurityExcep
 
         // Decrypt your encrypted data using the decrypt 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(privateKeyKeyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/rawrsa/RawRsa.java

@@ -89,8 +89,8 @@ public static void run(final byte[] sourcePlaintext) throws GeneralSecurityExcep
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)

src/examples/java/com/amazonaws/crypto/examples/keyring/rawrsa/RawRsaDerEncoded.java

@@ -111,8 +111,8 @@ public static void run(final byte[] sourcePlaintext) throws GeneralSecurityExcep
 
         // 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.
         final AwsCryptoResult<byte[]> decryptResult = awsEncryptionSdk.decrypt(
                 DecryptRequest.builder()
                         .keyring(keyring)