diff options
Diffstat (limited to 'docs/hazmat')
| -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 |
7 files changed, 388 insertions, 20 deletions
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 |