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/hazmat/primitives/symmetric-encryption.rst | 187 ++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 docs/hazmat/primitives/symmetric-encryption.rst (limited to 'docs/hazmat/primitives/symmetric-encryption.rst') 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 -- 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/primitives/symmetric-encryption.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/hazmat/primitives/symmetric-encryption.rst') 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/primitives/symmetric-encryption.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/hazmat/primitives/symmetric-encryption.rst') 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