Crate rustdns[−][src]

Expand description

rustdns is a simple, fast, and fully fledged DNS library for interacting with domain name services at a high or low level.

Features

Usage (low-level library)

use rustdns::Message;
use rustdns::types::*;
use std::net::UdpSocket;
use std::time::Duration;

fn udp_example() -> std::io::Result<()> {
    // A DNS Message can be easily constructed
    let mut m = Message::default();
    m.add_question("bramp.net", Type::A, Class::Internet);
    m.add_extension(Extension {   // Optionally add a EDNS extension
        payload_size: 4096,       // which supports a larger payload size.
        ..Default::default()
    });

    // Setup a UDP socket for sending to a DNS server.
    let socket = UdpSocket::bind("0.0.0.0:0")?;
    socket.set_read_timeout(Some(Duration::new(5, 0)))?;
    socket.connect("8.8.8.8:53")?; // Google's Public DNS Servers

    // Encode the DNS Message as a Vec<u8>.
    let question = m.to_vec()?;

    // Send to the server.
    socket.send(&question)?;

    // Wait for a response from the DNS server.
    let mut resp = [0; 4096];
    let len = socket.recv(&mut resp)?;

    // Take the response bytes and turn it into another DNS Message.
    let answer = Message::from_slice(&resp[0..len])?;

    // Now do something with `answer`, in this case print it!
    println!("DNS Response:\n{}", answer);

    Ok(())
}

If successful something like the following will be printed:

;; ->>HEADER<<- opcode: Query, status: NoError, id: 44857
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
; bramp.net.              IN   A

; ANSWER SECTION:
bramp.net.            299 IN   A      104.21.62.200
bramp.net.            299 IN   A      172.67.138.196

Usage (cli)

To use the demo CLI:

$ cargo run A www.google.com
...
response: 8.8.8.8:53
00000000: 86 17 81 80 00 01 00 01 00 00 00 01 03 77 77 77  †.€.........www
00000010: 06 67 6F 6F 67 6C 65 03 63 6F 6D 00 00 01 00 01  .google.com.....
00000020: C0 0C 00 01 00 01 00 00 00 6E 00 04 8E FA 48 C4  À........n..ŽúHÄ
00000030: 00 00 29 02 00 00 00 00 00 00 00                 ..)........

;; ->>HEADER<<- opcode: Query, status: NoError, id: 34327
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
; www.google.com.         IN   A

; ANSWER SECTION:
www.google.com.       110 IN   A      142.250.72.196

$ cargo run AAAA www.google.com
$ cargo run ANY www.google.com
$ cargo run CNAME code.google.com
$ cargo run MX google.com
$ cargo run PTR 4.4.8.8.in-addr.arpa
$ cargo run SOA google.com
$ cargo run SRV _ldap._tcp.google.com
$ cargo run TXT google.com

Testing

$ cargo test

# or the handy
$ cargo watch -- cargo test --lib -- --nocapture

The test suite is full of stored real life examples, from querying real DNS records. This was generated with cargo run -p generate_tests.

Fuzzing

The library has been extensively fuzzed. Try for yourself:

$ cargo fuzz run from_slice

Releasing

$ cargo readme > README.md
$ cargo publish --dry-run

TODO (in order of priority)

  • UDP/TCP library
  • Client side examples
  • Server side examples
  • DNS over TLS (DoT) and DNS over HTTPS (DoH)
  • DNSSEC: Signing, validating and key generation for DSA, RSA, ECDSA and Ed25519
  • RFC 1035 zone file parsing
  • NSID, Cookies, AXFR/IXFR, TSIG, SIG(0)
  • Refactoring to use https://github.com/tokio-rs/bytes

Reference

Modules

resource
types

Macros

bail

Handy macro for returning a formatted std::io::Error message.

Structs

Extension

EDNS(0) extension record as defined in rfc2671 and rfc6891.

MX

Mail EXchanger (MX) record specifies the mail server responsible for accepting email messages on behalf of a domain name.

Message

DNS Message that serves as the root of all DNS requests and responses.

Question

Question struct containing a domain name, question Type and question Class.

Record

Resource Record (RR) returned by DNS servers containing a answer to the question.

SOA

Start of Authority (SOA) record containing administrative information about the zone. See rfc1035.

SRV

Service (SRV) record, containg hostname and port number information of specified services. See rfc2782.

Enums

Class

Resource Record Class, for example Internet.

Opcode

Specifies kind of query in this message. See rfc1035, rfc6895 and DNS Parameters.

QR

Query or Response bit.

Rcode

Response Codes. See rfc1035 and DNS Parameters.

Resource

Recource Record Definitions.

Type

Resource Record Type, for example, A, CNAME or SOA.

Type Definitions

A

IPv4 Address (A) record.

AAAA

IPv6 Address (AAAA) record.

CNAME

Canonical name (CNAME) record, for aliasing one name to another.

NS

Name Server (NS) record for delegating a the given authoritative name servers.

PTR

Pointer (PTR) record most commonly used for most common use is for implementing reverse DNS lookups.

TXT

Text (TXT) record for arbitrary human-readable text in a DNS record.