diff options
Diffstat (limited to 'docs/hazmat/primitives/asymmetric/rsa.rst')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 6c96090a..b553a067 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -128,9 +128,83 @@ provider. ... ) ... ) +Padding +~~~~~~~ + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding + +.. class:: PSS(mgf, salt_length) + + .. versionadded:: 0.3 + + .. versionchanged:: 0.4 + Added ``salt_length`` parameter. + + 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. It cannot + be used with RSA encryption. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + + :param int salt_length: The length of the salt. It is recommended that this + be set to ``PSS.MAX_LENGTH``. + + .. attribute:: MAX_LENGTH + + 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`. This padding + can be used for signing and encryption. + + It is not recommended that ``PKCS1v15`` be used for new applications, + :class:`OAEP` should be preferred for encryption and :class:`PSS` should be + preferred for signatures. + +Mask generation functions +------------------------- + +.. class:: MGF1(algorithm) + + .. versionadded:: 0.3 + + .. versionchanged:: 0.6 + Removed the deprecated ``salt_length`` parameter. + + MGF1 (Mask Generation Function 1) is used as the mask generation function + in :class:`PSS` padding. It takes a hash algorithm and a salt length. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + Numbers ~~~~~~~ +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa + These classes hold the constituent components of an RSA key. They are useful only when more traditional :doc:`/hazmat/primitives/asymmetric/serialization` is unavailable. @@ -272,3 +346,6 @@ this without having to do the math themselves. .. _`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`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm +.. _`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 |