domain 0.12.0

A DNS library for Rust.
Documentation 
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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

//! Domain names.
//!
//! Domain names are a core concept of DNS. The whole system is essentially
//! just a mapping from domain names to arbitrary information. This module
//! provides types and essential functionality for working with them.
//!
//! A domain name is a sequence of labels, separated by ASCII periods (`.`).
//! For example, `example.org.` contains three labels: `example`, `org`, and
//! `` (the root label). Outside DNS-specific code, the root label (and its
//! separator) are almost always omitted, but keep them in mind here.
//!
//! Domain names form a hierarchy, where `b.a` is the "parent" of `.c.b.a`.
//! The owner of `example.org` is thus responsible for _every_ domain ending
//! with the `.example.org` suffix. The reverse order in which this hierarchy
//! is expressed can sometimes be confusing.
//!
//! ## Domain Name Types
//!
//! There are several different types that can be used to represent domain
//! names. Each one is appropriate for certain situations and less useful for
//! others. Most of `domain`'s high-level APIs will hard-code domain name
//! types to the right options.
//!
//! - [`Name`] is the standard domain name type. As is common in DNS
//!   implementations, it stores labels in the wire format from innermost to
//!   outermost (i.e. `example, org` for `example.org.`). It is the right
//!   type to use in DNS record data.
//!
//! - [`RevName`] is similar to [`Name`], except that labels are stored in
//!   _reverse_ order, from outermost to innermost (i.e. `org, example` in
//!   `example.org.`). It is the right type to use as the owner name of a
//!   DNS record ([`Record.rname`]).
//!
//! These types are _dynamically sized_; this means that they cannot be used
//! by value. The following table illustrates the various container and
//! pointer types that can be used around them, and the situations they are
//! most appropriate for.
//!
//! | Type | Ownership | Decompression | Intended Usage |
//! |----------------|-----|-----|----------------------------|
//! | `&'a Name`     | No  | No  | Whenever possible
//! | `Box<Name>`    | Yes | Yes | Compact, long-term storage
//! | `NameBuf`      | Yes | Yes | Efficient short-term usage
//! | `Box<RevName>` | Yes | Yes | Compact, long-term storage
//! | `RevNameBuf`   | Yes | Yes | Efficient short-term usage

use core::cmp::Ordering;

use super::wire::{BuildBytes, TruncationError};

//--- Submodules

mod label;
pub use label::{Label, LabelBuf, LabelIter, LabelParseError};

mod absolute;
pub use absolute::{Name, NameBuf, NameParseError};

mod reversed;
pub use reversed::{RevName, RevNameBuf};

mod unparsed;
pub use unparsed::UnparsedName;

mod compressor;
pub use compressor::NameCompressor;

//----------- CanonicalName --------------------------------------------------

/// DNSSEC-conformant operations for domain names.
///
/// As specified by [RFC 4034, section 6], domain names are used in two
/// different ways: they can be serialized into byte sequences or compared.
///
/// - In record data, they are serialized following the regular wire format
///   (specifically without name compression). However, in some record data
///   types, labels are converted to lowercase for serialization.
///
/// - In record owner names, they are compared from the root label outwards,
///   with the contents of each label being compared case-insensitively.
///
/// - In record data, they are compared as serialized byte sequences. As
///   explained above, there are two different valid serializations (i.e. the
///   labels may be lowercased, or the original case may be retained).
///
/// [RFC 4034, section 6]: https://datatracker.ietf.org/doc/html/rfc4034#section-6
///
/// If a domain name type implements [`CanonicalName`], then [`BuildBytes`]
/// will serialize the name in the wire format (without changing the case of
/// its labels). [`Ord`] will compare domain names as if they were the owner
/// names of records (i.e. not as if they were serialized byte sequences).
pub trait CanonicalName: BuildBytes + Ord {
    /// Serialize a domain name with lowercased labels.
    ///
    /// This is subtly different from [`BuildBytes`]; it requires all the
    /// characters in the domain name to be lowercased. It is implemented
    /// automatically, but it could be overriden for performance.
    fn build_lowercased_bytes<'b>(
        &self,
        bytes: &'b mut [u8],
    ) -> Result<&'b mut [u8], TruncationError> {
        // Build the bytes as usual.
        let rest = self.build_bytes(bytes)?.len();

        // Find the built bytes and lowercase them.
        let (bytes, rest) = bytes.split_at_mut(rest);
        bytes.make_ascii_lowercase();

        Ok(rest)
    }

    /// Compare domain names as if they were in the wire format.
    ///
    /// This is equivalent to serializing both domain names in the wire format
    /// using [`BuildBytes`] and comparing the resulting byte sequences.
    /// It is implemented automatically, but it could be overriden for
    /// performance.
    fn cmp_composed(&self, other: &Self) -> Ordering {
        // Build both names into byte arrays.

        let mut this = [0u8; 255];
        let rest_len = self
            .build_bytes(&mut this)
            .expect("domain names are at most 255 bytes when serialized")
            .len();
        let this = &this[..this.len() - rest_len];

        let mut that = [0u8; 255];
        let rest_len = other
            .build_bytes(&mut that)
            .expect("domain names are at most 255 bytes when serialized")
            .len();
        let that = &that[..that.len() - rest_len];

        // Compare the byte sequences.
        this.cmp(that)
    }

    /// Compare domain names as if they were in the wire format, lowercased.
    ///
    /// This is equivalent to serializing both domain names in the wire format
    /// using [`build_lowercased_bytes()`] and comparing the resulting byte
    /// sequences. It is implemented automatically, but it could be overriden
    /// for performance.
    ///
    /// [`build_lowercased_bytes()`]: Self::build_lowercased_bytes()
    fn cmp_lowercase_composed(&self, other: &Self) -> Ordering {
        // Build both names into byte arrays.

        let mut this = [0u8; 255];
        let rest_len = self
            .build_lowercased_bytes(&mut this)
            .expect("domain names are at most 255 bytes when serialized")
            .len();
        let this = &this[..this.len() - rest_len];

        let mut that = [0u8; 255];
        let rest_len = other
            .build_lowercased_bytes(&mut that)
            .expect("domain names are at most 255 bytes when serialized")
            .len();
        let that = &that[..that.len() - rest_len];

        // Compare the byte sequences.
        this.cmp(that)
    }
}

/// Implement [`CanonicalName`] for a [`Deref`]-based generic container.
macro_rules! impl_canonical_name_for_deref {
    {$(
        $(#[$attr:meta])*
        impl[$($args:tt)*] CanonicalName for $subject:ty;
    )*} => {$(
        $(#[$attr])*
        impl<$($args)*> CanonicalName for $subject {
            fn build_lowercased_bytes<'b>(
                &self,
                bytes: &'b mut [u8],
            ) -> Result<&'b mut [u8], TruncationError> {
                (**self).build_lowercased_bytes(bytes)
            }

            fn cmp_composed(&self, other: &Self) -> Ordering {
                (**self).cmp_composed(&**other)
            }

            fn cmp_lowercase_composed(&self, other: &Self) -> Ordering {
                (**self).cmp_lowercase_composed(&**other)
            }
        }
    )*};
}

impl_canonical_name_for_deref! {
    impl[N: ?Sized + CanonicalName] CanonicalName for &N;
    impl[N: ?Sized + CanonicalName] CanonicalName for &mut N;

    #[cfg(feature = "alloc")]
    impl[N: ?Sized + CanonicalName] CanonicalName for alloc::boxed::Box<N>;
    #[cfg(feature = "alloc")]
    impl[N: ?Sized + CanonicalName] CanonicalName for alloc::rc::Rc<N>;
    #[cfg(feature = "alloc")]
    impl[N: ?Sized + CanonicalName] CanonicalName for alloc::sync::Arc<N>;
}