Merge pull request #9 from juneb/scrub-code-comments

Scrub Python code comments

Author: mattsb42-aws

README.rst

@@ -44,7 +44,7 @@ An example of a CMM is the default CMM, which is automatically generated anywher
 key provider. The default CMM collects encrypted data keys from all master keys referenced by the master key
 provider.
 
-An example of a more advanced CMM is the caching CMM, which caches cryptographic materials provided by a another CMM.
+An example of a more advanced CMM is the caching CMM, which caches cryptographic materials provided by another CMM.
 
 Master Key Providers
 --------------------
@@ -57,12 +57,13 @@ To encrypt data in this client, a ``MasterKeyProvider`` object must contain at l
 
 Master Keys
 -----------
-Master keys provide data keys.
+Master keys generate, encrypt, and decrypt data keys.
 An example of a master key is a `KMS customer master key (CMK)`_.
 
 Data Keys
 ---------
-Data Keys are the actual encryption keys which are used to encrypt your data.
+Data keys are the encryption keys that are used to encrypt your data. If your algorithm suite
+uses a key derivation function, the data key is used to generate the key that directly encrypts the data.
 
 *****
 Usage

examples/src/basic_encryption.py

@@ -19,18 +19,18 @@
 def cycle_string(key_arn, source_plaintext, botocore_session=None):
     """Encrypts and then decrypts a string under a KMS customer master key (CMK).
 
-    :param str key_arn: Amazon Resource Name (Arn) of the KMS CMK
+    :param str key_arn: Amazon Resource Name (ARN) of the KMS CMK
     :param bytes source_plaintext: Data to encrypt
     :param botocore_session: existing botocore session instance
     :type botocore_session: botocore.session.Session
     """
-    # Create the KMS Master Key Provider
+    # Create a KMS master key provider
     kms_kwargs = dict(key_ids=[key_arn])
     if botocore_session is not None:
         kms_kwargs['botocore_session'] = botocore_session
     master_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(**kms_kwargs)
 
-    # Encrypt the source plaintext
+    # Encrypt the plaintext source data
     ciphertext, encryptor_header = aws_encryption_sdk.encrypt(
         source=source_plaintext,
         key_provider=master_key_provider
@@ -43,10 +43,14 @@ def cycle_string(key_arn, source_plaintext, botocore_session=None):
         key_provider=master_key_provider
     )
 
-    # Validate that the cycled plaintext is identical to the source plaintext
+    # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source plaintext
     assert cycled_plaintext == source_plaintext
 
-    # Validate that the encryption context used by the decryptor has all the key-pairs from the encryptor
+    # Verify that the encryption context used in the decrypt operation includes all key pairs from
+    # the encrypt operation. (The SDK can add pairs, so don't require an exact match.)
+    #
+    # In production, always use a meaningful encryption context. In this sample, we omit the
+    # encryption context (no key pairs).
     assert all(
         pair in decrypted_header.encryption_context.items()
         for pair in encryptor_header.encryption_context.items()

examples/src/basic_file_encryption_with_multiple_providers.py

@@ -38,8 +38,8 @@ def __init__(self, **kwargs):  # pylint: disable=unused-argument
     def _get_raw_key(self, key_id):
         """Retrieves a static, randomly generated, RSA key for the specified key id.
 
-        :param str key_id: Key ID
-        :returns: Wrapping key which contains the specified static key
+        :param str key_id: User-defined ID for the static key
+        :returns: Wrapping key that contains the specified static key
         :rtype: :class:`aws_encryption_sdk.internal.crypto.WrappingKey`
         """
         try:
@@ -64,32 +64,38 @@ def _get_raw_key(self, key_id):
 
 
 def cycle_file(key_arn, source_plaintext_filename, botocore_session=None):
-    """Encrypts and then decrypts a file under both a KMS Master Key Provider and a custom static Master Key Provider.
+    """Encrypts and then decrypts a file using a KMS master key provider and a custom static master
+    key provider. Both master key providers are used to encrypt the plaintext file, so either one alone
+    can decrypt it.
 
-    :param str key_arn: Amazon Resource Name (Arn) of the KMS CMK
+    :param str key_arn: Amazon Resource Name (ARN) of the KMS Customer Master Key (CMK)
+    (http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html)
     :param str source_plaintext_filename: Filename of file to encrypt
     :param botocore_session: existing botocore session instance
     :type botocore_session: botocore.session.Session
     """
+    # "Cycled" means encrypted and then decrypted
     ciphertext_filename = source_plaintext_filename + '.encrypted'
     cycled_kms_plaintext_filename = source_plaintext_filename + '.kms.decrypted'
     cycled_static_plaintext_filename = source_plaintext_filename + '.static.decrypted'
 
-    # Create KMS Master Key Provider
+    # Create a KMS master key provider
     kms_kwargs = dict(key_ids=[key_arn])
     if botocore_session is not None:
         kms_kwargs['botocore_session'] = botocore_session
     kms_master_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(**kms_kwargs)
 
-    # Create Static Master Key Provider and add to KMS Master Key Provider
+    # Create a static master key provider and add a master key to it
     static_key_id = os.urandom(8)
     static_master_key_provider = StaticRandomMasterKeyProvider()
     static_master_key_provider.add_master_key(static_key_id)
 
-    # Add Static Master Key Provider to KMS Master Key Provider
+    # Add the static master key provider to the KMS master key provider
+    #   The resulting master key provider uses KMS master keys to generate (and encrypt)
+    #   data keys and static master keys to create an additional encrypted copy of each data key.
     kms_master_key_provider.add_master_key_provider(static_master_key_provider)
 
-    # Encrypt plaintext with both KMS and Static Master Keys
+    # Encrypt plaintext with both KMS and static master keys
     with open(source_plaintext_filename, 'rb') as plaintext, open(ciphertext_filename, 'wb') as ciphertext:
         with aws_encryption_sdk.stream(
             source=plaintext,
@@ -99,7 +105,7 @@ def cycle_file(key_arn, source_plaintext_filename, botocore_session=None):
             for chunk in encryptor:
                 ciphertext.write(chunk)
 
-    # Decrypt the ciphertext with the KMS Master Key
+    # Decrypt the ciphertext with only the KMS master key
     with open(ciphertext_filename, 'rb') as ciphertext, open(cycled_kms_plaintext_filename, 'wb') as plaintext:
         with aws_encryption_sdk.stream(
             source=ciphertext,
@@ -109,7 +115,7 @@ def cycle_file(key_arn, source_plaintext_filename, botocore_session=None):
             for chunk in kms_decryptor:
                 plaintext.write(chunk)
 
-    # Decrypt the ciphertext with the Static Master Key only
+    # Decrypt the ciphertext with only the static master key
     with open(ciphertext_filename, 'rb') as ciphertext, open(cycled_static_plaintext_filename, 'wb') as plaintext:
         with aws_encryption_sdk.stream(
             source=ciphertext,
@@ -119,11 +125,15 @@ def cycle_file(key_arn, source_plaintext_filename, botocore_session=None):
             for chunk in static_decryptor:
                 plaintext.write(chunk)
 
-    # Validate that the cycled plaintext is identical to the source plaintext
+    # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source plaintext
     assert filecmp.cmp(source_plaintext_filename, cycled_kms_plaintext_filename)
     assert filecmp.cmp(source_plaintext_filename, cycled_static_plaintext_filename)
 
-    # Validate that the encryption context used by the decryptor has all the key-pairs from the encryptor
+    # Verify that the encryption context in the decrypt operation includes all key pairs from the
+    # encrypt operation.
+    #
+    # In production, always use a meaningful encryption context. In this sample, we omit the
+    # encryption context (no key pairs).
     assert all(
         pair in kms_decryptor.header.encryption_context.items()
         for pair in encryptor.header.encryption_context.items()

examples/src/basic_file_encryption_with_raw_key_provider.py

@@ -21,7 +21,7 @@
 
 
 class StaticRandomMasterKeyProvider(RawMasterKeyProvider):
-    """Randomly generates and provides 256-bit keys consistently per unique key id."""
+    """Randomly generates 256-bit keys for each unique key ID."""
 
     provider_id = 'static-random'
 
@@ -30,10 +30,10 @@ def __init__(self, **kwargs):  # pylint: disable=unused-argument
         self._static_keys = {}
 
     def _get_raw_key(self, key_id):
-        """Retrieves a static, randomly generated, symmetric key for the specified key id.
+        """Returns a static, randomly-generated symmetric key for the specified key ID.
 
         :param str key_id: Key ID
-        :returns: Wrapping key which contains the specified static key
+        :returns: Wrapping key that contains the specified static key
         :rtype: :class:`aws_encryption_sdk.internal.crypto.WrappingKey`
         """
         try:
@@ -49,19 +49,19 @@ def _get_raw_key(self, key_id):
 
 
 def cycle_file(source_plaintext_filename):
-    """Encrypts and then decrypts a file under a custom static Master Key Provider.
+    """Encrypts and then decrypts a file under a custom static master key provider.
 
     :param str source_plaintext_filename: Filename of file to encrypt
     """
-    # Create the Static Random Master Key Provider
+    # Create a static random master key provider
     key_id = os.urandom(8)
     master_key_provider = StaticRandomMasterKeyProvider()
     master_key_provider.add_master_key(key_id)
 
     ciphertext_filename = source_plaintext_filename + '.encrypted'
     cycled_plaintext_filename = source_plaintext_filename + '.decrypted'
 
-    # Encrypt the source plaintext
+    # Encrypt the plaintext source data
     with open(source_plaintext_filename, 'rb') as plaintext, open(ciphertext_filename, 'wb') as ciphertext:
         with aws_encryption_sdk.stream(
             mode='e',
@@ -81,10 +81,15 @@ def cycle_file(source_plaintext_filename):
             for chunk in decryptor:
                 plaintext.write(chunk)
 
-    # Validate that the cycled plaintext is identical to the source plaintext
+    # Verify that the "cycled" (encrypted, then decrypted) plaintext is identical to the source
+    # plaintext
     assert filecmp.cmp(source_plaintext_filename, cycled_plaintext_filename)
 
-    # Validate that the encryption context used by the decryptor has all the key-pairs from the encryptor
+    # Verify that the encryption context used in the decrypt operation includes all key pairs from
+    # the encrypt operation
+    #
+    # In production, always use a meaningful encryption context. In this sample, we omit the
+    # encryption context (no key pairs).
     assert all(
         pair in decryptor.header.encryption_context.items()
         for pair in encryptor.header.encryption_context.items()