diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 67 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 485 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 176 |
3 files changed, 381 insertions, 347 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 6848d84c..2167e528 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -210,6 +210,73 @@ DSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` +.. class:: DSAParameterNumbers(p, q, g) + + .. versionadded:: 0.5 + + The collection of integers that make up a set of DSA parameters. + + .. attribute:: p + + :type: int + + The public modulus. + + .. attribute:: q + + :type: int + + The sub-group order. + + .. attribute:: g + + :type: int + + The generator. + +.. class:: DSAPublicNumbers(y, parameter_numbers) + + .. versionadded:: 0.5 + + The collection of integers that make up a DSA public key. + + .. attribute:: y + + :type: int + + The public value ``y``. + + .. attribute:: parameter_numbers + + :type: :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers` + + The :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers` + associated with the public key. + +.. class:: DSAPrivateNumbers(x, public_numbers) + + .. versionadded:: 0.5 + + The collection of integers that make up a DSA private key. + + .. warning:: + + Revealing the value of ``x`` will compromise the security of any + cryptographic operations performed. + + .. attribute:: x + + :type: int + + The private value ``x``. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers` + + The :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers` + associated with the private key. + .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf 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 diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 029c4c1f..755cef41 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -13,7 +13,7 @@ to document argument and return types. Symmetric ciphers -~~~~~~~~~~~~~~~~~ +----------------- .. currentmodule:: cryptography.hazmat.primitives.interfaces @@ -48,7 +48,7 @@ Symmetric ciphers Cipher modes ------------- +~~~~~~~~~~~~ Interfaces used by the symmetric cipher modes described in :ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`. @@ -104,7 +104,44 @@ Interfaces used by the symmetric cipher modes described in individual modes. Asymmetric interfaces -~~~~~~~~~~~~~~~~~~~~~ +--------------------- + +.. class:: AsymmetricSignatureContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you want to sign. + + .. method:: finalize() + + :return bytes signature: The signature. + + +.. class:: AsymmetricVerificationContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you wish to verify using the signature. + + .. method:: verify() + + :raises cryptography.exceptions.InvalidSignature: If the signature does + not validate. + + +.. class:: AsymmetricPadding + + .. versionadded:: 0.2 + + .. attribute:: name + + +RSA +~~~ .. class:: RSAPrivateKey @@ -236,55 +273,31 @@ Asymmetric interfaces instance. +DSA +~~~ + .. class:: DSAParameters .. versionadded:: 0.3 `DSA`_ parameters. - .. attribute:: modulus - :type: int +.. class:: DSAParametersWithNumbers - The prime modulus that is used in generating the DSA key pair and used - in the DSA signing and verification processes. - - .. attribute:: subgroup_order - - :type: int - - The subgroup order that is used in generating the DSA key pair - by the generator and used in the DSA signing and verification - processes. - - .. attribute:: generator - - :type: int - - The generator that is used in generating the DSA key pair and used - in the DSA signing and verification processes. - - .. attribute:: p - - :type: int - - The prime modulus that is used in generating the DSA key pair and used - in the DSA signing and verification processes. Alias for :attr:`modulus`. - - .. attribute:: q - - :type: int + .. versionadded:: 0.5 - The subgroup order that is used in generating the DSA key pair - by the generator and used in the DSA signing and verification - processes. Alias for :attr:`subgroup_order`. + Extends :class:`DSAParameters`. - .. attribute:: g + .. method:: parameter_numbers() - :type: int + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers` + object. - The generator that is used in generating the DSA key pair and used - in the DSA signing and verification processes. Alias for :attr:`generator`. + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers` + instance. .. class:: DSAPrivateKey @@ -328,17 +341,22 @@ Asymmetric interfaces The bit length of the modulus. - .. attribute:: x - :type: int +.. class:: DSAPrivateKeyWithNumbers - The private key. + .. versionadded:: 0.5 - .. attribute:: y + Extends :class:`DSAPrivateKey`. - :type: int + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + object. - The public key. + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + instance. .. class:: DSAPublicKey @@ -353,12 +371,6 @@ Asymmetric interfaces The bit length of the modulus. - .. attribute:: y - - :type: int - - The public key. - .. method:: parameters() :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` @@ -387,6 +399,23 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` +.. class:: DSAPublicKeyWithNumbers + + .. versionadded:: 0.5 + + Extends :class:`DSAPublicKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers` + object. + + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers` + instance. + + .. class:: EllipticCurve .. versionadded:: 0.5 @@ -407,6 +436,9 @@ Asymmetric interfaces The bit length of the curve's base point. +Elliptic Curve +~~~~~~~~~~~~~~ + .. class:: EllipticCurveSignatureAlgorithm .. versionadded:: 0.5 @@ -475,42 +507,8 @@ Asymmetric interfaces The elliptic curve for this key. -.. class:: AsymmetricSignatureContext - - .. versionadded:: 0.2 - - .. method:: update(data) - - :param bytes data: The data you want to sign. - - .. method:: finalize() - - :return bytes signature: The signature. - - -.. class:: AsymmetricVerificationContext - - .. versionadded:: 0.2 - - .. method:: update(data) - - :param bytes data: The data you wish to verify using the signature. - - .. method:: verify() - - :raises cryptography.exceptions.InvalidSignature: If the signature does - not validate. - - -.. class:: AsymmetricPadding - - .. versionadded:: 0.2 - - .. attribute:: name - - Hash algorithms -~~~~~~~~~~~~~~~ +--------------- .. class:: HashAlgorithm @@ -556,7 +554,7 @@ Hash algorithms Key derivation functions -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ .. class:: KeyDerivationFunction @@ -601,7 +599,7 @@ Key derivation functions `CMAC`_ -~~~~~~~ +------- .. class:: CMACContext |