Module Dns.Tsig

Transaction signature

A transaction signature is a resource record that authenticates a DNS packet. Its nature is not to persist in databases, but it is handled specially during decoding and encoding.

type algorithm =
| SHA1
| SHA224
| SHA256
| SHA384
| SHA512

The type of supported signature algorithms.

val algorithm_to_name : algorithm -> [ `host ] Domain_name.t

algorithm_to_name a is the hostname of the algorithm.

val algorithm_of_name : ?⁠off:int -> [ `host ] Domain_name.t -> (algorithm, [> `Not_implemented of int * string ]) Stdlib.result

algorithm_of_name ~off name is the algorithm represented by name, or an Error if no such algorithm exist.

val pp_algorithm : algorithm Fmt.t

pp_algorithm ppf a pretty-prints the algorithm a on ppf.

type t = private {
algorithm : algorithm;
signed : Ptime.t;
fudge : Ptime.Span.t;
mac : Cstruct.t;
original_id : int;
error : Rcode.t;
other : Ptime.t option;
}

The type of a transaction signature: algorithm, timestamp when it was signed, the span it is valid for, the actual signature (mac), the original DNS identifier, a potential error, and optionally the other timestamp (used to signal non-synchronized clocks).

val tsig : algorithm:algorithm -> signed:Ptime.t -> ?⁠fudge:Ptime.span -> ?⁠mac:Cstruct.t -> ?⁠original_id:int -> ?⁠error:Rcode.t -> ?⁠other:Ptime.t -> unit -> t option

tsig ~algorithm ~signed ~fudge ~mac ~original_id ~error ~other () constructs a transaction signature t if possible (timestamp needs to fit into 48 bit as seconds since Unix epoch).

val with_mac : t -> Cstruct.t -> t

with_mac t mac updates t with mac.

val with_error : t -> Rcode.t -> t

with_error t err updates t with err.

val with_signed : t -> Ptime.t -> t option

with_signed t ts updates t with signed timestamp ts, if ts fits in the representation (seconds since Unix epoch in 48 bit).

val with_other : t -> Ptime.t option -> t option

with_other t ts updates t with other timestamp ts, if ts fits in the representation (seconds since Unix epoch in 48 bit).

val pp : t Fmt.t

pp ppf t pretty-prints the transaction signature t on ppf.

val equal : t -> t -> bool

equal a b compares the transaction signature a with b, and is true if they are equal, false otherwise.

val encode_raw : [ `raw ] Domain_name.t -> t -> Cstruct.t

encode_raw name t encodes the transaction signature t as resource record using name. The mac is not included, this is used for computing the signature.

val encode_full : [ `raw ] Domain_name.t -> t -> Cstruct.t

encode_full name t encodes the transaction signature t as resource record using name.

val dnskey_to_tsig_algo : Dnskey.t -> (algorithm, [> `Msg of string ]) Stdlib.result

dnskey_to_tsig_algo dnskey is the TSIG algorithm of dnskey, or an Error.

val valid_time : Ptime.t -> t -> bool

valid_time ts t checks whether the signed timestamp (within fudge) matches ts.