Group PJ_DNS_PARSING¶
-
group
PJ_DNS_PARSING
This module provides low-level services to parse and packetize DNS queries and responses. The functions support building a DNS query packet and parse the data in the DNS response. This implementation conforms to the following specifications:
RFC 1035: DOMAIN NAMES - IMPLEMENTATION AND SPECIFICATION
RFC 1886: DNS Extensions to support IP version 6
To create a DNS query packet, application should call pj_dns_make_query() function, specifying the desired DNS query type, the name to be resolved, and the buffer where the DNS packet will be built into.
When incoming DNS query or response packet arrives, application can use pj_dns_parse_packet() to parse the TCP/UDP payload into parsed DNS packet structure.
This module does not provide any networking functionalities to send or receive DNS packets. This functionality should be provided by higher layer modules such as DNS Asynchronous/Caching Resolution Engine.
Defines
-
PJ_DNS_SET_RCODE
(c)¶ Create RCODE flag
-
PJ_DNS_SET_RA
(on)¶ Create RA (Recursion Available) bit
-
PJ_DNS_SET_RD
(on)¶ Create RD (Recursion Desired) bit
-
PJ_DNS_SET_TC
(on)¶ Create TC (Truncated) bit
-
PJ_DNS_SET_AA
(on)¶ Create AA (Authoritative Answer) bit
-
PJ_DNS_SET_OPCODE
(o)¶ Create four bits opcode
-
PJ_DNS_SET_QR
(on)¶ Create query/response bit
-
PJ_DNS_GET_RCODE
(val)¶ Get RCODE value
-
PJ_DNS_GET_RA
(val)¶ Get RA bit
-
PJ_DNS_GET_RD
(val)¶ Get RD bit
-
PJ_DNS_GET_TC
(val)¶ Get TC bit
-
PJ_DNS_GET_AA
(val)¶ Get AA bit
-
PJ_DNS_GET_OPCODE
(val)¶ Get OPCODE value
-
PJ_DNS_GET_QR
(val)¶ Get QR bit
Enums
-
enum
pj_dns_type
¶ This enumeration describes standard DNS record types as described by RFC 1035, RFC 2782, and others.
Values:
-
enumerator
PJ_DNS_TYPE_A
¶ Host address (A) record.
-
enumerator
PJ_DNS_TYPE_NS
¶ Authoritative name server (NS)
-
enumerator
PJ_DNS_TYPE_MD
¶ Mail destination (MD) record.
-
enumerator
PJ_DNS_TYPE_MF
¶ Mail forwarder (MF) record.
-
enumerator
PJ_DNS_TYPE_CNAME
¶ Canonical name (CNAME) record.
-
enumerator
PJ_DNS_TYPE_SOA
¶ Marks start of zone authority.
-
enumerator
PJ_DNS_TYPE_MB
¶ Mailbox domain name (MB).
-
enumerator
PJ_DNS_TYPE_MG
¶ Mail group member (MG).
-
enumerator
PJ_DNS_TYPE_MR
¶ Mail rename domain name.
-
enumerator
PJ_DNS_TYPE_NULL
¶ NULL RR.
-
enumerator
PJ_DNS_TYPE_WKS
¶ Well known service description
-
enumerator
PJ_DNS_TYPE_PTR
¶ Domain name pointer.
-
enumerator
PJ_DNS_TYPE_HINFO
¶ Host information.
-
enumerator
PJ_DNS_TYPE_MINFO
¶ Mailbox or mail list information.
-
enumerator
PJ_DNS_TYPE_MX
¶ Mail exchange record.
-
enumerator
PJ_DNS_TYPE_TXT
¶ Text string.
-
enumerator
PJ_DNS_TYPE_RP
¶ Responsible person.
-
enumerator
PJ_DNS_TYPE_AFSB
¶ AFS cell database.
-
enumerator
PJ_DNS_TYPE_X25
¶ X.25 calling address.
-
enumerator
PJ_DNS_TYPE_ISDN
¶ ISDN calling address.
-
enumerator
PJ_DNS_TYPE_RT
¶ Router.
-
enumerator
PJ_DNS_TYPE_NSAP
¶ NSAP address.
-
enumerator
PJ_DNS_TYPE_NSAP_PTR
¶ NSAP reverse address.
-
enumerator
PJ_DNS_TYPE_SIG
¶ Signature.
-
enumerator
PJ_DNS_TYPE_KEY
¶ Key.
-
enumerator
PJ_DNS_TYPE_PX
¶ X.400 mail mapping.
-
enumerator
PJ_DNS_TYPE_GPOS
¶ Geographical position (withdrawn)
-
enumerator
PJ_DNS_TYPE_AAAA
¶ IPv6 address.
-
enumerator
PJ_DNS_TYPE_LOC
¶ Location.
-
enumerator
PJ_DNS_TYPE_NXT
¶ Next valid name in the zone.
-
enumerator
PJ_DNS_TYPE_EID
¶ Endpoint idenfitier.
-
enumerator
PJ_DNS_TYPE_NIMLOC
¶ Nimrod locator.
-
enumerator
PJ_DNS_TYPE_SRV
¶ Server selection (SRV) record.
-
enumerator
PJ_DNS_TYPE_ATMA
¶ DNS ATM address record.
-
enumerator
PJ_DNS_TYPE_NAPTR
¶ DNS Naming authority pointer record.
-
enumerator
PJ_DNS_TYPE_KX
¶ DNS key exchange record.
-
enumerator
PJ_DNS_TYPE_CERT
¶ DNS certificate record.
-
enumerator
PJ_DNS_TYPE_A6
¶ DNS IPv6 address (experimental)
-
enumerator
PJ_DNS_TYPE_DNAME
¶ DNS non-terminal name redirection rec.
-
enumerator
PJ_DNS_TYPE_OPT
¶ DNS options - contains EDNS metadata.
-
enumerator
PJ_DNS_TYPE_APL
¶ DNS Address Prefix List (APL) record.
-
enumerator
PJ_DNS_TYPE_DS
¶ DNS Delegation Signer (DS)
-
enumerator
PJ_DNS_TYPE_SSHFP
¶ DNS SSH Key Fingerprint
-
enumerator
PJ_DNS_TYPE_IPSECKEY
¶ DNS IPSEC Key.
-
enumerator
PJ_DNS_TYPE_RRSIG
¶ DNS Resource Record signature.
-
enumerator
PJ_DNS_TYPE_NSEC
¶ DNS Next Secure Name.
-
enumerator
PJ_DNS_TYPE_DNSKEY
¶ DNSSEC Key.
-
enumerator
-
enum
pj_dns_rcode
¶ These constants describe DNS RCODEs. Application can fold these constants into PJLIB pj_status_t namespace by calling PJ_STATUS_FROM_DNS_RCODE() macro.
Values:
-
enumerator
PJ_DNS_RCODE_FORMERR
¶ Format error.
-
enumerator
PJ_DNS_RCODE_SERVFAIL
¶ Server failure.
-
enumerator
PJ_DNS_RCODE_NXDOMAIN
¶ Name Error.
-
enumerator
PJ_DNS_RCODE_NOTIMPL
¶ Not Implemented.
-
enumerator
PJ_DNS_RCODE_REFUSED
¶ Refused.
-
enumerator
PJ_DNS_RCODE_YXDOMAIN
¶ The name exists.
-
enumerator
PJ_DNS_RCODE_YXRRSET
¶ The RRset (name, type) exists.
-
enumerator
PJ_DNS_RCODE_NXRRSET
¶ The RRset (name, type) doesn’t exist
-
enumerator
PJ_DNS_RCODE_NOTAUTH
¶ Not authorized.
-
enumerator
PJ_DNS_RCODE_NOTZONE
¶ The zone specified is not a zone.
-
enumerator
-
enum
pj_dns_dup_options
¶ Option flags to be specified when calling pj_dns_packet_dup() function. These flags can be combined with bitwise OR operation.
Values:
-
enumerator
PJ_DNS_NO_QD
¶ Do not duplicate the query section.
-
enumerator
PJ_DNS_NO_ANS
¶ Do not duplicate the answer section.
-
enumerator
PJ_DNS_NO_NS
¶ Do not duplicate the NS section.
-
enumerator
PJ_DNS_NO_AR
¶ Do not duplicate the additional rec section
-
enumerator
Functions
-
pj_status_t
pj_dns_make_query
(void *packet, unsigned *size, pj_uint16_t id, int qtype, const pj_str_t *name)¶ Create DNS query packet to resolve the specified names. This function can be used to build any types of DNS query, such as A record or DNS SRV record.
Application specifies the type of record and the name to be queried, and the function will build the DNS query packet into the buffer specified. Once the packet is successfully built, application can send the packet via TCP or UDP connection.
- Parameters
packet – The buffer to put the DNS query packet.
size – On input, it specifies the size of the buffer. On output, it will be filled with the actual size of the DNS query packet.
id – DNS query ID to associate DNS response with the query.
qtype – DNS type of record to be queried (see pj_dns_type).
name – Name to be queried from the DNS server.
- Returns
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t
pj_dns_parse_packet
(pj_pool_t *pool, const void *packet, unsigned size, pj_dns_parsed_packet **p_res)¶ Parse raw DNS packet into parsed DNS packet structure. This function is able to parse few DNS resource records such as A record, PTR record, CNAME record, NS record, and SRV record.
- Parameters
pool – Pool to allocate memory for the parsed packet.
packet – Pointer to the DNS packet (the TCP/UDP payload of the raw packet).
size – The size of the DNS packet.
p_res – Pointer to store the resulting parsed packet.
- Returns
PJ_SUCCESS on success, or the appropriate error code.
-
void
pj_dns_packet_dup
(pj_pool_t *pool, const pj_dns_parsed_packet *p, unsigned options, pj_dns_parsed_packet **p_dst)¶ Duplicate DNS packet.
- Parameters
pool – The pool to allocate memory for the duplicated packet.
p – The DNS packet to be cloned.
options – Option flags, from pj_dns_dup_options.
p_dst – Pointer to store the cloned DNS packet.
-
const char *
pj_dns_get_type_name
(int type)¶ Utility function to get the type name string of the specified DNS type.
- Parameters
type – DNS type (see pj_dns_type).
- Returns
String name of the type (e.g. “A”, “SRV”, etc.).
-
void
pj_dns_init_srv_rr
(pj_dns_parsed_rr *rec, const pj_str_t *res_name, unsigned dnsclass, unsigned ttl, unsigned prio, unsigned weight, unsigned port, const pj_str_t *target)¶ Initialize DNS record as DNS SRV record.
- Parameters
rec – The DNS resource record to be initialized as DNS SRV record.
res_name – Resource name.
dnsclass – DNS class.
ttl – Resource TTL value.
prio – DNS SRV priority.
weight – DNS SRV weight.
port – Target port.
target – Target name.
-
void
pj_dns_init_cname_rr
(pj_dns_parsed_rr *rec, const pj_str_t *res_name, unsigned dnsclass, unsigned ttl, const pj_str_t *name)¶ Initialize DNS record as DNS CNAME record.
- Parameters
rec – The DNS resource record to be initialized as DNS CNAME record.
res_name – Resource name.
dnsclass – DNS class.
ttl – Resource TTL value.
name – Host name.
-
void
pj_dns_init_a_rr
(pj_dns_parsed_rr *rec, const pj_str_t *res_name, unsigned dnsclass, unsigned ttl, const pj_in_addr *ip_addr)¶ Initialize DNS record as DNS A record.
- Parameters
rec – The DNS resource record to be initialized as DNS A record.
res_name – Resource name.
dnsclass – DNS class.
ttl – Resource TTL value.
ip_addr – Host address.
-
void
pj_dns_dump_packet
(const pj_dns_parsed_packet *res)¶ Dump DNS packet to standard log.
- Parameters
res – The DNS packet.
-
struct
pj_dns_hdr
¶ - #include <dns.h>
Standard DNS header, according to RFC 1035, which will be present in both DNS query and DNS response.
Note that all values seen by application would be in host by order. The library would convert them to network byte order as necessary.
-
struct
pj_dns_parsed_query
¶ - #include <dns.h>
This structure describes a DNS query record.
-
struct
pj_dns_parsed_rr
¶ - #include <dns.h>
This structure describes a Resource Record parsed from the DNS packet. All integral values are in host byte order.
-
struct
pj_dns_parsed_packet
¶ - #include <dns.h>
This structure describes the parsed repersentation of the raw DNS packet. Note that all integral values in the parsed packet are represented in host byte order.