Fixed issue #61

src/aws_encryption_sdk/__init__.py

@@ -14,7 +14,7 @@
 # Below are imported for ease of use by implementors
 from aws_encryption_sdk.caches.local import LocalCryptoMaterialsCache  # noqa
 from aws_encryption_sdk.caches.null import NullCryptoMaterialsCache  # noqa
-from aws_encryption_sdk.identifiers import Algorithm, __version__  # noqa
+from aws_encryption_sdk.identifiers import AlgorithmSuite, __version__  # noqa
 from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider, KMSMasterKeyProviderConfig  # noqa
 from aws_encryption_sdk.materials_managers.caching import CachingCryptoMaterialsManager  # noqa
 from aws_encryption_sdk.materials_managers.default import DefaultCryptoMaterialsManager  # noqa
@@ -69,8 +69,8 @@ def encrypt(**kwargs):
             this is not enforced if a `key_provider` is provided.
 
     :param dict encryption_context: Dictionary defining encryption context
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param int frame_length: Frame length in bytes
     :returns: Tuple containing the encrypted ciphertext and the message header object
     :rtype: tuple of bytes and :class:`aws_encryption_sdk.structures.MessageHeader`

src/aws_encryption_sdk/identifiers.py

@@ -240,6 +240,8 @@ def safe_to_cache(self):
         return self.kdf is not KDFSuite.NONE
 
 
+# algorithm is just an alias for AlgorithmSuite ... but Sphinx does not recognize this fact
+# so we need to go through and fix the references
 Algorithm = AlgorithmSuite
 
 
@@ -271,9 +273,27 @@ class WrappingAlgorithm(Enum):
     :type padding_mgf:
     """
 
-    AES_128_GCM_IV12_TAG16_NO_PADDING = (EncryptionType.SYMMETRIC, Algorithm.AES_128_GCM_IV12_TAG16, None, None, None)
-    AES_192_GCM_IV12_TAG16_NO_PADDING = (EncryptionType.SYMMETRIC, Algorithm.AES_192_GCM_IV12_TAG16, None, None, None)
-    AES_256_GCM_IV12_TAG16_NO_PADDING = (EncryptionType.SYMMETRIC, Algorithm.AES_256_GCM_IV12_TAG16, None, None, None)
+    AES_128_GCM_IV12_TAG16_NO_PADDING = (
+        EncryptionType.SYMMETRIC,
+        AlgorithmSuite.AES_128_GCM_IV12_TAG16,
+        None,
+        None,
+        None,
+    )
+    AES_192_GCM_IV12_TAG16_NO_PADDING = (
+        EncryptionType.SYMMETRIC,
+        AlgorithmSuite.AES_192_GCM_IV12_TAG16,
+        None,
+        None,
+        None,
+    )
+    AES_256_GCM_IV12_TAG16_NO_PADDING = (
+        EncryptionType.SYMMETRIC,
+        AlgorithmSuite.AES_256_GCM_IV12_TAG16,
+        None,
+        None,
+        None,
+    )
     RSA_PKCS1 = (EncryptionType.ASYMMETRIC, rsa, padding.PKCS1v15, None, None)
     RSA_OAEP_SHA1_MGF1 = (EncryptionType.ASYMMETRIC, rsa, padding.OAEP, hashes.SHA1, padding.MGF1)
     RSA_OAEP_SHA256_MGF1 = (EncryptionType.ASYMMETRIC, rsa, padding.OAEP, hashes.SHA256, padding.MGF1)

src/aws_encryption_sdk/internal/crypto/authentication.py

@@ -33,8 +33,8 @@
 class _PrehashingAuthenticator(object):
     """Parent class for Signer/Verifier. Provides common behavior and interface.
 
-    :param algorithm: Algorithm on which to base authenticator
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite on which to base authenticator
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param key: Key with which to build authenticator
     """
 
@@ -46,7 +46,7 @@ def __init__(self, algorithm, key):
         self._hasher = self._build_hasher()
 
     def _set_signature_type(self):
-        """Ensures that the algorithm signature type is a known type and sets a reference value."""
+        """Ensures that the algorithm (suite) signature type is a known type and sets a reference value."""
         try:
             verify_interface(ec.EllipticCurve, self.algorithm.signing_algorithm_info)
             return ec.EllipticCurve
@@ -64,8 +64,8 @@ def _build_hasher(self):
 class Signer(_PrehashingAuthenticator):
     """Abstract signing handler.
 
-    :param algorithm: Algorithm on which to base signer
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite on which to base signer
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param key: Private key from which a signer can be generated
     :type key: currently only Elliptic Curve Private Keys are supported
     """
@@ -74,8 +74,8 @@ class Signer(_PrehashingAuthenticator):
     def from_key_bytes(cls, algorithm, key_bytes):
         """Builds a `Signer` from an algorithm suite and a raw signing key.
 
-        :param algorithm: Algorithm on which to base signer
-        :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+        :param algorithm: Algorithm suite on which to base signer
+        :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
         :param bytes key_bytes: Raw signing key
         :rtype: aws_encryption_sdk.internal.crypto.Signer
         """
@@ -127,18 +127,18 @@ class Verifier(_PrehashingAuthenticator):
     .. note::
         For ECC curves, the signature must be DER encoded as specified in RFC 3279.
 
-    :param algorithm: Algorithm on which to base verifier
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
-    :param public_key: Appropriate public key object for algorithm
+    :param algorithm: Algorithm suite on which to base verifier
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
+    :param public_key: Appropriate public key object for algorithm suite
     :type public_key: may vary
     """
 
     @classmethod
     def from_encoded_point(cls, algorithm, encoded_point):
-        """Creates a Verifier object based on the supplied algorithm and encoded compressed ECC curve point.
+        """Creates a Verifier object based on the supplied algorithm suite and encoded compressed ECC curve point.
 
-        :param algorithm: Algorithm on which to base verifier
-        :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+        :param algorithm: Algorithm suite on which to base verifier
+        :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
         :param bytes encoded_point: ECC public point compressed and encoded with _ecc_encode_compressed_point
         :returns: Instance of Verifier generated from encoded point
         :rtype: aws_encryption_sdk.internal.crypto.Verifier
@@ -152,10 +152,10 @@ def from_encoded_point(cls, algorithm, encoded_point):
 
     @classmethod
     def from_key_bytes(cls, algorithm, key_bytes):
-        """Creates a `Verifier` object based on the supplied algorithm and raw verification key.
+        """Creates a `Verifier` object based on the supplied algorithm suite and raw verification key.
 
-        :param algorithm: Algorithm on which to base verifier
-        :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+        :param algorithm: Algorithm suite on which to base verifier
+        :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
         :param bytes encoded_point: Raw verification key
         :returns: Instance of Verifier generated from encoded point
         :rtype: aws_encryption_sdk.internal.crypto.Verifier

src/aws_encryption_sdk/internal/crypto/data_keys.py

@@ -20,11 +20,11 @@
 
 
 def derive_data_encryption_key(source_key, algorithm, message_id):
-    """Derives the data encryption key using the defined algorithm.
+    """Derives the data encryption key using the defined algorithm suite.
 
     :param bytes source_key: Raw source key
-    :param algorithm: Algorithm used to encrypt this body
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite used to encrypt this body
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes message_id: Message ID
     :returns: Derived data encryption key
     :rtype: bytes

src/aws_encryption_sdk/internal/crypto/elliptic_curve.py

@@ -57,8 +57,8 @@ def _ecc_static_length_signature(key, algorithm, digest):
 
     :param key: Elliptic curve private key
     :type key: cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey
-    :param algorithm: Master algorithm to use
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Master algorithm suite to use
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes digest: Pre-calculated hash digest
     :returns: Signature with required length
     :rtype: bytes
@@ -177,10 +177,10 @@ def _ecc_public_numbers_from_compressed_point(curve, compressed_point):
 def generate_ecc_signing_key(algorithm):
     """Returns an ECC signing key.
 
-    :param algorithm: Algorithm object which determines what signature to generate
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite object which determines what signature to generate
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :returns: Generated signing key
-    :raises NotSupportedError: if signing algorithm is not supported on this platform
+    :raises NotSupportedError: if signing algorithm suite is not supported on this platform
     """
     try:
         verify_interface(ec.EllipticCurve, algorithm.signing_algorithm_info)

src/aws_encryption_sdk/internal/crypto/encryption.py

@@ -24,8 +24,8 @@
 class Encryptor(object):
     """Abstract encryption handler.
 
-    :param algorithm: Algorithm used to encrypt this body
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite used to encrypt this body
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes key: Encryption key
     :param bytes associated_data: Associated Data to send to encryption subsystem
     :param bytes iv: IV to use when encrypting message
@@ -76,8 +76,8 @@ def tag(self):
 def encrypt(algorithm, key, plaintext, associated_data, iv):
     """Encrypts a frame body.
 
-    :param algorithm: Algorithm used to encrypt this body
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite used to encrypt this body
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes key: Encryption key
     :param bytes plaintext: Body plaintext
     :param bytes associated_data: Body AAD Data
@@ -93,8 +93,8 @@ def encrypt(algorithm, key, plaintext, associated_data, iv):
 class Decryptor(object):
     """Abstract decryption handler.
 
-    :param algorithm: Algorithm used to encrypt this body
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite used to encrypt this body
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes key: Raw source key
     :param bytes associated_data: Associated Data to send to decryption subsystem
     :param bytes iv: IV value with which to initialize decryption subsystem
@@ -135,8 +135,8 @@ def finalize(self):
 def decrypt(algorithm, key, encrypted_data, associated_data):
     """Decrypts a frame body.
 
-    :param algorithm: Algorithm used to encrypt this body
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite used to encrypt this body
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes key: Plaintext data key
     :param encrypted_data: EncryptedData containing body data
     :type encrypted_data: :class:`aws_encryption_sdk.internal.structures.EncryptedData`,

src/aws_encryption_sdk/internal/crypto/iv.py

@@ -46,8 +46,8 @@
 def frame_iv(algorithm, sequence_number):
     """Builds the deterministic IV for a body frame.
 
-    :param algorithm: Algorithm for which to build IV
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite for which to build IV
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param int sequence_number: Frame sequence number
     :returns: Generated IV
     :rtype: bytes
@@ -67,8 +67,8 @@ def frame_iv(algorithm, sequence_number):
 def non_framed_body_iv(algorithm):
     """Builds the deterministic IV for a non-framed body.
 
-    :param algorithm: Algorithm for which to build IV
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite for which to build IV
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :returns: Generated IV
     :rtype: bytes
     """
@@ -78,8 +78,8 @@ def non_framed_body_iv(algorithm):
 def header_auth_iv(algorithm):
     """Builds the deterministic IV for header authentication.
 
-    :param algorithm: Algorithm for which to build IV
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite for which to build IV
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :returns: Generated IV
     :rtype: bytes
     """

src/aws_encryption_sdk/internal/defaults.py

@@ -29,7 +29,7 @@
 #: Default message structure Type as defined in specification
 TYPE = aws_encryption_sdk.identifiers.ObjectType.CUSTOMER_AE_DATA
 #: Default algorithm as defined in specification
-ALGORITHM = aws_encryption_sdk.identifiers.Algorithm.AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384
+ALGORITHM = aws_encryption_sdk.identifiers.AlgorithmSuite.AES_256_GCM_IV12_TAG16_HKDF_SHA384_ECDSA_P384
 
 #: Key to add encoded signing key to encryption context dictionary as defined in specification
 ENCODED_SIGNER_KEY = "aws-crypto-public-key"

src/aws_encryption_sdk/internal/formatting/serialize.py

@@ -121,8 +121,8 @@ def serialize_header(header, signer=None):
 def serialize_header_auth(algorithm, header, data_encryption_key, signer=None):
     """Creates serialized header authentication data.
 
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes header: Serialized message header
     :param bytes data_encryption_key: Data key with which to encrypt message
     :param signer: Cryptographic signer object (optional)
@@ -150,8 +150,8 @@ def serialize_header_auth(algorithm, header, data_encryption_key, signer=None):
 def serialize_non_framed_open(algorithm, iv, plaintext_length, signer=None):
     """Serializes the opening block for a non-framed message body.
 
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes iv: IV value used to encrypt body
     :param int plaintext_length: Length of plaintext (and thus ciphertext) in body
     :param signer: Cryptographic signer object (optional)
@@ -187,8 +187,8 @@ def serialize_frame(
     """Receives a message plaintext, breaks off a frame, encrypts and serializes
     the frame, and returns the encrypted frame and the remaining plaintext.
 
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param bytes plaintext: Source plaintext to encrypt and serialize
     :param bytes message_id: Message ID
     :param bytes data_encryption_key: Data key with which to encrypt message

src/aws_encryption_sdk/internal/utils/__init__.py

@@ -45,8 +45,8 @@ def validate_frame_length(frame_length, algorithm):
     """Validates that frame length is within the defined limits and is compatible with the selected algorithm.
 
     :param int frame_length: Frame size in bytes
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :raises SerializationError: if frame size is negative or not a multiple of the algorithm block size
     :raises SerializationError: if frame size is larger than the maximum allowed frame size
     """
@@ -103,8 +103,8 @@ def prepare_data_keys(primary_master_key, master_keys, algorithm, encryption_con
     :type primary_master_key: aws_encryption_sdk.key_providers.base.MasterKey
     :param master_keys: All master keys with which to encrypt data keys
     :type master_keys: list of :class:`aws_encryption_sdk.key_providers.base.MasterKey`
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite to use for encryption
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :param dict encryption_context: Encryption context to use when generating data key
     :rtype: tuple containing :class:`aws_encryption_sdk.structures.DataKey`
         and set of :class:`aws_encryption_sdk.structures.EncryptedDataKey`
@@ -151,8 +151,8 @@ def source_data_key_length_check(source_data_key, algorithm):
     :param source_data_key: Source data key object received from MasterKey decrypt or generate data_key methods
     :type source_data_key: :class:`aws_encryption_sdk.structures.RawDataKey`
         or :class:`aws_encryption_sdk.structures.DataKey`
-    :param algorithm: Algorithm object which directs how this data key will be used
-    :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+    :param algorithm: Algorithm suite object which directs how this data key will be used
+    :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
     :raises InvalidDataKeyError: if data key length does not match required kdf input length
     """
     if len(source_data_key.data_key) != algorithm.kdf_input_len:

src/aws_encryption_sdk/key_providers/base.py

@@ -218,8 +218,8 @@ def decrypt_data_key(self, encrypted_data_key, algorithm, encryption_context):
 
         :param encrypted_data_key: Encrypted data key to decrypt
         :type encrypted_data_key: aws_encryption_sdk.structures.EncryptedDataKey
-        :param algorithm: Algorithm object which directs how this Master Key will encrypt the data key
-        :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+        :param algorithm: Algorithm suite object which directs how this Master Key will encrypt the data key
+        :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
         :param dict encryption_context: Encryption context to use in encryption
         :returns: Decrypted data key
         :rtype: aws_encryption_sdk.structures.DataKey

src/aws_encryption_sdk/key_providers/kms.py

@@ -115,15 +115,13 @@ def __init__(self, **kwargs):  # pylint: disable=unused-argument
     def _process_config(self):
         """Traverses the config and adds master keys and regional clients as needed."""
         self._user_agent_adding_config = botocore.config.Config(user_agent_extra=USER_AGENT_SUFFIX)
-
         if self.config.region_names:
             self.add_regional_clients_from_list(self.config.region_names)
             self.default_region = self.config.region_names[0]
         else:
             self.default_region = self.config.botocore_session.get_config_variable("region")
             if self.default_region is not None:
                 self.add_regional_client(self.default_region)
-
         if self.config.key_ids:
             self.add_master_keys_from_list(self.config.key_ids)
 
@@ -244,8 +242,8 @@ def __init__(self, **kwargs):  # pylint: disable=unused-argument
     def _generate_data_key(self, algorithm, encryption_context=None):
         """Generates data key and returns plaintext and ciphertext of key.
 
-        :param algorithm: Algorithm on which to base data key
-        :type algorithm: aws_encryption_sdk.identifiers.Algorithm
+        :param algorithm: Algorithm suite on which to base data key
+        :type algorithm: aws_encryption_sdk.identifiers.AlgorithmSuite
         :param dict encryption_context: Encryption context to pass to KMS
         :returns: Generated data key
         :rtype: aws_encryption_sdk.structures.DataKey
@@ -306,7 +304,7 @@ def _decrypt_data_key(self, encrypted_data_key, algorithm, encryption_context=No
 
         :param data_key: Encrypted data key
         :type data_key: aws_encryption_sdk.structures.EncryptedDataKey
-        :type algorithm: `aws_encryption_sdk.identifiers.Algorithm` (not used for KMS)
+        :type algorithm: `aws_encryption_sdk.identifiers.AlgorithmSuite` (not used for KMS)
         :param dict encryption_context: Encryption context to use in decryption
         :returns: Decrypted data key
         :rtype: aws_encryption_sdk.structures.DataKey