diff options
author | David Reid <dreid@dreid.org> | 2014-06-24 20:10:59 -0700 |
---|---|---|
committer | David Reid <dreid@dreid.org> | 2014-06-24 20:10:59 -0700 |
commit | 48963c962a2a63b8faf2f5bc4aca7906a64a2bc6 (patch) | |
tree | cc50c3a0883fa6f6e96c668abf65afdb1bbb4284 /docs/hazmat/primitives | |
parent | 4a6104c766dcb93e1f9d88da7a60db4550e73aba (diff) | |
parent | a63083a7427a6e394bb3b6c0e841dd0e3172733c (diff) | |
download | cryptography-48963c962a2a63b8faf2f5bc4aca7906a64a2bc6.tar.gz cryptography-48963c962a2a63b8faf2f5bc4aca7906a64a2bc6.tar.bz2 cryptography-48963c962a2a63b8faf2f5bc4aca7906a64a2bc6.zip |
Merge pull request #1150 from reaperhulk/rsa-doc-update
RSA Deprecation Doc Update
Diffstat (limited to 'docs/hazmat/primitives')
-rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 485 |
1 files changed, 227 insertions, 258 deletions
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index c3962901..7250066a 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -7,6 +7,8 @@ RSA `RSA`_ is a `public-key`_ algorithm for encrypting and signing messages. +Generation +~~~~~~~~~~ .. function:: generate_private_key(public_exponent, key_size, backend) @@ -31,10 +33,233 @@ RSA the provided ``backend`` does not implement :class:`~cryptography.hazmat.backends.interfaces.RSABackend` +Signing +~~~~~~~ + +Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` +provider. + +.. 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.generate_private_key( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> signer = private_key.signer( + ... padding.PSS( + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH + ... ), + ... hashes.SHA256() + ... ) + >>> signer.update(b"this is some data I'd like") + >>> signer.update(b" to sign") + >>> signature = signer.finalize() + + +Verification +~~~~~~~~~~~~ + +Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` +provider. + +.. doctest:: + + >>> public_key = private_key.public_key() + >>> verifier = public_key.verifier( + ... signature, + ... padding.PSS( + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH + ... ), + ... hashes.SHA256() + ... ) + >>> data = b"this is some data I'd like to sign" + >>> verifier.update(data) + >>> verifier.verify() + +Encryption +~~~~~~~~~~ + +Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` +provider. + +.. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding + + >>> # Generate a key + >>> private_key = rsa.generate_private_key( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ) + ... ) + +Decryption +~~~~~~~~~~ + +Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` +provider. + +.. doctest:: + + >>> plaintext = private_key.decrypt( + ... ciphertext, + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ) + ... ) + +Numbers +~~~~~~~ + +These classes hold the constituent components of an RSA key. They are useful +only when more traditional :doc:`/hazmat/primitives/asymmetric/serialization` +is unavailable. + +.. class:: RSAPublicNumbers(e, n) + + .. versionadded:: 0.5 + + The collection of integers that make up an RSA public key. + + .. attribute:: n + + :type: int + + The public modulus. + + .. attribute:: e + + :type: int + + The public exponent. + + +.. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers) + + .. versionadded:: 0.5 + + The collection of integers that make up an RSA private key. + + .. warning:: + + With the exception of the integers contained in the + :class:`RSAPublicNumbers` all attributes of this class must be kept + secret. Revealing them will compromise the security of any + cryptographic operations performed with a key loaded from them. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.rsa.RSAPublicNumbers` + + The :class:`RSAPublicNumbers` which makes up the RSA public key + associated with this RSA private key. + + .. attribute:: p + + :type: int + + ``p``, one of the two primes composing the :attr:`modulus`. + + .. attribute:: q + + :type: int + + ``q``, one of the two primes composing the :attr:`modulus`. + + .. attribute:: d + + :type: int + + The private exponent. Alias for :attr:`private_exponent`. + + .. attribute:: dmp1 + + :type: int + + A `Chinese remainder theorem`_ coefficient used to speed up RSA + operations. Calculated as: d mod (p-1) + + .. attribute:: dmq1 + + :type: int + + A `Chinese remainder theorem`_ coefficient used to speed up RSA + operations. Calculated as: d mod (q-1) + + .. attribute:: iqmp + + :type: int + + A `Chinese remainder theorem`_ coefficient used to speed up RSA + operations. Calculated as: q\ :sup:`-1` mod p + +Handling partial RSA private keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you are trying to load RSA private keys yourself you may find that not all +parameters required by ``RSAPrivateNumbers`` 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``. + +Deprecated Concrete Classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These classes were deprecated in version 0.5 in favor of backend specific +providers of the +:class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` and +:class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` interfaces. + .. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus) .. versionadded:: 0.2 + .. deprecated:: 0.5 + An RSA private key is required for decryption and signing of messages. You should use :func:`generate_private_key` to generate new keys. @@ -47,10 +272,6 @@ RSA 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``, @@ -85,28 +306,6 @@ RSA Sign data which can be verified later by others using the public key. - .. 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( - ... public_exponent=65537, - ... key_size=2048, - ... backend=default_backend() - ... ) - >>> signer = private_key.signer( - ... padding.PSS( - ... mgf=padding.MGF1(hashes.SHA256()), - ... salt_length=padding.PSS.MAX_LENGTH - ... ), - ... 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. Valid values are @@ -181,55 +380,19 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. doctest:: - - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.primitives import hashes - >>> from cryptography.hazmat.primitives.asymmetric import padding - - >>> # Generate a key - >>> private_key = rsa.RSAPrivateKey.generate( - ... public_exponent=65537, - ... key_size=2048, - ... backend=default_backend() - ... ) - >>> public_key = private_key.public_key() - >>> # encrypt some data - >>> ciphertext = public_key.encrypt( - ... b"encrypted data", - ... padding.OAEP( - ... mgf=padding.MGF1(algorithm=hashes.SHA1()), - ... algorithm=hashes.SHA1(), - ... label=None - ... ), - ... default_backend() - ... ) - >>> # Now do the actual decryption - >>> 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) .. versionadded:: 0.2 + .. deprecated:: 0.5 + 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`` @@ -243,40 +406,6 @@ RSA Verify data was signed by the private key associated with this public key. - .. 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( - ... public_exponent=65537, - ... key_size=2048, - ... backend=default_backend() - ... ) - >>> signer = private_key.signer( - ... padding.PSS( - ... mgf=padding.MGF1(hashes.SHA256()), - ... salt_length=padding.PSS.MAX_LENGTH - ... ), - ... hashes.SHA256(), - ... default_backend() - ... ) - >>> data = b"this is some data I'd like to sign" - >>> signer.update(data) - >>> signature = signer.finalize() - >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier( - ... signature, - ... padding.PSS( - ... mgf=padding.MGF1(hashes.SHA256()), - ... salt_length=padding.PSS.MAX_LENGTH - ... ), - ... hashes.SHA256(), - ... default_backend() - ... ) - >>> verifier.update(data) - >>> verifier.verify() - :param bytes signature: The signature to verify. :param padding: An instance of a @@ -354,166 +483,6 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. doctest:: - - >>> from cryptography.hazmat.backends import default_backend - >>> from cryptography.hazmat.primitives import hashes - >>> from cryptography.hazmat.primitives.asymmetric import padding - - >>> # Generate a key - >>> private_key = rsa.RSAPrivateKey.generate( - ... public_exponent=65537, - ... key_size=2048, - ... backend=default_backend() - ... ) - >>> public_key = private_key.public_key() - >>> # encrypt some data - >>> ciphertext = public_key.encrypt( - ... b"encrypted data", - ... padding.OAEP( - ... mgf=padding.MGF1(algorithm=hashes.SHA1()), - ... algorithm=hashes.SHA1(), - ... label=None - ... ), - ... default_backend() - ... ) - - -.. class:: RSAPublicNumbers(e, n) - - .. versionadded:: 0.5 - - The collection of integers that make up an RSA public key. - - .. method:: public_key(backend) - - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - - :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` - provider. - - :raises UnsupportedAlgorithm: If the given backend does not support - loading numbers. - - .. attribute:: n - - :type: int - - The public modulus. - - .. attribute:: e - - :type: int - - The public exponent. - - -.. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers) - - .. versionadded:: 0.5 - - The collection of integers that make up an RSA private key. - - .. warning:: - - With the exception of the integers contained in the - :class:`RSAPublicNumbers` all attributes of this class must be kept - secret. Revealing them will compromise the security of any - cryptographic operations performed with a key loaded from them. - - .. method:: private_key(backend) - - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - - :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` - provider. - - :raises UnsupportedAlgorithm: If the given backend does not support - loading numbers. - - .. attribute:: public_numbers - - :type: :class:`~cryptography.hazmat.primitives.rsa.RSAPublicNumbers` - - The :class:`RSAPublicNumbers` which makes up the RSA public key - associated with this RSA private key. - - .. attribute:: p - - :type: int - - ``p``, one of the two primes composing the :attr:`modulus`. - - .. attribute:: q - - :type: int - - ``q``, one of the two primes composing the :attr:`modulus`. - - .. attribute:: d - - :type: int - - The private exponent. Alias for :attr:`private_exponent`. - - .. attribute:: dmp1 - - :type: int - - A `Chinese remainder theorem`_ coefficient used to speed up RSA - operations. Calculated as: d mod (p-1) - - .. attribute:: dmq1 - - :type: int - - A `Chinese remainder theorem`_ coefficient used to speed up RSA - operations. Calculated as: d mod (q-1) - - .. attribute:: iqmp - - :type: int - - A `Chinese remainder theorem`_ coefficient used to speed up RSA - operations. Calculated as: q\ :sup:`-1` mod p - - -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 |