/usr/include/pjlib-util/dns.h is in libpjproject-dev 2.1.0.0.ast20130823-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 | /* $Id: dns.h 3553 2011-05-05 06:14:19Z nanang $ */
/*
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
* Copyright (C) 2003-2008 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 PJ_PROTOCOLS
*/
/**
* @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);
/**
* Initialize DNS record as DNS SRV record.
*
* @param rec The DNS resource record to be initialized as DNS
* SRV record.
* @param res_name Resource name.
* @param dnsclass DNS class.
* @param ttl Resource TTL value.
* @param prio DNS SRV priority.
* @param weight DNS SRV weight.
* @param port Target port.
* @param target Target name.
*/
PJ_DECL(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 CNAME record.
*
* @param rec The DNS resource record to be initialized as DNS
* CNAME record.
* @param res_name Resource name.
* @param dnsclass DNS class.
* @param ttl Resource TTL value.
* @param name Host name.
*/
PJ_DECL(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 A record.
*
* @param rec The DNS resource record to be initialized as DNS
* A record.
* @param res_name Resource name.
* @param dnsclass DNS class.
* @param ttl Resource TTL value.
* @param ip_addr Host address.
*/
PJ_DECL(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);
/**
* 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__ */
|