diff options
Diffstat (limited to 'docs/hazmat/primitives')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 22 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 89 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 18 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 107 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/hmac.rst (renamed from docs/hazmat/primitives/hmac.rst) | 0 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/index.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 4 |
9 files changed, 248 insertions, 6 deletions
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 89af7eaa..40084799 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -19,7 +19,8 @@ Padding PSS (Probabilistic Signature Scheme) is a signature scheme defined in :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_. - This is the `recommended padding algorithm`_ for RSA signatures. + This is the `recommended padding algorithm`_ for RSA signatures. It cannot + be used with RSA encryption. :param mgf: A mask generation function object. At this time the only supported MGF is :class:`MGF1`. @@ -32,12 +33,28 @@ Padding Pass this attribute to ``salt_length`` to get the maximum salt length available. +.. class:: OAEP(mgf, label) + + .. versionadded:: 0.4 + + OAEP (Optimal Asymmetric Encryption Padding) is a padding scheme defined in + :rfc:`3447`. It provides probabilistic encryption and is `proven secure`_ + against several attack types. This is the `recommended padding algorithm`_ + for RSA encryption. It cannot be used with RSA signing. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + + :param bytes label: A label to apply. This is a rarely used field and + should typically be set to ``None`` or ``b""``, which are equivalent. + .. class:: PKCS1v15() .. versionadded:: 0.3 PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme - developed for use with RSA keys. It is defined in :rfc:`3447`. + developed for use with RSA keys. It is defined in :rfc:`3447`. This padding + can be used for signing and encryption. Mask generation functions ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -60,3 +77,4 @@ Mask generation functions .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ .. _`security proof`: http://eprint.iacr.org/2001/062.pdf .. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html +.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 5074f1c5..862df635 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -116,6 +116,60 @@ RSA :raises ValueError: This is raised when the chosen hash algorithm is too large for the key size. + .. method:: decrypt(ciphertext, padding, backend) + + .. versionadded:: 0.4 + + Decrypt data that was encrypted with the public key. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return bytes: Decrypted data. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when decryption fails or the data + is too large for the key size. If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` + it may also be raised for invalid label values. + + .. code-block:: python + + from cryptography.hazmat.backends import default_backend + from cryptography.hazmat.primitives import hashes + from cryptography.hazmat.primitives.asymmetric import padding + + plaintext = private_key.decrypt( + ciphertext, + padding.OAEP( + mgf=padding.MGF1(algorithm=hashes.SHA1()), + algorithm=hashes.SHA1(), + label=None + ), + default_backend() + ) + .. class:: RSAPublicKey(public_exponent, modulus) @@ -214,7 +268,42 @@ RSA too large for the key size. +Handling partial RSA private keys +--------------------------------- + +If you are trying to load RSA private keys yourself you may find that not all +parameters required by ``RSAPrivateKey`` are available. In particular the +`Chinese Remainder Theorem`_ (CRT) values ``dmp1``, ``dmq1``, ``iqmp`` may be +missing or present in a different form. For example `OpenPGP`_ does not include +the ``iqmp``, ``dmp1`` or ``dmq1`` parameters. + +The following functions are provided for users who want to work with keys like +this without having to do the math themselves. + +.. function:: rsa_crt_iqmp(p, q) + + .. versionadded:: 0.4 + + Generates the ``iqmp`` (also known as ``qInv``) parameter from the RSA + primes ``p`` and ``q``. + +.. function:: rsa_crt_dmp1(private_exponent, p) + + .. versionadded:: 0.4 + + Generates the ``dmp1`` parameter from the RSA private exponent and prime + ``p``. + +.. function:: rsa_crt_dmq1(private_exponent, q) + + .. versionadded:: 0.4 + + Generates the ``dmq1`` parameter from the RSA private exponent and prime + ``q``. + .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf +.. _`OpenPGP`: https://en.wikipedia.org/wiki/Pretty_Good_Privacy +.. _`Chinese Remainder Theorem`: http://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 90deec8b..a9ab38a0 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -7,7 +7,7 @@ Primitives :maxdepth: 1 cryptographic-hashes - hmac + mac/index symmetric-encryption padding key-derivation-functions diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 95fd6f9f..3b837a0d 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -133,6 +133,24 @@ Asymmetric interfaces :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + .. method:: decrypt(ciphertext, padding, backend) + + .. versionadded:: 0.4 + + Decrypt data that was encrypted via the public key. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return bytes: Decrypted data. + .. method:: public_key() :return: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst new file mode 100644 index 00000000..a6b048b5 --- /dev/null +++ b/docs/hazmat/primitives/mac/cmac.rst @@ -0,0 +1,107 @@ +.. hazmat:: + +Cipher-based message authentication code +======================================== + +.. currentmodule:: cryptography.hazmat.primitives.cmac + +.. testsetup:: + + import binascii + key = binascii.unhexlify(b"0" * 32) + +`Cipher-based message authentication codes`_ (or CMACs) are a tool for calculating +message authentication codes using a block cipher coupled with a +secret key. You can use an CMAC to verify both the integrity and authenticity +of a message. + +A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. + +.. class:: CMAC(algorithm, backend) + + .. versionadded:: 0.4 + + CMAC objects take a + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` provider. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import cmac + >>> from cryptography.hazmat.primitives.ciphers import algorithms + >>> c = cmac.CMAC(algorithms.AES(key), backend=default_backend()) + >>> c.update(b"message to authenticate") + >>> c.finalize() + 'CT\x1d\xc8\x0e\x15\xbe4e\xdb\xb6\x84\xca\xd9Xk' + + If the backend doesn't support the requested ``algorithm`` an + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. + + If the `algorithm`` isn't a + :class:`~cryptography.primitives.interfaces.BlockCipherAlgorithm` provider, + ``TypeError`` will be raised. + + To check that a given signature is correct use the :meth:`verify` method. + You will receive an exception if the signature is wrong: + + .. code-block:: pycon + + >>> c.verify(b"an incorrect signature") + Traceback (most recent call last): + ... + cryptography.exceptions.InvalidSignature: Signature did not match digest. + + :param algorithm: An + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + provider. + :param backend: An + :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` + provider. + :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of + :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` + + .. method:: update(data) + + :param bytes data: The bytes to hash and authenticate. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + + .. method:: copy() + + Copy this :class:`CMAC` instance, usually so that we may call + :meth:`finalize` to get an intermediate value while we continue + to call :meth:`update` on the original instance. + + :return: A new instance of :class:`CMAC` that can be updated + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + + .. method:: verify(signature) + + Finalize the current context and securely compare the MAC to + ``signature``. + + :param bytes signature: The bytes to compare the current CMAC + against. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :raises cryptography.exceptions.InvalidSignature: If signature does not + match digest + + .. method:: finalize() + + Finalize the current context and return the message authentication code + as bytes. + + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. + + :return bytes: The message authentication code as bytes. + :raises cryptography.exceptions.AlreadyFinalized: + + +.. _`Cipher-based message authentication codes`: https://en.wikipedia.org/wiki/CMAC diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/mac/hmac.rst index 11b10735..11b10735 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/mac/hmac.rst diff --git a/docs/hazmat/primitives/mac/index.rst b/docs/hazmat/primitives/mac/index.rst new file mode 100644 index 00000000..59fb8da2 --- /dev/null +++ b/docs/hazmat/primitives/mac/index.rst @@ -0,0 +1,10 @@ +.. hazmat:: + +Message Authentication Codes +============================ + +.. toctree:: + :maxdepth: 1 + + cmac + hmac diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst index d23f31bb..3056eb92 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -5,7 +5,7 @@ Padding .. currentmodule:: cryptography.hazmat.primitives.padding -Padding is a way to take data that may or may not be be a multiple of the block +Padding is a way to take data that may or may not be a multiple of the block size for a cipher and extend it out so that it is. This is required for many block cipher modes as they require the data to be encrypted to be an exact multiple of the block size. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 1a4df222..c2692ae2 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -21,7 +21,7 @@ message but an attacker can create bogus messages and force the application to decrypt them. For this reason it is *strongly* recommended to combine encryption with a -message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in +message authentication code, such as :doc:`HMAC </hazmat/primitives/mac/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode, backend) @@ -289,7 +289,7 @@ Modes block cipher mode that simultaneously encrypts the message as well as authenticating it. Additional unencrypted data may also be authenticated. Additional means of verifying integrity such as - :doc:`HMAC </hazmat/primitives/hmac>` are not necessary. + :doc:`HMAC </hazmat/primitives/mac/hmac>` are not necessary. **This mode does not require padding.** |