DNSSEC

Dnspython can do simple DNSSEC signature validation and signing. In order to use DNSSEC functions, you must have python cryptography installed.

DNSSEC Functions

dns.dnssec.algorithm_from_text(text: str) → Algorithm

Convert text into a DNSSEC algorithm value.

text, a str, the text to convert to into an algorithm value.

Returns an int.

dns.dnssec.algorithm_to_text(value: Algorithm | int) → str

Convert a DNSSEC algorithm value to text

value, a dns.dnssec.Algorithm.

Returns a str, the name of a DNSSEC algorithm.

dns.dnssec.key_id(key: DNSKEY | CDNSKEY) → int

Return the key id (a 16-bit number) for the specified key.

key, a dns.rdtypes.ANY.DNSKEY.DNSKEY

Returns an int between 0 and 65535

dns.dnssec.make_ds(name: Name | str, key: Rdata, algorithm: DSDigest | str, origin: Name | None = None, policy: Policy | None = None, validating: bool = False) → DS

Create a DS record for a DNSSEC key.

name, a dns.name.Name or str, the owner name of the DS record.

key, a dns.rdtypes.ANY.DNSKEY.DNSKEY or dns.rdtypes.ANY.DNSKEY.CDNSKEY, the key the DS is about.

algorithm, a str or int specifying the hash algorithm. The currently supported hashes are “SHA1”, “SHA256”, and “SHA384”. Case does not matter for these strings.

origin, a dns.name.Name or None. If key is a relative name, then it will be made absolute using the specified origin.

policy, a dns.dnssec.Policy or None. If None, the default policy, dns.dnssec.default_policy is used; this policy defaults to that of RFC 8624.

validating, a bool. If True, then policy is checked in validating mode, i.e. “Is it ok to validate using this digest algorithm?”. Otherwise the policy is checked in creating mode, i.e. “Is it ok to create a DS with this digest algorithm?”.

Raises UnsupportedAlgorithm if the algorithm is unknown.

Raises DeniedByPolicy if the algorithm is denied by policy.

Returns a dns.rdtypes.ANY.DS.DS

dns.dnssec.make_cds(name: Name | str, key: Rdata, algorithm: DSDigest | str, origin: Name | None = None) → CDS

Create a CDS record for a DNSSEC key.

name, a dns.name.Name or str, the owner name of the DS record.

key, a dns.rdtypes.ANY.DNSKEY.DNSKEY or dns.rdtypes.ANY.DNSKEY.CDNSKEY, the key the DS is about.

algorithm, a str or int specifying the hash algorithm. The currently supported hashes are “SHA1”, “SHA256”, and “SHA384”. Case does not matter for these strings.

origin, a dns.name.Name or None. If key is a relative name, then it will be made absolute using the specified origin.

Raises UnsupportedAlgorithm if the algorithm is unknown.

Returns a dns.rdtypes.ANY.DS.CDS

dns.dnssec.make_dnskey(public_key: ~dns.dnssecalgs.base.GenericPublicKey | ~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey | ~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey | ~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey | ~cryptography.hazmat.primitives.asymmetric.ed448.Ed448PublicKey, algorithm: int | str, flags: int = <Flag.ZONE: 256>, protocol: int = 3) → DNSKEY

Convert a public key to DNSKEY Rdata

public_key, a PublicKey (GenericPublicKey or cryptography.hazmat.primitives.asymmetric) to convert.

algorithm, a str or int specifying the DNSKEY algorithm.

flags: DNSKEY flags field as an integer.

protocol: DNSKEY protocol field as an integer.

Raises ValueError if the specified key algorithm parameters are not unsupported, TypeError if the key type is unsupported, UnsupportedAlgorithm if the algorithm is unknown and AlgorithmKeyMismatch if the algorithm does not match the key type.

Return DNSKEY Rdata.

dns.dnssec.make_cdnskey()

Convert a public key to CDNSKEY Rdata

public_key, the public key to convert, a cryptography.hazmat.primitives.asymmetric public key class applicable for DNSSEC.

algorithm, a str or int specifying the DNSKEY algorithm.

flags: DNSKEY flags field as an integer.

protocol: DNSKEY protocol field as an integer.

Raises ValueError if the specified key algorithm parameters are not unsupported, TypeError if the key type is unsupported, UnsupportedAlgorithm if the algorithm is unknown and AlgorithmKeyMismatch if the algorithm does not match the key type.

Return CDNSKEY Rdata.

dns.dnssec.sign(rrset: RRset | Tuple[Name, Rdataset], private_key: GenericPrivateKey | RSAPrivateKey | EllipticCurvePrivateKey | Ed25519PrivateKey | Ed448PrivateKey, signer: Name, dnskey: DNSKEY, inception: datetime | str | int | float | None = None, expiration: datetime | str | int | float | None = None, lifetime: int | None = None, verify: bool = False, policy: Policy | None = None, origin: Name | None = None, deterministic: bool = True) → RRSIG

Sign RRset using private key.

rrset, the RRset to validate. This can be a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

private_key, the private key to use for signing, a cryptography.hazmat.primitives.asymmetric private key class applicable for DNSSEC.

signer, a dns.name.Name, the Signer’s name.

dnskey, a DNSKEY matching private_key.

inception, a datetime, str, int, float or None, the signature inception time. If None, the current time is used. If a str, the format is “YYYYMMDDHHMMSS” or alternatively the number of seconds since the UNIX epoch in text form; this is the same the RRSIG rdata’s text form. Values of type int or float are interpreted as seconds since the UNIX epoch.

expiration, a datetime, str, int, float or None, the signature expiration time. If None, the expiration time will be the inception time plus the value of the lifetime parameter. See the description of inception above for how the various parameter types are interpreted.

lifetime, an int or None, the signature lifetime in seconds. This parameter is only meaningful if expiration is None.

verify, a bool. If set to True, the signer will verify signatures after they are created; the default is False.

policy, a dns.dnssec.Policy or None. If None, the default policy, dns.dnssec.default_policy is used; this policy defaults to that of RFC 8624.

origin, a dns.name.Name or None. If None, the default, then all names in the rrset (including its owner name) must be absolute; otherwise the specified origin will be used to make names absolute when signing.

deterministic, a bool. If True, the default, use deterministic (reproducible) signatures when supported by the algorithm used for signing. Currently, this only affects ECDSA.

Raises DeniedByPolicy if the signature is denied by policy.

dns.dnssec.validate(rrset: RRset | Tuple[Name, Rdataset], rrsigset: RRset | Tuple[Name, Rdataset], keys: Dict[Name, Rdataset | Node], origin: Name | None = None, now: float | None = None, policy: Policy | None = None) → None

Validate an RRset against a signature RRset, throwing an exception if none of the signatures validate.

rrset, the RRset to validate. This can be a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

rrsigset, the signature RRset. This can be a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

keys, 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, a dns.name.Name, the origin to use for relative names; defaults to None.

now, an int or None, the time, in seconds since the epoch, to use as the current time when validating. If None, the actual current time is used.

policy, a dns.dnssec.Policy or None. If None, the default policy, dns.dnssec.default_policy is used; this policy defaults to that of RFC 8624.

Raises ValidationFailure if the signature is expired, not yet valid, the public key is invalid, the algorithm is unknown, the verification fails, etc.

dns.dnssec.validate_rrsig(rrset: RRset | Tuple[Name, Rdataset], rrsig: RRSIG, keys: Dict[Name, Rdataset | Node], origin: Name | None = None, now: float | None = None, policy: Policy | None = None) → None

Validate an RRset against a single signature rdata, throwing an exception if validation is not successful.

rrset, the RRset to validate. This can be a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

rrsig, a dns.rdata.Rdata, the signature to validate.

keys, 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, a dns.name.Name or None, the origin to use for relative names.

now, a float or None, the time, in seconds since the epoch, to use as the current time when validating. If None, the actual current time is used.

policy, a dns.dnssec.Policy or None. If None, the default policy, dns.dnssec.default_policy is used; this policy defaults to that of RFC 8624.

Raises ValidationFailure if the signature is expired, not yet valid, the public key is invalid, the algorithm is unknown, the verification fails, etc.

Raises UnsupportedAlgorithm if the algorithm is recognized by dnspython but not implemented.

dns.dnssec.nsec3_hash(domain: Name | str, salt: str | bytes | None, iterations: int, algorithm: int | str) → str

Calculate the NSEC3 hash, according to https://tools.ietf.org/html/rfc5155#section-5

domain, a dns.name.Name or str, the name to hash.

salt, a str, bytes, or None, the hash salt. If a string, it is decoded as a hex string.

iterations, an int, the number of iterations.

algorithm, a str or int, the hash algorithm. The only defined algorithm is SHA1.

Returns a str, the encoded NSEC3 hash.

dns.dnssec.make_ds_rdataset()

Create a DS record from DNSKEY/CDNSKEY/CDS.

rrset, the RRset to create DS Rdataset for. This can be a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

algorithms, a set of str or int specifying the hash algorithms. The currently supported hashes are “SHA1”, “SHA256”, and “SHA384”. Case does not matter for these strings. If the RRset is a CDS, only digest algorithms matching algorithms are accepted.

origin, a dns.name.Name or None. If key is a relative name, then it will be made absolute using the specified origin.

Raises UnsupportedAlgorithm if any of the algorithms are unknown and ValueError if the given RRset is not usable.

Returns a dns.rdataset.Rdataset

dns.dnssec.cds_rdataset_to_ds_rdataset()

Create a CDS record from DS.

rdataset, a dns.rdataset.Rdataset, to create DS Rdataset for.

Raises ValueError if the rdataset is not CDS.

Returns a dns.rdataset.Rdataset

dns.dnssec.dnskey_rdataset_to_cds_rdataset()

Create a CDS record from DNSKEY/CDNSKEY.

name, a dns.name.Name or str, the owner name of the CDS record.

rdataset, a dns.rdataset.Rdataset, to create DS Rdataset for.

algorithm, a str or int specifying the hash algorithm. The currently supported hashes are “SHA1”, “SHA256”, and “SHA384”. Case does not matter for these strings.

origin, a dns.name.Name or None. If key is a relative name, then it will be made absolute using the specified origin.

Raises UnsupportedAlgorithm if the algorithm is unknown or ValueError if the rdataset is not DNSKEY/CDNSKEY.

Returns a dns.rdataset.Rdataset

dns.dnssec.dnskey_rdataset_to_cdnskey_rdataset()

Create a CDNSKEY record from DNSKEY.

rdataset, a dns.rdataset.Rdataset, to create CDNSKEY Rdataset for.

Returns a dns.rdataset.Rdataset

dns.dnssec.default_rrset_signer()

Default RRset signer

dns.dnssec.sign_zone()

Sign zone.

zone, a dns.zone.Zone, the zone to sign.

txn, a dns.transaction.Transaction, an optional transaction to use for signing.

keys, a list of (PrivateKey, DNSKEY) tuples, to use for signing. KSK/ZSK roles are assigned automatically if the SEP flag is used, otherwise all RRsets are signed by all keys.

add_dnskey, a bool. If True, the default, all specified DNSKEYs are automatically added to the zone on signing.

dnskey_ttl, a``int``, specifies the TTL for DNSKEY RRs. If not specified the TTL of the existing DNSKEY RRset used or the TTL of the SOA RRset.

inception, a datetime, str, int, float or None, the signature inception time. If None, the current time is used. If a str, the format is “YYYYMMDDHHMMSS” or alternatively the number of seconds since the UNIX epoch in text form; this is the same the RRSIG rdata’s text form. Values of type int or float are interpreted as seconds since the UNIX epoch.

expiration, a datetime, str, int, float or None, the signature expiration time. If None, the expiration time will be the inception time plus the value of the lifetime parameter. See the description of inception above for how the various parameter types are interpreted.

lifetime, an int or None, the signature lifetime in seconds. This parameter is only meaningful if expiration is None.

nsec3, a NSEC3PARAM Rdata, configures signing using NSEC3. Not yet implemented.

rrset_signer, a Callable, an optional function for signing RRsets. The function requires two arguments: transaction and RRset. If the not specified, dns.dnssec.default_rrset_signer will be used.

deterministic, a bool. If True, the default, use deterministic (reproducible) signatures when supported by the algorithm used for signing. Currently, this only affects ECDSA.

Returns None.

DNSSEC Algorithms

dns.dnssec.RSAMD5 = Algorithm.RSAMD5

dns.dnssec.DH = Algorithm.DH

dns.dnssec.DSA = Algorithm.DSA

dns.dnssec.ECC = Algorithm.ECC

dns.dnssec.RSASHA1 = Algorithm.RSASHA1

dns.dnssec.DSANSEC3SHA1 = Algorithm.DSANSEC3SHA1

dns.dnssec.RSASHA1NSEC3SHA1 = Algorithm.RSASHA1NSEC3SHA1

dns.dnssec.RSASHA256 = Algorithm.RSASHA256

dns.dnssec.RSASHA512 = Algorithm.RSASHA512

dns.dnssec.ECDSAP256SHA256 = Algorithm.ECDSAP256SHA256

dns.dnssec.ECDSAP384SHA384 = Algorithm.ECDSAP384SHA384

dns.dnssec.INDIRECT = Algorithm.INDIRECT

dns.dnssec.PRIVATEDNS = Algorithm.PRIVATEDNS

dns.dnssec.PRIVATEOID = Algorithm.PRIVATEOID