diff options
Diffstat (limited to 'docs/hazmat/primitives/asymmetric/rsa.rst')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 89 |
1 files changed, 89 insertions, 0 deletions
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 |