Updating wording

Author: WesleyRosenblum

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

@@ -78,14 +78,17 @@ static void encryptAndDecrypt(final AwsKmsCmkId keyArn) {
                         .keyring(keyring)
                         .ciphertext(ciphertext).build());
 
-        // 6. The Keyring Trace may be inspected to verify which CMK was used for decryption.
+        // 6. To verify the CMK that was actually used in the decrypt operation, inspect the keyring trace.
         if(!decryptResult.getKeyringTrace().getEntries().get(0).getKeyName().equals(keyArn.toString())) {
             throw new IllegalStateException("Wrong key ID!");
         }
 
-        // 7. Verify that the encryption context in the result contains the
-        //    data that we expect. The SDK can add values to the encryption context,
-        //    so there may be additional keys in the result context.
+        // 7.  To verify that the encryption context used to decrypt the data was the encryption context you expected,
+        //     examine the encryption context in the result. This helps to ensure that you decrypted the ciphertext that
+        //     you intended.
+        //
+        //     When verifying, test that your expected encryption context is a subset of the actual encryption context,
+        //     not an exact match. The Encryption SDK adds the signing key to the encryption context when appropriate.
         assert decryptResult.getEncryptionContext().get("ExampleContextKey").equals("ExampleContextValue");
 
         // 8. Verify that the decrypted plaintext matches the original plaintext

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

@@ -64,7 +64,7 @@ static void encryptAndDecrypt(final File srcFile, final File encryptedFile, fina
         final AwsCrypto crypto = new AwsCrypto();
 
         // 2. Get an encryption key. In this example, we generate a random key.
-        //    In practice, you would get a key from an existing key store
+        //    In practice, you would get a key from an existing key store.
         final SecretKey cryptoKey = generateEncryptKey();
 
         // 3. Instantiate a RawAesKeyring using the random key
@@ -104,11 +104,12 @@ static void encryptAndDecrypt(final File srcFile, final File encryptedFile, fina
                         .keyring(keyring)
                         .inputStream(new FileInputStream(encryptedFile)).build())) {
 
-            // 8. Verify that the encryption context in the result contains the
-            //    encryption context supplied to the createEncryptingStream method.
-            if (!"FileStreaming".equals(decryptingStream.getAwsCryptoResult().getEncryptionContext().get("Example"))) {
-                throw new IllegalStateException("Bad encryption context");
-            }
+            // 8. Verify that the encryption context that was used to decrypt the data is the one that you expect.
+            //    This helps to ensure that the ciphertext that you decrypted was the one that you intended.
+            //
+            //    When verifying, test that your expected encryption context is a subset of the actual encryption context,
+            //    not an exact match. When appropriate, the Encryption SDK adds the signing key to the encryption context.
+            assert "FileStreaming".equals(decryptingStream.getAwsCryptoResult().getEncryptionContext().get("Example"));
 
             // 9. Copy the plaintext data to a file
             try (FileOutputStream out = new FileOutputStream(decryptedFile)) {
@@ -122,7 +123,7 @@ static void encryptAndDecrypt(final File srcFile, final File encryptedFile, fina
 
     /**
      * In practice, this key would be saved in a secure location.
-     * For this demo, we generate a new random key for each operation.
+     * In this example, we generate a new random key for each operation.
      */
     private static SecretKey generateEncryptKey() {
         SecureRandom rnd = new SecureRandom();

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

@@ -50,7 +50,7 @@ static void encryptAndDecrypt() {
         final SecretKey cryptoKey = generateEncryptKey();
 
         // 3. Instantiate a Raw AES Keyring with the encryption key
-        final Keyring keyring = StandardKeyrings.rawAes()
+        final Keyring keyring = StandardKeyrings.rawAesBuilder()
                 .keyNamespace("ExampleKeyNamespace")
                 .keyName("ExampleKeyName")
                 .wrappingKey(cryptoKey).build();
@@ -76,9 +76,11 @@ static void encryptAndDecrypt() {
                 .keyring(keyring)
                 .ciphertext(ciphertext).build());
 
-        // 7. Verify that the encryption context in the result contains the
-        // data that we expect. The SDK can add values to the encryption context,
-        // so there may be additional keys in the result context.
+        // 7. Verify that the encryption context that was used to decrypt the data is the one that you expect.
+        //    This helps to ensure that the ciphertext that you decrypted was the one that you intended.
+        //
+        //    When verifying, test that your expected encryption context is a subset of the actual encryption context,
+        //    not an exact match. When appropriate, the Encryption SDK adds the signing key to the encryption context.
         assert decryptResult.getEncryptionContext().get("ExampleContextKey").equals("ExampleContextValue");
 
         // 8. Verify that the decrypted plaintext matches the original plaintext

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

@@ -32,7 +32,7 @@ public static byte[] decrypt(byte[] ciphertext, KeyPair keyPair) {
         final AwsCrypto crypto = new AwsCrypto();
 
         // 2. Instantiate a Raw RSA Keyring with the private key
-        final Keyring keyring = StandardKeyrings.rawRsa()
+        final Keyring keyring = StandardKeyrings.rawRsaBuilder()
                 .keyNamespace("ExampleKeyNamespace")
                 .keyName("ExampleKeyName")
                 .wrappingAlgorithm("RSA/ECB/OAEPWithSHA-512AndMGF1Padding")
@@ -43,9 +43,11 @@ public static byte[] decrypt(byte[] ciphertext, KeyPair keyPair) {
                 .keyring(keyring)
                 .ciphertext(ciphertext).build());
 
-        // 4. Verify that the encryption context in the result contains the
-        // data that we expect. The SDK can add values to the encryption context,
-        // so there may be additional keys in the result context.
+        // 4. Verify that the encryption context that was used to decrypt the data is the one that you expect.
+        //    This helps to ensure that the ciphertext that you decrypted was the one that you intended.
+        //
+        //    When verifying, test that your expected encryption context is a subset of the actual encryption context,
+        //    not an exact match. When appropriate, the Encryption SDK adds the signing key to the encryption context.
         assert decryptResult.getEncryptionContext().get("ExampleContextKey").equals("ExampleContextValue");
 
         // 5. Return the decrypted byte array result

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

@@ -36,7 +36,7 @@ public static byte[] encrypt(PublicKey publicKey) {
         final AwsCrypto crypto = new AwsCrypto();
 
         // 2. Instantiate a Raw RSA Keyring with the public key
-        final Keyring keyring = StandardKeyrings.rawRsa()
+        final Keyring keyring = StandardKeyrings.rawRsaBuilder()
                 .keyNamespace("ExampleKeyNamespace")
                 .keyName("ExampleKeyName")
                 .wrappingAlgorithm("RSA/ECB/OAEPWithSHA-512AndMGF1Padding")

src/examples/java/com/amazonaws/crypto/examples/datakeycaching/LambdaDecryptAndWriteExample.java

@@ -45,12 +45,11 @@ public class LambdaDecryptAndWriteExample implements RequestHandler<KinesisEvent
     private final Table table_;
 
     /**
-     * Because the cache is used only for decryption, the code doesn't set
-     * the max bytes or max message security thresholds that are enforced
-     * only on on data keys used for encryption.
+     * This code doesn't set the max bytes or max message security thresholds that are enforced
+     * only on data keys used for encryption.
      *
      * @param cmkArn The AWS KMS customer master key to use for decryption
-     * @param tableName The DynamoDB table name to store decrypted messages in
+     * @param tableName The name of the DynamoDB table name that stores decrypted messages
      */
     public LambdaDecryptAndWriteExample(final String cmkArn, final String tableName) {
         cachingMaterialsManager_ = CachingCryptoMaterialsManager.newBuilder()

src/examples/java/com/amazonaws/crypto/examples/datakeycaching/MultiRegionRecordPusherExample.java

@@ -63,7 +63,7 @@ public MultiRegionRecordPusherExample(final Region[] regions, final String kmsAl
 
         final DefaultAWSCredentialsProviderChain credentialsProvider = new DefaultAWSCredentialsProviderChain();
 
-        // Build AwsKmsKeyring and AmazonKinesisClient objects for each target region
+        // Build AwsKmsKeyring and AmazonKinesisClient objects for each target Region
         final List<Keyring> keyrings = new ArrayList<>();
 
         for (Region region : regions) {
@@ -72,16 +72,16 @@ public MultiRegionRecordPusherExample(final Region[] regions, final String kmsAl
                     .withRegion(region.getName())
                     .build());
 
-            keyrings.add(StandardKeyrings.awsKms()
+            keyrings.add(StandardKeyrings.awsKmsBuilder()
                     .awsKmsClientSupplier(AwsKmsClientSupplier.builder()
                             .credentialsProvider(credentialsProvider)
                             .allowedRegions(Collections.singleton(region.getName()))
                             .build())
                     .generatorKeyId(AwsKmsCmkId.fromString(kmsAliasName)).build());
         }
 
-        // Collect keyrings into single multi keyring and add cache. The keyring for the
-        // first region will be used to generate a data key.
+        // Collect keyrings into a single multi-keyring and add cache. In this example, the keyring for the
+        // first region is used as the generatorKeyring to generate a data key.
         final List<Keyring> childrenKeyrings = keyrings.size() > 1 ? keyrings.subList(1, keyrings.size()) : emptyList();
         final Keyring keyring = StandardKeyrings.multi(keyrings.get(0), childrenKeyrings);
 

src/test/java/com/amazonaws/crypto/examples/RawRsaKeyringEncryptExampleTest.java

@@ -34,7 +34,7 @@ void testEncrypt() throws Exception {
 
         byte[] ciphertext = RawRsaKeyringEncryptExample.encrypt(keyPair.getPublic());
 
-        final Keyring keyring = StandardKeyrings.rawRsa()
+        final Keyring keyring = StandardKeyrings.rawRsaBuilder()
                 .keyNamespace("ExampleKeyNamespace")
                 .keyName("ExampleKeyName")
                 .privateKey(keyPair.getPrivate())