docs: adjust wording

Author: mattsb42-aws

examples/README.md

@@ -87,7 +87,8 @@ you can find these examples in [`examples/src/master_key_provider`](./src/master
 
 ## Legacy
 
-This section includes older examples, including examples of using master keys and master key providers in Java and Python.
+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, which explain the preferred ways of using this library.
 You can find these examples in [`examples/src/legacy`](./src/legacy).

examples/src/file_streaming_defaults.py

@@ -54,7 +54,7 @@ def run(aws_kms_cmk, source_plaintext_filename):
             for segment in encryptor:
                 ciphertext.write(segment)
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert not filecmp.cmp(source_plaintext_filename, ciphertext_filename)
 
     # Open the files you want to work with.
@@ -78,5 +78,5 @@ def run(aws_kms_cmk, source_plaintext_filename):
             for segment in decryptor:
                 decrypted.write(segment)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert filecmp.cmp(source_plaintext_filename, decrypted_filename)

examples/src/in_memory_streaming_defaults.py

@@ -49,7 +49,7 @@ def run(aws_kms_cmk, source_plaintext):
         for segment in encryptor:
             ciphertext.write(segment)
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext.getvalue() != source_plaintext
 
     # Reset the ciphertext stream position so that we can read from the beginning.
@@ -75,5 +75,5 @@ def run(aws_kms_cmk, source_plaintext):
         for segment in decryptor:
             decrypted.write(segment)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted.getvalue() == source_plaintext

examples/src/keyring/aws_kms/custom_client_supplier.py

@@ -95,7 +95,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -104,7 +104,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/aws_kms/custom_kms_client_config.py

@@ -68,7 +68,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -77,7 +77,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/aws_kms/discovery_decrypt.py

@@ -58,7 +58,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=encrypt_keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the KMS discovery keyring.
@@ -67,7 +67,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=decrypt_keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/aws_kms/discovery_decrypt_in_region_only.py

@@ -66,7 +66,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=encrypt_keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the KMS discovery keyring.
@@ -75,7 +75,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=decrypt_keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/aws_kms/discovery_decrypt_with_preferred_regions.py

@@ -89,7 +89,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=encrypt_keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the KMS discovery keyring.
@@ -98,7 +98,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=decrypt_keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/aws_kms/multiple_regions.py

@@ -66,7 +66,7 @@ def run(aws_kms_generator_cmk, aws_kms_additional_cmks, source_plaintext):
     # It should contain one EDK for each CMK.
     assert len(encrypt_header.encrypted_data_keys) == len(aws_kms_additional_cmks) + 1
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data separately using the single-CMK keyrings.
@@ -80,7 +80,7 @@ def run(aws_kms_generator_cmk, aws_kms_additional_cmks, source_plaintext):
         source=ciphertext, keyring=single_cmk_keyring_that_encrypted
     )
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted_1 == source_plaintext
     assert decrypted_2 == source_plaintext
 

examples/src/keyring/aws_kms/single_cmk.py

@@ -46,7 +46,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -55,7 +55,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/multi/aws_kms_with_escrow.py

@@ -100,7 +100,7 @@ def run(aws_kms_cmk, source_plaintext):
     # It should contain one EDK for KMS and one for the escrow key.
     assert len(encrypt_header.encrypted_data_keys) == 2
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data separately using the KMS keyring and the escrow decrypt keyring.
@@ -112,7 +112,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=ciphertext, keyring=escrow_decrypt_keyring
     )
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted_kms == source_plaintext
     assert decrypted_escrow == source_plaintext
 

examples/src/keyring/raw_aes/raw_aes.py

@@ -58,7 +58,7 @@ def run(source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -67,7 +67,7 @@ def run(source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/raw_rsa/private_key_only.py

@@ -65,7 +65,7 @@ def run(source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -74,7 +74,7 @@ def run(source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/raw_rsa/private_key_only_from_pem.py

@@ -78,7 +78,7 @@ def run(source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -87,7 +87,7 @@ def run(source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/keyring/raw_rsa/public_private_key_separate.py

@@ -90,7 +90,7 @@ def run(source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=public_key_keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Try to decrypt your encrypted data using the *encrypt* keyring.
@@ -111,7 +111,7 @@ def run(source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=private_key_keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/onestep_defaults.py

@@ -37,7 +37,7 @@ def run(aws_kms_cmk, source_plaintext):
         source=source_plaintext, encryption_context=encryption_context, keyring=keyring
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -46,7 +46,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the encryption context.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes

examples/src/onestep_unsigned.py

@@ -54,7 +54,7 @@ def run(aws_kms_cmk, source_plaintext):
         algorithm=AlgorithmSuite.AES_256_GCM_IV12_TAG16_HKDF_SHA256,
     )
 
-    # Verify that the ciphertext and plaintext are different.
+    # Demonstrate that the ciphertext and plaintext are different.
     assert ciphertext != source_plaintext
 
     # Decrypt your encrypted data using the same keyring you used on encrypt.
@@ -66,7 +66,7 @@ def run(aws_kms_cmk, source_plaintext):
     # because the header message includes the algorithm suite identifier.
     decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, keyring=keyring)
 
-    # Verify that the decrypted plaintext is identical to the original plaintext.
+    # Demonstrate that the decrypted plaintext is identical to the original plaintext.
     assert decrypted == source_plaintext
 
     # Verify that the encryption context used in the decrypt operation includes