From 4c0a374dd90cd48c21267e4d8be1ddef8288b29c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 5 Apr 2014 19:51:00 -0500 Subject: docs, tests, general huge improvements to RSA decryption --- docs/hazmat/backends/interfaces.rst | 12 ++++++++++++ docs/hazmat/primitives/asymmetric/padding.rst | 22 ++++++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 394d060b..71cd4564 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -263,6 +263,18 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: ``True`` if the specified ``algorithm`` is supported by this backend, otherwise ``False``. + .. method:: decrypt_rsa(private_key, ciphertext, padding) + + :param private_key: An instance of an + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + provider. + + :param bytes ciphertext: The ciphertext to decrypt. + + :param padding: An instance of an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + .. class:: OpenSSLSerializationBackend diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 89af7eaa..0c2f7ce7 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,6 +10,21 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. +.. 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 many + backends do not support it. + .. class:: PSS(mgf, salt_length) .. versionadded:: 0.3 @@ -19,7 +34,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`. @@ -37,7 +53,8 @@ Padding .. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -58,5 +75,6 @@ Mask generation functions .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ +.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf .. _`security proof`: http://eprint.iacr.org/2001/062.pdf .. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -- cgit v1.2.3 From e1c89f3d25c381f945db9de45c4782b123b7fe49 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 7 Apr 2014 21:44:57 -0500 Subject: update docs for OAEP --- docs/hazmat/primitives/asymmetric/padding.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 0c2f7ce7..06bd2c42 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -22,8 +22,8 @@ Padding :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 many - backends do not support it. + :param bytes label: A label to apply. This is a rarely used field and + should typically be set to ``None`` or ``b""`` (equivalent values). .. class:: PSS(mgf, salt_length) -- cgit v1.2.3 From af9a2cc7bc73129fcd807ac890be59dcc9672a4c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 7 Apr 2014 22:15:38 -0500 Subject: add InvalidDecryption exception, check for ct > key size --- docs/exceptions.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 28da8ecc..23e0df0a 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -43,3 +43,7 @@ Exceptions This is raised when the verify method of a one time password function's computed token does not match the expected token. + +.. class:: InvalidDecryption + + This is raised when RSA decryption does not succeed. -- cgit v1.2.3 From 7bdcdc175675bc78edaa7e0f931676652ab7a427 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 15 Apr 2014 14:16:35 -0400 Subject: remove OAEP decryption to simplify review --- docs/hazmat/primitives/asymmetric/padding.rst | 16 ---------------- 1 file changed, 16 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 06bd2c42..f33ca4e2 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,21 +10,6 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. -.. 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""`` (equivalent values). - .. class:: PSS(mgf, salt_length) .. versionadded:: 0.3 @@ -75,6 +60,5 @@ Mask generation functions .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ -.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf .. _`security proof`: http://eprint.iacr.org/2001/062.pdf .. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -- cgit v1.2.3 From 27f9ca663def6fdccd97297ef40c55923a43394a Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 15 Apr 2014 17:59:27 -0400 Subject: more docs --- docs/hazmat/primitives/asymmetric/rsa.rst | 33 +++++++++++++++++++++++++++++++ docs/hazmat/primitives/interfaces.rst | 18 +++++++++++++++++ 2 files changed, 51 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index c9de2831..e72e8835 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -116,6 +116,39 @@ 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 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. + + :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. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when the chosen hash algorithm is + too large for the key size. + + :raises cryptography.exceptions.InvalidDecryption: This is raised if + decryption fails due to invalid ciphertext. + .. class:: RSAPublicKey(public_exponent, modulus) 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` -- cgit v1.2.3 From 8ab7a360330daa195ea1c0cf70d606dc7dce88c8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Apr 2014 09:34:56 -0500 Subject: remove InvalidDecryption and replace with ValueError --- docs/exceptions.rst | 4 ---- docs/hazmat/primitives/asymmetric/rsa.rst | 7 ++----- 2 files changed, 2 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 23e0df0a..28da8ecc 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -43,7 +43,3 @@ Exceptions This is raised when the verify method of a one time password function's computed token does not match the expected token. - -.. class:: InvalidDecryption - - This is raised when RSA decryption does not succeed. diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index e72e8835..aef15691 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -143,11 +143,8 @@ RSA :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. - :raises ValueError: This is raised when the chosen hash algorithm is - too large for the key size. - - :raises cryptography.exceptions.InvalidDecryption: This is raised if - decryption fails due to invalid ciphertext. + :raises ValueError: This is raised when decryption fails or the chosen + hash algorithm is too large for the key size. .. class:: RSAPublicKey(public_exponent, modulus) -- cgit v1.2.3 From 8e764396471beb13d0cdfbc9a299b9445f96abb2 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 20 Apr 2014 10:25:48 -0500 Subject: more key length checks, docs update --- docs/hazmat/primitives/asymmetric/rsa.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index aef15691..c282d9ef 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -120,7 +120,7 @@ RSA .. versionadded:: 0.4 - Decrypt data that was encrypted via the public key. + Decrypt data that was encrypted with the public key. :param bytes ciphertext: The ciphertext to decrypt. @@ -251,7 +251,7 @@ 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 ``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. @@ -271,7 +271,7 @@ this without having to do the math themselves. ``p``. .. function:: rsa_crt_dmq1(private_exponent, q) - + .. versionadded:: 0.4 Generates the ``dmq1`` parameter from the RSA private exponent and prime -- cgit v1.2.3