| Copyright | (c) Viktor Dukhovni 2026 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | ietf-dane@dukhovni.org |
| Stability | unstable |
| Safe Haskell | None |
| Language | GHC2024 |
Net.DNSBase.Flags
Description
The DNSFlags field of a DNSMessage carries the genuine
flag bits from the basic DNS header
(RFC 1035 section 4.1.1)
— QR, AA, TC, RD, RA, Z, AD, CD: eight bits in total, of which
Z must be zero per the protocol, leaving seven in practical
use — plus the extended flag bits that arrive in the OPT
pseudo-RR
(RFC 6891 section 6.1.4),
chiefly the DO bit. The OPCODE and RCODE fields of the header
are masked out of DNSFlags and carried separately in the
DNSMessage record.
The FlagOps machinery is the building block resolver
QueryControls uses for per-call flag tweaks: setFlagBits /
clearFlagBits / resetFlagBits build endomorphisms that the
resolver applies to its default outgoing flags, so callers
specify only the bits they want to change rather than the
whole flag word.
Synopsis
- data DNSFlags where
- basicFlags :: Opcode -> RCODE -> DNSFlags -> Word16
- extendFlags :: DNSFlags -> Word16 -> DNSFlags
- extendedFlags :: DNSFlags -> Word16
- hasAllFlags :: DNSFlags -> DNSFlags -> Bool
- hasAnyFlags :: DNSFlags -> DNSFlags -> Bool
- makeDNSFlags :: Integral a => a -> DNSFlags
- maskDNSFlags :: DNSFlags -> DNSFlags -> DNSFlags
- data FlagOps
- setFlagBits :: DNSFlags -> FlagOps -> FlagOps
- clearFlagBits :: DNSFlags -> FlagOps -> FlagOps
- resetFlagBits :: DNSFlags -> FlagOps -> FlagOps
- emptyFlagOps :: FlagOps
- applyFlagOps :: FlagOps -> DNSFlags -> DNSFlags
DNS Message basic and extended flags
The basic DNS header flags word is a mixture of flag bits and numbers, https://tools.ietf.org/html/rfc2535#section-6.1.
1 1 1 1 1 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 > +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ > |QR| Opcode |AA|TC|RD|RA| Z|AD|CD| RCODE | > +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
The RFC numbering of the bits looks little-endian, but we represent the
basic flags as a big-ending 16 bit word with QR in the high (15th) bit.
This gives correct values for the Opcode and RCODE, whose MSB bits are
on the left (the Opcode and RCODE values are big-endian).
Therefore, when ordering the bits for presentation, we output the stored bits in MSB-to-LSB order, and also do the same with the extended bits below. This matches the left-to-right order from the RFCs.
The basic header flags are extended with 16 more bits in the low-order second word (bytes 3+4) of the TTL field of the EDNS(0) OPT pseudo-RR: https://tools.ietf.org/html/rfc6891#section-6.1.3.
1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 > +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ > |DO| Z | > +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
The DNSFlags type combines both the extended and basic flags into a 32-bit
word, with the extended flags in the MSB 16-bits. The bits corresponding
to the Opcode and RCODE cannot be set and are always zero.
Additional bits may be registered from time to time, see the IANA DNS Header Flags and IANA EDNS Header Flags registries.
Flags can be combined via the Monoid instance, or set explicitly via
makeDNSFlags.
The integral values of the flags are user-visible, users manipulating the flags directly, rather than exclusively via the provided pattern synonyms need to be mindful of the representation.
Bundled Patterns
| pattern AAflag :: DNSFlags | AA (Authoritative answer) - This bit is valid in responses, and specifies that the responding name server is an authority for the domain name in question section. |
| pattern ADflag :: DNSFlags | AD (Authentic Data) bit - RFC4035, Section 3.2.3. See also RFC6840, Section 5.8 |
| pattern CDflag :: DNSFlags | CD (Checking Disabled) bit - RFC4035, Section 3.2.2. |
| pattern DOflag :: DNSFlags | DO (DNSSEC OK) bit - RFC3225, Section 3, RFC6891, Section-6.1.4. |
| pattern QRflag :: DNSFlags | QR (Query or Response) - Clear in queries, set in responses. |
| pattern RAflag :: DNSFlags | RA (Recursion available) - This is a response bit, and denotes whether recursive query support is available in the name server. |
| pattern RDflag :: DNSFlags | RD (Recursion Desired) - This bit may be set in a query and is copied into the response. If RD is set, it directs the name server to pursue the query recursively. Authoritative servers may refuse recursive queries, and, conversely, iterative resolvers may refuse non-recursive queries. |
| pattern TCflag :: DNSFlags | TC (Truncated Response) - Specifies that the response was truncated due to length greater than that permitted on the transmission channel. |
| pattern Zflag :: DNSFlags | Z (Reserved, zero until future specification) |
Instances
| Presentable DNSFlags Source # | Output the names of the flags set. If none set, outputs a dash: |
Defined in Net.DNSBase.Internal.Flags Methods present :: DNSFlags -> Builder -> Builder Source # presentLazy :: DNSFlags -> ByteString -> ByteString Source # | |
| Monoid DNSFlags Source # | |
| Semigroup DNSFlags Source # | |
| Show DNSFlags Source # | |
| Eq DNSFlags Source # | |
DNS flag construction and inspection
Arguments
| :: Opcode | Opcode |
| -> RCODE | Extended (12-bit) RCODE |
| -> DNSFlags | Basic and EDNS flags |
| -> Word16 | Flags field for basic DNS header |
Compute a combined basic DNS header flags word
extendFlags :: DNSFlags -> Word16 -> DNSFlags Source #
Combine basic header flags (low 16 bits) with EDNS extended flags (high 16 bits)
Compute the EDNS flags
hasAllFlags :: DNSFlags -> DNSFlags -> Bool Source #
Test whether all flags in the first argument are set in the second.
hasAnyFlags :: DNSFlags -> DNSFlags -> Bool Source #
Test whether any flags in the first argument are set in the second.
makeDNSFlags :: Integral a => a -> DNSFlags Source #
Construct flags from an explicit integral bit field. The basic DNS bits are taken from the least-significant 16 bits of the input, and the EDNS flags from the adjacent 16 bits of the input. Reserved and out of range bits are silently ignored.