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 [source]
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 [source]
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 [source]
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 [source]
Create a DS record for a DNSSEC key.
name, a
dns.name.Name
orstr
, the owner name of the DS record.key, a
dns.rdtypes.ANY.DNSKEY.DNSKEY
ordns.rdtypes.ANY.DNSKEY.CDNSKEY
, the key the DS is about.algorithm, a
str
orint
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
orNone
. If key is a relative name, then it will be made absolute using the specified origin.policy, a
dns.dnssec.Policy
orNone
. IfNone
, the default policy,dns.dnssec.default_policy
is used; this policy defaults to that of RFC 8624.validating, a
bool
. IfTrue
, 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 [source]
Create a CDS record for a DNSSEC key.
name, a
dns.name.Name
orstr
, the owner name of the DS record.key, a
dns.rdtypes.ANY.DNSKEY.DNSKEY
ordns.rdtypes.ANY.DNSKEY.CDNSKEY
, the key the DS is about.algorithm, a
str
orint
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
orNone
. 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: GenericPublicKey | RSAPublicKey | EllipticCurvePublicKey | Ed25519PublicKey | Ed448PublicKey, algorithm: int | str, flags: int = Flag.ZONE, protocol: int = 3) DNSKEY
Convert a public key to DNSKEY Rdata
public_key, a
PublicKey
(GenericPublicKey
orcryptography.hazmat.primitives.asymmetric
) to convert.algorithm, a
str
orint
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
orint
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) 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
matchingprivate_key
.inception, a
datetime
,str
,int
,float
orNone
, the signature inception time. IfNone
, the current time is used. If astr
, 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
orNone
, the signature expiration time. IfNone
, 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
orNone
, the signature lifetime in seconds. This parameter is only meaningful if expiration isNone
.verify, a
bool
. If set toTrue
, the signer will verify signatures after they are created; the default isFalse
.policy, a
dns.dnssec.Policy
orNone
. IfNone
, the default policy,dns.dnssec.default_policy
is used; this policy defaults to that of RFC 8624.origin, a
dns.name.Name
orNone
. IfNone
, 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.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 hasdns.node.Node
ordns.rdataset.Rdataset
values.origin, a
dns.name.Name
, the origin to use for relative names; defaults to None.now, an
int
orNone
, the time, in seconds since the epoch, to use as the current time when validating. IfNone
, the actual current time is used.policy, a
dns.dnssec.Policy
orNone
. IfNone
, 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 hasdns.node.Node
ordns.rdataset.Rdataset
values.origin, a
dns.name.Name
orNone
, the origin to use for relative names.now, a
float
orNone
, the time, in seconds since the epoch, to use as the current time when validating. IfNone
, the actual current time is used.policy, a
dns.dnssec.Policy
orNone
. IfNone
, 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 [source]
Calculate the NSEC3 hash, according to https://tools.ietf.org/html/rfc5155#section-5
domain, a
dns.name.Name
orstr
, the name to hash.salt, a
str
,bytes
, orNone
, the hash salt. If a string, it is decoded as a hex string.iterations, an
int
, the number of iterations.algorithm, a
str
orint
, the hash algorithm. The only defined algorithm is SHA1.Returns a
str
, the encoded NSEC3 hash.
- dns.dnssec.make_ds_rdataset()[source]
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
orint
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
orNone
. 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 andValueError
if the given RRset is not usable.Returns a
dns.rdataset.Rdataset
- dns.dnssec.cds_rdataset_to_ds_rdataset()[source]
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()[source]
Create a CDS record from DNSKEY/CDNSKEY.
name, a
dns.name.Name
orstr
, the owner name of the CDS record.rdataset, a
dns.rdataset.Rdataset
, to create DS Rdataset for.algorithm, a
str
orint
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
orNone
. If key is a relative name, then it will be made absolute using the specified origin.Raises
UnsupportedAlgorithm
if the algorithm is unknown orValueError
if the rdataset is not DNSKEY/CDNSKEY.Returns a
dns.rdataset.Rdataset
- dns.dnssec.dnskey_rdataset_to_cdnskey_rdataset()[source]
Create a CDNSKEY record from DNSKEY.
rdataset, a
dns.rdataset.Rdataset
, to create CDNSKEY Rdataset for.Returns a
dns.rdataset.Rdataset
- dns.dnssec.sign_zone()[source]
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
. IfTrue
, 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
orNone
, the signature inception time. IfNone
, the current time is used. If astr
, 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
orNone
, the signature expiration time. IfNone
, 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
orNone
, the signature lifetime in seconds. This parameter is only meaningful if expiration isNone
.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.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