aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat/primitives/asymmetric
diff options
context:
space:
mode:
Diffstat (limited to 'docs/hazmat/primitives/asymmetric')
-rw-r--r--docs/hazmat/primitives/asymmetric/padding.rst22
-rw-r--r--docs/hazmat/primitives/asymmetric/rsa.rst89
2 files changed, 109 insertions, 2 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