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 From ce0d781707979ccb7f6983601c5ccb25d2354582 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Sun, 27 Oct 2013 16:52:33 -0400 Subject: Move the bindings into the hazmat module --- docs/architecture.rst | 10 +++++----- docs/bindings/index.rst | 7 ------- docs/bindings/openssl.rst | 30 ------------------------------ docs/hazmat/bindings/index.rst | 7 +++++++ docs/hazmat/bindings/openssl.rst | 30 ++++++++++++++++++++++++++++++ docs/index.rst | 2 +- 6 files changed, 43 insertions(+), 43 deletions(-) delete mode 100644 docs/bindings/index.rst delete mode 100644 docs/bindings/openssl.rst create mode 100644 docs/hazmat/bindings/index.rst create mode 100644 docs/hazmat/bindings/openssl.rst (limited to 'docs') diff --git a/docs/architecture.rst b/docs/architecture.rst index 8de8649d..4cf639c2 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -8,11 +8,11 @@ Architecture ``cryptography`` has three different layers: -* ``cryptography.bindings``: This package contains bindings to low level - cryptographic libraries. Our initial target will be OpenSSL. -* ``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.hazmat.primitives``. +* ``cryptography.hazmat.primitives``: This packages contains low level + algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of + ``cryptography.hazmat.bindings``. +* ``cryptography.hazmat.bindings``: This package contains bindings to low level + cryptographic libraries. Our initial target will be OpenSSL. diff --git a/docs/bindings/index.rst b/docs/bindings/index.rst deleted file mode 100644 index 80f53594..00000000 --- a/docs/bindings/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Bindings -======== - -.. toctree:: - :maxdepth: 1 - - openssl diff --git a/docs/bindings/openssl.rst b/docs/bindings/openssl.rst deleted file mode 100644 index e59b0c13..00000000 --- a/docs/bindings/openssl.rst +++ /dev/null @@ -1,30 +0,0 @@ -OpenSSL -======= - -.. warning:: - - The OpenSSL API is not easy to use, small mistakes can lead to significant - security vulnerabilities. We strongly recommend not using this directly, - and instead using one of the higher level APIs exposed by ``cryptography``. - - -These are `CFFI`_ bindings to the `OpenSSL`_ C library. - -.. data:: cryptography.bindings.openssl.backend - - This is the exposed API for the OpenSSL bindings. It has two public - attributes: - - .. attribute:: ffi - - This is a :class:`cffi.FFI` instance. It can be used to allocate and - otherwise manipulate OpenSSL structures. - - .. attribute:: lib - - This is a ``cffi`` library. It can be used to call OpenSSL functions, - and access constants. - - -.. _`CFFI`: http://cffi.readthedocs.org/ -.. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst new file mode 100644 index 00000000..80f53594 --- /dev/null +++ b/docs/hazmat/bindings/index.rst @@ -0,0 +1,7 @@ +Bindings +======== + +.. toctree:: + :maxdepth: 1 + + openssl diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst new file mode 100644 index 00000000..5a00395e --- /dev/null +++ b/docs/hazmat/bindings/openssl.rst @@ -0,0 +1,30 @@ +OpenSSL +======= + +.. warning:: + + The OpenSSL API is not easy to use, small mistakes can lead to significant + security vulnerabilities. We strongly recommend not using this directly, + and instead using one of the higher level APIs exposed by ``cryptography``. + + +These are `CFFI`_ bindings to the `OpenSSL`_ C library. + +.. data:: cryptography.hazmat.bindings.openssl.backend + + This is the exposed API for the OpenSSL bindings. It has two public + attributes: + + .. attribute:: ffi + + This is a :class:`cffi.FFI` instance. It can be used to allocate and + otherwise manipulate OpenSSL structures. + + .. attribute:: lib + + This is a ``cffi`` library. It can be used to call OpenSSL functions, + and access constants. + + +.. _`CFFI`: http://cffi.readthedocs.org/ +.. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/index.rst b/docs/index.rst index 47418abb..b2420a8f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,7 +31,6 @@ Contents :maxdepth: 2 architecture - bindings/index contributing security community @@ -43,3 +42,4 @@ Hazard Materials :maxdepth: 2 hazmat/primitives/index + hazmat/bindings/index -- cgit v1.2.3 From d8f0118745ca0f6308e462b8bfd3ddd9caaa3607 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Sun, 27 Oct 2013 16:59:56 -0400 Subject: Warn about dragons and dinosaurs with laser guns --- docs/hazmat/bindings/index.rst | 7 +++++++ docs/hazmat/bindings/openssl.rst | 8 ++++---- docs/hazmat/primitives/cryptographic-hashes.rst | 7 +++++++ docs/hazmat/primitives/index.rst | 7 +++++++ docs/hazmat/primitives/symmetric-encryption.rst | 7 +++++++ 5 files changed, 32 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index 80f53594..163e82e8 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -1,6 +1,13 @@ Bindings ======== +.. 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. + + .. toctree:: :maxdepth: 1 diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 5a00395e..04532466 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -1,11 +1,11 @@ OpenSSL ======= -.. warning:: +.. danger:: - The OpenSSL API is not easy to use, small mistakes can lead to significant - security vulnerabilities. We strongly recommend not using this directly, - and instead using one of the higher level APIs exposed by ``cryptography``. + 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. These are `CFFI`_ bindings to the `OpenSSL`_ C library. diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 05004080..72fd8692 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -1,6 +1,13 @@ Message Digests =============== +.. 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. + + .. currentmodule:: cryptography.hazmat.primitives.hashes .. class:: BaseHash(data=None) diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index c18c62ca..bd3ef410 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -1,6 +1,13 @@ Primitives ========== +.. 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. + + .. toctree:: :maxdepth: 1 diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index e2586aaf..e65e48d4 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -1,6 +1,13 @@ Symmetric Encryption ==================== +.. 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. + + .. currentmodule:: cryptography.hazmat.primitives.block .. testsetup:: -- cgit v1.2.3 From e51fb935bf27ce56282d8bd9b33f708d2e660449 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Sun, 27 Oct 2013 17:26:17 -0400 Subject: Move the danger to the very top of the file --- docs/hazmat/bindings/index.rst | 6 +++--- docs/hazmat/bindings/openssl.rst | 6 +++--- docs/hazmat/primitives/cryptographic-hashes.rst | 6 +++--- docs/hazmat/primitives/index.rst | 6 +++--- docs/hazmat/primitives/symmetric-encryption.rst | 6 +++--- 5 files changed, 15 insertions(+), 15 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index 163e82e8..4de2df47 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -1,6 +1,3 @@ -Bindings -======== - .. danger:: This is a "Hazardous Materials" module. You should **ONLY** use it if @@ -8,6 +5,9 @@ Bindings module is full of land mines, dragons, and dinosaurs with laser guns. +Bindings +======== + .. toctree:: :maxdepth: 1 diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 04532466..00e8094a 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -1,6 +1,3 @@ -OpenSSL -======= - .. danger:: This is a "Hazardous Materials" module. You should **ONLY** use it if @@ -8,6 +5,9 @@ OpenSSL module is full of land mines, dragons, and dinosaurs with laser guns. +OpenSSL +======= + These are `CFFI`_ bindings to the `OpenSSL`_ C library. .. data:: cryptography.hazmat.bindings.openssl.backend diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 72fd8692..de66b7fe 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -1,6 +1,3 @@ -Message Digests -=============== - .. danger:: This is a "Hazardous Materials" module. You should **ONLY** use it if @@ -8,6 +5,9 @@ Message Digests module is full of land mines, dragons, and dinosaurs with laser guns. +Message Digests +=============== + .. currentmodule:: cryptography.hazmat.primitives.hashes .. class:: BaseHash(data=None) diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index bd3ef410..6ae769a6 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -1,6 +1,3 @@ -Primitives -========== - .. danger:: This is a "Hazardous Materials" module. You should **ONLY** use it if @@ -8,6 +5,9 @@ Primitives module is full of land mines, dragons, and dinosaurs with laser guns. +Primitives +========== + .. toctree:: :maxdepth: 1 diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index e65e48d4..758a4648 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -1,6 +1,3 @@ -Symmetric Encryption -==================== - .. danger:: This is a "Hazardous Materials" module. You should **ONLY** use it if @@ -8,6 +5,9 @@ Symmetric Encryption module is full of land mines, dragons, and dinosaurs with laser guns. +Symmetric Encryption +==================== + .. currentmodule:: cryptography.hazmat.primitives.block .. testsetup:: -- cgit v1.2.3 From 0a1550e86fbb8a64a1f534babd76da5afd1c4c11 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Mon, 28 Oct 2013 12:13:33 -0400 Subject: Hazard -> Hazardous --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index b2420a8f..23e966d1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,8 +35,8 @@ Contents security community -Hazard Materials ----------------- +Hazardous Materials +------------------- .. toctree:: :maxdepth: 2 -- cgit v1.2.3