diff options
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 70 |
1 files changed, 54 insertions, 16 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5852dc21..5f1a64a1 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -4,7 +4,7 @@ Symmetric Encryption ==================== -.. currentmodule:: cryptography.hazmat.primitives.block +.. currentmodule:: cryptography.hazmat.primitives.ciphers .. testsetup:: @@ -16,24 +16,23 @@ Symmetric Encryption 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) +.. class:: Cipher(algorithm, 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 + Cipher objects combine an 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)) + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> cipher = Cipher(algorithms.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 algorithms: One of the algorithms described below. :param mode: One of the modes described below. .. method:: encryptor() @@ -42,17 +41,26 @@ where the encrypter and decrypter both use the same key. :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + .. method:: decryptor() :return: A decrypting :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` provider. + If the backend doesn't support the requested combination of ``cipher`` + and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` + will be raised. + + .. currentmodule:: cryptography.hazmat.primitives.interfaces .. class:: CipherContext - When calling ``encryptor()`` or ``decryptor()`` on a ``BlockCipher`` object + When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` 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 @@ -63,14 +71,20 @@ where the encrypter and decrypter both use the same key. :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. + When the ``Cipher`` was constructed in a mode that turns it into a + stream cipher (e.g. + :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will + return bytes immediately, however in other modes it will return chunks, + whose size is determined by the cipher's block size. + .. method:: finalize() :return bytes: Returns the remainder of the data. -Ciphers -~~~~~~~ +Algorithms +~~~~~~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.block.ciphers +.. currentmodule:: cryptography.hazmat.primitives.ciphers.algorithms .. class:: AES(key) @@ -135,10 +149,13 @@ Weak Ciphers :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. + +.. _symmetric-encryption-modes: + Modes ~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.block.modes +.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes .. class:: CBC(initialization_vector) @@ -149,9 +166,29 @@ Modes 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``. + ``block_size`` of the cipher. Each time + something is encrypted a new + ``initialization_vector`` should be + generated. Do not reuse an + ``initialization_vector`` with + a given ``key``, and particularly do + not use a constant + ``initialization_vector``. + + A good construction looks like: + + .. code-block:: pycon + + >>> import os + >>> iv = os.urandom(16) + >>> mode = CBC(iv) + + While the following is bad and will leak information: + + .. code-block:: pycon + + >>> iv = "a" * 16 + >>> mode = CBC(iv) .. class:: CTR(nonce) @@ -162,7 +199,8 @@ Modes block size of less than 128-bits. CTR (Counter) is a mode of operation for block ciphers. It is considered - cryptographically strong. + cryptographically strong. It transforms a block cipher into a stream + cipher. :param bytes nonce: Should be random bytes. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce |