diff options
Diffstat (limited to 'docs/hazmat/primitives')
-rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 92 | ||||
-rw-r--r-- | docs/hazmat/primitives/index.rst | 8 | ||||
-rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 187 |
3 files changed, 287 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..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 |