dns

An opinionated Domain Name System (DNS) library
Library dns
Module Dns . Packet
module Flag : sig ... end
module Flags : Set.S with type elt = Flag.t

The set of flags

module Header : sig ... end

A DNS header

module Question : sig ... end

A DNS Question - the first section of a DNS packet

module Answer : sig ... end

A DNS answer, consisting of the answer and authority sections.

module Axfr : sig ... end

A DNS zone transfer.

module Ixfr : sig ... end

Incremental DNS zone transfer.

module Update : sig ... end

DNS update packets.

type request = [
| `Query
| `Notify of Soa.t option
| `Axfr_request
| `Ixfr_request of Soa.t
| `Update of Update.t
]

The type of a DNS request: depending on opcode and rr_typ.

val equal_request : request -> request -> bool

equal_request a b is true if the request a is the same as b, false otherwise.

val pp_request : request Fmt.t

pp_request ppf r pretty-prints the request r on ppf.

type reply = [
| `Answer of Answer.t
| `Notify_ack
| `Axfr_reply of Axfr.t
| `Axfr_partial_reply of [ `First of Soa.t | `Mid | `Last of Soa.t ] * Name_rr_map.t
| `Ixfr_reply of Ixfr.t
| `Update_ack
| `Rcode_error of Rcode.t * Opcode.t * Answer.t option
]

The type of a DNS reply: depending on opcode, rr_typ, and rcode.

val equal_reply : reply -> reply -> bool

equal_reply a b is true if the reply a is the same as b, false otherwise.

val pp_reply : reply Fmt.t

pp_reply ppf r pretty-prints the reply r on ppf.

type data = [
| request
| reply
]

The type of either request or reply.

val opcode_data : data -> Opcode.t

opcode_data data is the opcode of data.

val rcode_data : data -> Rcode.t

rcode_data data is the response code of data.

val equal_data : data -> data -> bool

equal_data a b is true if a and b are the same, false otherwise.

val pp_data : data Fmt.t

pp_data ppf data pretty-prints data on ppf.

type t = private {
header : Header.t;
question : Question.t;
data : data;
additional : Name_rr_map.t;
edns : Edns.t option;
tsig : ([ `raw ] Domain_name.t * Tsig.t * int) option;
}

The type of a DNS packet: its header, question, data, additional section, and optional EDNS and TSIG records.

val create : ?max_size:int -> ?additional:Name_rr_map.t -> ?edns:Edns.t -> ?tsig:([ `raw ] Domain_name.t * Tsig.t * int) -> Header.t -> Question.t -> data -> t

create ~max_size ~additional ~edns ~tsig hdr q data is a DNS packet.

val with_edns : t -> Edns.t option -> t

with_edns t edns is t with the edns field set to edns.

val pp : t Fmt.t

pp ppf t pretty-prints the DNS packet t on ppf.

val pp_header : t Fmt.t

pp_header ppf t pretty-prints the header of the DNS packet on ppf.

val equal : t -> t -> bool

equal a b is true if the DNS packet a and b are equal, false otherwise.

type err = [
| `Bad_edns_version of int
| `Leftover of int * string
| `Malformed of int * string
| `Not_implemented of int * string
| `Notify_ack_answer_count of int
| `Notify_ack_authority_count of int
| `Notify_answer_count of int
| `Notify_authority_count of int
| `Partial
| `Query_answer_count of int
| `Query_authority_count of int
| `Rcode_cant_change of Rcode.t
| `Rcode_error_cant_noerror of Rcode.t
| `Request_rcode of Rcode.t
| `Truncated_request
| `Update_ack_answer_count of int
| `Update_ack_authority_count of int
]

The type of decode errors.

val pp_err : err Fmt.t

pp_err ppf err pretty-prints the decode error err on ppf.

val decode : Cstruct.t -> ( t, err ) result

decode cs decode the binary data cs to a DNS packet t or an error.

type mismatch = [
| `Not_a_reply of request
| `Id_mismatch of int * int
| `Operation_mismatch of request * reply
| `Question_mismatch of Question.t * Question.t
| `Expected_request
]

The type of request / reply mismatches.

val pp_mismatch : mismatch Fmt.t

pp_mismatch ppf m pretty-prints the mismatch m on ppf.

val reply_matches_request : request:t -> t -> ( reply, mismatch ) result

reply_matches_request ~request reply validates that the reply match the request, and returns either Ok data or an Error. The following basic checks are performed:

  • Is the header identifier of request and reply equal?
  • Does the request operation match the reply operation?
  • Is question and the question of response equal?
val size_edns : int option -> Edns.t option -> proto -> bool -> int * Edns.t option

size_edns max_size edns protocol query computes the size of the reply packet, and optionally an EDNS record.

val encode : ?max_size:int -> proto -> t -> Cstruct.t * int

encode ~max_size protocol t allocates a buffer and encodes the DNS packet t into it. If the maximum size (depending on max_size and protocol) is reached, the truncation flag is set. The last component of the result is the maximum size.

val encode_axfr_reply : ?max_size:int -> int -> proto -> t -> Axfr.t -> Cstruct.t list * int

encode_axfr_reply ~max_size tsig_size protocol t axfr encodes the axfr into a list of buffers to be sent out (each with at least tsig_size space for a tsig signature. The second component of the result is the maximum size (dependent on max_size and protocol).

val raw_error : Cstruct.t -> Rcode.t -> Cstruct.t option

raw_error cs rcode is an error reply with rcode to cs, or None if cs is already a reply.