domain/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
//! A DNS library for Rust.
//!
//! This crates provides a number of building blocks for developing
//! functionality related to the
//! [Domain Name System (DNS)](https://www.rfc-editor.org/rfc/rfc9499.html).
//! 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:
//!
#![cfg_attr(feature = "net", doc = "* [net]:")]
#![cfg_attr(not(feature = "net"), doc = "* net:")]
//!   Sending and receiving DNS messages.
#![cfg_attr(feature = "resolv", doc = "* [resolv]:")]
#![cfg_attr(not(feature = "resolv"), doc = "* resolv:")]
//!   An asynchronous DNS resolver based on the
//!   [Tokio](https://tokio.rs/) async runtime.
#![cfg_attr(feature = "sign", doc = "* [sign]:")]
#![cfg_attr(not(feature = "sign"), doc = "* sign:")]
//!   Experimental support for DNSSEC signing.
#![cfg_attr(feature = "tsig", doc = "* [tsig]:")]
#![cfg_attr(not(feature = "tsig"), doc = "* tsig:")]
//!   Support for securing DNS transactions with TSIG records.
#![cfg_attr(feature = "validate", doc = "* [validate]:")]
#![cfg_attr(not(feature = "validate"), doc = "* validate:")]
//!   Experimental support for DNSSEC validation.
#![cfg_attr(feature = "unstable-validator", doc = "* [validator]:")]
#![cfg_attr(not(feature = "unstable-validator"), doc = "* validator:")]
//!   A DNSSEC validator.
#![cfg_attr(feature = "zonefile", doc = "* [zonefile]:")]
#![cfg_attr(not(feature = "zonefile"), doc = "* zonefile:")]
//!   Experimental reading and writing of zone files, i.e. the textual
//!   representation of DNS data.
#![cfg_attr(feature = "unstable-zonetree", doc = "* [zonetree]:")]
#![cfg_attr(not(feature = "unstable-zonetree"), doc = "* 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 types `Bytes` and `BytesMut` from the
//!   [bytes](https://github.com/tokio-rs/bytes) crate as octet sequences.
//! * `chrono`: Adds the [chrono](https://github.com/chronotope/chrono)
//!   crate as a dependency. This adds support for generating serial numbers
//!   from time stamps.
//! * `heapless`: enables the use of the `Vec` type from the
//!   [heapless](https://github.com/japaric/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
#![cfg_attr(feature = "resolv", doc = "  [resolv]")]
#![cfg_attr(not(feature = "resolv"), doc = "  resolv")]
//!   module.
//! * `resolv-sync`: Enables the synchronous version of the stub resolver.
//! * `ring`: Enables crypto functionality via the
//!   [ring](https://github.com/briansmith/ring) crate.
//! * `serde`: Enables serde serialization for a number of basic types.
//! * `sign`: basic DNSSEC signing support. This will enable the
#![cfg_attr(feature = "sign", doc = "  [sign]")]
#![cfg_attr(not(feature = "sign"), doc = "  sign")]
//!   module and requires the `std` 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 the `ring`
//!   module, but support for OpenSSL is coming soon.
//! * `siphasher`: enables the dependency on the
//!   [siphasher](https://github.com/jedisct1/rust-siphash) crate which allows
//!   generating and checking hashes in [standard server
//!   cookies][crate::base::opt::cookie::StandardServerCookie].
//! * `smallvec`: enables the use of the `Smallvec` type from the
//!   [smallvec](https://github.com/servo/rust-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
#![cfg_attr(feature = "tsig", doc = "  [tsig]")]
#![cfg_attr(not(feature = "tsig"), doc = "  tsig")]
//!   module and currently pulls in the
//!   `bytes`, `ring`, and `smallvec` features.
//! * `validate`: basic DNSSEC validation support. This feature enables the
#![cfg_attr(feature = "validate", doc = "  [validate]")]
#![cfg_attr(not(feature = "validate"), doc = "  validate")]
//!   module and currently also enables the `std` and `ring`
//!   features.
//! * `zonefile`: reading and writing of zonefiles. This feature enables the
#![cfg_attr(feature = "zonefile", doc = "  [zonefile]")]
#![cfg_attr(not(feature = "zonefile"), doc = "  zonefile")]
//!   module and currently also enables the `bytes` and `std` 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.:
//!
//! ```text
//! [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-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.

#![no_std]
#![allow(renamed_and_removed_lints)]
#![allow(clippy::unknown_clippy_lints)]
#![allow(clippy::uninlined_format_args)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(feature = "std")]
#[allow(unused_imports)] // Import macros even if unused.
#[macro_use]
extern crate std;

#[macro_use]
extern crate core;

pub mod base;
pub mod dep;
pub mod net;
pub mod rdata;
pub mod resolv;
pub mod sign;
pub mod stelline;
pub mod tsig;
pub mod utils;
pub mod validate;
pub mod validator;
pub mod zonefile;
pub mod zonetree;