Module domain::base

Handling of DNS data.

This module provides types and traits for working with DNS data. The types allow creating such data from scratch and processing it. Crucially, the module provides means to extract the data from wire-format DNS messages and assemble such messages.

Representation of Variable-length Data and DNS Messages

Various types have to deal with data of variable length. For instance, a domain name can be anywhere between one and 255 bytes long. Since there is no single best type to deal with such data – slices, vecs, or even byte arrays may all be prefered in certain cases –, the crate uses a set of traits to be able to be generic over bytes sequences. We call types that provide these traits ‘octet sequences’ or simple ‘octets.’

Different traits exist for octet references, owned octets, and octet builder, that is types that allow constructing an octet stequence from indidivual bytes or slice. The octets module contains all traits and trait implementations. It also contains a detailed descriptions of the traits, their purpose, and how it all fits together.

Parsing and Composing Messages

In order to easily distinguish the process of creating and disecting wire-format messages other forms of representation conversion such as reading from a master file, we use the term parsing for extracting data from a wire-format representation and composing for producing such a representation.

Both parsing and composing happen on buffers holding a complete DNS message. This seems to be a reasonable choice given the limited size of DNS messages and the complexities introduced by compressing domain names in message by referencing other parts of the message. The fundamental types for parsing and composing are also part of the octets module. But unless you are implementing your own resource record types, you are unlikely to ever having to deal with parsing and composing directly.

Instead, the types Message and MessageBuilder are there to make parsing and constructing DNS messages easy. A Message takes the binary data of a DNS message and allows iterating over its four sections to look at the questions and resource records. Similarly, a MessageBuilder takes a bytes vector (or creates one for you) and has functionality to build the sections of the message step-by-step.

Types for DNS Data

The module contains a number of types for DNS data, both fundamental and composed. Because they often come with a number of support types, they are arranged in submodules. You will find detailed explanations for all of them in their module. These are:

• charstr for DNS character strings,
• header for the header of DNS messages,
• name for domain names,
• opt for the record data of OPT records used in EDNS,
• question for questions,
• serial for serial numbers of zones, and
• record for DNS resource records including record data,
• rdata for all the individual record types.

Master File Processing

Handling for the text format for DNS data, sometimes called master files or zone files is available via the master module. See there for more information.

Support for no_std

The crate is capable of operating without the std crate. Obviously, the set of features is somewhat limited. Specifically, most owned octet sequence types require an allocator. The octets module thus defines a set of types atop fixed size byte arrays that can be kept on the stack. Additional types can be created via the octets_array macro.

Use of the std crate is selected via the std feature. This is part of the default set, so you will have to disable the default features.

Re-exports

pub use self::charstr::CharStr;

pub use self::cmp::CanonicalOrd;

pub use self::header::Header;

pub use self::header::HeaderCounts;

pub use self::header::HeaderSection;

pub use self::iana::Rtype;

pub use self::message::Message;

pub use self::message::QuestionSection;

pub use self::message::RecordSection;

pub use self::message_builder::TreeCompressor;

pub use self::message_builder::MessageBuilder;

pub use self::message_builder::RecordSectionBuilder;

pub use self::message_builder::StaticCompressor;

pub use self::message_builder::StreamTarget;

pub use self::octets::OctetsVec;

pub use self::octets::Compose;

pub use self::octets::Parser;

pub use self::octets::ShortBuf;

pub use self::question::Question;

pub use self::rdata::ParseRecordData;

pub use self::rdata::RecordData;

pub use self::rdata::UnknownRecordData;

pub use self::record::ParsedRecord;

pub use self::record::Record;

pub use self::record::RecordHeader;

pub use self::serial::Serial;

Modules

charstr	Character strings.
cmp	Additional traits for comparisions.
header	The header of a DNS message.
iana	IANA Definitions for DNS.
message	Accessing existing DNS messages.
message_builder	Building a new DNS message.
name	Domain names.
net	Networking-related types not available in core.
octets	Variable length octet sequences.
opt	Record data for OPT records.
question	A single question in a DNS message.
rdata	Resource record data.
record	Resource Records.
serial	Serial numbers.
str	Support for converting from and to strings.

Structs

Dname	An uncompressed, absolute domain name.
DnameBuilder	Builds a domain name step by step by appending data.
ParsedDname	A domain name parsed from a DNS message.
RelativeDname	An uncompressed, relative domain name.

Traits

ToDname	A type that represents an absolute domain name.
ToRelativeDname	A type that represents a relative domain name.