pjlib-util/include/pjlib-util/dns.h

/* $Id$ */
/* 
 * Copyright (C) 2003-2007 Benny Prijono <benny@prijono.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
 */
#ifndef __PJLIB_UTIL_DNS_H__
#define __PJLIB_UTIL_DNS_H__


/**
 * @file dns.h
 * @brief Low level DNS message parsing and packetization.
 */
#include <pjlib-util/types.h>
#include <pj/sock.h>

PJ_BEGIN_DECL

/**
 * @defgroup PJ_DNS DNS and Asynchronous DNS Resolver
 * @ingroup PJLIB_UTIL
 */

/**
 * @defgroup PJ_DNS_PARSING Low-level DNS Message Parsing and Packetization
 * @ingroup PJ_DNS
 * @{
 *
 * 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 @ref PJ_DNS_RESOLVER.
 */

enum
{
    PJ_DNS_CLASS_IN	= 1	/**< DNS class IN.			    */
};

/**
 * This enumeration describes standard DNS record types as described by
 * RFC 1035, RFC 2782, and others.
 */
typedef enum pj_dns_type
{
    PJ_DNS_TYPE_A	= 1,    /**< Host address (A) record.		    */
    PJ_DNS_TYPE_NS	= 2,    /**< Authoritative name server (NS)	    */
    PJ_DNS_TYPE_MD	= 3,    /**< Mail destination (MD) record.	    */
    PJ_DNS_TYPE_MF	= 4,    /**< Mail forwarder (MF) record.	    */
    PJ_DNS_TYPE_CNAME	= 5,	/**< Canonical name (CNAME) record.	    */
    PJ_DNS_TYPE_SOA	= 6,    /**< Marks start of zone authority.	    */
    PJ_DNS_TYPE_MB	= 7,    /**< Mailbox domain name (MB).		    */
    PJ_DNS_TYPE_MG	= 8,    /**< Mail group member (MG).		    */
    PJ_DNS_TYPE_MR	= 9,    /**< Mail rename domain name.		    */
    PJ_DNS_TYPE_NULL	= 10,	/**< NULL RR.				    */
    PJ_DNS_TYPE_WKS	= 11,	/**< Well known service description	    */
    PJ_DNS_TYPE_PTR	= 12,	/**< Domain name pointer.		    */
    PJ_DNS_TYPE_HINFO	= 13,	/**< Host information.			    */
    PJ_DNS_TYPE_MINFO	= 14,	/**< Mailbox or mail list information.	    */
    PJ_DNS_TYPE_MX	= 15,	/**< Mail exchange record.		    */
    PJ_DNS_TYPE_TXT	= 16,	/**< Text string.			    */
    PJ_DNS_TYPE_RP	= 17,	/**< Responsible person.		    */
    PJ_DNS_TYPE_AFSB	= 18,	/**< AFS cell database.			    */
    PJ_DNS_TYPE_X25	= 19,	/**< X.25 calling address.		    */
    PJ_DNS_TYPE_ISDN	= 20,	/**< ISDN calling address.		    */
    PJ_DNS_TYPE_RT	= 21,	/**< Router.				    */
    PJ_DNS_TYPE_NSAP	= 22,	/**< NSAP address.			    */
    PJ_DNS_TYPE_NSAP_PTR= 23,	/**< NSAP reverse address.		    */
    PJ_DNS_TYPE_SIG	= 24,	/**< Signature.				    */
    PJ_DNS_TYPE_KEY	= 25,	/**< Key.				    */
    PJ_DNS_TYPE_PX	= 26,	/**< X.400 mail mapping.		    */
    PJ_DNS_TYPE_GPOS	= 27,	/**< Geographical position (withdrawn)	    */
    PJ_DNS_TYPE_AAAA	= 28,	/**< IPv6 address.			    */
    PJ_DNS_TYPE_LOC	= 29,	/**< Location.				    */
    PJ_DNS_TYPE_NXT	= 30,	/**< Next valid name in the zone.	    */
    PJ_DNS_TYPE_EID	= 31,	/**< Endpoint idenfitier.		    */
    PJ_DNS_TYPE_NIMLOC	= 32,	/**< Nimrod locator.			    */
    PJ_DNS_TYPE_SRV	= 33,	/**< Server selection (SRV) record.	    */
    PJ_DNS_TYPE_ATMA	= 34,	/**< DNS ATM address record.		    */
    PJ_DNS_TYPE_NAPTR	= 35,	/**< DNS Naming authority pointer record.   */
    PJ_DNS_TYPE_KX	= 36,	/**< DNS key exchange record.		    */
    PJ_DNS_TYPE_CERT	= 37,	/**< DNS certificate record.		    */
    PJ_DNS_TYPE_A6	= 38,	/**< DNS IPv6 address (experimental)	    */
    PJ_DNS_TYPE_DNAME	= 39,	/**< DNS non-terminal name redirection rec. */

    PJ_DNS_TYPE_OPT	= 41,	/**< DNS options - contains EDNS metadata.  */
    PJ_DNS_TYPE_APL	= 42,	/**< DNS Address Prefix List (APL) record.  */
    PJ_DNS_TYPE_DS	= 43,	/**< DNS Delegation Signer (DS)		    */
    PJ_DNS_TYPE_SSHFP	= 44,	/**< DNS SSH Key Fingerprint		    */
    PJ_DNS_TYPE_IPSECKEY= 45,	/**< DNS IPSEC Key.			    */
    PJ_DNS_TYPE_RRSIG	= 46,	/**< DNS Resource Record signature.	    */
    PJ_DNS_TYPE_NSEC	= 47,	/**< DNS Next Secure Name.		    */
    PJ_DNS_TYPE_DNSKEY	= 48	/**< DNSSEC Key.			    */
} pj_dns_type;



/**
 * 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.
 */
typedef struct pj_dns_hdr
{
    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  */
} pj_dns_hdr;

/** Create RCODE flag */
#define PJ_DNS_SET_RCODE(c)	((pj_uint16_t)((c) & 0x0F))

/** Create RA (Recursion Available) bit */
#define PJ_DNS_SET_RA(on)	((pj_uint16_t)((on) << 7))

/** Create RD (Recursion Desired) bit */
#define PJ_DNS_SET_RD(on)	((pj_uint16_t)((on) << 8))

/** Create TC (Truncated) bit */
#define PJ_DNS_SET_TC(on)	((pj_uint16_t)((on) << 9))

/** Create AA (Authoritative Answer) bit */
#define PJ_DNS_SET_AA(on)	((pj_uint16_t)((on) << 10))

/** Create four bits opcode */
#define PJ_DNS_SET_OPCODE(o)	((pj_uint16_t)((o)  << 11))

/** Create query/response bit */
#define PJ_DNS_SET_QR(on)	((pj_uint16_t)((on) << 15))


/** Get RCODE value */
#define PJ_DNS_GET_RCODE(val)	(((val) & PJ_DNS_SET_RCODE(0x0F)) >> 0)

/** Get RA bit */
#define PJ_DNS_GET_RA(val)	(((val) & PJ_DNS_SET_RA(1)) >> 7)

/** Get RD bit */
#define PJ_DNS_GET_RD(val)	(((val) & PJ_DNS_SET_RD(1)) >> 8)

/** Get TC bit */
#define PJ_DNS_GET_TC(val)	(((val) & PJ_DNS_SET_TC(1)) >> 9)

/** Get AA bit */
#define PJ_DNS_GET_AA(val)	(((val) & PJ_DNS_SET_AA(1)) >> 10)

/** Get OPCODE value */
#define PJ_DNS_GET_OPCODE(val)	(((val) & PJ_DNS_SET_OPCODE(0x0F)) >> 11)

/** Get QR bit */
#define PJ_DNS_GET_QR(val)	(((val) & PJ_DNS_SET_QR(1)) >> 15)


/** 
 * These constants describe DNS RCODEs. Application can fold these constants
 * into PJLIB pj_status_t namespace by calling #PJ_STATUS_FROM_DNS_RCODE()
 * macro.
 */
typedef enum pj_dns_rcode
{
    PJ_DNS_RCODE_FORMERR    = 1,    /**< Format error.			    */
    PJ_DNS_RCODE_SERVFAIL   = 2,    /**< Server failure.		    */
    PJ_DNS_RCODE_NXDOMAIN   = 3,    /**< Name Error.			    */
    PJ_DNS_RCODE_NOTIMPL    = 4,    /**< Not Implemented.		    */
    PJ_DNS_RCODE_REFUSED    = 5,    /**< Refused.			    */
    PJ_DNS_RCODE_YXDOMAIN   = 6,    /**< The name exists.		    */
    PJ_DNS_RCODE_YXRRSET    = 7,    /**< The RRset (name, type) exists.	    */
    PJ_DNS_RCODE_NXRRSET    = 8,    /**< The RRset (name, type) doesn't exist*/
    PJ_DNS_RCODE_NOTAUTH    = 9,    /**< Not authorized.		    */
    PJ_DNS_RCODE_NOTZONE    = 10    /**< The zone specified is not a zone.  */

} pj_dns_rcode;


/**
 * This structure describes a DNS query record.
 */
typedef struct pj_dns_parsed_query
{
    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)	    */
} pj_dns_parsed_query;


/**
 * This structure describes a Resource Record parsed from the DNS packet.
 * All integral values are in host byte order.
 */
typedef struct pj_dns_parsed_rr
{
    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.	    */
    
    /** For resource types that are recognized/supported by this library,
     *  the parsed resource data will be placed in this rdata union.
     */
    union rdata
    {
	/** SRV Resource Data (PJ_DNS_TYPE_SRV, 33) */
	struct srv {
	    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.			    */
	} srv;

	/** CNAME Resource Data (PJ_DNS_TYPE_CNAME, 5) */
	struct cname {
	    pj_str_t	name;	/**< Primary canonical name for an alias.   */
	} cname;

	/** NS Resource Data (PJ_DNS_TYPE_NS, 2) */
	struct ns {
	    pj_str_t	name;	/**< Primary name server.		    */
	} ns;

	/** PTR Resource Data (PJ_DNS_TYPE_PTR, 12) */
	struct ptr {
	    pj_str_t	name;	/**< PTR name.				    */
	} ptr;

	/** A Resource Data (PJ_DNS_TYPE_A, 1) */
	struct a {
	    pj_in_addr	ip_addr;/**< IPv4 address in network byte order.    */
	} a;

	/** AAAA Resource Data (PJ_DNS_TYPE_AAAA, 28) */
	struct aaaa {
	    pj_in6_addr	ip_addr;/**< IPv6 address in network byte order.    */
	} aaaa;

    } rdata;

} pj_dns_parsed_rr;


/**
 * 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.
 */
typedef struct pj_dns_parsed_packet
{
    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.	    */
} pj_dns_parsed_packet;


/**
 * Option flags to be specified when calling #pj_dns_packet_dup() function.
 * These flags can be combined with bitwise OR operation.
 */
enum pj_dns_dup_options
{
    PJ_DNS_NO_QD    = 1, /**< Do not duplicate the query section.	    */
    PJ_DNS_NO_ANS   = 2, /**< Do not duplicate the answer section.	    */
    PJ_DNS_NO_NS    = 4, /**< Do not duplicate the NS section.		    */
    PJ_DNS_NO_AR    = 8  /**< Do not duplicate the additional rec section   */
};


/**
 * 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.
 *
 * @param packet	The buffer to put the DNS query packet.
 * @param 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.
 * @param id		DNS query ID to associate DNS response with the
 *			query.
 * @param qtype		DNS type of record to be queried (see #pj_dns_type).
 * @param name		Name to be queried from the DNS server.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 */
PJ_DECL(pj_status_t) pj_dns_make_query(void *packet,
				       unsigned *size,
				       pj_uint16_t id,
				       int qtype,
				       const pj_str_t *name);

/**
 * 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.
 *
 * @param pool		Pool to allocate memory for the parsed packet.
 * @param packet	Pointer to the DNS packet (the TCP/UDP payload of 
 *			the raw packet).
 * @param size		The size of the DNS packet.
 * @param p_res		Pointer to store the resulting parsed packet.
 *
 * @return		PJ_SUCCESS on success, or the appropriate error code.
 */
PJ_DECL(pj_status_t) pj_dns_parse_packet(pj_pool_t *pool,
					 const void *packet,
					 unsigned size,
					 pj_dns_parsed_packet **p_res);

/**
 * Duplicate DNS packet.
 *
 * @param pool		The pool to allocate memory for the duplicated packet.
 * @param p		The DNS packet to be cloned.
 * @param options	Option flags, from pj_dns_dup_options.
 * @param p_dst		Pointer to store the cloned DNS packet.
 */
PJ_DECL(void) pj_dns_packet_dup(pj_pool_t *pool,
				const pj_dns_parsed_packet*p,
				unsigned options,
				pj_dns_parsed_packet **p_dst);


/**
 * Utility function to get the type name string of the specified DNS type.
 *
 * @param type		DNS type (see #pj_dns_type).
 *
 * @return		String name of the type (e.g. "A", "SRV", etc.).
 */
PJ_DECL(const char *) pj_dns_get_type_name(int type);


/**
 * Dump DNS packet to standard log.
 *
 * @param res		The DNS packet.
 */
PJ_DECL(void) pj_dns_dump_packet(const pj_dns_parsed_packet *res);


/**
 * @}
 */

PJ_END_DECL


#endif	/* __PJLIB_UTIL_DNS_H__ */