Merge pull request #188 from dstufft/hazmat

Create a Hazardous Materials Area

3 files changed, 308 insertions, 0 deletions

diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst
new file mode 100644
index 00000000..de66b7fe
--- /dev/null
+++ b/docs/hazmat/primitives/cryptographic-hashes.rst
@@ -0,0 +1,99 @@
+.. danger::
+
+    This is a "Hazardous Materials" module. You should **ONLY** use it if
+    you're 100% absolutely sure that you know what you're doing because this
+    module is full of land mines, dragons, and dinosaurs with laser guns.
+
+
+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..6ae769a6
--- /dev/null
+++ b/docs/hazmat/primitives/index.rst
@@ -0,0 +1,15 @@
+.. danger::
+
+    This is a "Hazardous Materials" module. You should **ONLY** use it if
+    you're 100% absolutely sure that you know what you're doing because this
+    module is full of land mines, dragons, and dinosaurs with laser guns.
+
+
+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..758a4648
--- /dev/null
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -0,0 +1,194 @@
+.. danger::
+
+    This is a "Hazardous Materials" module. You should **ONLY** use it if
+    you're 100% absolutely sure that you know what you're doing because this
+    module is full of land mines, dragons, and dinosaurs with laser guns.
+
+
+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