Crate hickory_client

Hickory DNS is intended to be a fully compliant domain name server and client library.

The Client library is responsible for the basic protocols responsible for communicating with DNS servers (authorities) and resolvers. It can be used for managing DNS records through the use of update operations. It is possible to send raw DNS Messages with the Client, but for ease of use the query and various other update operations are recommended for general use.

For a system-like resolver, see hickory-resolver. This is most likely what you want if all you want to do is lookup IP addresses.

For serving DNS serving, see hickory-server.

Goals

• Only safe Rust
• All errors handled
• Simple to manage servers
• High level abstraction for clients
• Secure dynamic update
• New features for securing public information

Usage

This shows basic usage of the SyncClient. More examples will be associated directly with other types.

Dependency

[dependencies]
hickory-client = "*"

By default DNSSEC validation is built in with OpenSSL, this can be disabled with:

[dependencies]
hickory-client = { version = "*", default-features = false }

Objects

There are two variations of implementations of the client: the client::Client, an async client usually used with the Tokio runtime and the client::DnssecClient, which validates DNSSEC records. For these basic examples we’ll only look at the Client.

First we must decide on the type of connection. For the purpose of this example, we’ll show how to set up a TCP-based connection.

This example is meant to show basic usage, using the #[tokio::main] macro to setup a simple runtime. The Tokio documentation should be reviewed for more advanced usage.

use std::net::Ipv4Addr;
use std::str::FromStr;
use tokio::net::TcpStream as TokioTcpStream;
use hickory_client::client::{Client, ClientHandle};
use hickory_client::proto::runtime::TokioRuntimeProvider;
use hickory_client::proto::rr::{DNSClass, Name, RData, RecordType};
use hickory_client::proto::rr::rdata::A;
use hickory_client::proto::tcp::TcpClientStream;

#[tokio::main]
async fn main() {
    // Since we used UDP in the previous examples, let's change things up a bit and use TCP here
    let (stream, sender) =
        TcpClientStream::new(([8, 8, 8, 8], 53).into(), None, None, TokioRuntimeProvider::new());

    // Create a new client, the bg is a background future which handles
    //   the multiplexing of the DNS requests to the server.
    //   the client is a handle to an unbounded queue for sending requests via the
    //   background. The background must be scheduled to run before the client can
    //   send any dns requests
    let client = Client::new(stream, sender, None);

    // await the connection to be established
    let (mut client, bg) = client.await.expect("connection failed");

    // make sure to run the background task
    tokio::spawn(bg);

    // Create a query future
    let query = client.query(
        Name::from_str("www.example.com.").unwrap(),
        DNSClass::IN,
        RecordType::A,
   );

    // wait for its response
    let response = query.await.unwrap();

    // validate it's what we expected
    if let RData::A(addr) = response.answers()[0].data() {
        assert_eq!(*addr, A::new(93, 184, 215, 14));
    }
}

In the above example we successfully queried for a A record. There are many other types, each can be independently queried and the associated crate::proto::rr::record_data::RData has a variant with the deserialized data for the record stored.

Dynamic update

Currently hickory-client supports SIG(0) signed records for authentication and authorization of dynamic DNS updates. Consult the client::DnssecClient API for more information.

Re-exports

pub use hickory_proto as proto;

Modules

client

DNS Client associated classes for performing queries and other operations.

Structs

ClientError

The error type for errors that get returned in the crate

Enums

ClientErrorKind

The error kind for errors that get returned in the crate

Functions

version

Returns a version as specified in Cargo.toml