From 4ccceaf4484dce24c5f0994b52079293a5fdb37c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 11:26:37 -0600 Subject: add RSA PKCS1 signing (and structure for PSS + verification) --- docs/hazmat/primitives/asymmetric/index.rst | 10 +++ docs/hazmat/primitives/asymmetric/padding.rst | 20 +++++ docs/hazmat/primitives/asymmetric/rsa.rst | 107 ++++++++++++++++++++++++++ docs/hazmat/primitives/index.rst | 2 +- docs/hazmat/primitives/rsa.rst | 77 ------------------ 5 files changed, 138 insertions(+), 78 deletions(-) create mode 100644 docs/hazmat/primitives/asymmetric/index.rst create mode 100644 docs/hazmat/primitives/asymmetric/padding.rst create mode 100644 docs/hazmat/primitives/asymmetric/rsa.rst delete mode 100644 docs/hazmat/primitives/rsa.rst (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst new file mode 100644 index 00000000..10319fad --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -0,0 +1,10 @@ +.. hazmat:: + +Asymmetric Algorithms +===================== + +.. toctree:: + :maxdepth: 1 + + rsa + padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst new file mode 100644 index 00000000..d3f713ae --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -0,0 +1,20 @@ +.. 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:: PKCS1() + + .. versionadded:: 0.3 + + PKCS1 (also known as PKCS1 v1.5) is a simple padding scheme developed for + use with RSA keys. It is also defined in :rfc:`3447`. + +.. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst new file mode 100644 index 00000000..82cf3528 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -0,0 +1,107 @@ +.. hazmat:: + +RSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa + +`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. + +.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA private key is required for decryption and signing of messages. + + You should use :meth:`~generate` to generate new keys. + + .. warning:: + This method only checks a limited set of properties of its arguments. + Using an RSA private key that you do not trust or with incorrect + parameters may lead to insecure operation, crashes, and other undefined + behavior. We recommend that you only ever load private keys that were + generated with software you trust. + + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``p``, ``q``, + ``private_exponent``, ``public_exponent``, or + ``modulus`` do not match the bounds specified in + :rfc:`3447`. + + .. classmethod:: generate(public_exponent, key_size, backend) + + Generate a new ``RSAPrivateKey`` instance using ``backend``. + + :param int public_exponent: The public exponent of the new key. + Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in + doubt you should `use 65537`_. + :param int key_size: The length of the modulus in bits. For keys + generated in 2014 this should be `at least 2048`_. (See page 41.) + Must be at least 512. Some backends may have additional + limitations. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + :return: A new instance of ``RSAPrivateKey``. + + .. method:: signer(padding, algorithm, backend) + + .. versionadded:: 0.3 + + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding + >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) + >>> signer.update(b"this is some data I'd like") + >>> signer.update(b" to sign") + >>> signature = signer.finalize() + + +.. class:: RSAPublicKey(public_exponent, modulus) + + .. versionadded:: 0.2 + + An RSA public key is required for encryption and verification of messages. + + Normally you do not need to directly construct public keys because you'll + be loading them from a file, generating them automatically or receiving + them from a 3rd party. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``public_exponent`` + or ``modulus`` do not match the bounds specified in + :rfc:`3447`. + +.. _`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 diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index 5199d493..90deec8b 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -11,7 +11,7 @@ Primitives symmetric-encryption padding key-derivation-functions - rsa + asymmetric/index constant-time interfaces twofactor diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/rsa.rst deleted file mode 100644 index 4e1f8e49..00000000 --- a/docs/hazmat/primitives/rsa.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. hazmat:: - -RSA -=== - -.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa - -`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. - -.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) - - .. versionadded:: 0.2 - - An RSA private key is required for decryption and signing of messages. - - You should use :meth:`~generate` to generate new keys. - - .. warning:: - This method only checks a limited set of properties of its arguments. - Using an RSA private key that you do not trust or with incorrect - parameters may lead to insecure operation, crashes, and other undefined - behavior. We recommend that you only ever load private keys that were - generated with software you trust. - - - This class conforms to the - :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` - interface. - - :raises TypeError: This is raised when the arguments are not all integers. - - :raises ValueError: This is raised when the values of ``p``, ``q``, - ``private_exponent``, ``public_exponent``, or - ``modulus`` do not match the bounds specified in - :rfc:`3447`. - - .. classmethod:: generate(public_exponent, key_size, backend) - - Generate a new ``RSAPrivateKey`` instance using ``backend``. - - :param int public_exponent: The public exponent of the new key. - Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in - doubt you should `use 65537`_. - :param int key_size: The length of the modulus in bits. For keys - generated in 2014 this should be `at least 2048`_. (See page 41.) - Must be at least 512. Some backends may have additional - limitations. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :return: A new instance of ``RSAPrivateKey``. - - -.. class:: RSAPublicKey(public_exponent, modulus) - - .. versionadded:: 0.2 - - An RSA public key is required for encryption and verification of messages. - - Normally you do not need to directly construct public keys because you'll - be loading them from a file, generating them automatically or receiving - them from a 3rd party. - - This class conforms to the - :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` - interface. - - :raises TypeError: This is raised when the arguments are not all integers. - - :raises ValueError: This is raised when the values of ``public_exponent`` - or ``modulus`` do not match the bounds specified in - :rfc:`3447`. - -.. _`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 -- cgit v1.2.3 From 8dd9713ae2a69a3e870275c088df08ce2a50dce9 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 23 Feb 2014 19:26:05 -0600 Subject: incorporate review feedback. kwarg! --- docs/hazmat/primitives/asymmetric/rsa.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 82cf3528..5e71c7c8 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -74,7 +74,11 @@ RSA >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding - >>> private_key = rsa.RSAPrivateKey.generate(65537, 2048, default_backend()) + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") -- cgit v1.2.3 From 0377f5a78de949f2f1e719ac89cf8b98b910bf81 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 24 Feb 2014 19:04:46 -0600 Subject: rename PKCS1->PKCS1v15 & UnsupportedAsymmetricPadding->UnsupportedPadding --- docs/hazmat/primitives/asymmetric/padding.rst | 6 +++--- docs/hazmat/primitives/asymmetric/rsa.rst | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index d3f713ae..7aec3bd3 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,11 +10,11 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. -.. class:: PKCS1() +.. class:: PKCS1v15() .. versionadded:: 0.3 - PKCS1 (also known as PKCS1 v1.5) is a simple padding scheme developed for - use with RSA keys. It is also defined in :rfc:`3447`. + 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`. .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 5e71c7c8..64928878 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -79,7 +79,7 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") >>> signature = signer.finalize() -- cgit v1.2.3 From 62a9217aa3f6cf34d4cafcd1d147082bc7c7918c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 25 Feb 2014 13:56:53 -0600 Subject: reorganize docs slightly --- docs/hazmat/primitives/asymmetric/rsa.rst | 36 ++++++++++++++++++------------- 1 file changed, 21 insertions(+), 15 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 64928878..682820b3 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -54,20 +54,7 @@ RSA .. versionadded:: 0.3 - :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. - - :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` - provider. - - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - - :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + Sign data which can be verified later by others using the public key. .. doctest:: @@ -79,11 +66,30 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer( + ... padding.PKCS1v15(), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> signer.update(b"this is some data I'd like") >>> signer.update(b" to sign") >>> signature = signer.finalize() + :param padding: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + .. class:: RSAPublicKey(public_exponent, modulus) -- cgit v1.2.3