Module domain_core::bits

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. Tools for processing the textual master format representation of DNS data are not part of this module but can be found in master.

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. Such types, all the way up to complete DNS messages, use the bytes::Bytes type for holding the actual octets. Values of this type provide a good compromise between the convenience of owned values and the performance gained by using slices wherever possible. (The prize for the latter would be excessive use of generic types and, worse yet, lifetime arguments all over the place.)

In order to distinguish between the various possible representations of a sequence of bytes, the module attempts to use a consistent terminology. The term ‘bytes’ will always mean a Bytes value; a slice or byte slice is always a reference to a slice of u8; and a vec is always a Vec<u8>. Thus a method as_bytes on a type would return a Bytes reference of the types raw content, while as_slice will provide access to the even more raw [u8] of it.

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 reasonably good choice given the limited size of DNS messages and the complexities introduced by to compress domain names in message by referencing other parts of the message. The details are explained in the parse and compose sub-modules. 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,
• rdata for infrastructure around record data; the actual implementations of the various record types are in the top-level rdata module, and
• record for DNS resource records.

The main types from each module are being reimported here.

Re-exports

pub use self::charstr::CharStr;

pub use self::charstr::CharStrMut;

pub use self::compose::Compose;

pub use self::compose::Compress;

pub use self::compose::Compressor;

pub use self::header::Header;

pub use self::header::HeaderCounts;

pub use self::header::HeaderSection;

pub use self::message::Message;

pub use self::message::RecordSection;

pub use self::message::Section;

pub use self::message_builder::MessageBuilder;

pub use self::message_builder::SectionBuilder;

pub use self::message_builder::RecordSectionBuilder;

pub use self::parse::Parser;

pub use self::parse::Parse;

pub use self::parse::ParseAll;

pub use self::parse::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::Record;

pub use self::record::RecordHeader;

pub use self::record::ParsedRecord;

Modules

charstr	Character strings.
compose	Assembling wire-format DNS data.
header	The header of a DNS message.
message	Accessing exisiting DNS messages.
message_builder	Building a new DNS message.
name	Domain names.
opt	Record data for OPT records.
parse	Parsing DNS wire-format data.
query	Message handling for queries.
question	A single question in a DNS message.
rdata	Resource record data handling.
record	Resource Records.
serial	Serial numbers.

Structs

Dname	An uncompressed, absolute domain name.
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.