From: Emanuel Moser Date: Mon, 30 Dec 2019 18:50:10 +0000 (+0100) Subject: refactoring of dnssec documentation X-Git-Tag: v2.0.0rc1~340^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=aaaf8ab1769727dacec5684aaf9886e4146ba9c3;p=thirdparty%2Fdnspython.git refactoring of dnssec documentation - replaces old comments with sphinx style comments - adds support for sphinx.ext.todo - since `_validate()` and `_validate_rrsig()` are only internal functions they are removed from documentation --- diff --git a/dns/dnssec.py b/dns/dnssec.py index de69de87..1abab941 100644 --- a/dns/dnssec.py +++ b/dns/dnssec.py @@ -95,7 +95,10 @@ _algorithm_by_value = {y: x for x, y in _algorithm_by_text.items()} def algorithm_from_text(text): """Convert text into a DNSSEC algorithm value. - Returns an ``int``. + :param text: text to convert to value + :type text: string + :return: a DNSSEC algorithm value + :rtype: integer """ value = _algorithm_by_text.get(text.upper()) @@ -107,7 +110,10 @@ def algorithm_from_text(text): def algorithm_to_text(value): """Convert a DNSSEC algorithm value to text - Returns a ``str``. + :param value: Value of a DNSSEC algorithm + :type value: integer + :return: the name of a DNSSEC algorithm + :rtype: string """ text = _algorithm_by_value.get(value) @@ -125,10 +131,13 @@ def _to_rdata(record, origin): def key_id(key, origin=None): """Return the key id (a 16-bit number) for the specified key. - Note the *origin* parameter of this function is historical and - is not needed. + :param key: a DNSKEY + :type key: :py:data:`dns.rdtypes.ANY.DNSKEY` + :param origin: Parameter is historical and **NOT** needed, defaults to None + :type origin: [type], optional + :return: an integer between 0 and 65535 + :rtype: integer - Returns an ``int`` between 0 and 65535. """ rdata = _to_rdata(key, origin) @@ -148,19 +157,19 @@ def key_id(key, origin=None): def make_ds(name, key, algorithm, origin=None): """Create a DS record for a DNSSEC key. - *name* is the owner name of the DS record. - - *key* is a ``dns.rdtypes.ANY.DNSKEY``. - - *algorithm* is a string describing which hash algorithm to use. The - currently supported hashes are "SHA1" and "SHA256". Case does not - matter for these strings. - - *origin* is a ``dns.name.Name`` and will be used as the origin - if *key* is a relative name. - - Returns a ``dns.rdtypes.ANY.DS``. + :param name: Owner name of the DS record + :type name: string + :param key: a DNSKEY + :type key: :py:data:`dns.rdtypes.ANY.DNSKEY` + :param algorithm: a string describing which hash algorithm to use.The currently supported hashes are "SHA1" and "SHA256". Case does not matter for these strings. + :type algorithm: string + :param origin: Will be used as origin if `key` is a relative name, defaults to None + :type origin: :py:data:`dns.name.Name`, optional + :raises UnsupportedAlgorithm: If the algorithm is not either "SHA1" or "SHA256" exception will be thrown + :return: a DS record + :rtype: :py:data:`dns.rdtypes.ANY.DS` """ + if algorithm.upper() == 'SHA1': dsalg = 1 dshash = hashlib.sha1() @@ -272,22 +281,27 @@ def _make_algorithm_id(algorithm): def _validate_rrsig(rrset, rrsig, keys, origin=None, now=None): """Validate an RRset against a single signature rdata - The owner name of *rrsig* is assumed to be the same as the owner name - of *rrset*. - - *rrset* is the RRset to validate. It can be a ``dns.rrset.RRset`` or - a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple. - - *rrsig* is a ``dns.rdata.Rdata``, the signature to validate. - - *keys* is the key dictionary, used to find the DNSKEY associated with - a given name. The dictionary is keyed by a ``dns.name.Name``, and has - ``dns.node.Node`` or ``dns.rdataset.Rdataset`` values. - - *origin* is a ``dns.name.Name``, the origin to use for relative names. - - *now* is an ``int``, the time to use when validating the signatures, - in seconds since the UNIX epoch. The default is the current time. + :param rrset: The RRset to validate + :type rrset: :py:data:`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`) + :param rrsig: Signature to validate + :type rrsig: :py:data:`dns.rdata.Rdata` + :param keys: Key dictionary, used to find the DNSKEY associated with a given name. The dictionary is keyed by a :py:data:`dns.name.Name`, and has :py:data:`dns.node.Node` or :py:data:`dns.rdataset.Rdataset` values. + :type keys: dictionary + :param origin: Origin to use for relative name, defaults to None + :type origin: :py:data:`dns.name.Name`, optional + :param now: time to use when validating the signatures, in seconds since the UNIX epoch, defaults to current time + :type now: integer, optional + :raises ValidationFailure: RRSig expired + :raises ValidationFailure: RRSig not yet valid + :raises ValidationFailure: Invalid public key + :raises ValidationFailure: Invalid ECDSA key + :raises ValidationFailure: Unknown algorithm + :raises ValueError: Generic Value Error + :raises ValidationFailure: Verify failure + :return: none + :rtype: none + + .. todo:: Fill in missing infos """ if isinstance(origin, str): @@ -425,20 +439,18 @@ def _validate_rrsig(rrset, rrsig, keys, origin=None, now=None): def _validate(rrset, rrsigset, keys, origin=None, now=None): """Validate an RRset. - *rrset* is the RRset to validate. It can be a ``dns.rrset.RRset`` or - a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple. - - *rrsigset* is the signature RRset to be validated. It can be a - ``dns.rrset.RRset`` or a ``(dns.name.Name, dns.rdataset.Rdataset)`` tuple. - - *keys* is the key dictionary, used to find the DNSKEY associated with - a given name. The dictionary is keyed by a ``dns.name.Name``, and has - ``dns.node.Node`` or ``dns.rdataset.Rdataset`` values. - - *origin* is a ``dns.name.Name``, the origin to use for relative names. - - *now* is an ``int``, the time to use when validating the signatures, - in seconds since the UNIX epoch. The default is the current time. + :param rrset: RRset to validate + :type rrset: :py:data:`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`) tuple + :param rrsigset: Signature RRset to be validated + :type rrsigset: :py:data`dns.rrset.RRset` or (:py:data:`dns.name.Name`, :py:data:`dns.rdataset.Rdataset`) tuple + :param keys: Key dictionary, used to find the DNSKEY associated with a given name. The dictionary is keyed by a :py:data:`dns.name.Name`, and has :py:data:`dns.node.Node` or :py:data:`dns.rdataset.Rdataset` values. + :type keys: dictionary + :param origin: Origin to use for relative name, defaults to None + :type origin: :py:data:`dns.name.Name`, optional + :param now: time to use when validating the signatures, in seconds since the UNIX epoch, defaults to current time + :type now: integer, optional + :raises ValidationFailure: Owner names do not match + :raises ValidationFailure: No RRSIGs validated """ if isinstance(origin, str): diff --git a/doc/conf.py b/doc/conf.py index 10211f95..f6595afc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,9 +31,12 @@ sys.path.insert(0, os.path.abspath('..')) # 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', +extensions = [ + 'sphinx.ext.autodoc', 'sphinx.ext.viewcode', - 'sphinx.ext.githubpages'] + 'sphinx.ext.githubpages', + 'sphinx.ext.todo' + ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -77,7 +80,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +todo_include_todos = True # -- Options for autodoc -------------------------------------------------- @@ -99,7 +102,7 @@ html_theme = 'alabaster' # 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'] +# html_static_path = ['_static'] # -- Options for HTMLHelp output ------------------------------------------ @@ -156,6 +159,3 @@ texinfo_documents = [ author, 'dnspython', 'One line description of project.', 'Miscellaneous'), ] - - - diff --git a/doc/dnssec.rst b/doc/dnssec.rst index 115f9734..eee8ea74 100644 --- a/doc/dnssec.rst +++ b/doc/dnssec.rst @@ -9,6 +9,14 @@ facilities for signing. In order to use DNSSEC functions, you must have ``pycryptodome`` or ``pycryptodomex`` installed. If you want to do elliptic curves, you must also have ``ecdsa`` installed. +DNSSEC Functions +---------------- + +.. autofunction:: dns.dnssec.algorithm_from_text +.. autofunction:: dns.dnssec.algorithm_to_text +.. autofunction:: dns.dnssec.key_id +.. autofunction:: dns.dnssec.make_ds + DNSSEC Algorithms ----------------- @@ -25,14 +33,4 @@ DNSSEC Algorithms .. autodata:: dns.dnssec.ECDSAP384SHA384 .. autodata:: dns.dnssec.INDIRECT .. autodata:: dns.dnssec.PRIVATEDNS -.. autodata:: dns.dnssec.PRIVATEOID - -DNSSEC Functions ----------------- - -.. autofunction:: dns.dnssec.algorithm_from_text -.. autofunction:: dns.dnssec.algorithm_to_text -.. autofunction:: dns.dnssec.key_id -.. autofunction:: dns.dnssec.make_ds -.. autofunction:: dns.dnssec.validate -.. autofunction:: dns.dnssec.validate_rrsig +.. autodata:: dns.dnssec.PRIVATEOID \ No newline at end of file