domain/
lib.rs

1//! A DNS library for Rust.
2//!
3//! This crate provides a number of building blocks for developing
4//! functionality related to the [Domain Name System (DNS)][dns].
5//!
6//! [dns]: https://www.rfc-editor.org/rfc/rfc9499.html
7//!
8//! The crate uses feature flags to allow you to select only those modules
9//! you need for your particular project. In most cases, the feature names
10//! are equal to the module they enable.
11//!
12//! # Modules
13//!
14//! A set of modules providing fundamental types and functionality is always
15//! enabled:
16//!
17//! * [base] contains a wide variety of types, traits, and functionality
18//!   to deal with DNS data, and
19//! * [rdata] contains types and implementations for a growing number of
20//!   record types.
21//!
22//! The following additional modules exist, although they are gated behind
23//! feature flags (with the same names as the modules):
24//!
25#![cfg_attr(feature = "net", doc = "* [net]:")]
26#![cfg_attr(not(feature = "net"), doc = "* net:")]
27//!   Sending and receiving DNS messages.
28#![cfg_attr(feature = "resolv", doc = "* [resolv]:")]
29#![cfg_attr(not(feature = "resolv"), doc = "* resolv:")]
30//!   An asynchronous DNS resolver based on the
31//!   [Tokio](https://tokio.rs/) async runtime.
32#![cfg_attr(feature = "unstable-crypto", doc = "* [crypto]:")]
33#![cfg_attr(not(feature = "unstable-crypto"), doc = "* crypto:")]
34//!   Experimental support for cryptographic backends, key generation and
35//!   import.  Gated behind the `unstable-crypto` flag.
36//! * [dnssec]: DNSSEC signing and validation.
37#![cfg_attr(feature = "tsig", doc = "* [tsig]:")]
38#![cfg_attr(not(feature = "tsig"), doc = "* tsig:")]
39//!   Support for securing DNS transactions with TSIG records.
40#![cfg_attr(feature = "zonefile", doc = "* [zonefile]:")]
41#![cfg_attr(not(feature = "zonefile"), doc = "* zonefile:")]
42//!   Experimental reading and writing of zone files, i.e. the textual
43//!   representation of DNS data.
44#![cfg_attr(feature = "unstable-zonetree", doc = "* [zonetree]:")]
45#![cfg_attr(not(feature = "unstable-zonetree"), doc = "* zonetree:")]
46//!   Experimental storing and querying of zone trees.  Gated behind the
47//!   `unstable-zonetree` flag.
48//!
49//! Finally, the [dep] module contains re-exports of some important
50//! dependencies to help avoid issues with multiple versions of a crate.
51//!
52//! # The `new` Module
53//!
54//! The API of `domain` is undergoing several large-scale changes, that are
55//! collected under the `new` module.  It is gated behind the `unstable-new`
56//! flag.
57#![cfg_attr(
58    feature = "unstable-new",
59    doc = "See [its documentation][new] for more information."
60)]
61//!
62//! # Reference of feature flags
63//!
64//! Several feature flags simply enable support for other crates, e.g. by
65//! adding `impl`s for their types.  They are optional and do not introduce
66//! new functionality into this crate.
67//!
68//! * `bytes`: Enables using the types `Bytes` and `BytesMut` from the
69//!   [bytes](https://github.com/tokio-rs/bytes) crate as octet sequences.
70//!
71//! * `heapless`: enables the use of the `Vec` type from the
72//!   [heapless](https://github.com/japaric/heapless) crate as octet
73//!   sequences.
74//!
75//! * `smallvec`: enables the use of the `Smallvec` type from the
76//!   [smallvec](https://github.com/servo/rust-smallvec) crate as octet
77//!   sequences.
78//!
79//! Some flags enable support for specific kinds of operations that are not
80//! otherwise possible.  They are gated as they may not always be necessary
81//! and they may introduce new dependencies.
82//!
83//! * `chrono`: Adds the [chrono](https://github.com/chronotope/chrono)
84//!   crate as a dependency. This adds support for generating serial numbers
85//!   from time stamps.
86//!
87//! * `rand`: Enables a number of methods that rely on a random number
88//!   generator being available in the system.
89//!
90//! * `serde`: Enables serde serialization for a number of basic types.
91//!
92//! * `siphasher`: enables the dependency on the
93//!   [siphasher](https://github.com/jedisct1/rust-siphash) crate which allows
94//!   generating and checking hashes in [standard server
95//!   cookies][crate::base::opt::cookie::StandardServerCookie].
96//!
97//! * `std`: support for the Rust std library. This feature is enabled by
98//!   default.
99//!
100//! A special case here is cryptographic backends.  Certain modules (e.g. for
101//! DNSSEC signing and validation) require a backend to provide cryptography.
102//! At least one such module should be enabled.
103//!
104//! * `openssl`: Enables crypto functionality via OpenSSL through the
105//!   [rust-openssl](https://github.com/sfackler/rust-openssl) crate.
106//!
107//! * `ring`: Enables crypto functionality via the
108//!   [ring](https://github.com/briansmith/ring) crate.
109//!
110//! Some flags represent entire categories of functionality within this crate.
111//! Each flag is associated with a particular module.  Note that some of these
112//! modules are under heavy development, and so have unstable feature flags
113//! which are categorized separately.
114//!
115//! * `net`: Enables sending and receiving DNS messages via the
116#![cfg_attr(feature = "net", doc = "  [net]")]
117#![cfg_attr(not(feature = "net"), doc = "  net")]
118//!   module.
119//!
120//! * `resolv`: Enables the asynchronous stub resolver via the
121#![cfg_attr(feature = "resolv", doc = "  [resolv]")]
122#![cfg_attr(not(feature = "resolv"), doc = "  resolv")]
123//!   module.
124//!
125//!   * `resolv-sync`: Enables the synchronous version of the stub resolver.
126//!
127//! * `tsig`: support for signing and validating message exchanges via TSIG
128//!   signatures. This enables the
129#![cfg_attr(feature = "tsig", doc = "  [tsig]")]
130#![cfg_attr(not(feature = "tsig"), doc = "  tsig")]
131//!   module and currently enables `bytes`, `ring`, and `smallvec`.
132//!
133//! * `zonefile`: reading and writing of zonefiles. This feature enables the
134#![cfg_attr(feature = "zonefile", doc = "  [zonefile]")]
135#![cfg_attr(not(feature = "zonefile"), doc = "  zonefile")]
136//!   module and currently also enables `bytes`, `serde`, and `std`.
137//!
138//! # Unstable features
139//!
140//! When adding new functionality to the crate, practical experience is
141//! necessary to arrive at a good, user friendly design. Unstable features
142//! allow adding and rapidly changing new code without having to release
143//! versions allowing breaking changes all the time. If you use unstable
144//! features, it is best to specify a concrete version as a dependency in
145//! `Cargo.toml` using the `=` operator, e.g.:
146//!
147//! ```text
148//! [dependencies]
149//! domain = "=0.9.3"
150//! ```
151//!
152//! Currently, the following unstable features exist:
153//!
154//! * `unstable-client-transport`: sending and receiving DNS messages from
155//!   a client perspective; primarily the `net::client` module.
156//! * `unstable-server-transport`: receiving and sending DNS messages from
157//!   a server perspective; primarily the `net::server` module.
158//! * `unstable-crypto`: this feature flag needs to be combined with one or
159//!   more feature flags that enable cryptographic backends (currently `ring`
160//!   and `openssl`). This feature flags enables all parts of the crypto
161//!   module except for private key generation and signing.
162//! * `unstable-crypto-sign`: this feature flag needs to be combined with one
163//!   or more feature flags that enable cryptographic backends. This feature
164//!   flag enables all parts of the crypto module.
165//! * `unstable-sign`: basic DNSSEC signing support. This will enable the
166//!   `dnssec::sign`
167//!   module and requires the `std` feature. In order to actually perform any
168//!   signing, also enable one or more cryptographic backend modules (`ring`
169//!   and `openssl`). Enabling this will also enable `unstable-crypto-sign`.
170//! * `unstable-validator`: a DNSSEC validator, primarily the `validator`
171//!   and the `net::client::validator` modules.
172//! * `unstable-xfr`: zone transfer related functionality..
173//! * `unstable-zonetree`: building & querying zone trees; primarily the
174//!   `zonetree` module.
175//!
176//! Note: Some functionality is currently informally marked as
177//! “experimental” since it was introduced before adoption of the concept
178//! of unstable features. These will follow proper Semver practice but may
179//! change significantly in releases with breaking changes.
180
181#![no_std]
182#![allow(renamed_and_removed_lints)]
183#![allow(clippy::unknown_clippy_lints)]
184#![allow(clippy::uninlined_format_args)]
185#![cfg_attr(docsrs, feature(doc_cfg))]
186
187#[cfg(feature = "alloc")]
188extern crate alloc;
189
190#[cfg(feature = "std")]
191#[allow(unused_imports)] // Import macros even if unused.
192#[macro_use]
193extern crate std;
194
195// The 'domain-macros' crate introduces 'derive' macros which can be used by
196// users of the 'domain' crate, but also by the 'domain' crate itself.  Within
197// those macros, references to declarations in the 'domain' crate are written
198// as '::domain::*' ... but this doesn't work when those proc macros are used
199// in the 'domain' crate itself.  The alias introduced here fixes this: now
200// '::domain' means the same thing within this crate as in dependents of it.
201extern crate self as domain;
202
203// Re-export 'core' for use in macros.
204#[doc(hidden)]
205pub use core as __core;
206
207pub mod base;
208pub mod crypto;
209pub mod dep;
210pub mod dnssec;
211pub mod net;
212pub mod rdata;
213pub mod resolv;
214pub mod stelline;
215pub mod tsig;
216pub mod utils;
217pub mod zonefile;
218pub mod zonetree;
219
220#[cfg(feature = "unstable-new")]
221pub mod new;
222
223mod logging;