Crate domain

A DNS library for Rust.

This crate provides a number of building blocks for developing functionality related to the Domain Name System (DNS).

The crate uses feature flags to allow you to select only those modules you need for your 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.

The following additional modules exist, although they are gated behind feature flags (with the same names as the modules):

• net: Sending and receiving DNS messages.
• resolv: An asynchronous DNS resolver based on the Tokio async runtime.
• crypto: Experimental support for cryptographic backends, key generation and import. Gated behind the unstable-crypto flag.
• dnssec: DNSSEC signing and validation.
• tsig: Support for securing DNS transactions with TSIG records.
• zonefile: Experimental reading and writing of zone files, i.e. the textual representation of DNS data.
• zonetree: Experimental storing and querying of zone trees. Gated behind the unstable-zonetree flag.

Finally, the dep module contains re-exports of some important dependencies to help avoid issues with multiple versions of a crate.

The new Module

The API of domain is undergoing several large-scale changes, that are collected under the new module. It is gated behind the unstable-new flag. See its documentation for more information.

Reference of feature flags

Several feature flags simply enable support for other crates, e.g. by adding impls for their types. They are optional and do not introduce new functionality into this crate.

• bytes: Enables using the types Bytes and BytesMut from the bytes crate as octet sequences.

• heapless: enables the use of the Vec type from the heapless crate as octet sequences.

• smallvec: enables the use of the Smallvec type from the smallvec crate as octet sequences.

Some flags enable support for specific kinds of operations that are not otherwise possible. They are gated as they may not always be necessary and they may introduce new dependencies.

• chrono: Adds the chrono crate as a dependency. This adds support for generating serial numbers from time stamps.

• rand: Enables a number of methods that rely on a random number generator being available in the system.

• serde: Enables serde serialization for a number of basic types.

• siphasher: enables the dependency on the siphasher crate which allows generating and checking hashes in standard server cookies.

• std: support for the Rust std library. This feature is enabled by default.

A special case here is cryptographic backends. Certain modules (e.g. for DNSSEC signing and validation) require a backend to provide cryptography. At least one such module should be enabled.

• openssl: Enables crypto functionality via OpenSSL through the rust-openssl crate.

• ring: Enables crypto functionality via the ring crate.

Some flags represent entire categories of functionality within this crate. Each flag is associated with a particular module. Note that some of these modules are under heavy development, and so have unstable feature flags which are categorized separately.

• net: Enables sending and receiving DNS messages via the net module.

• resolv: Enables the asynchronous stub resolver via the resolv module.

  • resolv-sync: Enables the synchronous version of the stub resolver.

• tsig: support for signing and validating message exchanges via TSIG signatures. This enables the tsig module and currently enables bytes, ring, and smallvec.

• zonefile: reading and writing of zonefiles. This feature enables the zonefile module and currently also enables bytes, serde, and std.

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 the net::client module.
• unstable-server-transport: receiving and sending DNS messages from a server perspective; primarily the net::server module.
• unstable-crypto: this feature flag needs to be combined with one or more feature flags that enable cryptographic backends (currently ring and openssl). This feature flags enables all parts of the crypto module except for private key generation and signing.
• unstable-crypto-sign: this feature flag needs to be combined with one or more feature flags that enable cryptographic backends. This feature flag enables all parts of the crypto module.
• unstable-sign: basic DNSSEC signing support. This will enable the dnssec::sign module and requires the std feature. In order to actually perform any signing, also enable one or more cryptographic backend modules (ring and openssl). Enabling this will also enable unstable-crypto-sign.
• unstable-validator: a DNSSEC validator, primarily the validator and the net::client::validator modules.
• unstable-xfr: zone transfer related functionality..
• unstable-zonetree: building & querying zone trees; primarily the zonetree 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

base

Handling of DNS data.

crypto

Cryptographic backends, key generation and import.

dep

Re-exports of dependencies

dnssec

DNSSEC signing and validation

netnet

Sending and receiving DNS messages.

new

A new API for domain.

rdata

Record Data of Well-defined Record Types

resolvresolv

Asynchronous DNS resolving.

stelline

Stelline

tsigtsig

Support for TSIG.

utils

Various utility modules.

zonefilezonefile

Experimental reading and writing of zonefiles.

zonetreeunstable-zonetree

Experimental storing and querying of zones and zone trees.