Repository files navigation

This project's home page and main repository is located athttp://25thandClement.com/~william/projects/dns.c.html.

But feel free to rely on Github for tracking the source tree.

A non-blocking DNS resolver library in a single .c file.

• No dependencies!

• Supportsboth stub and recursive modes.

• No event callbacks! Callbacks are usually inevitable when writingnon-blocking network software, but when too many libraries introduce toomany callback interfaces code quickly becomes incomprehensible beyondnecessity. dns.c requires no particular callback scheme, nor enforcescallbacks at all. That makes it easy to use and embed within othercomponents.

• Works with any event loop. All resolver objects support three commonmethods: pollfd, events, and timeout.

• Core DNS API built around actual DNS packet; as generic as DNS itself.This makes querying and manipulating records other than A, AAAA, and PTRmuch easier, yet with similar simplicity as API's which make annoyingassumptions.

• Type-specific interfaces for A, AAAA, CNAME, NS, SOA, PTR, MX, TXT, SRV,SSHFP, and SPF records.

• Restartable record iterators with user-specified sorting. Iterate over MXor SRV records in semantic order (i.e. preference and priority) using asingle dns_rr_foreach loop. Interruptible loops supported withdns_rr_grep.

• Thoughtful /etc/resolv.conf, /etc/nsswitch.conf, and /etc/hostsintegration. Easy to change system defaults, or to skip entirely.

• getaddrinfo-like auxiliary interface.

• Pluggable cache interface. Application can specify a synchronous orasynchronous local cache for use by the core resolver.

• "Smart" queries which automatically dereference NS, MX, SRV, PTR, etc. toA or AAAA records. Recursing, caching nameservers don't usually do thisexplicitly, but merely rely on the authoritative server to include glue,which won't exist for out-of-bailiwick references (very common thesedays). This means software must do two separate logical DNS operations; aheadache when patching software which only supported A lookups. Smartqueries are available with a flag to the core resolver-—in both stub andrecursive modes—-and more efficiently with the built-in getaddrinfo-likeauxiliary interface.

• Randomized source ports and encrypted QIDs using a 16-bit Feistel blockcipher. User specifiable entropy source. Defaults to arc4random whereavailable; knows how to use OpenSSL RAND_bytes if specified during thebuild (-DDNS_RANDOM=RAND_bytes).

• Statistics interface. Retrieve count of packets and bytes, sent andreceived; and number of queries processed.

• Used successfully by many projects for many years, including severalSilicon Valley giants.

• Regularly testing on Linux, OS X, OpenBSD, FreeBSD, NetBSD, and Solaris.Occassionally tested in MinGW environment. Builds with GCC, Clang, andSunPro.

Asynchronous SPF resolver--no threading, no forking, no callbacks, nolibrary dependencies.

• A single source file. Requires Ragel precompiler, but no run-timedependencies other than dns.c. The Ragel translation can be done onceand the result stored if you don't plan on hacking spf.c.
• Passes over 90% of OpenSPF test suite. 100% test suite compliance is notthe goal, as some tests are fairly debatable. (The SPF specification has some bugs.)
• Used successfully in countless MTA installations and for billions (trillions?)of queries.

dns.c is intended to be dropped into existing project builds. The includedMakefile is mostly for development and testing.

Until the API is properly documented you must rely on the source code. Theheader, dns.h, and the API is fairly straight-forward, with each objectimplementating a simple, consistent, and hopefully self-explanatory pattern.

The last 1/6 of dns.c implements a command-line utility and a full regressiontesting suite permitting each component to be tested individually. This isexcellent usage documentation as well.

Copyright (c) 2008-2015 William Ahernwilliam@25thandClement.com

Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), todeal in the Software without restriction, including without limitation therights to use, copy, modify, merge, publish, distribute, sublicense, and/orsell copies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included inall copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISINGFROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGSIN THE SOFTWARE.