The dns.message.Message Class
This is the base class for all messages, and the class used for any DNS opcodes that do not have a more specific class.
- class dns.message.Message(id: int | None = None)[source]
A DNS message.
- id
An
int
, the query id; the default is a randomly chosen id.
- flags
An
int
, the DNS flags of the message.
- sections
A list of lists of
dns.rrset.RRset
objects.
- edns
An
int
, the EDNS level to use. The default is -1, no EDNS.
- ednsflags
An
int
, the EDNS flags.
- payload
An
int
, the EDNS payload size. The default is 0.
- options
The EDNS options, a list of
dns.edns.Option
objects. The default is the empty list.
- request_payload
The associated request’s EDNS payload size. This field is meaningful in response messages, and if set to a non-zero value, will limit the size of the response to the specified size. The default is 0, which means “use the default limit” which is currently 65535.
- keyring
A
dns.tsig.Key
, the TSIG key. The default is None.
- keyname
The TSIG keyname to use, a
dns.name.Name
. The default isNone
.
- keyalgorithm
A
dns.name.Name
, the TSIG algorithm to use. Defaults todns.tsig.default_algorithm
. Constants for TSIG algorithms are defined the indns.tsig
module.
- request_mac
A
bytes
, the TSIG MAC of the request message associated with this message; used when validating TSIG signatures.
- fudge
An
int
, the TSIG time fudge. The default is 300 seconds.
- original_id
An
int
, the TSIG original id; defaults to the message’s id.
- tsig_error
An
int
, the TSIG error code. The default is 0.
- other_data
A
bytes
, the TSIG “other data”. The default is the emptybytes
.
- mac
A
bytes
, the TSIG MAC for this message.
- xfr
A
bool
. This attribute is true when the message being used for the results of a DNS zone transfer. The default isFalse
.
- origin
A
dns.name.Name
. The origin of the zone in messages which are used for zone transfers or for DNS dynamic updates. The default isNone
.
- tsig_ctx
An
hmac.HMAC
, the TSIG signature context associated with this message. The default isNone
.
- had_tsig
A
bool
, which isTrue
if the message had a TSIG signature when it was decoded from wire format.
- multi
A
bool
, which isTrue
if this message is part of a multi-message sequence. The default isFalse
. This attribute is used when validating TSIG signatures on messages which are part of a zone transfer.
- first
A
bool
, which isTrue
if this message is stand-alone, or the first of a multi-message sequence. The default isTrue
. This variable is used when validating TSIG signatures on messages which are part of a zone transfer.
- index
A
dict
, an index of RRsets in the message. The index key is(section, name, rdclass, rdtype, covers, deleting)
. The default is{}
. Indexing improves the performance of finding RRsets. Indexing can be disabled by setting the index toNone
.
- wire
A
bytes
orNone
, the encoded wire format data used to create this message withdns.message.from_wire()
or the output most recently generated byto_wire()
.
- extended_errors() List[EDEOption] [source]
Return the list of Extended DNS Error (EDE) options in the message
- find_rrset(section: int | str | List[RRset], name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, deleting: RdataClass | None = None, create: bool = False, force_unique: bool = False, idna_codec: IDNACodec | None = None) RRset [source]
Find the RRset with the given attributes in the specified section.
section, an
int
section number, astr
section name, or one of the section attributes of this message. This specifies the the section of the message to search. For example:my_message.find_rrset(my_message.answer, name, rdclass, rdtype) my_message.find_rrset(dns.message.ANSWER, name, rdclass, rdtype) my_message.find_rrset("ANSWER", name, rdclass, rdtype)
name, a
dns.name.Name
orstr
, the name of the RRset.rdclass, an
int
orstr
, the class of the RRset.rdtype, an
int
orstr
, the type of the RRset.covers, an
int
orstr
, the covers value of the RRset. The default isdns.rdatatype.NONE
.deleting, an
int
,str
, orNone
, the deleting value of the RRset. The default isNone
.create, a
bool
. IfTrue
, create the RRset if it is not found. The created RRset is appended to section.force_unique, a
bool
. IfTrue
and create is alsoTrue
, create a new RRset regardless of whether a matching RRset exists already. The default isFalse
. This is useful when creating DDNS Update messages, as order matters for them.idna_codec, a
dns.name.IDNACodec
, specifies the IDNA encoder/decoder. IfNone
, the default IDNA 2003 encoder/decoder is used.Raises
KeyError
if the RRset was not found and create wasFalse
.Returns a
dns.rrset.RRset object
.
- get_options(otype: OptionType) List[Option] [source]
Return the list of options of the specified type.
- get_rrset(section: int | str | List[RRset], name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, deleting: RdataClass | None = None, create: bool = False, force_unique: bool = False, idna_codec: IDNACodec | None = None) RRset | None [source]
Get the RRset with the given attributes in the specified section.
If the RRset is not found, None is returned.
section, an
int
section number, astr
section name, or one of the section attributes of this message. This specifies the the section of the message to search. For example:my_message.get_rrset(my_message.answer, name, rdclass, rdtype) my_message.get_rrset(dns.message.ANSWER, name, rdclass, rdtype) my_message.get_rrset("ANSWER", name, rdclass, rdtype)
name, a
dns.name.Name
orstr
, the name of the RRset.rdclass, an
int
orstr
, the class of the RRset.rdtype, an
int
orstr
, the type of the RRset.covers, an
int
orstr
, the covers value of the RRset. The default isdns.rdatatype.NONE
.deleting, an
int
,str
, orNone
, the deleting value of the RRset. The default isNone
.create, a
bool
. IfTrue
, create the RRset if it is not found. The created RRset is appended to section.force_unique, a
bool
. IfTrue
and create is alsoTrue
, create a new RRset regardless of whether a matching RRset exists already. The default isFalse
. This is useful when creating DDNS Update messages, as order matters for them.idna_codec, a
dns.name.IDNACodec
, specifies the IDNA encoder/decoder. IfNone
, the default IDNA 2003 encoder/decoder is used.Returns a
dns.rrset.RRset object
orNone
.
- is_response(other: Message) bool [source]
Is other, also a
dns.message.Message
, a response to this message?Returns a
bool
.
- section_count(section: int | str | List[RRset]) int [source]
Returns the number of records in the specified section.
section, an
int
section number, astr
section name, or one of the section attributes of this message. This specifies the the section of the message to count. For example:my_message.section_count(my_message.answer) my_message.section_count(dns.message.ANSWER) my_message.section_count("ANSWER")
- section_from_number(number: int) List[RRset] [source]
Return the section list associated with the specified section number.
number is a section number int or the text form of a section name.
Raises
ValueError
if the section isn’t known.Returns a
list
.
- section_number(section: List[RRset]) int [source]
Return the “section number” of the specified section for use in indexing.
section is one of the section attributes of this message.
Raises
ValueError
if the section isn’t known.Returns an
int
.
- set_opcode(opcode: Opcode) None [source]
Set the opcode.
opcode, a
dns.opcode.Opcode
, is the opcode to set.
- set_rcode(rcode: Rcode) None [source]
Set the rcode.
rcode, a
dns.rcode.Rcode
, is the rcode to set.
- to_text(origin: Name | None = None, relativize: bool = True, **kw: Dict[str, Any]) str [source]
Convert the message to text.
The origin, relativize, and any other keyword arguments are passed to the RRset
to_wire()
method.Returns a
str
.
- to_wire(origin: Name | None = None, max_size: int = 0, multi: bool = False, tsig_ctx: Any | None = None, prepend_length: bool = False, prefer_truncation: bool = False, **kw: Dict[str, Any]) bytes [source]
Return a string containing the message in DNS compressed wire format.
Additional keyword arguments are passed to the RRset
to_wire()
method.origin, a
dns.name.Name
orNone
, the origin to be appended to any relative names. IfNone
, and the message has an origin attribute that is notNone
, then it will be used.max_size, an
int
, the maximum size of the wire format output; default is 0, which means “the message’s request payload, if nonzero, or 65535”.multi, a
bool
, should be set toTrue
if this message is part of a multiple message sequence.tsig_ctx, a
dns.tsig.HMACTSig
ordns.tsig.GSSTSig
object, the ongoing TSIG context, used when signing zone transfers.prepend_length, a
bool
, should be set toTrue
if the caller wants the message length prepended to the message itself. This is useful for messages sent over TCP, TLS (DoT), or QUIC (DoQ).prefer_truncation, a
bool
, should be set toTrue
if the caller wants the message to be truncated if it would otherwise exceed the maximum length. If the truncation occurs before the additional section, the TC bit will be set.Raises
dns.exception.TooBig
if max_size was exceeded.Returns a
bytes
.
- use_edns(edns: int | bool | None = 0, ednsflags: int = 0, payload: int = 1232, request_payload: int | None = None, options: List[Option] | None = None, pad: int = 0) None [source]
Configure EDNS behavior.
edns, an
int
, is the EDNS level to use. SpecifyingNone
,False
, or-1
means “do not use EDNS”, and in this case the other parameters are ignored. SpecifyingTrue
is equivalent to specifying 0, i.e. “use EDNS0”.ednsflags, an
int
, the EDNS flag values.payload, an
int
, is the EDNS sender’s payload field, which is the maximum size of UDP datagram the sender can handle. I.e. how big a response to this message can be.request_payload, an
int
, is the EDNS payload size to use when sending this message. If not specified, defaults to the value of payload.options, a list of
dns.edns.Option
objects orNone
, the EDNS options.pad, a non-negative
int
. If 0, the default, do not pad; otherwise add padding bytes to make the message size a multiple of pad. Note that if padding is non-zero, an EDNS PADDING option will always be added to the message.
- use_tsig(keyring: ~typing.Any, keyname: ~dns.name.Name | str | None = None, fudge: int = 300, original_id: int | None = None, tsig_error: int = 0, other_data: bytes = b'', algorithm: ~dns.name.Name | str = <DNS name hmac-sha256.>) None [source]
When sending, a TSIG signature using the specified key should be added.
key, a
dns.tsig.Key
is the key to use. If a key is specified, the keyring and algorithm fields are not used.keyring, a
dict
,callable
ordns.tsig.Key
, is either the TSIG keyring or key to use.The format of a keyring dict is a mapping from TSIG key name, as
dns.name.Name
todns.tsig.Key
or a TSIG secret, abytes
. If adict
keyring is specified but a keyname is not, the key used will be the first key in the keyring. Note that the order of keys in a dictionary is not defined, so applications should supply a keyname when adict
keyring is used, unless they know the keyring contains only one key. If acallable
keyring is specified, the callable will be called with the message and the keyname, and is expected to return a key.keyname, a
dns.name.Name
,str
orNone
, the name of this TSIG key to use; defaults toNone
. If keyring is adict
, the key must be defined in it. If keyring is adns.tsig.Key
, this is ignored.fudge, an
int
, the TSIG time fudge.original_id, an
int
, the TSIG original id. IfNone
, the message’s id is used.tsig_error, an
int
, the TSIG error code.other_data, a
bytes
, the TSIG other data.algorithm, a
dns.name.Name
orstr
, the TSIG algorithm to use. This is only used if keyring is adict
, and the key entry is abytes
.
The following constants may be used to specify sections in the
find_rrset()
and get_rrset()
methods:
- dns.message.QUESTION = MessageSection.QUESTION
Message sections
- dns.message.ANSWER = MessageSection.ANSWER
Message sections
- dns.message.AUTHORITY = MessageSection.AUTHORITY
Message sections
- dns.message.ADDITIONAL = MessageSection.ADDITIONAL
Message sections