From 8531f73aa81d174abc6bd1e7792fe57e4845182f Mon Sep 17 00:00:00 2001 From: Hubert Kario Date: Sat, 29 May 2021 19:00:33 +0200 Subject: [PATCH 1/2] initial docs skeleton --- docs/Makefile | 20 +++++++++ docs/make.bat | 35 +++++++++++++++ docs/source/conf.py | 69 +++++++++++++++++++++++++++++ docs/source/ecdsa.curves.rst | 7 +++ docs/source/ecdsa.der.rst | 7 +++ docs/source/ecdsa.ecdh.rst | 7 +++ docs/source/ecdsa.ecdsa.rst | 7 +++ docs/source/ecdsa.ellipticcurve.rst | 7 +++ docs/source/ecdsa.errors.rst | 7 +++ docs/source/ecdsa.keys.rst | 7 +++ docs/source/ecdsa.numbertheory.rst | 7 +++ docs/source/ecdsa.rfc6979.rst | 7 +++ docs/source/ecdsa.rst | 24 ++++++++++ docs/source/ecdsa.util.rst | 7 +++ docs/source/index.rst | 20 +++++++++ docs/source/modules.rst | 7 +++ 16 files changed, 245 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/conf.py create mode 100644 docs/source/ecdsa.curves.rst create mode 100644 docs/source/ecdsa.der.rst create mode 100644 docs/source/ecdsa.ecdh.rst create mode 100644 docs/source/ecdsa.ecdsa.rst create mode 100644 docs/source/ecdsa.ellipticcurve.rst create mode 100644 docs/source/ecdsa.errors.rst create mode 100644 docs/source/ecdsa.keys.rst create mode 100644 docs/source/ecdsa.numbertheory.rst create mode 100644 docs/source/ecdsa.rfc6979.rst create mode 100644 docs/source/ecdsa.rst create mode 100644 docs/source/ecdsa.util.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/modules.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..6247f7e2 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..df4de1b3 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,69 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +sys.path.insert(0, os.path.abspath("../../src")) + + +# -- Project information ----------------------------------------------------- + +project = "python-ecdsa" +copyright = "2021, Brian Warner and Hubert Kario" +author = "Brian Warner and Hubert Kario" + +# The full version, including alpha/beta/rc tags +release = "0.17.0" + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.coverage", + "sphinx.ext.imgmath", + "sphinx.ext.viewcode", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + +todo_include_todos = False + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +autodoc_default_options = { + "undoc-members": True, + "inherited-members": True, +} + +intersphinx_mapping = {"https://docs.python.org/": None} diff --git a/docs/source/ecdsa.curves.rst b/docs/source/ecdsa.curves.rst new file mode 100644 index 00000000..d2ff907b --- /dev/null +++ b/docs/source/ecdsa.curves.rst @@ -0,0 +1,7 @@ +ecdsa.curves module +=================== + +.. automodule:: ecdsa.curves + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.der.rst b/docs/source/ecdsa.der.rst new file mode 100644 index 00000000..28c6c592 --- /dev/null +++ b/docs/source/ecdsa.der.rst @@ -0,0 +1,7 @@ +ecdsa.der module +================ + +.. automodule:: ecdsa.der + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.ecdh.rst b/docs/source/ecdsa.ecdh.rst new file mode 100644 index 00000000..1d125f80 --- /dev/null +++ b/docs/source/ecdsa.ecdh.rst @@ -0,0 +1,7 @@ +ecdsa.ecdh module +================= + +.. automodule:: ecdsa.ecdh + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.ecdsa.rst b/docs/source/ecdsa.ecdsa.rst new file mode 100644 index 00000000..794dd11b --- /dev/null +++ b/docs/source/ecdsa.ecdsa.rst @@ -0,0 +1,7 @@ +ecdsa.ecdsa module +================== + +.. automodule:: ecdsa.ecdsa + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.ellipticcurve.rst b/docs/source/ecdsa.ellipticcurve.rst new file mode 100644 index 00000000..334dee5e --- /dev/null +++ b/docs/source/ecdsa.ellipticcurve.rst @@ -0,0 +1,7 @@ +ecdsa.ellipticcurve module +========================== + +.. automodule:: ecdsa.ellipticcurve + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.errors.rst b/docs/source/ecdsa.errors.rst new file mode 100644 index 00000000..839e560c --- /dev/null +++ b/docs/source/ecdsa.errors.rst @@ -0,0 +1,7 @@ +ecdsa.errors module +=================== + +.. automodule:: ecdsa.errors + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.keys.rst b/docs/source/ecdsa.keys.rst new file mode 100644 index 00000000..b470715a --- /dev/null +++ b/docs/source/ecdsa.keys.rst @@ -0,0 +1,7 @@ +ecdsa.keys module +================= + +.. automodule:: ecdsa.keys + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.numbertheory.rst b/docs/source/ecdsa.numbertheory.rst new file mode 100644 index 00000000..569b39bd --- /dev/null +++ b/docs/source/ecdsa.numbertheory.rst @@ -0,0 +1,7 @@ +ecdsa.numbertheory module +========================= + +.. automodule:: ecdsa.numbertheory + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.rfc6979.rst b/docs/source/ecdsa.rfc6979.rst new file mode 100644 index 00000000..3b891f52 --- /dev/null +++ b/docs/source/ecdsa.rfc6979.rst @@ -0,0 +1,7 @@ +ecdsa.rfc6979 module +==================== + +.. automodule:: ecdsa.rfc6979 + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/ecdsa.rst b/docs/source/ecdsa.rst new file mode 100644 index 00000000..2b5b548c --- /dev/null +++ b/docs/source/ecdsa.rst @@ -0,0 +1,24 @@ +ecdsa package +============= + +.. automodule:: ecdsa + :members: + :undoc-members: + :show-inheritance: + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + ecdsa.curves + ecdsa.der + ecdsa.ecdh + ecdsa.ecdsa + ecdsa.ellipticcurve + ecdsa.errors + ecdsa.keys + ecdsa.numbertheory + ecdsa.rfc6979 + ecdsa.util diff --git a/docs/source/ecdsa.util.rst b/docs/source/ecdsa.util.rst new file mode 100644 index 00000000..9ea91d1d --- /dev/null +++ b/docs/source/ecdsa.util.rst @@ -0,0 +1,7 @@ +ecdsa.util module +================= + +.. automodule:: ecdsa.util + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..9aa5b3f1 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. python-ecdsa documentation master file, created by + sphinx-quickstart on Sat May 29 18:34:49 2021. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to python-ecdsa's documentation! +======================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 00000000..d74a83e1 --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,7 @@ +src +=== + +.. toctree:: + :maxdepth: 4 + + ecdsa From ef898fc22804aac465bd2c9ff0c346318c82d14d Mon Sep 17 00:00:00 2001 From: Hubert Kario Date: Sat, 29 May 2021 20:18:50 +0200 Subject: [PATCH 2/2] fix sphinx warnings in doc stings --- src/ecdsa/_compat.py | 2 +- src/ecdsa/ecdh.py | 20 +++++----- src/ecdsa/ecdsa.py | 82 +++++++++++++++++++++++--------------- src/ecdsa/ellipticcurve.py | 22 +++++----- src/ecdsa/keys.py | 53 ++++++++++++------------ src/ecdsa/rfc6979.py | 19 +++++---- 6 files changed, 110 insertions(+), 88 deletions(-) diff --git a/src/ecdsa/_compat.py b/src/ecdsa/_compat.py index af21be17..83d41a5f 100644 --- a/src/ecdsa/_compat.py +++ b/src/ecdsa/_compat.py @@ -128,7 +128,7 @@ def a2b_hex(val): raise ValueError("base16 error: %s" % e) # pylint: disable=invalid-name - # pylint is stupid here and deson't notice it's a function, not + # pylint is stupid here and doesn't notice it's a function, not # constant bytes_to_int = int.from_bytes # pylint: enable=invalid-name diff --git a/src/ecdsa/ecdh.py b/src/ecdsa/ecdh.py index 824a09b4..7f697d9a 100644 --- a/src/ecdsa/ecdh.py +++ b/src/ecdsa/ecdh.py @@ -116,7 +116,7 @@ def generate_private_key(self): :raises NoCurveError: Curve must be set before key generation. :return: public (verifying) key from this private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ if not self.curve: raise NoCurveError("Curve must be set prior to key generation.") @@ -135,7 +135,7 @@ def load_private_key(self, private_key): :raises InvalidCurveError: private_key curve not the same as self.curve :return: public (verifying) key from this private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ if not self.curve: self.curve = private_key.curve @@ -158,7 +158,7 @@ def load_private_key_bytes(self, private_key): :raises NoCurveError: Curve must be set before loading. :return: public (verifying) key from this private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ if not self.curve: raise NoCurveError("Curve must be set prior to key load.") @@ -183,7 +183,7 @@ def load_private_key_der(self, private_key_der): :raises InvalidCurveError: private_key curve not the same as self.curve :return: public (verifying) key from this private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ return self.load_private_key(SigningKey.from_der(private_key_der)) @@ -204,7 +204,7 @@ def load_private_key_pem(self, private_key_pem): :raises InvalidCurveError: private_key curve not the same as self.curve :return: public (verifying) key from this private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ return self.load_private_key(SigningKey.from_pem(private_key_pem)) @@ -215,7 +215,7 @@ def get_public_key(self): Needs to be sent to the remote party. :return: public (verifying) key from local private key. - :rtype: VerifyingKey object + :rtype: VerifyingKey """ return self.private_key.get_verifying_key() @@ -310,7 +310,7 @@ def generate_sharedsecret_bytes(self): :raises NoKeyError: public_key or private_key is not set :return: shared secret - :rtype: byte string + :rtype: bytes """ return number_to_string( self.generate_sharedsecret(), self.private_key.curve.curve.p() @@ -323,9 +323,9 @@ def generate_sharedsecret(self): The objects needs to have both private key and received public key before generation is allowed. - It's the same for local and remote party. - shared secret(local private key, remote public key ) == - shared secret (local public key, remote private key) + It's the same for local and remote party, + shared secret(local private key, remote public key) == + shared secret(local public key, remote private key) :raises InvalidCurveError: public_key curve not the same as self.curve :raises NoKeyError: public_key or private_key is not set diff --git a/src/ecdsa/ecdsa.py b/src/ecdsa/ecdsa.py index bf7daaef..33282816 100644 --- a/src/ecdsa/ecdsa.py +++ b/src/ecdsa/ecdsa.py @@ -1,59 +1,67 @@ #! /usr/bin/env python """ -Implementation of Elliptic-Curve Digital Signatures. +Low level implementation of Elliptic-Curve Digital Signatures. + +.. note :: + You're most likely looking for the :py:class:`~ecdsa.keys` module. + This is a low-level implementation of the ECDSA that operates on + integers, not byte strings. NOTE: This a low level implementation of ECDSA, for normal applications you should be looking at the keys.py module. Classes and methods for elliptic-curve signatures: private keys, public keys, signatures, -NIST prime-modulus curves with modulus lengths of -192, 224, 256, 384, and 521 bits. +and definitions of prime-modulus curves. Example: - # (In real-life applications, you would probably want to - # protect against defects in SystemRandom.) - from random import SystemRandom - randrange = SystemRandom().randrange +.. code-block:: python - # Generate a public/private key pair using the NIST Curve P-192: + # (In real-life applications, you would probably want to + # protect against defects in SystemRandom.) + from random import SystemRandom + randrange = SystemRandom().randrange - g = generator_192 - n = g.order() - secret = randrange( 1, n ) - pubkey = Public_key( g, g * secret ) - privkey = Private_key( pubkey, secret ) + # Generate a public/private key pair using the NIST Curve P-192: - # Signing a hash value: + g = generator_192 + n = g.order() + secret = randrange( 1, n ) + pubkey = Public_key( g, g * secret ) + privkey = Private_key( pubkey, secret ) - hash = randrange( 1, n ) - signature = privkey.sign( hash, randrange( 1, n ) ) + # Signing a hash value: - # Verifying a signature for a hash value: + hash = randrange( 1, n ) + signature = privkey.sign( hash, randrange( 1, n ) ) - if pubkey.verifies( hash, signature ): - print_("Demo verification succeeded.") - else: - print_("*** Demo verification failed.") + # Verifying a signature for a hash value: - # Verification fails if the hash value is modified: + if pubkey.verifies( hash, signature ): + print_("Demo verification succeeded.") + else: + print_("*** Demo verification failed.") - if pubkey.verifies( hash-1, signature ): - print_("**** Demo verification failed to reject tampered hash.") - else: - print_("Demo verification correctly rejected tampered hash.") + # Verification fails if the hash value is modified: -Version of 2009.05.16. + if pubkey.verifies( hash-1, signature ): + print_("**** Demo verification failed to reject tampered hash.") + else: + print_("Demo verification correctly rejected tampered hash.") Revision history: 2005.12.31 - Initial version. + 2008.11.25 - Substantial revisions introducing new classes. + 2009.05.16 - Warn against using random.randrange in real applications. + 2009.05.17 - Use random.SystemRandom by default. -Written in 2005 by Peter Pearson and placed in the public domain. +Originally written in 2005 by Peter Pearson and placed in the public domain, +modified as part of the python-ecdsa package. """ from six import int2byte, b @@ -72,16 +80,26 @@ class InvalidPointError(RuntimeError): class Signature(object): - """ECDSA signature.""" + """ + ECDSA signature. + + :ivar int r: the ``r`` element of the ECDSA signature + :ivar int s: the ``s`` element of the ECDSA signature + """ def __init__(self, r, s): self.r = r self.s = s def recover_public_keys(self, hash, generator): - """Returns two public keys for which the signature is valid - hash is signed hash - generator is the used generator of the signature + """ + Returns two public keys for which the signature is valid + + :param int hash: signed hash + :param AbstractPoint generator: is the generator used in creation + of the signature + :rtype: tuple(Public_key, Public_key) + :return: a pair of public keys that can validate the signature """ curve = generator.curve() n = generator.order() diff --git a/src/ecdsa/ellipticcurve.py b/src/ecdsa/ellipticcurve.py index 77f210e1..f358fbd5 100644 --- a/src/ecdsa/ellipticcurve.py +++ b/src/ecdsa/ellipticcurve.py @@ -342,7 +342,7 @@ def from_bytes( :param data: single point encoding of the public key :type data: :term:`bytes-like object` :param curve: the curve on which the public key is expected to lay - :type curve: ecdsa.ellipticcurve.CurveFp + :type curve: ~ecdsa.ellipticcurve.CurveFp :param validate_encoding: whether to verify that the encoding of the point is self-consistent, defaults to True, has effect only on ``hybrid`` encoding @@ -353,8 +353,8 @@ def from_bytes( name). All formats by default (specified with ``None``). :type valid_encodings: :term:`set-like object` - :raises MalformedPointError: if the public point does not lay on the - curve or the encoding is invalid + :raises `~ecdsa.errors.MalformedPointError`: if the public point does + not lay on the curve or the encoding is invalid :return: x and y coordinates of the encoded point :rtype: tuple(int, int) @@ -547,7 +547,7 @@ def from_bytes( :param data: single point encoding of the public key :type data: :term:`bytes-like object` :param curve: the curve on which the public key is expected to lay - :type curve: ecdsa.ellipticcurve.CurveFp + :type curve: ~ecdsa.ellipticcurve.CurveFp :param validate_encoding: whether to verify that the encoding of the point is self-consistent, defaults to True, has effect only on ``hybrid`` encoding @@ -563,8 +563,8 @@ def from_bytes( such, it will be commonly used with scalar multiplication. This will cause to precompute multiplication table generation for it - :raises MalformedPointError: if the public point does not lay on the - curve or the encoding is invalid + :raises `~ecdsa.errors.MalformedPointError`: if the public point does + not lay on the curve or the encoding is invalid :return: Point on curve :rtype: PointJacobi @@ -1110,7 +1110,7 @@ def from_bytes( :param data: single point encoding of the public key :type data: :term:`bytes-like object` :param curve: the curve on which the public key is expected to lay - :type curve: ecdsa.ellipticcurve.CurveFp + :type curve: ~ecdsa.ellipticcurve.CurveFp :param validate_encoding: whether to verify that the encoding of the point is self-consistent, defaults to True, has effect only on ``hybrid`` encoding @@ -1123,8 +1123,8 @@ def from_bytes( :param int order: the point order, must be non zero when using generator=True - :raises MalformedPointError: if the public point does not lay on the - curve or the encoding is invalid + :raises `~ecdsa.errors.MalformedPointError`: if the public point does + not lay on the curve or the encoding is invalid :return: Point on curve :rtype: Point @@ -1320,8 +1320,8 @@ def from_bytes( this will cause the library to pre-compute some values to make repeated usages of the point much faster - :raises MalformedPointError: if the public point does not lay on the - curve or the encoding is invalid + :raises `~ecdsa.errors.MalformedPointError`: if the public point does + not lay on the curve or the encoding is invalid :return: Initialised point on an Edwards curve :rtype: PointEdwards diff --git a/src/ecdsa/keys.py b/src/ecdsa/keys.py index 06cb9f00..b606f57d 100644 --- a/src/ecdsa/keys.py +++ b/src/ecdsa/keys.py @@ -57,12 +57,13 @@ portable and cross-platform way. bytes-like object - All the types that implement the buffer protocol. That includes ``str`` - (only on python2), ``bytes``, ``bytesarray``, ``array.array` and - ``memoryview`` of those objects. Please note that ``array.array` - serialisation (converting it to byte string) is endianness dependent! - Signature computed over ``array.array`` of integers on a big-endian - system will not be verified on a little-endian system and vice-versa. + All the types that implement the buffer protocol. That includes + ``str`` (only on python2), ``bytes``, ``bytesarray``, ``array.array`` + and ``memoryview`` of those objects. + Please note that ``array.array`` serialisation (converting it to byte + string) is endianess dependant! Signature computed over ``array.array`` + of integers on a big-endian system will not be verified on a + little-endian system and vice-versa. set-like object All the types that support the ``in`` operator, like ``list``, @@ -159,13 +160,13 @@ class VerifyingKey(object): """ Class for handling keys that can verify signatures (public keys). - :ivar ecdsa.curves.Curve curve: The Curve over which all the cryptographic - operations will take place + :ivar `~ecdsa.curves.Curve` ~.curve: The Curve over which all the + cryptographic operations will take place :ivar default_hashfunc: the function that will be used for hashing the data. Should implement the same API as hashlib.sha1 :vartype default_hashfunc: callable :ivar pubkey: the actual public key - :vartype pubkey: ecdsa.ecdsa.Public_key + :vartype pubkey: ~ecdsa.ecdsa.Public_key """ def __init__(self, _error__please_use_generate=None): @@ -208,13 +209,13 @@ def from_public_point( This is a low-level method, generally you will not want to use it. :param point: The point to wrap around, the actual public key - :type point: ecdsa.ellipticcurve.Point + :type point: ~ecdsa.ellipticcurve.AbstractPoint :param curve: The curve on which the point needs to reside, defaults to NIST192p - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for verification, needs to implement the same interface - as hashlib.sha1 + as :py:class:`hashlib.sha1` :type hashfunc: callable :type bool validate_point: whether to check if the point lays on curve should always be used if the public point is not a result @@ -308,7 +309,7 @@ def from_string( :param string: single point encoding of the public key :type string: :term:`bytes-like object` :param curve: the curve on which the public key is expected to lay - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1. Ignored for EdDSA. @@ -372,7 +373,7 @@ def from_pem( By default :term:`uncompressed`, :term:`compressed`, and :term:`hybrid`. To read malformed files, include :term:`raw encoding` with ``raw`` in the list. - :type valid_encodings: :term:`set-like object + :type valid_encodings: :term:`set-like object` :param valid_curve_encodings: list of allowed encoding formats for curve parameters. By default (``None``) all are supported: ``named_curve`` and ``explicit``. @@ -425,7 +426,7 @@ def from_der( By default :term:`uncompressed`, :term:`compressed`, and :term:`hybrid`. To read malformed files, include :term:`raw encoding` with ``raw`` in the list. - :type valid_encodings: :term:`set-like object + :type valid_encodings: :term:`set-like object` :param valid_curve_encodings: list of allowed encoding formats for curve parameters. By default (``None``) all are supported: ``named_curve`` and ``explicit``. @@ -499,7 +500,7 @@ def from_public_key_recovery( :param data: the data to be hashed for signature verification :type data: bytes-like object :param curve: the curve over which the signature was performed - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1 :type hashfunc: callable @@ -551,7 +552,7 @@ def from_public_key_recovery_with_digest( :param digest: the hash value of the message signed by the signature :type digest: bytes-like object :param curve: the curve over which the signature was performed - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for verification, needs to implement the same interface as hashlib.sha1 :type hashfunc: callable @@ -800,14 +801,14 @@ class SigningKey(object): """ Class for handling keys that can create signatures (private keys). - :ivar ecdsa.curves.Curve curve: The Curve over which all the cryptographic - operations will take place + :ivar `~ecdsa.curves.Curve` ~.curve: The Curve over which all the + cryptographic operations will take place :ivar default_hashfunc: the function that will be used for hashing the - data. Should implement the same API as hashlib.sha1 + data. Should implement the same API as :py:class:`hashlib.sha1` :ivar int baselen: the length of a :term:`raw encoding` of private key - :ivar ecdsa.keys.VerifyingKey verifying_key: the public key + :ivar `~ecdsa.keys.VerifyingKey` verifying_key: the public key associated with this private key - :ivar ecdsa.ecdsa.Private_key privkey: the actual private key + :ivar `~ecdsa.ecdsa.Private_key` privkey: the actual private key """ def __init__(self, _error__please_use_generate=None): @@ -868,7 +869,7 @@ def generate(cls, curve=NIST192p, entropy=None, hashfunc=sha1): :param curve: The curve on which the point needs to reside, defaults to NIST192p - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param entropy: Source of randomness for generating the private keys, should provide cryptographically secure random numbers if the keys need to be secure. Uses os.urandom() by default. @@ -896,7 +897,7 @@ def from_secret_exponent(cls, secexp, curve=NIST192p, hashfunc=sha1): :param int secexp: secret multiplier (the actual private key in ECDSA). Needs to be an integer between 1 and the curve order. :param curve: The curve on which the point needs to reside - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1 @@ -948,7 +949,7 @@ def from_string(cls, string, curve=NIST192p, hashfunc=sha1): :param string: the raw encoding of the private key :type string: bytes like object :param curve: The curve on which the point needs to reside - :type curve: ecdsa.curves.Curve + :type curve: ~ecdsa.curves.Curve :param hashfunc: The default hash function that will be used for signing, needs to implement the same interface as hashlib.sha1 @@ -1063,7 +1064,7 @@ def from_der(cls, string, hashfunc=sha1, valid_curve_encodings=None): is part of the PrivateKeyAlgorithmIdentifier. The PKCS #8 format includes an ECPrivateKey object as the `privateKey` - field within a larger structure: + field within a larger structure:: OneAsymmetricKey ::= SEQUENCE { version Version, diff --git a/src/ecdsa/rfc6979.py b/src/ecdsa/rfc6979.py index a0259917..0728b5a4 100644 --- a/src/ecdsa/rfc6979.py +++ b/src/ecdsa/rfc6979.py @@ -42,14 +42,17 @@ def bits2octets(data, order): # https://tools.ietf.org/html/rfc6979#section-3.2 def generate_k(order, secexp, hash_func, data, retry_gen=0, extra_entropy=b""): """ - order - order of the DSA generator used in the signature - secexp - secure exponent (private key) in numeric form - hash_func - reference to the same hash function used for generating - hash - data - hash in binary form of the signing data - retry_gen - int - how many good 'k' values to skip before returning - extra_entropy - extra added data in binary form as per section-3.6 of - rfc6979 + Generate the ``k`` value - the nonce for DSA. + + :param int order: order of the DSA generator used in the signature + :param int secexp: secure exponent (private key) in numeric form + :param hash_func: reference to the same hash function used for generating + hash, like :py:class:`hashlib.sha1` + :param bytes data: hash in binary form of the signing data + :param int retry_gen: how many good 'k' values to skip before returning + :param bytes extra_entropy: additional added data in binary form as per + section-3.6 of rfc6979 + :rtype: int """ qlen = bit_length(order)