Expand description
A DNS library for Rust.
This crates provides a number of building blocks for developing functionality related to the Domain Name System (DNS). It provides fundamental types, traits, and code as well as a wide range of optional features. The intent is to eventually cover all aspects of modern DNS.
The crate uses feature flags to allow you to select only those modules you need for you particular project. In most cases, the feature names are equal to the module they enable.
§Modules
A set of modules providing fundamental types and functionality is always enabled:
- base contains a wide variety of types, traits, and functionality to deal with DNS data, and
- rdata contains types and implementations for a growing number of record types.
In addition to those two basic modules, there are a number of modules for more specific features that are not required in all applications. In order to keep the amount of code to be compiled and the number of dependencies small, these are hidden behind feature flags through which they can be enabled if required. The flags have the same names as the modules.
Currently, there are the following modules:
- net: Sending and receiving DNS messages.
- resolv: An asynchronous DNS resolver based on the Tokio async runtime.
- sign: Experimental support for DNSSEC signing.
- tsig: Support for securing DNS transactions with TSIG records.
- validate: Experimental support for DNSSEC validation.
- validator: A DNSSEC validator.
- zonefile: Experimental reading and writing of zone files, i.e. the textual representation of DNS data.
- zonetree: Experimental storing and querying of zone trees.
Finally, the dep module contains re-exports of some important dependencies to help avoid issues with multiple versions of a crate.
§Reference of feature flags
The following is the complete list of the feature flags with the exception of unstable features which are described below.
bytes
: Enables using the typesBytes
andBytesMut
from the bytes crate as octet sequences.chrono
: Adds the chrono crate as a dependency. This adds support for generating serial numbers from time stamps.heapless
: enables the use of theVec
type from the heapless crate as octet sequences.interop
: Activate interoperability tests that rely on other software to be installed in the system (currently NSD and dig) and will fail if it isn’t. This feature is not meaningful for users of the crate.rand
: Enables a number of methods that rely on a random number generator being available in the system.resolv
: Enables the asynchronous stub resolver via the resolv module.resolv-sync
: Enables the synchronous version of the stub resolver.ring
: Enables crypto functionality via the ring crate.serde
: Enables serde serialization for a number of basic types.sign
: basic DNSSEC signing support. This will enable the sign module and requires thestd
feature. Note that this will not directly enable actual signing. For that you will also need to pick a crypto module via an additional feature. Currently we only support thering
module, but support for OpenSSL is coming soon.siphasher
: enables the dependency on the siphasher crate which allows generating and checking hashes in standard server cookies.smallvec
: enables the use of theSmallvec
type from the smallvec crate as octet sequences.std
: support for the Rust std library. This feature is enabled by default.tsig
: support for signing and validating message exchanges via TSIG signatures. This enables the tsig module and currently pulls in thebytes
,ring
, andsmallvec
features.validate
: basic DNSSEC validation support. This feature enables the validate module and currently also enables thestd
andring
features.zonefile
: reading and writing of zonefiles. This feature enables the zonefile module and currently also enables thebytes
andstd
features.
§Unstable features
When adding new functionality to the crate, practical experience is
necessary to arrive at a good, user friendly design. Unstable features
allow adding and rapidly changing new code without having to release
versions allowing breaking changes all the time. If you use unstable
features, it is best to specify a concrete version as a dependency in
Cargo.toml
using the =
operator, e.g.:
[dependencies]
domain = "=0.9.3"
Currently, the following unstable features exist:
unstable-client-transport
: sending and receiving DNS messages from a client perspective; primarily thenet::client
module.unstable-server-transport
: receiving and sending DNS messages from a server perspective; primarily thenet::server
module.unstable-validator
: a DNSSEC validator, primarily thevalidator
and thenet::client::validator
modules.unstable-xfr
: zone transfer related functionality..unstable-zonetree
: building & querying zone trees; primarily thezonetree
module.
Note: Some functionality is currently informally marked as “experimental” since it was introduced before adoption of the concept of unstable features. These will follow proper Semver practice but may change significantly in releases with breaking changes.
Modules§
- Handling of DNS data.
- Re-exports of dependencies
- net
net
Sending and receiving DNS messages. - Record Data of Well-defined Record Types
- resolv
resolv
Asynchronous DNS resolving. - sign
sign
DNSSEC signing. - tsig
tsig
Support for TSIG. - Various utility modules.
- validate
validate
DNSSEC validation. - This module provides a DNSSEC validator as described in RFCs 4033, 4034, 4035, 5155, and 6840. DNSSEC validation requires a trust anchor. A trust anchor can be created using anchor::TrustAnchors. The trust anchor is then used, together with a net::client transport and optionally a context::Config to create a DNSSEC validation context::ValidationContext. The validation context provides the method validate_msg() to validate a reply message.
- zonefile
zonefile
Experimental reading and writing of zonefiles. - zonetree
unstable-zonetree
Experimental storing and querying of zones and zone trees.