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) dns.dnssectypes.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: Union[dns.dnssectypes.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: Union[dns.rdtypes.ANY.DNSKEY.DNSKEY, dns.rdtypes.ANY.CDNSKEY.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: Union[dns.name.Name, str], key: dns.rdata.Rdata, algorithm: Union[dns.dnssectypes.DSDigest, str], origin: Optional[dns.name.Name] = None, policy: Optional[dns.dnssec.Policy] = None, validating: bool = False) dns.rdtypes.ANY.DS.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: Union[dns.name.Name, str], key: dns.rdata.Rdata, algorithm: Union[dns.dnssectypes.DSDigest, str], origin: Optional[dns.name.Name] = None) dns.rdtypes.ANY.CDS.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: Union[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: Union[int, str], flags: int = Flag.ZONE, protocol: int = 3) dns.rdtypes.ANY.DNSKEY.DNSKEY ¶
Convert a public key to DNSKEY 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 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: Union[dns.rrset.RRset, Tuple[dns.name.Name, dns.rdataset.Rdataset]], private_key: Union[cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey, cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKey, cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey, cryptography.hazmat.primitives.asymmetric.ed448.Ed448PrivateKey], signer: dns.name.Name, dnskey: dns.rdtypes.ANY.DNSKEY.DNSKEY, inception: Optional[Union[datetime.datetime, str, int, float]] = None, expiration: Optional[Union[datetime.datetime, str, int, float]] = None, lifetime: Optional[int] = None, verify: bool = False, policy: Optional[dns.dnssec.Policy] = None) dns.rdtypes.ANY.RRSIG.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.Raises
DeniedByPolicy
if the signature is denied by policy.
- dns.dnssec.validate(rrset: Union[dns.rrset.RRset, Tuple[dns.name.Name, dns.rdataset.Rdataset]], rrsigset: Union[dns.rrset.RRset, Tuple[dns.name.Name, dns.rdataset.Rdataset]], keys: Dict[dns.name.Name, Union[dns.rdataset.Rdataset, dns.node.Node]], origin: Optional[dns.name.Name] = None, now: Optional[float] = None, policy: Optional[dns.dnssec.Policy] = 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: Union[dns.rrset.RRset, Tuple[dns.name.Name, dns.rdataset.Rdataset]], rrsig: dns.rdtypes.ANY.RRSIG.RRSIG, keys: Dict[dns.name.Name, Union[dns.rdataset.Rdataset, dns.node.Node]], origin: Optional[dns.name.Name] = None, now: Optional[float] = None, policy: Optional[dns.dnssec.Policy] = 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: Union[dns.name.Name, str], salt: Optional[Union[str, bytes]], iterations: int, algorithm: Union[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
DNSSEC Algorithms¶
- dns.dnssec.RSAMD5 = Algorithm.RSAMD5¶
An enumeration.
- dns.dnssec.DH = Algorithm.DH¶
An enumeration.
- dns.dnssec.DSA = Algorithm.DSA¶
An enumeration.
- dns.dnssec.ECC = Algorithm.ECC¶
An enumeration.
- dns.dnssec.RSASHA1 = Algorithm.RSASHA1¶
An enumeration.
- dns.dnssec.DSANSEC3SHA1 = Algorithm.DSANSEC3SHA1¶
An enumeration.
- dns.dnssec.RSASHA1NSEC3SHA1 = Algorithm.RSASHA1NSEC3SHA1¶
An enumeration.
- dns.dnssec.RSASHA256 = Algorithm.RSASHA256¶
An enumeration.
- dns.dnssec.RSASHA512 = Algorithm.RSASHA512¶
An enumeration.
- dns.dnssec.ECDSAP256SHA256 = Algorithm.ECDSAP256SHA256¶
An enumeration.
- dns.dnssec.ECDSAP384SHA384 = Algorithm.ECDSAP384SHA384¶
An enumeration.
- dns.dnssec.INDIRECT = Algorithm.INDIRECT¶
An enumeration.
- dns.dnssec.PRIVATEDNS = Algorithm.PRIVATEDNS¶
An enumeration.
- dns.dnssec.PRIVATEOID = Algorithm.PRIVATEOID¶
An enumeration.