From f04317ae24441082279ea73ccca0a6630c33cc86 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Sun, 27 Oct 2013 16:44:30 -0400 Subject: Move primtives into a hazmat package --- docs/architecture.rst | 6 +- docs/hazmat/primitives/cryptographic-hashes.rst | 92 ++++++++++++ docs/hazmat/primitives/index.rst | 8 + docs/hazmat/primitives/symmetric-encryption.rst | 187 ++++++++++++++++++++++++ docs/index.rst | 9 +- docs/primitives/cryptographic-hashes.rst | 92 ------------ docs/primitives/index.rst | 8 - docs/primitives/symmetric-encryption.rst | 187 ------------------------ 8 files changed, 298 insertions(+), 291 deletions(-) create mode 100644 docs/hazmat/primitives/cryptographic-hashes.rst create mode 100644 docs/hazmat/primitives/index.rst create mode 100644 docs/hazmat/primitives/symmetric-encryption.rst delete mode 100644 docs/primitives/cryptographic-hashes.rst delete mode 100644 docs/primitives/index.rst delete mode 100644 docs/primitives/symmetric-encryption.rst (limited to 'docs') diff --git a/docs/architecture.rst b/docs/architecture.rst index 0a9550c0..8de8649d 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -10,9 +10,9 @@ Architecture * ``cryptography.bindings``: This package contains bindings to low level cryptographic libraries. Our initial target will be OpenSSL. -* ``cryptography.primitives``: This packages contains low level algorithms, - things like ``AES`` or ``SHA1``. This is implemented on top of +* ``cryptography.hazmat.primitives``: This packages contains low level + algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of ``cryptography.bindings``. * ``cryptography``: This package contains higher level recipes, for example "encrypt and then MAC". This is implemented on top of - ``cryptography.primitives``. + ``cryptography.hazmat.primitives``. diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst new file mode 100644 index 00000000..05004080 --- /dev/null +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -0,0 +1,92 @@ +Message Digests +=============== + +.. currentmodule:: cryptography.hazmat.primitives.hashes + +.. class:: BaseHash(data=None) + + Abstract base class that implements a common interface for all hash + algorithms that follow here. + + If ``data`` is provided ``update(data)`` is called upon construction. + + .. method:: update(data) + + :param bytes data: The bytes you wish to hash. + + .. method:: copy() + + :return: a new instance of this object with a copied internal state. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +SHA-1 +~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. class:: SHA1() + + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. + +SHA-2 Family +~~~~~~~~~~~~ + +.. class:: SHA224() + + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. + +.. class:: SHA256() + + SHA-256 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 256-bit message digest. + +.. class:: SHA384() + + SHA-384 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 384-bit message digest. + +.. class:: SHA512() + + SHA-512 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 512-bit message digest. + +RIPEMD160 +~~~~~~~~~ + +.. class:: RIPEMD160() + + RIPEMD160 is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 160-bit message digest. + +Whirlpool +~~~~~~~~~ + +.. class:: Whirlpool() + + Whirlpool is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 512-bit message digest. + +MD5 +~~~ + +.. warning:: + + MD5 is a deprecated hash algorithm that has practical known collision + attacks. You are strongly discouraged from using it. + +.. class:: MD5() + + MD5 is a deprecated cryptographic hash function. It has a 128-bit message + digest and has practical known collision attacks. diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst new file mode 100644 index 00000000..c18c62ca --- /dev/null +++ b/docs/hazmat/primitives/index.rst @@ -0,0 +1,8 @@ +Primitives +========== + +.. toctree:: + :maxdepth: 1 + + cryptographic-hashes + symmetric-encryption diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst new file mode 100644 index 00000000..e2586aaf --- /dev/null +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -0,0 +1,187 @@ +Symmetric Encryption +==================== + +.. currentmodule:: cryptography.hazmat.primitives.block + +.. testsetup:: + + import binascii + key = binascii.unhexlify(b"0" * 32) + iv = binascii.unhexlify(b"0" * 32) + + +Symmetric encryption is a way to encrypt (hide the plaintext value) material +where the encrypter and decrypter both use the same key. + +.. class:: BlockCipher(cipher, mode) + + Block ciphers work by encrypting content in chunks, often 64- or 128-bits. + They combine an underlying algorithm (such as AES), with a mode (such as + CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) + content with AES is: + + .. doctest:: + + >>> from cryptography.hazmat.primitives.block import BlockCipher, ciphers, modes + >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + decryptor.finalize() + 'a secret message' + + :param cipher: One of the ciphers described below. + :param mode: One of the modes described below. + + .. method:: encryptor() + + :return: An encrypting + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + provider. + + .. method:: decryptor() + + :return: A decrypting + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + provider. + +.. currentmodule:: cryptography.hazmat.primitives.interfaces + +.. class:: CipherContext() + + When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you + will receive a return object conforming to the CipherContext interface. You + can then call ``update(data)`` with data until you have fed everything into + the context. Once that is done call ``finalize()`` to finish the operation and + obtain the remainder of the data. + + + .. method:: update(data) + + :param bytes data: The text you wish to pass into the context. + :return bytes: Returns the data that was encrypted or decrypted. + + .. method:: finalize() + + :return bytes: Returns the remainder of the data. + +Ciphers +~~~~~~~ + +.. currentmodule:: cryptography.hazmat.primitives.block.ciphers + +.. class:: AES(key) + + AES (Advanced Encryption Standard) is a block cipher standardized by NIST. + AES is both fast, and cryptographically strong. It is a good default + choice for encryption. + + :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. + This must be kept secret. + +.. class:: Camellia(key) + + Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. + It is considered to have comparable security and performance to AES, but + is not as widely studied or deployed. + + :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. + This must be kept secret. + + +.. class:: TripleDES(key) + + Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a + block cipher standardized by NIST. Triple DES has known cryptoanalytic + flaws, however none of them currently enable a practical attack. + Nonetheless, Triples DES is not reccomended for new applications because it + is incredibly slow; old applications should consider moving away from it. + + :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits + (note that DES functionally uses ``56``, ``112``, or + ``168`` bits of the key, there is a parity byte in each + component of the key), in some materials these are + referred to as being up to three separate keys (each + ``56`` bits long), they can simply be concatenated to + produce the full key. This must be kept secret. + + +Modes +~~~~~ + +.. currentmodule:: cryptography.hazmat.primitives.block.modes + +.. class:: CBC(initialization_vector) + + CBC (Cipher block chaining) is a mode of operation for block ciphers. It is + considered cryptographically strong. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + + +.. class:: CTR(nonce) + + .. warning:: + + Counter mode is not recommended for use with block ciphers that have a + block size of less than 128-bits. + + CTR (Counter) is a mode of operation for block ciphers. It is considered + cryptographically strong. + + :param bytes nonce: Should be random bytes. It is critical to never reuse a + ``nonce`` with a given key. Any reuse of a nonce + with the same key compromises the security of every + message encrypted with that key. Must be the same + number of bytes as the ``block_size`` of the cipher + with a given key. The nonce does not need to be kept + secret and may be included alongside the ciphertext. + +.. class:: OFB(initialization_vector) + + OFB (Output Feedback) is a mode of operation for block ciphers. It + transforms a block cipher into a stream cipher. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + +.. class:: CFB(initialization_vector) + + CFB (Cipher Feedback) is a mode of operation for block ciphers. It + transforms a block cipher into a stream cipher. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). Must be the + same number of bytes as the + ``block_size`` of the cipher. Do not + reuse an ``initialization_vector`` with + a given ``key``. + + +Insecure Modes +-------------- + +.. warning:: + + These modes are insecure. New applications should never make use of them, + and existing applications should strongly consider migrating away. + + +.. class:: ECB() + + ECB (Electronic Code Book) is the simplest mode of operation for block + ciphers. Each block of data is encrypted in the same way. This means + identical plaintext blocks will always result in identical ciphertext + blocks, and thus result in information leakage diff --git a/docs/index.rst b/docs/index.rst index a868a5d6..47418abb 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,8 +31,15 @@ Contents :maxdepth: 2 architecture - primitives/index bindings/index contributing security community + +Hazard Materials +---------------- + +.. toctree:: + :maxdepth: 2 + + hazmat/primitives/index diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst deleted file mode 100644 index dcf21250..00000000 --- a/docs/primitives/cryptographic-hashes.rst +++ /dev/null @@ -1,92 +0,0 @@ -Message Digests -=============== - -.. currentmodule:: cryptography.primitives.hashes - -.. class:: BaseHash(data=None) - - Abstract base class that implements a common interface for all hash - algorithms that follow here. - - If ``data`` is provided ``update(data)`` is called upon construction. - - .. method:: update(data) - - :param bytes data: The bytes you wish to hash. - - .. method:: copy() - - :return: a new instance of this object with a copied internal state. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - -SHA-1 -~~~~~ - -.. attention:: - - NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications - are strongly suggested to use SHA-2 over SHA-1. - -.. class:: SHA1() - - SHA-1 is a cryptographic hash function standardized by NIST. It has a - 160-bit message digest. - -SHA-2 Family -~~~~~~~~~~~~ - -.. class:: SHA224() - - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. - -.. class:: SHA256() - - SHA-256 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 256-bit message digest. - -.. class:: SHA384() - - SHA-384 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 384-bit message digest. - -.. class:: SHA512() - - SHA-512 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 512-bit message digest. - -RIPEMD160 -~~~~~~~~~ - -.. class:: RIPEMD160() - - RIPEMD160 is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 160-bit message digest. - -Whirlpool -~~~~~~~~~ - -.. class:: Whirlpool() - - Whirlpool is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 512-bit message digest. - -MD5 -~~~ - -.. warning:: - - MD5 is a deprecated hash algorithm that has practical known collision - attacks. You are strongly discouraged from using it. - -.. class:: MD5() - - MD5 is a deprecated cryptographic hash function. It has a 128-bit message - digest and has practical known collision attacks. diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst deleted file mode 100644 index c18c62ca..00000000 --- a/docs/primitives/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Primitives -========== - -.. toctree:: - :maxdepth: 1 - - cryptographic-hashes - symmetric-encryption diff --git a/docs/primitives/symmetric-encryption.rst b/docs/primitives/symmetric-encryption.rst deleted file mode 100644 index 87e1e692..00000000 --- a/docs/primitives/symmetric-encryption.rst +++ /dev/null @@ -1,187 +0,0 @@ -Symmetric Encryption -==================== - -.. currentmodule:: cryptography.primitives.block - -.. testsetup:: - - import binascii - key = binascii.unhexlify(b"0" * 32) - iv = binascii.unhexlify(b"0" * 32) - - -Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. - -.. class:: BlockCipher(cipher, mode) - - Block ciphers work by encrypting content in chunks, often 64- or 128-bits. - They combine an underlying algorithm (such as AES), with a mode (such as - CBC, CTR, or GCM). A simple example of encrypting (and then decrypting) - content with AES is: - - .. doctest:: - - >>> from cryptography.primitives.block import BlockCipher, ciphers, modes - >>> cipher = BlockCipher(ciphers.AES(key), modes.CBC(iv)) - >>> encryptor = cipher.encryptor() - >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() - >>> decryptor = cipher.decryptor() - >>> decryptor.update(ct) + decryptor.finalize() - 'a secret message' - - :param cipher: One of the ciphers described below. - :param mode: One of the modes described below. - - .. method:: encryptor() - - :return: An encrypting - :class:`~cryptography.primitives.interfaces.CipherContext` - provider. - - .. method:: decryptor() - - :return: A decrypting - :class:`~cryptography.primitives.interfaces.CipherContext` - provider. - -.. currentmodule:: cryptography.primitives.interfaces - -.. class:: CipherContext() - - When calling ``encryptor()`` or ``decryptor()`` on a BlockCipher object you - will receive a return object conforming to the CipherContext interface. You - can then call ``update(data)`` with data until you have fed everything into - the context. Once that is done call ``finalize()`` to finish the operation and - obtain the remainder of the data. - - - .. method:: update(data) - - :param bytes data: The text you wish to pass into the context. - :return bytes: Returns the data that was encrypted or decrypted. - - .. method:: finalize() - - :return bytes: Returns the remainder of the data. - -Ciphers -~~~~~~~ - -.. currentmodule:: cryptography.primitives.block.ciphers - -.. class:: AES(key) - - AES (Advanced Encryption Standard) is a block cipher standardized by NIST. - AES is both fast, and cryptographically strong. It is a good default - choice for encryption. - - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. - -.. class:: Camellia(key) - - Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. - It is considered to have comparable security and performance to AES, but - is not as widely studied or deployed. - - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. - - -.. class:: TripleDES(key) - - Triple DES (Data Encryption Standard), sometimes refered to as 3DES, is a - block cipher standardized by NIST. Triple DES has known cryptoanalytic - flaws, however none of them currently enable a practical attack. - Nonetheless, Triples DES is not reccomended for new applications because it - is incredibly slow; old applications should consider moving away from it. - - :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits - (note that DES functionally uses ``56``, ``112``, or - ``168`` bits of the key, there is a parity byte in each - component of the key), in some materials these are - referred to as being up to three separate keys (each - ``56`` bits long), they can simply be concatenated to - produce the full key. This must be kept secret. - - -Modes -~~~~~ - -.. currentmodule:: cryptography.primitives.block.modes - -.. class:: CBC(initialization_vector) - - CBC (Cipher block chaining) is a mode of operation for block ciphers. It is - considered cryptographically strong. - - :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with - a given ``key``. - - -.. class:: CTR(nonce) - - .. warning:: - - Counter mode is not recommended for use with block ciphers that have a - block size of less than 128-bits. - - CTR (Counter) is a mode of operation for block ciphers. It is considered - cryptographically strong. - - :param bytes nonce: Should be random bytes. It is critical to never reuse a - ``nonce`` with a given key. Any reuse of a nonce - with the same key compromises the security of every - message encrypted with that key. Must be the same - number of bytes as the ``block_size`` of the cipher - with a given key. The nonce does not need to be kept - secret and may be included alongside the ciphertext. - -.. class:: OFB(initialization_vector) - - OFB (Output Feedback) is a mode of operation for block ciphers. It - transforms a block cipher into a stream cipher. - - :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with - a given ``key``. - -.. class:: CFB(initialization_vector) - - CFB (Cipher Feedback) is a mode of operation for block ciphers. It - transforms a block cipher into a stream cipher. - - :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included - in a transmitted message). Must be the - same number of bytes as the - ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with - a given ``key``. - - -Insecure Modes --------------- - -.. warning:: - - These modes are insecure. New applications should never make use of them, - and existing applications should strongly consider migrating away. - - -.. class:: ECB() - - ECB (Electronic Code Book) is the simplest mode of operation for block - ciphers. Each block of data is encrypted in the same way. This means - identical plaintext blocks will always result in identical ciphertext - blocks, and thus result in information leakage -- cgit v1.2.3