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 [anonymous]

Values:

enumerator PJ_DNS_CLASS_IN

DNS class IN.

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.

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.

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

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_init_aaaa_rr(pj_dns_parsed_rr *rec, const pj_str_t *res_name, unsigned dnsclass, unsigned ttl, const pj_in6_addr *ip_addr)

Initialize DNS record as DNS AAAA record.

Parameters:

• rec – The DNS resource record to be initialized as DNS AAAA 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.

Public Members

pj_uint16_t id

Transaction ID.

pj_uint16_t flags

Flags.

pj_uint16_t qdcount

Nb. of queries.

pj_uint16_t anscount

Nb. of res records

pj_uint16_t nscount

Nb. of NS records.

pj_uint16_t arcount

Nb. of additional records

struct pj_dns_parsed_query

#include <dns.h>

This structure describes a DNS query record.

Public Members

pj_str_t name

The domain in the query.

pj_uint16_t type

Type of the query (pj_dns_type)

pj_uint16_t dnsclass

Network class (PJ_DNS_CLASS_IN=1)

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.

Public Members

pj_str_t name

The domain name which this rec pertains.

pj_uint16_t type

RR type code.

pj_uint16_t dnsclass

Class of data (PJ_DNS_CLASS_IN=1).

pj_uint32_t ttl

Time to live.

pj_uint16_t rdlength

Resource data length.

void *data

Pointer to the raw resource data, only when the type is not known. If it is known, the data will be put in rdata below.

union rdata

#include <dns.h>

For resource types that are recognized/supported by this library, the parsed resource data will be placed in this rdata union.

Public Members

struct pj_dns_parsed_rr::rdata::srv srv

SRV Resource Data (PJ_DNS_TYPE_SRV, 33)

struct pj_dns_parsed_rr::rdata::cname cname

CNAME Resource Data (PJ_DNS_TYPE_CNAME, 5)

struct pj_dns_parsed_rr::rdata::ns ns

NS Resource Data (PJ_DNS_TYPE_NS, 2)

struct pj_dns_parsed_rr::rdata::ptr ptr

PTR Resource Data (PJ_DNS_TYPE_PTR, 12)

struct pj_dns_parsed_rr::rdata::a a

A Resource Data (PJ_DNS_TYPE_A, 1)

struct pj_dns_parsed_rr::rdata::aaaa aaaa

AAAA Resource Data (PJ_DNS_TYPE_AAAA, 28)

struct a

#include <dns.h>

A Resource Data (PJ_DNS_TYPE_A, 1)

Public Members

pj_in_addr ip_addr

IPv4 address in network byte order.

struct aaaa

#include <dns.h>

AAAA Resource Data (PJ_DNS_TYPE_AAAA, 28)

Public Members

pj_in6_addr ip_addr

IPv6 address in network byte order.

struct cname

#include <dns.h>

CNAME Resource Data (PJ_DNS_TYPE_CNAME, 5)

Public Members

pj_str_t name

Primary canonical name for an alias.

struct ns

#include <dns.h>

NS Resource Data (PJ_DNS_TYPE_NS, 2)

Public Members

pj_str_t name

Primary name server.

struct ptr

#include <dns.h>

PTR Resource Data (PJ_DNS_TYPE_PTR, 12)

Public Members

pj_str_t name

PTR name.

struct srv

#include <dns.h>

SRV Resource Data (PJ_DNS_TYPE_SRV, 33)

Public Members

pj_uint16_t prio

Target priority (lower is higher).

pj_uint16_t weight

Weight/proportion

pj_uint16_t port

Port number of the service

pj_str_t target

Target name.

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.

Public Members

pj_dns_hdr hdr

Pointer to DNS hdr, in host byte order

pj_dns_parsed_query *q

Array of DNS queries.

pj_dns_parsed_rr *ans

Array of DNS RR answer.

pj_dns_parsed_rr *ns

Array of NS record in the answer.

pj_dns_parsed_rr *arr

Array of additional RR answer.