diff options
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 80 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 77 |
3 files changed, 77 insertions, 81 deletions
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 24f0f5b1..dfa81d09 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -9,6 +9,5 @@ Asymmetric algorithms dsa ec rsa - padding serialization utils diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst deleted file mode 100644 index 00c77590..00000000 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. hazmat:: - -Padding -======= - -.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding - -.. warning:: - `Padding is critical`_ when signing or encrypting data using RSA. Without - correct padding signatures can be forged, messages decrypted, and private - keys compromised. - -.. 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. - -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. - - -.. _`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 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 |