diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 16 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 28 |
2 files changed, 42 insertions, 2 deletions
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index f33ca4e2..40084799 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -33,6 +33,21 @@ 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 @@ -62,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 c282d9ef..862df635 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -138,13 +138,37 @@ RSA 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 chosen - hash algorithm is too large for the key size. + :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) |