Release 0.1.2 Alastair Houghton

asyncdns DocumentationRelease 0.1.2

Alastair Houghton

Nov 15, 2018

Contents

1 What is this? 3

2 Usage 52.1 Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Replies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 What are Resolvers? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 Indices and tables 17

i

asyncdns Documentation, Release 0.1.2

Contents 1

https://travis-ci.org/al45tair/asyncdns

http://asyncdns.readthedocs.io/en/latest/?badge=latest


2 Contents

CHAPTER 1

What is this?

asyncdns is a pure Python asynchronous DNS resolver implementation written on top of asyncio. It doesn’t requireany external libraries, and it doesn’t use threads or blocking functions.

3


4 Chapter 1. What is this?

CHAPTER 2

Usage

asyncdns doesn’t have an equivalent to the widely used gethostbyname() or getaddrinfo() functions.Instead, you use it by constructing a Query object specifying the DNS query you wish to run, then pass it to aResolver to actually perform the query.

There are a handful of built-in resolvers, but for demonstration purposes the easiest one to use is theSmartResolver, which automatically makes use of /etc/hosts, multicast DNS and regular DNS as appro-priate.

For instance, do a simple lookup for an A record:

>>> import asyncdns, asyncio>>> resolver = asyncdns.SmartResolver()>>> loop = asyncio.get_event_loop()>>> query = asyncdns.Query('www.example.com', asyncdns.A, asyncdns.IN)>>> f = resolver.lookup(query)>>> loop.run_until_complete(f)>>> print(f.result());; No error (RD, RA); 1 answers:www.example.com 54950 IN A 93.184.216.34; 0 authorities:; 0 additional:

Note that you may or may not want to use SmartResolver in your code, depending on your requirements - itprobably isn’t a good idea using multicast DNS on an untrusted network, for instance.

Contents:

2.1 Queries

DNS queries are represented by Query objects, which hold a name to look up, a query type and a query class.

class Query(name, q_type, q_class)

5


Represents a DNS query.

Parameters

• name (ipaddress.IPv6Address) – The name to query.

• q_type (int) – The RR type you’re querying for.

• q_class (int) – The RR class you’re querying for.

name may be specified as a Python string (in which case, IDNA is applied if necessary); or as a Python bytesobject (in which case the bytes are used literally, subject to the usual rules on DNS labels); or an IP addressusing the ipaddress module’s IPv4Address or IPv6Address objects, in which case the address will beautomatically turned into the appropriate form for a reverse lookup.

There are constants for most query types in the asyncdns module, e.g. asyncdns.A, asyncdns.AAAAand so on, but you can use the numeric value if required. Possible values are:

Constant Value MeaningA 1 IPv4 addressNS 2 NameserverMD 3 Mail destination (obsolete)MF 4 Mail forwarder (obsolete)CNAME 5 Canonical name record - an aliasSOA 6 Start Of AuthorityMB 7 Mailbox domain name (obsolete)MG 8 Mail group member (obsolete)MR 9 Mail rename (obsolete)NUL 10 NullWKS 11 Well Known Service description (obsolete)PTR 12 Pointer - for inverse queriesHINFO 13 Host information (obsolete)MINFO 14 Mailbox or list information (obsolete)MX 15 Mail eXchangerTXT 16 Free format textRP 17 Responsible personAFSDB 18 AFS database recordX25 19 X.121 address, as used on X.25 networksISDN 20 ISDN addressRT 21 Route record, for X.25 or ISDNNSAP 22 OSI NSAP addressNSAPPTR 23 NSAP Pointer - for inverse queriesSIG 24 (Old) DNSSEC signature (obsolete)KEY 25 (Old) DNSSEC key (obsolete)PX 26 X.400 mail mapping information (obsolete)GPOS 27 Geographical location (obsolete)AAAA 28 IPv6 addressLOC 29 Geographical locationNXT 30 (Old) DNSSEC Next record (obsolete)EID 31 Nimrod Endpoint Identifier (obsolete)NIMLOC 32 Nimrod Locator (obsolete)SRV 33 Service locatorATMA 34 ATM address

Continued on next page

6 Chapter 2. Usage


Table 1 – continued from previous pageNAPTR 35 Naming Authority Pointer - regex rewritingKX 36 Key exchanger recordCERT 37 Certificate recordA6 38 Intended to replace AAAA (obsolete)DNAME 39 Alias for a name and all subnamesSINK 40 Kitchen sink (joke, obsolete)OPT 41 EDNS option (PSEUDO-RR)APL 42 Address Prefix ListDS 43 Delegation Signer recordSSHFP 44 SSH public key fingerprintIPSECKEY 45 IPsec keyRRSIG 46 DNSSEC signatureNSEC 47 Next Secure record - to prove non-existenceDNSKEY 48 DNSSEC key recordDHCID 49 DHCP identifierNSEC3 50 Next Secure record (v3)NSEC3PARAM 51 NSEC3 parameter recordTLSA 52 TLSA cetificate associationHIP 55 Host Identity Protocol recordCDS 59 Child DS recordCDNSKEY 60 Child DNSKEYOPENPGPKEY 61 OpenPGP public keySPF 99 SPF record (obsolete)UINFO 100 ReservedUID 101 ReservedGID 102 ReservedUNSPEC 103 ReservedTKEY 249 Transaction keyTSIG 250 Transaction signatureIXFR 251 Incremental zone transfer (PSEUDO-RR)AXFR 252 Authoritative zone transfers (PSEUDO-RR)MAILB 253 Used to get MB/MG/MR/MINFO records (obsolete)MAILA 254 Used to retrieve MD or MF records (obsolete)ANY 255 Return all record types (PSEUDO-RR)URI 256 Maps a hostname to a URICAA 257 Certificate Authority AuthorizationTA 32768 DNSSEC Trust AuthoritiesDLV 32769 DNSSEC Lookaside Validation record

The query class will almost always be asyncdns.IN. Possible values are:

Constant Value MeaningIN 1 InternetCH 3 ChaosHS 4 HesiodNONE 254ANY 255

__lt__(other)

2.1. Queries 7


__eq__(other)

__ne__(other)

__gt__(other)

__ge__(other)

__le__(other)

Query provides comparison and ordering operators.

__hash__()

Query is also hashable, so it can be used as a key in a dict or set.

__repr__()

Returns a debug representation.

2.2 Replies

Replies are represented by Reply objects, which hold the flags, RCODE, and three sets of returned RRs (answers,authorities and additional).

class Reply

flagsThe flags returned by the server. These are as follows:

Constant Value MeaningAA 0x0400 Authoritative AnswerTC 0x0200 Truncated ResponseRD 0x0100 Recursion DesiredRA 0x0080 Recursion AllowedZ 0x0040 ReservedAD 0x0020 Authentic Data (DNSSEC)CD 0x0010 Checking Disabled (DNSSEC)

rcodeThe RCODE returned by the server. Possible values are:

8 Chapter 2. Usage


Constant Value MeaningNOERROR 0 Successful queryFORMERR 1 Format failureSERVFAIL 2 Server failureNXDOMAIN 3 Non-existent domainNOTIMP 4 Not implementedREFUSED 5 Query refursedYXDOMAIN 6 Name exists when it should notYXRRSET 7 RR set exists when it should notNXRRSET 8 RR set that should exist does notNOTAUTH 9 Server not authoritative OR Not authorizedNOTZONE 10 Name not contained in zoneBADVERS 16 Bad OPT versionBADSIG 16 TSIG signature failureBADKEY 17 Key not recognizedBADTIME 18 Signature out of time windowBADMODE 19 Bad TKEY modeBADNAME 20 Duplicate key nameBADALG 21 Algorithm not supportedBADTRUNC 22 Bad truncationBADCOOKIE 23 Bad/missing server cookie

answersA list of rr.RR returned by the server in the Answers section of the reply.

authoritiesA list of rr.RR returned by the server in the Authorities section of the reply.

additionalA list of additional rr.RR returned by the server.

2.2.1 RRs

RRs are represented by subclasses of rr.RR; a handful of common RR types have special subclasses that decode theRDATA field in the DNS reply for you. If you are using some other type of RR, you can create your own subclass andregister it using rr.RR.register(), or you can just decode the data in your own code.

class rr.RR(name, rr_type, rr_class, ttl)The base class of all RRs. You won’t get a raw rr.RR in a Reply - RRs that we don’t understand are mappedto rr.Unknown.

nameThe associated domain name, in the form given in the DNS packet (a bytes).

unicode_nameThe associated domain name, after IDNA processing (a str)

rr_typeThe RR type (see query for a list).

rr_classThe RR class (see query for a list).

ttlThe remaining time to live for this RR, in seconds. Note that this field is only updated

2.2. Replies 9


register(rr_type, rr_class, pyclass)Register a subclass of rr.RR; when we decode a response from the DNS server, we will create an instanceof the specified class to represent RRs of the specified type and class.

Parameters

• rr_type (int) – The RR type to map.

• rr_class (int) – The RR class to map, or ANY if the mapping should operate for anyclass.

• pyclass – The Python class we should use for RRs of the specified type and class.

decode(name, rr_type, rr_class, ttl, packet, ptr, rdlen)Decode an RR from a DNS packet, returning a new rr.RR instance representing it. The implementationin rr.RR looks up the correct Python class and calls its decode() method; if it doesn’t find a classregistered for the RR type with which it’s presented, it will use rr.Unknown.

Parameters

• name (bytes) – The domain name.

• rr_type (int) – The RR type.

• rr_class (int) – The RR class.

• ttl (int) – The remaining time to live for this RR.

• packet (bytes) – The entire DNS response packet.

• ptr (int) – The current offset within the DNS packet.

• rdlen (int) – The length of the RR’s data, starting from ptr.

class rr.A(name, ttl, address)

addressThe IPv4 address (an ipaddress.IPv4Address).

class rr.AAAA(name, ttl, address)

addressThe IPv6 address (an ipaddress.IPv6Address).

class rr.CNAME(name, ttl, address)

cnameThe aliased name, in the form given in the DNS packet (a bytes).

unicode_cnameThe aliased name after IDNA processing (a str)

class rr.HINFO(name, ttl, cpu, os)

cpuThe CPU model (as a string).

osThe operating system (as a string).

10 Chapter 2. Usage


Note that the RFC does not specify the encoding of either string, so for maximum robustness we decode thedata as ISO Latin 1. In most cases we would expect the two fields to be ASCII; if they are not, each code pointin the resulting string with have the same value as the byte in the byte string.

class rr.MB(name, ttl, host)

hostThe host specified in the record.

unicode_hostThe host name after IDNA processing.

class rr.MF(name, ttl, host)

hostThe host specified in the record.

unicode_hostThe host name after IDNA processing.

class rr.MG(name, ttl, mailbox)

mailboxThe mailbox specified in the record.

unicode_mailboxThe mailbox name after IDNA processing.

class rr.MINFO(name, ttl, mailbox)

rmailbox

emailboxThe mailboxes specified in the record.

unicode_rmailbox

unicode_emailboxThe mailbox names after IDNA processing.

class rr.MR(name, ttl, mailbox)

mailboxThe mailbox specified in the record.

unicode_mailboxThe mailbox name after IDNA processing.

class rr.MX(name, ttl, preference, exchange)

preferenceThe mail exchanger priority from the DNS record.

exchangeThe mail exchanger hostname as found in the DNS packet.

unicode_exchangeThe mail exchanger hostname after IDNA processing.

2.2. Replies 11


class rr.NUL(name, ttl, data)

dataThe RDATA from the record.

class rr.NS(name, ttl, host)

hostThe hostname of the nameserver.

unicode_hostThe hostname of the nameserver after IDNA processing.

class rr.PTR(name, ttl, dname)

addressThe IPv4 or IPv6 address, decoded from name, or None if no address could be decoded.

dnameThe name pointed to by this record.

unicode_hostThe name poitned to by this record, after IDNA processing.

rr.SOA(name, ttl, mname, rname, serial, refresh, retry, expire,minimum)

mnameThe name of the primary mailserver for the zone.

unicode_mnameSame as above, but after IDNA processing.

rnameThe mailbox name of the person responsible for the zone.

unicode_rnameAs above, but after IDNA processing.

serialThe zone’s serial number; this is used to detect changes to a zone (it must be incremented every time azone is changed).

refreshThe number of seconds for which a secondary nameserver may assume the zone data has not changed -controls how often the secondary checks the zone serial number.

retryThe number of seconds a secondary should wait to retry a refresh if the primary nameserver is busy.

expireThe number of seconds a secondary nameserver can cache the data before it is no longer authoritative.

minimumThe minimum time to live for RRs in the zone.

class rr.TXT(name, ttl, text)

12 Chapter 2. Usage


textThe stored text. Since no encoding is specified, this is decoded as ISO Latin 1 (since that is the most robustoption).

class rr.WKS(name, ttl, address, protocol, bitmap)

addressThe IPv4 address for this record.

protocolThe IP protocol number for this record (typically 6, for TCP, or 17, for UDP).

bitmapA bytes holding the port bitmap.

class rr.Unknown(name, ttl, rr_type, rr_class, ttl, data)This subclass of rr.RR is used when we don’t know how to decode the RR found in the data packet.

dataThe RDATA from the record.

2.3 What are Resolvers?

In asyncdns, Resolvers are the objects that are responsible for taking Query objects and returning Reply objectscorresponding to those queries.

Resolvers don’t derive from a single base class, as some of them work quite differently to others. Instead, they allimplement the following two methods:

close()Cancel all in-progress lookups and shut down the resolver.

lookup(query)

Parameters query – The Query to process.

Retval An asyncio.Future that will complete with a Reply .

Resolvers are guaranteed to cancel lookups that are in progress when the resolver itself is destroyed. Active lookupsdo not keep a resolver alive.

Individual resolvers may support additional parameters for their lookup() method, but those parameters are gener-ally specific to the workings of the resolver in question.

2.3.1 Resolver

class ResolverThe core DNS resolver. This class holds all of the code to perform normal DNS queries, including recursiveresolution, and maintains its own request cache, so that repeatedly querying for the same record won’t result inunnecessary network traffic or delay.

lookup(query, servers=None, should_cache=True,recursive=False, prefer_ipv6=False, force_tcp=False)

Perform a DNS lookup.

Parameters

• query – The Query to resolve.

2.3. What are Resolvers? 13


• servers – See discussion below.

• should_cache – Setting this to False disables the Resolver cache.

• recursive – Whether to perform recursive lookups.

• prefer_ipv6 – When doing recursive lookup, prefer servers that talk over IPv6.

• force_tcp – Prevents the resolver from using UDP for queries that are short enough tofit.


The servers parameter can be:

• An (address, port) tuple.

• A list of (address, port) tuples, which will be used randomly.

• An iterable of some sort that yields (address, port) tuples. Note that if the iterable raises StopIteration,any in-progress queries will fail with the StopIteration exception.

• None, in which case the resolver will be recursive (regardless of the setting of the recursiveparameter) and will start with the global root servers. We recommend not using this feature unlessabsolutely necessary, as it puts additional load on the root servers and it’s usually better to talk to yourown nameserver or use one provided by your ISP or infrastructure platform.

asyncdns provides two useful iterables, RandomServer and RoundRobinServer, both of whichprovide an infinite stream of tuples given a list of server addresses.

flush_cache()Flushes the resolver’s cache.

2.3.2 HostsResolver

class HostsResolverResolves names using the contents of /etc/hosts (or, on Windows,\Windows\System32\drivers\etc\hosts).

lookup(query)

Parameters query – The Query to resolve.


This method only supports A, AAAA and PTR queries. In addition to names listed in /etc/hosts, itknows about the .in-addr.arpa and .ip6.arpa pseudo-zones.

The HostsResolver will automatically re-read /etc/hosts if it has changed, but only if the lasttime it was read was more than 30 seconds ago.

2.3.3 MulticastResolver

class MulticastResolverResolves queries using Multicast DNS (aka MDNS). You don’t need to have Apple’s mdnsResponder softwareinstalled to use this - it will work on any system that can run Python and that supports IP multicast.

lookup(query, use_ipv6=False, unicast_reply=False)

Parameters


14 Chapter 2. Usage


• use_ipv6 – Whether to multicast using IPv6 or not. The default is to use IPv4.

• unicast_reply – Whether to request that the reply be sent via unicast. This is intendedto reduce multicast traffic.


2.3.4 SystemResolver

SystemResolver is actually a “class cluster”, in that there are separate implementations for Darwin/Mac OSX/macOS, Windows, and generic UNIX/Linux. The idea of SystemResolver is that it works like Resolver,but uses the system configured nameservers (and will automatically update its list of nameservers should the systemconfiguration change).

There are some limitations here: the UNIX/Linux generic implementation works by reading /etc/resolv.conf,so any other configuration mechanism that might be in use will be ignored, while the Windows version uses WindowsAPIs that appear to be limited to returning IPv4 nameservers only. On Windows, there doesn’t seem to be a mechanismto spot changes to the configuration, so we re-read it at most once every 30 seconds; on UNIX/Linux, we watch thetimestamp on /etc/resolv.conf, again, at most once every 30 seconds. Some people have suggested usingres_ninit() on UNIX rather than directly reading /etc/resolv.conf; that’s certainly a possibility, but if /etc/resolv.conf isn’t being used to configure the nameservers, we’d end up in the same situation as on Windows,where we have no way to tell if the server settings have been updated.

class SystemResolver

lookup(query, servers=None, should_cache=True,recursive=False, prefer_ipv6=False, force_tcp=False)

Perform a DNS lookup.

Parameters


• should_cache – Setting this to False disables the Resolver cache.

• recursive – Whether to perform recursive lookups.

• prefer_ipv6 – When doing recursive lookup, prefer servers that talk over IPv6.

• force_tcp – Prevents the resolver from using UDP for queries that are short enough tofit.


2.3.5 SmartResolver

SmartResolver is a convenience class that accepts a query and determines which of the other resolvers to use toprocess it. Specifically:

• It first tries HostsResolver, which means the hosts file can override resolution the way people expect.

• If that fails and the query is for a name ending .local, it uses MulticastResolver.

• Otherwise, it uses SystemResolver.

N.B. Pay attention to the security implications of using MulticastResolver here; if you are using a serverplatform where multicast isn’t appropriately restricted, this could open up a security hole that causes you to send datato an attacker’s system instead of the one you wanted to.

2.3. What are Resolvers? 15


16 Chapter 2. Usage

CHAPTER 3

Indices and tables

• genindex

• modindex

• search

17


18 Chapter 3. Indices and tables

Index

Symbols__eq__() (Query method), 7__ge__() (Query method), 8__gt__() (Query method), 8__hash__() (Query method), 8__le__() (Query method), 8__lt__() (Query method), 7__ne__() (Query method), 8__repr__() (Query method), 8

Aadditional (Reply attribute), 9address (rr.A attribute), 10address (rr.AAAA attribute), 10address (rr.PTR attribute), 12address (rr.WKS attribute), 13answers (Reply attribute), 9authorities (Reply attribute), 9

Bbitmap (rr.WKS attribute), 13

Cclose() (built-in function), 13cname (rr.CNAME attribute), 10cpu (rr.HINFO attribute), 10

Ddata (rr.NUL attribute), 12data (rr.Unknown attribute), 13decode() (rr.RR method), 10dname (rr.PTR attribute), 12

Eemailbox (rr.MINFO attribute), 11exchange (rr.MX attribute), 11expire, 12

Fflags (Reply attribute), 8

Hhost (rr.MB attribute), 11host (rr.MF attribute), 11host (rr.NS attribute), 12HostsResolver (built-in class), 14

Llookup() (built-in function), 13lookup() (HostsResolver method), 14lookup() (MulticastResolver method), 14

Mmailbox (rr.MG attribute), 11mailbox (rr.MR attribute), 11minimum, 12mname, 12MulticastResolver (built-in class), 14

Nname (rr.RR attribute), 9

Oos (rr.HINFO attribute), 10

Ppreference (rr.MX attribute), 11protocol (rr.WKS attribute), 13

QQuery (built-in class), 5

Rrcode (Reply attribute), 8refresh, 12register() (rr.RR method), 9

19


Reply (built-in class), 8Resolver (built-in class), 13Resolver.flush_cache() (built-in function), 14retry, 12rmailbox (rr.MINFO attribute), 11rname, 12rr.A (built-in class), 10rr.AAAA (built-in class), 10rr.CNAME (built-in class), 10rr.HINFO (built-in class), 10rr.MB (built-in class), 11rr.MF (built-in class), 11rr.MG (built-in class), 11rr.MINFO (built-in class), 11rr.MR (built-in class), 11rr.MX (built-in class), 11rr.NS (built-in class), 12rr.NUL (built-in class), 11rr.PTR (built-in class), 12rr.RR (built-in class), 9rr.TXT (built-in class), 12rr.Unknown (built-in class), 13rr.WKS (built-in class), 13rr_class (rr.RR attribute), 9rr_type (rr.RR attribute), 9

Sserial, 12SystemResolver (built-in class), 15

Ttext (rr.TXT attribute), 12ttl (rr.RR attribute), 9

Uunicode_cname (rr.CNAME attribute), 10unicode_emailbox (rr.MINFO attribute), 11unicode_exchange (rr.MX attribute), 11unicode_host (rr.MB attribute), 11unicode_host (rr.MF attribute), 11unicode_host (rr.NS attribute), 12unicode_host (rr.PTR attribute), 12unicode_mailbox (rr.MG attribute), 11unicode_mailbox (rr.MR attribute), 11unicode_mname, 12unicode_name (rr.RR attribute), 9unicode_rmailbox (rr.MINFO attribute), 11unicode_rname, 12

20 Index

Release 0.1.2 Alastair Houghton

Documents

Transcript of Release 0.1.2 Alastair Houghton