From 1a5d70e876346653b3dfa2a95f188ef0eb92bd7d Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 3 Jun 2017 17:11:55 -1000 Subject: deprecate signer/verifier on asymmetric keys (#3663) * deprecate signer/verifier on asymmetric keys * review feedback, switch deprecated_call to work around a bug --- docs/hazmat/primitives/asymmetric/dsa.rst | 91 ++++++++++-------------- docs/hazmat/primitives/asymmetric/ec.rst | 74 +++++++++---------- docs/hazmat/primitives/asymmetric/index.rst | 1 - docs/hazmat/primitives/asymmetric/interfaces.rst | 44 ------------ docs/hazmat/primitives/asymmetric/rsa.rst | 91 +++++++++--------------- 5 files changed, 105 insertions(+), 196 deletions(-) delete mode 100644 docs/hazmat/primitives/asymmetric/interfaces.rst (limited to 'docs/hazmat/primitives/asymmetric') diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index d4c25256..13cd0412 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -72,15 +72,6 @@ instance. ... key_size=1024, ... backend=default_backend() ... ) - >>> signer = private_key.signer(hashes.SHA256()) - >>> data = b"this is some data I'd like to sign" - >>> signer.update(data) - >>> signature = signer.finalize() - -There is a shortcut to sign sufficiently short messages directly: - -.. doctest:: - >>> data = b"this is some data I'd like to sign" >>> signature = private_key.sign( ... data, @@ -91,6 +82,23 @@ The ``signature`` is a ``bytes`` object, whose contents is DER encoded as described in :rfc:`3279`. This can be decoded using :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`. +If your data is too large to be passed in a single call, you can hash it +separately and pass that value using +:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. + +.. doctest:: + + >>> from cryptography.hazmat.primitives.asymmetric import utils + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() + >>> sig = private_key.sign( + ... digest, + ... utils.Prehashed(chosen_hash) + ... ) + Verification ~~~~~~~~~~~~ @@ -106,26 +114,35 @@ You can get a public key object with .. doctest:: >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier(signature, hashes.SHA256()) - >>> verifier.update(data) - >>> verifier.verify() - -There is a shortcut to verify sufficiently short messages directly: - -.. doctest:: - >>> public_key.verify( ... signature, ... data, ... hashes.SHA256() ... ) -``verifier()`` takes the signature in the same format as is returned by -``signer.finalize()``. +``verify()`` takes the signature in the same format as is returned by +``sign()``. ``verify()`` will raise an :class:`~cryptography.exceptions.InvalidSignature` exception if the signature isn't valid. +If your data is too large to be passed in a single call, you can hash it +separately and pass that value using +:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. + +.. doctest:: + + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() + >>> public_key.verify( + ... sig, + ... digest, + ... utils.Prehashed(chosen_hash) + ... ) + Numbers ~~~~~~~ @@ -275,23 +292,6 @@ Key interfaces The DSAParameters object associated with this private key. - .. method:: signer(algorithm, backend) - - .. versionadded:: 0.4 - - Sign data which can be verified later by others using the public key. - The signature is formatted as DER-encoded bytes, as specified in - :rfc:`3279`. - - :param algorithm: An instance of - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. - - :param backend: An instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` - .. attribute:: key_size :type: int @@ -380,25 +380,6 @@ Key interfaces The DSAParameters object associated with this public key. - .. method:: verifier(signature, algorithm, backend) - - .. versionadded:: 0.4 - - Verify data was signed by the private key associated with this public - key. - - :param bytes signature: The signature to verify. DER encoded as - specified in :rfc:`3279`. - - :param algorithm: An instance of - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. - - :param backend: An instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` - .. method:: public_numbers() Create a diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 55146175..113168fa 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -58,15 +58,6 @@ Elliptic Curve Signature Algorithms >>> private_key = ec.generate_private_key( ... ec.SECP384R1(), default_backend() ... ) - >>> signer = private_key.signer(ec.ECDSA(hashes.SHA256())) - >>> signer.update(b"this is some data I'd like") - >>> signer.update(b" to sign") - >>> signature = signer.finalize() - - There is a shortcut to sign sufficiently short messages directly: - - .. doctest:: - >>> data = b"this is some data I'd like to sign" >>> signature = private_key.sign( ... data, @@ -77,20 +68,51 @@ Elliptic Curve Signature Algorithms described in :rfc:`3279`. This can be decoded using :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`. + If your data is too large to be passed in a single call, you can hash it + separately and pass that value using + :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. + + .. doctest:: + + >>> from cryptography.hazmat.primitives.asymmetric import utils + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() + >>> sig = private_key.sign( + ... digest, + ... ec.ECDSA(utils.Prehashed(chosen_hash)) + ... ) + Verification requires the public key, the signature itself, the signed data, and knowledge of the hashing algorithm that was used when producing the signature: >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier(signature, ec.ECDSA(hashes.SHA256())) - >>> verifier.update(b"this is some data I'd like") - >>> verifier.update(b" to sign") - >>> verifier.verify() + >>> public_key.verify(signature, data, ec.ECDSA(hashes.SHA256())) If the signature is not valid, an :class:`~cryptography.exceptions.InvalidSignature` exception will be raised. + If your data is too large to be passed in a single call, you can hash it + separately and pass that value using + :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. + + .. doctest:: + + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() + >>> public_key.verify( + ... sig, + ... digest, + ... ec.ECDSA(utils.Prehashed(chosen_hash)) + ... ) + .. note:: Although in this case the public key was derived from the private one, in a typical setting you will not possess the private key. The @@ -421,18 +443,6 @@ Key Interfaces An elliptic curve private key for use with an algorithm such as `ECDSA`_ or `EdDSA`_. - .. method:: signer(signature_algorithm) - - Sign data which can be verified later by others using the public key. - The signature is formatted as DER-encoded bytes, as specified in - :rfc:`3279`. - - :param signature_algorithm: An instance of - :class:`EllipticCurveSignatureAlgorithm`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` - .. method:: exchange(algorithm, peer_public_key) .. versionadded:: 1.1 @@ -526,20 +536,6 @@ Key Interfaces An elliptic curve public key. - .. method:: verifier(signature, signature_algorithm) - - Verify data was signed by the private key associated with this public - key. - - :param bytes signature: The signature to verify. DER encoded as - specified in :rfc:`3279`. - - :param signature_algorithm: An instance of - :class:`EllipticCurveSignatureAlgorithm`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` - .. attribute:: curve :type: :class:`EllipticCurve` diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index e0080f0e..e14ce0d3 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -28,7 +28,6 @@ private key is able to decrypt it. rsa dh serialization - interfaces utils diff --git a/docs/hazmat/primitives/asymmetric/interfaces.rst b/docs/hazmat/primitives/asymmetric/interfaces.rst deleted file mode 100644 index a5dbc671..00000000 --- a/docs/hazmat/primitives/asymmetric/interfaces.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. hazmat:: - -.. module:: cryptography.hazmat.primitives.asymmetric - -Signature Interfaces -==================== - -.. class:: AsymmetricSignatureContext - - .. versionadded:: 0.2 - - .. note:: - - :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed` - is not supported by this context. You must use the ``sign`` method - on the private key object. - - .. method:: update(data) - - :param bytes data: The data you want to sign. - - .. method:: finalize() - - :return bytes signature: The signature. - - -.. class:: AsymmetricVerificationContext - - .. versionadded:: 0.2 - - .. note:: - - :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed` - is not supported by this context. You must use the ``verify`` method - on the public key object. - - .. 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. diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 6cf0e499..121f156d 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -141,22 +141,6 @@ secure hash function and padding: >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.asymmetric import padding - - >>> signer = private_key.signer( - ... padding.PSS( - ... mgf=padding.MGF1(hashes.SHA256()), - ... salt_length=padding.PSS.MAX_LENGTH - ... ), - ... hashes.SHA256() - ... ) - >>> message = b"A message I want to sign" - >>> signer.update(message) - >>> signature = signer.finalize() - -There is a shortcut to sign sufficiently short messages directly: - -.. doctest:: - >>> message = b"A message I want to sign" >>> signature = private_key.sign( ... message, @@ -173,6 +157,27 @@ Valid paddings for signatures are is the recommended choice for any new protocols or applications, ``PKCS1v15`` should only be used to support legacy protocols. +If your data is too large to be passed in a single call, you can hash it +separately and pass that value using +:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. + +.. doctest:: + + >>> from cryptography.hazmat.primitives.asymmetric import utils + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() + >>> sig = private_key.sign( + ... digest, + ... padding.PSS( + ... mgf=padding.MGF1(hashes.SHA256()), + ... salt_length=padding.PSS.MAX_LENGTH + ... ), + ... utils.Prehashed(chosen_hash) + ... ) + Verification ~~~~~~~~~~~~ @@ -190,32 +195,38 @@ a public key to use in verification using .. doctest:: >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier( + >>> public_key.verify( ... signature, + ... message, ... padding.PSS( ... mgf=padding.MGF1(hashes.SHA256()), ... salt_length=padding.PSS.MAX_LENGTH ... ), ... hashes.SHA256() ... ) - >>> verifier.update(message) - >>> verifier.verify() If the signature does not match, ``verify()`` will raise an :class:`~cryptography.exceptions.InvalidSignature` exception. -There is a shortcut to verify sufficiently short messages directly: +If your data is too large to be passed in a single call, you can hash it +separately and pass that value using +:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`. .. doctest:: + >>> chosen_hash = hashes.SHA256() + >>> hasher = hashes.Hash(chosen_hash, default_backend()) + >>> hasher.update(b"data & ") + >>> hasher.update(b"more data") + >>> digest = hasher.finalize() >>> public_key.verify( - ... signature, - ... message, + ... sig, + ... digest, ... padding.PSS( ... mgf=padding.MGF1(hashes.SHA256()), ... salt_length=padding.PSS.MAX_LENGTH ... ), - ... hashes.SHA256() + ... utils.Prehashed(chosen_hash) ... ) Encryption @@ -520,22 +531,6 @@ Key interfaces An `RSA`_ private key. - .. method:: signer(padding, algorithm) - - .. versionadded:: 0.3 - - Get signer to sign data which can be verified later by others using - the public key. - - :param padding: An instance of - :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`. - - :param algorithm: An instance of - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` - .. method:: decrypt(ciphertext, padding) .. versionadded:: 0.4 @@ -634,24 +629,6 @@ Key interfaces An `RSA`_ public key. - .. method:: verifier(signature, padding, algorithm) - - .. versionadded:: 0.3 - - Get verifier to verify data was signed by the private key associated - with this public key. - - :param bytes signature: The signature to verify. - - :param padding: An instance of - :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`. - - :param algorithm: An instance of - :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`. - - :returns: - :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` - .. method:: encrypt(plaintext, padding) .. versionadded:: 0.4 -- cgit v1.2.3