diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/architecture.rst | 5 | ||||
| -rw-r--r-- | docs/contributing.rst | 15 | ||||
| -rw-r--r-- | docs/cryptography-docs.py | 9 | ||||
| -rw-r--r-- | docs/exceptions.rst | 17 | ||||
| -rw-r--r-- | docs/glossary.rst | 13 | ||||
| -rw-r--r-- | docs/hazmat/bindings/index.rst | 25 | ||||
| -rw-r--r-- | docs/hazmat/bindings/interfaces.rst | 141 | ||||
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 37 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 29 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 26 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 142 | ||||
| -rw-r--r-- | docs/security.rst | 2 |
13 files changed, 440 insertions, 29 deletions
diff --git a/docs/architecture.rst b/docs/architecture.rst index 4cf639c2..5ca2c252 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -1,11 +1,6 @@ Architecture ============ -.. warning:: - - Because ``cryptography`` is so young, much of this document is - aspirational, rather than documentation. - ``cryptography`` has three different layers: * ``cryptography``: This package contains higher level recipes, for example diff --git a/docs/contributing.rst b/docs/contributing.rst index 3b301842..4647818a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -122,6 +122,18 @@ So, specifically: * No blank line at the end. * Use Sphinx parameter/attribute documentation `syntax`_. +Because of the inherent challenges in implementing correct cryptographic +systems, we want to make our documentation point people in the right directions +as much as possible. To that end: + +* When documenting a generic interface, use a strong algorithm in examples. + (e.g. when showing a hashing example, don't use + :class:`cryptography.hazmat.primitives.hashes.MD5`) +* When giving prescriptive advice, always provide references and supporting + material. +* When there is real disagreement between cryptographic experts, represent both + sides of the argument and describe the trade-offs clearly. + When documenting a new module in the ``hazmat`` package, its documentation should begin with the "Hazardous Materials" warning: @@ -129,6 +141,9 @@ should begin with the "Hazardous Materials" warning: .. hazmat:: +When referring to a hypothetical individual (such as "a person receiving an +encrypted message") use gender neutral pronouns (they/them/their). + Development Environment ----------------------- diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index 4ed5526a..ea7e8eef 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -31,10 +31,14 @@ class Hazmat(nodes.Admonition, nodes.Element): pass -def visit_hazmat_node(self, node): +def html_visit_hazmat_node(self, node): return self.visit_admonition(node, "danger") +def latex_visit_hazmat_node(self, node): + return self.visit_admonition(node) + + def depart_hazmat_node(self, node): return self.depart_admonition(node) @@ -42,6 +46,7 @@ def depart_hazmat_node(self, node): def setup(app): app.add_node( Hazmat, - html=(visit_hazmat_node, depart_hazmat_node) + html=(html_visit_hazmat_node, depart_hazmat_node), + latex=(latex_visit_hazmat_node, depart_hazmat_node), ) app.add_directive("hazmat", HazmatDirective) diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 6ac11b3c..087066b8 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -3,6 +3,23 @@ Exceptions .. currentmodule:: cryptography.exceptions +.. class:: AlreadyFinalized + + This is raised when a context is used after being finalized. + + +.. class:: NotYetFinalized + + This is raised when the AEAD tag property is accessed on a context + before it is finalized. + + +.. class:: AlreadyUpdated + + This is raised when additional data is added to a context after update + has already been called. + + .. class:: UnsupportedAlgorithm This is raised when a backend doesn't support the requested algorithm (or diff --git a/docs/glossary.rst b/docs/glossary.rst index e4fc8283..63e0a6ce 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -27,4 +27,15 @@ Glossary asymmetric cryptography Cryptographic operations where encryption and decryption use different - keys. There are seperate encryption and decryption keys. + keys. There are separate encryption and decryption keys. + + authentication + The process of verifying that a message was created by a specific + individual (or program). Like encryption, authentication can be either + symmetric or asymmetric. Authentication is necessary for effective + encryption. + + Ciphertext indistinguishability + This is a property of encryption systems whereby two encrypted messages + aren't distinguishable without knowing the encryption key. This is + considered a basic, necessary property for a working encryption system. diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index 19e03999..746f4596 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -7,3 +7,28 @@ Bindings :maxdepth: 1 openssl + interfaces + + +Getting a Backend Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: cryptography.hazmat.bindings + +``cryptography`` aims to support multiple backends to ensure it can provide +the widest number of supported cryptographic algorithms as well as supporting +platform specific implementations. + +You can get the default backend by calling +:func:`~default_backend`. + +The default backend will change over time as we implement new backends and +the libraries we use in those backends changes. + + +.. function:: default_backend() + + :returns: An object that provides at least + :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and + :class:`~interfaces.HMACBackend`. + diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst new file mode 100644 index 00000000..711c82c2 --- /dev/null +++ b/docs/hazmat/bindings/interfaces.rst @@ -0,0 +1,141 @@ +.. hazmat:: + +Backend Interfaces +================== + +.. currentmodule:: cryptography.hazmat.bindings.interfaces + + +Backend implementations may provide a number of interfaces to support operations +such as :doc:`/hazmat/primitives/symmetric-encryption`, +:doc:`/hazmat/primitives/cryptographic-hashes`, and +:doc:`/hazmat/primitives/hmac`. + +A specific ``backend`` may provide one or more of these interfaces. + + +.. class:: CipherBackend + + A backend which provides methods for using ciphers for encryption + and decryption. + + .. method:: cipher_supported(cipher, mode) + + Check if a ``cipher`` and ``mode`` combination is supported by + this backend. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: ``True`` if the specified ``cipher`` and ``mode`` combination + is supported by this backend, otherwise ``False`` + + .. method:: register_cipher_adapter(cipher_cls, mode_cls, adapter) + + Register an adapter which can be used to create a backend specific + object from instances of the + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` and + the :class:`~cryptography.hazmat.primitives.interfaces.Mode` primitives. + + :param cipher_cls: A class whose instances provide + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :param mode_cls: A class whose instances provide: + :class:`~cryptography.hazmat.primitives.interfaces.Mode` + :param adapter: A ``function`` that takes 3 arguments, ``backend`` (a + :class:`CipherBackend` provider), ``cipher`` (a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider ), and ``mode`` (a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider). + It returns a backend specific object which may be used to construct + a :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext`. + + + .. method:: create_symmetric_encryption_ctx(cipher, mode) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + can be used for encrypting data with the symmetric ``cipher`` using + the given ``mode``. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + + :raises ValueError: When tag is not None in an AEAD mode + + + .. method:: create_symmetric_decryption_ctx(cipher, mode) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + can be used for decrypting data with the symmetric ``cipher`` using + the given ``mode``. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + + :raises ValueError: When tag is None in an AEAD mode + + +.. class:: HashBackend + + A backend with methods for using cryptographic hash functions. + + .. method:: hash_supported(algorithm) + + Check if the specified ``algorithm`` is supported by this backend. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported by this + backend, otherwise ``False``. + + + .. method:: create_hash_ctx(algorithm) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + uses the specified ``algorithm`` to calculate a message digest. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` + + +.. class:: HMACBackend + + A backend with methods for using cryptographic hash functions as message + authentication codes. + + .. method:: create_hmac_ctx(algorithm) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + uses the specified ``algorithm`` to calculate a hash-based message + authentication code. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 20fa23cf..312d7e69 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -5,7 +5,7 @@ Message Digests .. currentmodule:: cryptography.hazmat.primitives.hashes -.. class:: Hash(algorithm) +.. class:: Hash(algorithm, backend) A cryptographic hash function takes an arbitrary block of data and calculates a fixed-size bit string (a digest), such that different data @@ -20,30 +20,56 @@ Message Digests .. doctest:: + >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes - >>> digest = hashes.Hash(hashes.SHA256()) + >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) >>> digest.update(b"abc") >>> digest.update(b"123") >>> digest.finalize() 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' + Keep in mind that attacks against cryptographic hashes only get stronger + with time, and that often algorithms that were once thought to be strong, + become broken. Because of this it's important to include a plan for + upgrading the hash algorithm you use over time. For more information, see + `Lifetimes of cryptographic hash functions`_. + + :param algorithm: A + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider such as those described in + :ref:`below <cryptographic-hash-algorithms>`. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.HashBackend` + provider. + .. method:: update(data) :param bytes data: The bytes you wish to hash. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: copy() - :return: a new instance of this object with a copied internal state. + Copy this :class:`Hash` instance, usually so that we may call + :meth:`finalize` and get an intermediate digest value while we continue + to call :meth:`update` on the original. + + :return: A new instance of :class:`Hash` which can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used. + Once ``finalize`` is called this object can no longer be used and + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. +.. _cryptographic-hash-algorithms: + SHA-1 ~~~~~ @@ -109,3 +135,6 @@ MD5 MD5 is a deprecated cryptographic hash function. It has a 128-bit message digest and has practical known collision attacks. + + +.. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index bd1a4934..db5e98d3 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -15,7 +15,7 @@ message authentication codes using a cryptographic hash function coupled with a secret key. You can use an HMAC to verify integrity as well as authenticate a message. -.. class:: HMAC(key, algorithm) +.. class:: HMAC(key, algorithm, backend) HMAC objects take a ``key`` and a provider of :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. @@ -27,24 +27,45 @@ message. .. doctest:: + >>> from cryptography.hazmat.bindings import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac - >>> h = hmac.HMAC(key, hashes.SHA256()) + >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") >>> h.finalize() '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' + + :param key: Secret key as ``bytes``. + :param algorithm: A + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider such as those described in + :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend` + provider. + .. method:: update(msg) :param bytes msg: The bytes to hash and authenticate. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: copy() - :return: a new instance of this object with a copied internal state. + Copy this :class:`HMAC` instance, usually so that we may call + :meth:`finalize` and get an intermediate digest value while we continue + to call :meth:`update` on the original. + + :return: A new instance of :class:`HMAC` which can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used. + Once ``finalize`` is called this object can no longer be used and + :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. :return bytes: The message digest as bytes. + :raises cryptography.exceptions.AlreadyFinalized: diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 7068316e..11cff51a 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -12,11 +12,33 @@ to document argument and return types. .. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html -Cipher Modes -~~~~~~~~~~~~ +Symmetric Ciphers +~~~~~~~~~~~~~~~~~ .. currentmodule:: cryptography.hazmat.primitives.interfaces + +.. class:: CipherAlgorithm + + A named symmetric encryption algorithm. + + .. attribute:: name + + :type: str + + The standard name for the mode, for example, "AES", "Camellia", or + "Blowfish". + + .. attribute:: key_size + + :type: int + + The number of bits in the key being used. + + +Cipher Modes +------------ + Interfaces used by the symmetric cipher modes described in :ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`. diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index aebb4d4d..4d79ac8f 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -25,8 +25,14 @@ multiple of the block size. >>> padder = padding.PKCS7(128).padder() >>> padder.update(b"1111111111") '' - >>> padder.finalize() + >>> padded_data = padder.finalize() + >>> padded_data '1111111111\x06\x06\x06\x06\x06\x06' + >>> unpadder = padding.PKCS7(128).unpadder() + >>> unpadder.update(padded_data) + '' + >>> unpadder.finalize() + '1111111111' :param block_size: The size of the block in bits that the data is being padded to. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 5542e832..2f390175 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -12,17 +12,20 @@ Symmetric Encryption key = binascii.unhexlify(b"0" * 32) iv = binascii.unhexlify(b"0" * 32) + from cryptography.hazmat.bindings import default_backend + backend = default_backend() + Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the encrypter and decrypter both use the same key. Note that symmetric +where the sender and receiver both use the same key. Note that symmetric encryption is **not** sufficient for most applications, because it only provides secrecy (an attacker can't see the message) but not authenticity (an attacker can create bogus messages and force the application to decrypt them). -For this reason it is *strongly* reccomended to combine encryption with a +For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. -.. class:: Cipher(algorithm, mode) +.. class:: Cipher(algorithm, mode, backend) Cipher objects combine an algorithm (such as :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a @@ -34,15 +37,23 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv)) + >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() >>> decryptor = cipher.decryptor() >>> decryptor.update(ct) + decryptor.finalize() 'a secret message' - :param algorithms: One of the algorithms described below. - :param mode: One of the modes described below. + :param algorithms: A + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider such as those described + :ref:`below <symmetric-encryption-algorithms>`. + :param mode: A :class:`~cryptography.hazmat.primitives.interfaces.Mode` + provider such as those described + :ref:`below <symmetric-encryption-modes>`. + :param backend: A + :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + provider. .. method:: encryptor() @@ -75,10 +86,20 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. everything into the context. Once that is done call ``finalize()`` to finish the operation and obtain the remainder of the data. + Block ciphers require that plaintext or ciphertext always be a multiple of + their block size, because of that **padding** is often required to make a + message the correct size. ``CipherContext`` will not automatically apply + any padding; you'll need to add your own. For block ciphers the recommended + padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you + are using a stream cipher mode (such as + :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry + about this. + .. method:: update(data) :param bytes data: The data you wish to pass into the context. :return bytes: Returns the data that was encrypted or decrypted. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` When the ``Cipher`` was constructed in a mode that turns it into a stream cipher (e.g. @@ -89,6 +110,45 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. method:: finalize() :return bytes: Returns the remainder of the data. + :raises ValueError: This is raised when the data provided isn't + correctly padded to be a multiple of the + algorithm's block size. + + Once ``finalize`` is called this object can no longer be used and + :meth:`update` and :meth:`finalize` will raise + :class:`~cryptography.exceptions.AlreadyFinalized`. + +.. class:: AEADCipherContext + + When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object + with an AEAD mode you will receive a return object conforming to the + ``AEADCipherContext`` interface (in addition to the ``CipherContext`` + interface). If it is an encryption context it will additionally be an + ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an + additional method ``authenticate_additional_data`` for adding additional + authenticated but unencrypted data. You should call this before calls to + ``update``. When you are done call ``finalize()`` to finish the operation. + + .. method:: authenticate_additional_data(data) + + :param bytes data: The data you wish to authenticate but not encrypt. + :raises: :class:`~cryptography.exceptions.AlreadyFinalized` + +.. class:: AEADEncryptionContext + + When creating an encryption context using ``encryptor()`` on a ``Cipher`` + object with an AEAD mode you will receive a return object conforming to the + ``AEADEncryptionContext`` interface (as well as ``AEADCipherContext``). + This interface provides one additional attribute ``tag``. ``tag`` can only + be obtained after ``finalize()``. + + .. attribute:: tag + + :return bytes: Returns the tag value as bytes. + :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called + before the context is finalized. + +.. _symmetric-encryption-algorithms: Algorithms ~~~~~~~~~~ @@ -116,10 +176,10 @@ Algorithms .. 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 + Triple DES (Data Encryption Standard), sometimes referred to as 3DES, is a + block cipher standardized by NIST. Triple DES has known crypto-analytic flaws, however none of them currently enable a practical attack. - Nonetheless, Triples DES is not reccomended for new applications because it + Nonetheless, Triples DES is not recommended 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 @@ -157,6 +217,27 @@ Weak Ciphers :param bytes key: The secret key, 32-448 bits in length (in increments of 8). This must be kept secret. +.. class:: ARC4(key) + + ARC4 (Alleged RC4) is a stream cipher with serious weaknesses in its + initial stream output. Its use is strongly discouraged. ARC4 does not use + mode constructions. + + :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``, + ``192``, or ``256`` bits in length. This must be kept + secret. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> algorithm = algorithms.ARC4(key) + >>> cipher = Cipher(algorithm, mode=None, backend=backend) + >>> encryptor = cipher.encryptor() + >>> ct = encryptor.update(b"a secret message") + >>> decryptor = cipher.decryptor() + >>> decryptor.update(ct) + 'a secret message' + .. _symmetric-encryption-modes: @@ -244,6 +325,48 @@ Modes reuse an ``initialization_vector`` with a given ``key``. +.. class:: GCM(initialization_vector, tag=None) + + .. danger:: + + When using this mode you MUST not use the decrypted data until + :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` + has been called. GCM provides NO guarantees of ciphertext integrity + until decryption is complete. + + GCM (Galois Counter Mode) is a mode of operation for block ciphers. An + AEAD (authenticated encryption with additional data) mode is a type of + block cipher mode that encrypts the message as well as authenticating it + (and optionally additional data that is not encrypted) simultaneously. + Additional means of verifying integrity (like + :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary. + + :param bytes initialization_vector: Must be random bytes. They do not need + to be kept secret (they can be included + in a transmitted message). NIST + `recommends 96-bit IV length`_ for + performance critical situations, but it + can be up to 2\ :sup:`64` - 1 bits. + Do not reuse an ``initialization_vector`` + with a given ``key``. + + :param bytes tag: The tag bytes to verify during decryption. When encrypting + this must be None. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend) + >>> encryptor = cipher.encryptor() + >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") + >>> ct = encryptor.update(b"a secret message") + encryptor.finalize() + >>> tag = encryptor.tag + >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv, tag), backend) + >>> decryptor = cipher.decryptor() + >>> decryptor.authenticate_additional_data(b"authenticated but not encrypted payload") + >>> decryptor.update(ct) + decryptor.finalize() + 'a secret message' + Insecure Modes -------------- @@ -263,3 +386,4 @@ Insecure Modes .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html +.. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf diff --git a/docs/security.rst b/docs/security.rst index 36c8e0f7..88959709 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -5,7 +5,7 @@ We take the security of ``cryptography`` seriously. If you believe you've identified a security issue in it, please report it to ``alex.gaynor@gmail.com``. Message may be encrypted with PGP using key fingerprint ``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public -key is available from most commonly-used keyservers). +key is available from most commonly-used key servers). Once you’ve submitted an issue via email, you should receive an acknowledgment within 48 hours, and depending on the action to be taken, you may receive |