Hickory DNS

A Rust based DNS client, server, and resolver, built to be safe and secure from the ground up.

This repo consists of multiple crates:

Library	Description
Hickory DNS	Provides the hickory-dns binary for running a DNS server.
Proto	Low-level DNS library, including message encoding/decoding and DNS transports.
Client	Used for sending query, update, and notify messages directly to a DNS server.
Server	Used to build DNS servers. The hickory-dns binary makes use of this library.
Resolver	Utilizes the client library to perform DNS resolution. Can be used in place of the standard OS resolution facilities.
Recursor	Performs recursive DNS resolution, looking up records from their authoritative name servers.

NOTICE This project was rebranded from Trust-DNS to Hickory DNS and has been moved to the https://github.com/hickory-dns/hickory-dns organization and repo.

Goals

• Build a safe and secure DNS server and client with modern features.
• No panics, all code is guarded
• Use only safe Rust, and avoid all panics with proper Error handling
• Use only stable Rust
• Protect against DDOS attacks (to a degree)
• Support options for Global Load Balancing functions
• Make it dead simple to operate

Cryptography provider

The hickory-dns application and lower-level library crates support choosing between two cryptography providers for protocols that require cryptography (DNSSEC, DNS-over-TLS, etc):

1. aws-lc-rs
2. ring

Feature flags that require cryptography are suffixed by the choice of provider. For example, for DNS-over-TLS the feature is offered as tls-aws-lc-rs or tls-ring depending on whether you wish to use aws-lc-rs or ring.

Status

DNSSEC status

The current root key is bundled into the system, and used by default. This gives validation of DNSKEY and DS records back to the root. NSEC and NSEC3 are implemented.

Zones will be automatically resigned on any record updates via dynamic DNS. To enable DNSSEC, enable the dnssec-ring feature.

Offline signing of records/zones is not presently supported.

RFCs implemented

• RFC 8499: No more master/slave, in honor of Juneteenth

Basic operations

• RFC 1035: Base DNS spec (see the Resolver for caching)
• RFC 2308: Negative Caching of DNS Queries (see the Resolver)
• RFC 2782: Service location
• RFC 3596: IPv6
• RFC 6891: Extension Mechanisms for DNS
• RFC 6761: Special-Use Domain Names (resolver)
• RFC 6762: mDNS Multicast DNS (experimental feature: mdns)
• RFC 6763: DNS-SD Service Discovery (experimental feature: mdns)
• draft-ietf-dnsop-aname: Address-specific DNS aliases (ANAME)

Update operations

• RFC 2136: Dynamic Update
• RFC 7477: Child-to-Parent Synchronization in DNS

Secure DNS operations

• RFC 2931: SIG(0)
• RFC 3007: Secure Dynamic Update
• RFC 4034: DNSSEC Resource Records
• RFC 4035: Protocol Modifications for DNSSEC
• RFC 4509: SHA-256 in DNSSEC Delegation Signer
• RFC 5155: DNSSEC Hashed Authenticated Denial of Existence
• RFC 5702: SHA-2 Algorithms with RSA in DNSKEY and RRSIG for DNSSEC
• RFC 6844: DNS Certification Authority Authorization (CAA) Resource Record
• RFC 6698: The DNS-Based Authentication of Named Entities (DANE) Transport Layer Security (TLS) Protocol: TLSA
• RFC 6840: Clarifications and Implementation Notes for DNSSEC
• RFC 6844: DNS Certification Authority Authorization Resource Record
• RFC 6944: DNSKEY Algorithm Implementation Status
• RFC 6975: Signaling Cryptographic Algorithm Understanding
• RFC 7858: DNS over TLS (feature: tls-aws-lc-rs/tls-ring)
• RFC 8162: Using Secure DNS to Associate Certificates with Domain Names for S/MIME
• RFC 8484: DNS over HTTPS, DoH (feature: https-aws-lc-rs/https-ring)

RFCs in progress or not yet implemented

Basic operations

• RFC 2317: Classless IN-ADDR.ARPA delegation

Update operations

• RFC 1995: Incremental Zone Transfer
• RFC 1996: Notify secondaries of update
• Update Leases: Dynamic DNS Update Leases
• RFC 8764: Notify with bells

Secure DNS operations

• DNSCrypt: Trusted DNS queries
• RFC 8162: Domain Names For S/MIME

Testing

Hickory DNS uses just for build workflow management. While running cargo test at the project root will work, this is not exhaustive. Install just with cargo install just. A few of the just recipes require cargo-workspaces to be installed, a plugin to optimize the workflow around cargo workspaces. Install the plugin with cargo install cargo-workspaces.

• Default tests

  These are good for running on local systems. They will create sockets for local tests, but will not attempt to access remote systems. Tests can also be run from the crate directory, i.e. client or server and cargo test

just default

• Default feature tests

  Hickory DNS has many features, to quickly test with them or without, there are three targets supported, default, no-default-features, all-features:

just all-features

• Individual feature tests

  Hickory DNS has many features, each individual feature can be tested independently. See individual crates for all their features. Each feature can be tested with itself as the task target for just:

just tls-aws-lc-rs

• Benchmarks

  Waiting on benchmarks to stabilize in mainline Rust.

Building

• Production build, from the hickory-dns base dir, to get all features, just pass the --all-features flag.

cargo build --release -p hickory-dns

Using the hickory-resolver CLI

Available in 0.20

cargo install --bin resolve hickory-util

Or from source, in the hickory-dns directory

cargo install --bin resolve --path util

example:

$ resolve www.example.com.
Querying for www.example.com. A from udp:8.8.8.8:53, tcp:8.8.8.8:53, udp:8.8.4.4:53, tcp:8.8.4.4:53, udp:[2001:4860:4860::8888]:53, tcp:[2001:4860:4860::8888]:53, udp:[2001:4860:4860::8844]:53, tcp:[2001:4860:4860::8844]:53
Success for query name: www.example.com. type: A class: IN
        www.example.com. 21063 IN A 93.184.215.14

Usage with Docker

A Docker image with a pre-compiled version of hickory-dns is availalbe at https://github.com/hickory-dns/docker.

FAQ

• Why are you building another DNS server?

  To offer a DNS server written in a memory-safe language.

  Using Rust semantics it should be possible to develop a high performance and safe DNS Server that is more resilient to attacks.

• What is the MSRV (minimum stable Rust version) policy?

  Hickory DNS will work to support backward compatibility with three Rust versions.

  For example, if 1.50 is the current release, then the MSRV will be 1.47. The version is only increased as necessary, so it's possible that the MSRV is older than this policy states. Additionally, the MSRV is only supported for the no-default-features build due to it being an intractable issue of trying to enforce this policy on dependencies.

Community

For live discussions beyond this repository, please see this Discord.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.