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.

Parameters:

text (str) – The text to convert into an algorithm value.

Return type:

int

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

Convert a DNSSEC algorithm value to text

Parameters:

value (dns.dnssectypes.Algorithm) – The algorithm value.

Return type:

str

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

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

Parameters:

key (dns.rdtypes.ANY.DNSKEY.DNSKEY) – The DNSKEY or CDNSKEY rdata.

Return type:

int

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.

Parameters:

• name (dns.name.Name or str) – The owner name of the DS record.

• key (dns.rdtypes.ANY.DNSKEY.DNSKEY or dns.rdtypes.ANY.CDNSKEY.CDNSKEY) – The key the DS is about.

• algorithm (str or int) – The hash algorithm. Currently supported: "SHA1", "SHA256", "SHA384" (case-insensitive).

• origin (dns.name.Name or None) – If key is a relative name, it will be made absolute using this origin.

• policy (dns.dnssec.Policy or None) – The policy to use. If None, dns.dnssec.default_policy is used (defaults to RFC 8624 policy).

• validating (bool) – If True, policy is checked in validating mode (“Is it ok to validate using this digest algorithm?”). Otherwise checked in creating mode.

Raises:

• UnsupportedAlgorithm – If the algorithm is unknown.

• DeniedByPolicy – If the algorithm is denied by policy.

Return type:

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.

Parameters:

• name (dns.name.Name or str) – The owner name of the DS record.

• key (dns.rdtypes.ANY.DNSKEY.DNSKEY or dns.rdtypes.ANY.CDNSKEY.CDNSKEY) – The key the DS is about.

• algorithm (str or int) – The hash algorithm. Currently supported: "SHA1", "SHA256", "SHA384" (case-insensitive).

• origin (dns.name.Name or None) – If key is a relative name, it will be made absolute using this origin.

Raises:

UnsupportedAlgorithm – If the algorithm is unknown.

Return type:

dns.rdtypes.ANY.CDS.CDS

dns.dnssec.make_dnskey(public_key: GenericPublicKey | RSAPublicKey | EllipticCurvePublicKey | Ed25519PublicKey | Ed448PublicKey, algorithm: int | str, flags: int = <Flag.ZONE: 256>, protocol: int = 3) → DNSKEY

Convert a public key to DNSKEY Rdata

Parameters:

• public_key – The public key to convert (a GenericPublicKey or cryptography.hazmat.primitives.asymmetric key).

• algorithm (str or int) – The DNSKEY algorithm.

• flags (int) – DNSKEY flags field.

• protocol (int) – DNSKEY protocol field.

Raises:

• ValueError – If the key algorithm parameters are unsupported.

• TypeError – If the key type is unsupported.

• UnsupportedAlgorithm – If the algorithm is unknown.

• AlgorithmKeyMismatch – If the algorithm does not match the key type.

Return type:

dns.rdtypes.ANY.DNSKEY.DNSKEY

dns.dnssec.make_cdnskey()

Convert a public key to CDNSKEY Rdata

Parameters:

• public_key – The public key to convert (cryptography.hazmat.primitives.asymmetric key for DNSSEC).

• algorithm (str or int) – The DNSKEY algorithm.

• flags (int) – DNSKEY flags field.

• protocol (int) – DNSKEY protocol field.

Raises:

• ValueError – If the key algorithm parameters are unsupported.

• TypeError – If the key type is unsupported.

• UnsupportedAlgorithm – If the algorithm is unknown.

• AlgorithmKeyMismatch – If the algorithm does not match the key type.

Return type:

dns.rdtypes.ANY.CDNSKEY.CDNSKEY

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.

Parameters:

• rrset – The RRset to sign — a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

• private_key – The private key to use for signing.

• signer (dns.name.Name) – The signer’s name.

• dnskey – A DNSKEY matching private_key.

• inception (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 the number of seconds since the UNIX epoch. int and float values are interpreted as seconds since the UNIX epoch.

• expiration (datetime, str, int, float, or None) – The signature expiration time. If None, the expiration is inception plus lifetime. Interpreted the same as inception.

• lifetime (int or None) – The signature lifetime in seconds. Only meaningful if expiration is None.

• verify (bool) – If True, signatures will be verified after creation. Default is False.

• policy (dns.dnssec.Policy or None) – The policy to use. If None, dns.dnssec.default_policy is used (defaults to RFC 8624 policy).

• origin (dns.name.Name or None) – If None (the default), all names must be absolute. Otherwise, this origin is used to make names absolute when signing.

• deterministic (bool) – If True (the default), use deterministic (reproducible) signatures when supported. Currently 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, Node | Rdataset], 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.

Parameters:

• rrset – The RRset to validate — a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

• rrsigset – The signature RRset — a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

• keys – The key dictionary, keyed by dns.name.Name, with dns.node.Node or dns.rdataset.Rdataset values.

• origin (dns.name.Name or None) – The origin to use for relative names. Defaults to None.

• now (int or None) – The current time in seconds since the epoch. If None, the actual current time is used.

• policy (dns.dnssec.Policy or None) – The policy to use. If None, dns.dnssec.default_policy is used (defaults to RFC 8624 policy).

Raises:

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

dns.dnssec.validate_rrsig(rrset: RRset | tuple[Name, Rdataset], rrsig: RRSIG, keys: dict[Name, Node | Rdataset], 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.

Parameters:

• rrsig (dns.rdata.Rdata) – The signature to validate.

• keys – The key dictionary, keyed by dns.name.Name, with dns.node.Node or dns.rdataset.Rdataset values.

• origin (dns.name.Name or None) – The origin to use for relative names.

• now (float or None) – The current time in seconds since the epoch. If None, the actual current time is used.

• policy (dns.dnssec.Policy or None) – The policy to use. If None, dns.dnssec.default_policy is used (defaults to RFC 8624 policy).

Raises:

• ValidationFailure – If the signature is expired, not yet valid, the public key is invalid, the algorithm is unknown, verification fails, etc.

• UnsupportedAlgorithm – If the algorithm is recognized 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

Parameters:

• domain (dns.name.Name or str) – The name to hash.

• salt (str, bytes, or None) – The hash salt. If a string, it is decoded as a hex string.

• iterations (int) – The number of iterations.

• algorithm (str or int) – The hash algorithm. The only defined algorithm is SHA1.

Return type:

str

dns.dnssec.make_ds_rdataset()

Create a DS record from DNSKEY/CDNSKEY/CDS.

Parameters:

• rrset – The RRset — a dns.rrset.RRset or a (dns.name.Name, dns.rdataset.Rdataset) tuple.

• algorithms (set of str or int) – A set of hash algorithms. Currently supported: "SHA1", "SHA256", "SHA384" (case-insensitive). If the RRset is a CDS, only digest algorithms matching algorithms are accepted.

• origin (dns.name.Name or None) – If the key name is relative, it will be made absolute using this origin.

Raises:

• UnsupportedAlgorithm – If any algorithm is unknown.

• ValueError – If the given RRset is not usable.

Return type:

dns.rdataset.Rdataset

dns.dnssec.cds_rdataset_to_ds_rdataset()

Create a CDS record from DS.

Parameters:

rdataset (dns.rdataset.Rdataset) – The CDS rdataset to convert to DS.

Raises:

ValueError – If the rdataset is not CDS.

Return type:

dns.rdataset.Rdataset

dns.dnssec.dnskey_rdataset_to_cds_rdataset()

Create a CDS record from DNSKEY/CDNSKEY.

Parameters:

• name (dns.name.Name or str) – The owner name of the CDS record.

• rdataset (dns.rdataset.Rdataset) – The DNSKEY/CDNSKEY rdataset to create CDS for.

• algorithm (str or int) – The hash algorithm. Currently supported: "SHA1", "SHA256", "SHA384" (case-insensitive).

• origin (dns.name.Name or None) – If the key name is relative, it will be made absolute using this origin.

Raises:

• UnsupportedAlgorithm – If the algorithm is unknown.

• ValueError – If the rdataset is not DNSKEY/CDNSKEY.

Return type:

dns.rdataset.Rdataset

dns.dnssec.dnskey_rdataset_to_cdnskey_rdataset()

Create a CDNSKEY record from DNSKEY.

Parameters:

rdataset (dns.rdataset.Rdataset) – The DNSKEY rdataset to convert to CDNSKEY.

Return type:

dns.rdataset.Rdataset

dns.dnssec.default_rrset_signer()

Default RRset signer

dns.dnssec.sign_zone()

Sign zone.

Parameters:

• zone (dns.zone.Zone) – The zone to sign.

• txn (dns.transaction.Transaction or None) – 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 (bool) – If True (the default), all specified DNSKEYs are automatically added to the zone on signing.

• dnskey_ttl (int or None) – The TTL for DNSKEY RRs. If not specified, uses the TTL of the existing DNSKEY RRset or the SOA RRset.

• inception (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 seconds since UNIX epoch. int and float are seconds since epoch.

• expiration (datetime, str, int, float, or None) – The signature expiration time. If None, the expiration is inception plus lifetime. Interpreted the same as inception.

• lifetime (int or None) – The signature lifetime in seconds. Only meaningful if expiration is None.

• nsec3 – If specified, configures signing using NSEC3. Not yet implemented.

• rrset_signer – An optional function for signing RRsets, accepting two arguments: transaction and RRset. If not specified, dns.dnssec.default_rrset_signer is used.

• deterministic (bool) – If True (the default), use deterministic (reproducible) signatures when supported. Currently affects ECDSA.

DNSSEC Policy

class dns.dnssec.Policy

DNSSEC Algorithm Types

class dns.dnssectypes.Algorithm(value)

class dns.dnssectypes.DSDigest(value)

DNSSEC Delegation Signer Digest Algorithm

DNSSEC Algorithm Implementations

class dns.dnssecalgs.base.GenericPublicKey(key: Any)

abstractmethod encode_key_bytes() → bytes

Encode key as bytes for DNSKEY

abstractmethod classmethod from_dnskey(key: DNSKEY) → GenericPublicKey

Create public key from DNSKEY

abstractmethod classmethod from_pem(public_pem: bytes) → GenericPublicKey

Create public key from PEM-encoded SubjectPublicKeyInfo as specified in RFC 5280

to_dnskey(flags: int = <Flag.ZONE: 256>, protocol: int = 3) → DNSKEY

Return public key as DNSKEY

abstractmethod to_pem() → bytes

Return public-key as PEM-encoded SubjectPublicKeyInfo as specified in RFC 5280

abstractmethod verify(signature: bytes, data: bytes) → None

Verify signed DNSSEC data

class dns.dnssecalgs.base.GenericPrivateKey(key: Any)

abstractmethod classmethod from_pem(private_pem: bytes, password: bytes | None = None) → GenericPrivateKey

Create private key from PEM-encoded PKCS#8

abstractmethod public_key() → GenericPublicKey

Return public key instance

abstractmethod sign(data: bytes, verify: bool = False, deterministic: bool = True) → bytes

Sign DNSSEC data

abstractmethod to_pem(password: bytes | None = None) → bytes

Return private key as PEM-encoded PKCS#8

DNSSEC Algorithm Constants

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