From ca723c42d0e48c4a17aaed2505c2a5be80e1165f Mon Sep 17 00:00:00 2001 From: Harry Stern Date: Thu, 15 Aug 2019 21:53:56 -0400 Subject: Improve documentation for ECDSA sign and verify (#4970) - Note that signatures are DER-encoded - Note that signatures can be encoded from r,s using util function --- docs/hazmat/primitives/asymmetric/ec.rst | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 3025f334..d8b8c052 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -64,7 +64,7 @@ Elliptic Curve Signature Algorithms ... ec.ECDSA(hashes.SHA256()) ... ) - The ``signature`` is a ``bytes`` object, whose contents is DER encoded as + The ``signature`` is a ``bytes`` object, whose contents are DER encoded as described in :rfc:`3279`. This can be decoded using :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`. @@ -86,13 +86,18 @@ Elliptic Curve Signature Algorithms ... ) - Verification requires the public key, the signature itself, the signed - data, and knowledge of the hashing algorithm that was used when producing - the signature: + Verification requires the public key, the DER-encoded signature itself, the + signed data, and knowledge of the hashing algorithm that was used when + producing the signature: >>> public_key = private_key.public_key() >>> public_key.verify(signature, data, ec.ECDSA(hashes.SHA256())) + As above, the ``signature`` is a ``bytes`` object whose contents are DER + encoded as described in :rfc:`3279`. It can be created from a raw ``(r,s)`` + pair by using + :func:`~cryptography.hazmat.primitives.asymmetric.utils.encode_dss_signature`. + If the signature is not valid, an :class:`~cryptography.exceptions.InvalidSignature` exception will be raised. @@ -601,7 +606,10 @@ Key Interfaces :param signature_algorithm: An instance of :class:`EllipticCurveSignatureAlgorithm`, such as :class:`ECDSA`. - :return bytes: Signature. + :return bytes: The signature as a ``bytes`` object, whose contents are + DER encoded as described in :rfc:`3279`. This can be decoded using + :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`, + which returns the decoded tuple ``(r, s)``. .. attribute:: key_size @@ -704,7 +712,10 @@ Key Interfaces Verify one block of data was signed by the private key associated with this public key. - :param bytes signature: The signature to verify. + :param bytes signature: The DER-encoded signature to verify. + A raw signature may be DER-encoded by splitting it into the ``r`` + and ``s`` components and passing them into + :func:`~cryptography.hazmat.primitives.asymmetric.utils.encode_dss_signature`. :param bytes data: The message string that was signed. -- cgit v1.2.3