DNS-C Messages

Introduction

Any application may use DNS-C-… messages to the DnsClientApp to request that an outbound DNS (including ENUM) request be made to an external DNS/ENUM Server via UDP.

The following LuaApp agents from the core n2svcd module use DnsClientApp.

The internal DNS-C-… messages are:

Note that this page uses the term “on-the-wire” to refer to the sending or receiving of DNS content (including ENUM) by the DnsClientApp. This term is also inclusive of the case where the message is sent by local loopback and does not physically transit a Network Interface Controller (NIC).

DNS-C-REQUEST

The DNS-C-REQUEST message is sent to DnsClientApp by any application that wishes to perform an outbound DNS/ENUM request.

Refer to the DnsClientApp Configuration documentation for more information on setting default parameters.

The attributes of the DNS-C-REQUEST message are:

Field Type Description
dns Object Container for the parameters of the DNS request that we are to send.
.opcode 0 - 2 The DNS opcode to send in the request as per RFC 1035 section 4.1.1.
The only typically relevant value is 0 for QUERY.
(Default = 0).
.recursion_desired 0 / 1 Is recursion desired in the DNS lookup?
(Default = 1).
.checking_disabled 0 / 1 Are non-authenticated answers acceptable in the DNS lookup?
(Default = 1).
.e164_digits String [Required] The digits of the E.164 domain address string to put in the Query block.
This may include an optional leading + character, which will be stripped.

Note that the DNS-C-REQUEST provides very limited control over the on-the-wire UDP packet.
Specifically it does not provide control over:

Some of these parameters can only be set in the DnsClientApp configuration, others are implicit in the implemented DNS/ENUM lookup functionality.

DNS-C-SENT

The DNS-C-SENT message is sent by DnsClientApp to the requesting application when the original DNS-C-REQUEST is placed on-the-wire.

The attributes of the DNS-C-SENT message are:

Field Type Description
dns Object The DNS parameters used to encode the final on-the-wire UDP/DNS Request.
This object has the same structure as the dns object in DNS-C-REQUEST.
Note however that this object may also contain any field values which were filled-in using default values configured within DnsClientApp itself.
bytes String The on-the wire bytes placed into the UDP/DNS packet.

DNS-C-RESPONSE

The DNS-C-RESPONSE message is sent by DnsClientApp to the requesting application when a UDP/DNS Response is received to the original DNS-C-REQUEST, or if a failure occurs which indicates that no UDP/DNS Response will be received.

The attributes of the DNS-C-RESPONSE message are:

Field Type Description
success 0/1 [Required] Indicates if the request was successful or not.
error String Indicates the reason why the request failed.
Present and applicable only if success == 0.
dns Object Container for the DNS response parameters received.
Present only if success == 1.
.flags Integer An integer representation of the top-level DNS message two-byte flags field.
.authoritative_answer 0 / 1 [Required] The returned value of the 1-bit AA value in the top-level flags.
.recursion_available 0 / 1 [Required] The returned value of the 1-bit RA value in the top-level flags.
.authenticated_data 0 / 1 [Required] The returned value of the 1-bit AD value in the top-level flags.
.reply_code 0 - 15 [Required] The top-level 4-bit Reply Code from the top-level flags.
A value of 0 indicates success. A non-zero value is a failed lookup.
.queries Array of Object The list of Query records parsed from the DNS response Response (see below for object structure).
.authorities Array of Object The list of Authority response records parsed from the DNS response Response (see below for object structure).
.additional Array of Object The list of Additional response records parsed from the DNS response Response (see below for object structure).
.answers Array of Object The list of Answer response records parsed from the DNS response Response (see below for object structure).

The queries Object in the dns Object for DNS-C-RESPONSE has the following structure.

Field Type Description
.name String [Required] The name of the record as a dot-notation string.
.type Integer [Required] The integer value of the Type, e.g. 35 indicating NAPTR.
.class Integer [Required] The integer value of the Class, e.g. 1 indicating IN.
.e164_digits String If the name appears to be an E.164 digit string, then the decoded (non-dot-notation) ASCII address string equivalent E.164 address will be decoded and provided here. It will not be given a '+' prefix.

The answers, authorities, and additional Objects in the dns Object for DNS-C-RESPONSE have the following structure.

Note that the sub-fields name (and e164_digits), type, class, ttl are common to all DNS response records. All other sub-fields are specific to individual record Types. At this time the only supported response record types for which extra sub-fields will be decoded are the following:

Field Type Description
.name String [Required] The name of the record as a dot-notation string.
.type Integer [Required] The integer value of the Type, e.g. 35 indicating NAPTR.
.class Integer [Required] The integer value of the Class, e.g. 1 indicating IN.
.e164_digits String If the name appears to be an E.164 digit string, then the decoded (non-dot-notation) ASCII address string equivalent E.164 address will be decoded and provided here. It will not be given a '+' prefix.
.order Integer [Required for NAPTR (Type = 35)] The Order value (0-65535) returned in the NAPTR response record.
.preference Integer [Required for NAPTR (Type = 35)] The Preference value (0-65535) returned in the NAPTR response record.
.flags Integer [Required for NAPTR (Type = 35)] An integer representation of the flags returned in the NAPTR response record.
.service String [Required for NAPTR (Type = 35)] The Service string returned in the NAPTR response record.
.regex String [Required for NAPTR (Type = 35)] The Regex string (if any) returned in the NAPTR response record.
.replacement String [Required for NAPTR (Type = 35)] The Replacement domain name (if any) returned in the NAPTR response record, expressed as a dot-separated domain name.