/contrib/bind9/lib/dns/include/dns/name.h

https://bitbucket.org/freebsd/freebsd-head/ · C Header · 1362 lines · 220 code · 93 blank · 1049 comment · 11 complexity · 5dcc098f4575c60734974d9ebf468d5b MD5 · raw file

  1. /*
  2. * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC")
  3. * Copyright (C) 1998-2003 Internet Software Consortium.
  4. *
  5. * Permission to use, copy, modify, and/or distribute this software for any
  6. * purpose with or without fee is hereby granted, provided that the above
  7. * copyright notice and this permission notice appear in all copies.
  8. *
  9. * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10. * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11. * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12. * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13. * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14. * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15. * PERFORMANCE OF THIS SOFTWARE.
  16. */
  17. /* $Id: name.h,v 1.137 2011/01/13 04:59:26 tbox Exp $ */
  18. #ifndef DNS_NAME_H
  19. #define DNS_NAME_H 1
  20. /*****
  21. ***** Module Info
  22. *****/
  23. /*! \file dns/name.h
  24. * \brief
  25. * Provides facilities for manipulating DNS names and labels, including
  26. * conversions to and from wire format and text format.
  27. *
  28. * Given the large number of names possible in a nameserver, and because
  29. * names occur in rdata, it was important to come up with a very efficient
  30. * way of storing name data, but at the same time allow names to be
  31. * manipulated. The decision was to store names in uncompressed wire format,
  32. * and not to make them fully abstracted objects; i.e. certain parts of the
  33. * server know names are stored that way. This saves a lot of memory, and
  34. * makes adding names to messages easy. Having much of the server know
  35. * the representation would be perilous, and we certainly don't want each
  36. * user of names to be manipulating such a low-level structure. This is
  37. * where the Names and Labels module comes in. The module allows name or
  38. * label handles to be created and attached to uncompressed wire format
  39. * regions. All name operations and conversions are done through these
  40. * handles.
  41. *
  42. * MP:
  43. *\li Clients of this module must impose any required synchronization.
  44. *
  45. * Reliability:
  46. *\li This module deals with low-level byte streams. Errors in any of
  47. * the functions are likely to crash the server or corrupt memory.
  48. *
  49. * Resources:
  50. *\li None.
  51. *
  52. * Security:
  53. *
  54. *\li *** WARNING ***
  55. *
  56. *\li dns_name_fromwire() deals with raw network data. An error in
  57. * this routine could result in the failure or hijacking of the server.
  58. *
  59. * Standards:
  60. *\li RFC1035
  61. *\li Draft EDNS0 (0)
  62. *\li Draft Binary Labels (2)
  63. *
  64. */
  65. /***
  66. *** Imports
  67. ***/
  68. #include <stdio.h>
  69. #include <isc/boolean.h>
  70. #include <isc/lang.h>
  71. #include <isc/magic.h>
  72. #include <isc/region.h> /* Required for storage size of dns_label_t. */
  73. #include <dns/types.h>
  74. ISC_LANG_BEGINDECLS
  75. /*****
  76. ***** Labels
  77. *****
  78. ***** A 'label' is basically a region. It contains one DNS wire format
  79. ***** label of type 00 (ordinary).
  80. *****/
  81. /*****
  82. ***** Names
  83. *****
  84. ***** A 'name' is a handle to a binary region. It contains a sequence of one
  85. ***** or more DNS wire format labels of type 00 (ordinary).
  86. ***** Note that all names are not required to end with the root label,
  87. ***** as they are in the actual DNS wire protocol.
  88. *****/
  89. /***
  90. *** Types
  91. ***/
  92. /*%
  93. * Clients are strongly discouraged from using this type directly, with
  94. * the exception of the 'link' and 'list' fields which may be used directly
  95. * for whatever purpose the client desires.
  96. */
  97. struct dns_name {
  98. unsigned int magic;
  99. unsigned char * ndata;
  100. unsigned int length;
  101. unsigned int labels;
  102. unsigned int attributes;
  103. unsigned char * offsets;
  104. isc_buffer_t * buffer;
  105. ISC_LINK(dns_name_t) link;
  106. ISC_LIST(dns_rdataset_t) list;
  107. };
  108. #define DNS_NAME_MAGIC ISC_MAGIC('D','N','S','n')
  109. #define DNS_NAMEATTR_ABSOLUTE 0x00000001
  110. #define DNS_NAMEATTR_READONLY 0x00000002
  111. #define DNS_NAMEATTR_DYNAMIC 0x00000004
  112. #define DNS_NAMEATTR_DYNOFFSETS 0x00000008
  113. #define DNS_NAMEATTR_NOCOMPRESS 0x00000010
  114. /*
  115. * Attributes below 0x0100 reserved for name.c usage.
  116. */
  117. #define DNS_NAMEATTR_CACHE 0x00000100 /*%< Used by resolver. */
  118. #define DNS_NAMEATTR_ANSWER 0x00000200 /*%< Used by resolver. */
  119. #define DNS_NAMEATTR_NCACHE 0x00000400 /*%< Used by resolver. */
  120. #define DNS_NAMEATTR_CHAINING 0x00000800 /*%< Used by resolver. */
  121. #define DNS_NAMEATTR_CHASE 0x00001000 /*%< Used by resolver. */
  122. #define DNS_NAMEATTR_WILDCARD 0x00002000 /*%< Used by server. */
  123. #define DNS_NAMEATTR_PREREQUISITE 0x00004000 /*%< Used by client. */
  124. #define DNS_NAMEATTR_UPDATE 0x00008000 /*%< Used by client. */
  125. #define DNS_NAMEATTR_HASUPDATEREC 0x00010000 /*%< Used by client. */
  126. /*
  127. * Various flags.
  128. */
  129. #define DNS_NAME_DOWNCASE 0x0001
  130. #define DNS_NAME_CHECKNAMES 0x0002 /*%< Used by rdata. */
  131. #define DNS_NAME_CHECKNAMESFAIL 0x0004 /*%< Used by rdata. */
  132. #define DNS_NAME_CHECKREVERSE 0x0008 /*%< Used by rdata. */
  133. #define DNS_NAME_CHECKMX 0x0010 /*%< Used by rdata. */
  134. #define DNS_NAME_CHECKMXFAIL 0x0020 /*%< Used by rdata. */
  135. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_rootname;
  136. LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_wildcardname;
  137. /*%
  138. * Standard size of a wire format name
  139. */
  140. #define DNS_NAME_MAXWIRE 255
  141. /*
  142. * Text output filter procedure.
  143. * 'target' is the buffer to be converted. The region to be converted
  144. * is from 'buffer'->base + 'used_org' to the end of the used region.
  145. */
  146. typedef isc_result_t (*dns_name_totextfilter_t)(isc_buffer_t *target,
  147. unsigned int used_org,
  148. isc_boolean_t absolute);
  149. /***
  150. *** Initialization
  151. ***/
  152. void
  153. dns_name_init(dns_name_t *name, unsigned char *offsets);
  154. /*%<
  155. * Initialize 'name'.
  156. *
  157. * Notes:
  158. * \li 'offsets' is never required to be non-NULL, but specifying a
  159. * dns_offsets_t for 'offsets' will improve the performance of most
  160. * name operations if the name is used more than once.
  161. *
  162. * Requires:
  163. * \li 'name' is not NULL and points to a struct dns_name.
  164. *
  165. * \li offsets == NULL or offsets is a dns_offsets_t.
  166. *
  167. * Ensures:
  168. * \li 'name' is a valid name.
  169. * \li dns_name_countlabels(name) == 0
  170. * \li dns_name_isabsolute(name) == ISC_FALSE
  171. */
  172. void
  173. dns_name_reset(dns_name_t *name);
  174. /*%<
  175. * Reinitialize 'name'.
  176. *
  177. * Notes:
  178. * \li This function distinguishes itself from dns_name_init() in two
  179. * key ways:
  180. *
  181. * \li + If any buffer is associated with 'name' (via dns_name_setbuffer()
  182. * or by being part of a dns_fixedname_t) the link to the buffer
  183. * is retained but the buffer itself is cleared.
  184. *
  185. * \li + Of the attributes associated with 'name', all are retained except
  186. * DNS_NAMEATTR_ABSOLUTE.
  187. *
  188. * Requires:
  189. * \li 'name' is a valid name.
  190. *
  191. * Ensures:
  192. * \li 'name' is a valid name.
  193. * \li dns_name_countlabels(name) == 0
  194. * \li dns_name_isabsolute(name) == ISC_FALSE
  195. */
  196. void
  197. dns_name_invalidate(dns_name_t *name);
  198. /*%<
  199. * Make 'name' invalid.
  200. *
  201. * Requires:
  202. * \li 'name' is a valid name.
  203. *
  204. * Ensures:
  205. * \li If assertion checking is enabled, future attempts to use 'name'
  206. * without initializing it will cause an assertion failure.
  207. *
  208. * \li If the name had a dedicated buffer, that association is ended.
  209. */
  210. /***
  211. *** Dedicated Buffers
  212. ***/
  213. void
  214. dns_name_setbuffer(dns_name_t *name, isc_buffer_t *buffer);
  215. /*%<
  216. * Dedicate a buffer for use with 'name'.
  217. *
  218. * Notes:
  219. * \li Specification of a target buffer in dns_name_fromwire(),
  220. * dns_name_fromtext(), and dns_name_concatenate() is optional if
  221. * 'name' has a dedicated buffer.
  222. *
  223. * \li The caller must not write to buffer until the name has been
  224. * invalidated or is otherwise known not to be in use.
  225. *
  226. * \li If buffer is NULL and the name previously had a dedicated buffer,
  227. * than that buffer is no longer dedicated to use with this name.
  228. * The caller is responsible for ensuring that the storage used by
  229. * the name remains valid.
  230. *
  231. * Requires:
  232. * \li 'name' is a valid name.
  233. *
  234. * \li 'buffer' is a valid binary buffer and 'name' doesn't have a
  235. * dedicated buffer already, or 'buffer' is NULL.
  236. */
  237. isc_boolean_t
  238. dns_name_hasbuffer(const dns_name_t *name);
  239. /*%<
  240. * Does 'name' have a dedicated buffer?
  241. *
  242. * Requires:
  243. * \li 'name' is a valid name.
  244. *
  245. * Returns:
  246. * \li ISC_TRUE 'name' has a dedicated buffer.
  247. * \li ISC_FALSE 'name' does not have a dedicated buffer.
  248. */
  249. /***
  250. *** Properties
  251. ***/
  252. isc_boolean_t
  253. dns_name_isabsolute(const dns_name_t *name);
  254. /*%<
  255. * Does 'name' end in the root label?
  256. *
  257. * Requires:
  258. * \li 'name' is a valid name
  259. *
  260. * Returns:
  261. * \li TRUE The last label in 'name' is the root label.
  262. * \li FALSE The last label in 'name' is not the root label.
  263. */
  264. isc_boolean_t
  265. dns_name_iswildcard(const dns_name_t *name);
  266. /*%<
  267. * Is 'name' a wildcard name?
  268. *
  269. * Requires:
  270. * \li 'name' is a valid name
  271. *
  272. * \li dns_name_countlabels(name) > 0
  273. *
  274. * Returns:
  275. * \li TRUE The least significant label of 'name' is '*'.
  276. * \li FALSE The least significant label of 'name' is not '*'.
  277. */
  278. unsigned int
  279. dns_name_hash(dns_name_t *name, isc_boolean_t case_sensitive);
  280. /*%<
  281. * Provide a hash value for 'name'.
  282. *
  283. * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
  284. * case will have the same hash value.
  285. *
  286. * Requires:
  287. * \li 'name' is a valid name
  288. *
  289. * Returns:
  290. * \li A hash value
  291. */
  292. unsigned int
  293. dns_name_fullhash(dns_name_t *name, isc_boolean_t case_sensitive);
  294. /*%<
  295. * Provide a hash value for 'name'. Unlike dns_name_hash(), this function
  296. * always takes into account of the entire name to calculate the hash value.
  297. *
  298. * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
  299. * case will have the same hash value.
  300. *
  301. * Requires:
  302. *\li 'name' is a valid name
  303. *
  304. * Returns:
  305. *\li A hash value
  306. */
  307. unsigned int
  308. dns_name_hashbylabel(dns_name_t *name, isc_boolean_t case_sensitive);
  309. /*%<
  310. * Provide a hash value for 'name', where the hash value is the sum
  311. * of the hash values of each label.
  312. *
  313. * Note: if 'case_sensitive' is ISC_FALSE, then names which differ only in
  314. * case will have the same hash value.
  315. *
  316. * Requires:
  317. *\li 'name' is a valid name
  318. *
  319. * Returns:
  320. *\li A hash value
  321. */
  322. /*
  323. *** Comparisons
  324. ***/
  325. dns_namereln_t
  326. dns_name_fullcompare(const dns_name_t *name1, const dns_name_t *name2,
  327. int *orderp, unsigned int *nlabelsp);
  328. /*%<
  329. * Determine the relative ordering under the DNSSEC order relation of
  330. * 'name1' and 'name2', and also determine the hierarchical
  331. * relationship of the names.
  332. *
  333. * Note: It makes no sense for one of the names to be relative and the
  334. * other absolute. If both names are relative, then to be meaningfully
  335. * compared the caller must ensure that they are both relative to the
  336. * same domain.
  337. *
  338. * Requires:
  339. *\li 'name1' is a valid name
  340. *
  341. *\li dns_name_countlabels(name1) > 0
  342. *
  343. *\li 'name2' is a valid name
  344. *
  345. *\li dns_name_countlabels(name2) > 0
  346. *
  347. *\li orderp and nlabelsp are valid pointers.
  348. *
  349. *\li Either name1 is absolute and name2 is absolute, or neither is.
  350. *
  351. * Ensures:
  352. *
  353. *\li *orderp is < 0 if name1 < name2, 0 if name1 = name2, > 0 if
  354. * name1 > name2.
  355. *
  356. *\li *nlabelsp is the number of common significant labels.
  357. *
  358. * Returns:
  359. *\li dns_namereln_none There's no hierarchical relationship
  360. * between name1 and name2.
  361. *\li dns_namereln_contains name1 properly contains name2; i.e.
  362. * name2 is a proper subdomain of name1.
  363. *\li dns_namereln_subdomain name1 is a proper subdomain of name2.
  364. *\li dns_namereln_equal name1 and name2 are equal.
  365. *\li dns_namereln_commonancestor name1 and name2 share a common
  366. * ancestor.
  367. */
  368. int
  369. dns_name_compare(const dns_name_t *name1, const dns_name_t *name2);
  370. /*%<
  371. * Determine the relative ordering under the DNSSEC order relation of
  372. * 'name1' and 'name2'.
  373. *
  374. * Note: It makes no sense for one of the names to be relative and the
  375. * other absolute. If both names are relative, then to be meaningfully
  376. * compared the caller must ensure that they are both relative to the
  377. * same domain.
  378. *
  379. * Requires:
  380. * \li 'name1' is a valid name
  381. *
  382. * \li 'name2' is a valid name
  383. *
  384. * \li Either name1 is absolute and name2 is absolute, or neither is.
  385. *
  386. * Returns:
  387. * \li < 0 'name1' is less than 'name2'
  388. * \li 0 'name1' is equal to 'name2'
  389. * \li > 0 'name1' is greater than 'name2'
  390. */
  391. isc_boolean_t
  392. dns_name_equal(const dns_name_t *name1, const dns_name_t *name2);
  393. /*%<
  394. * Are 'name1' and 'name2' equal?
  395. *
  396. * Notes:
  397. * \li Because it only needs to test for equality, dns_name_equal() can be
  398. * significantly faster than dns_name_fullcompare() or dns_name_compare().
  399. *
  400. * \li Offsets tables are not used in the comparision.
  401. *
  402. * \li It makes no sense for one of the names to be relative and the
  403. * other absolute. If both names are relative, then to be meaningfully
  404. * compared the caller must ensure that they are both relative to the
  405. * same domain.
  406. *
  407. * Requires:
  408. * \li 'name1' is a valid name
  409. *
  410. * \li 'name2' is a valid name
  411. *
  412. * \li Either name1 is absolute and name2 is absolute, or neither is.
  413. *
  414. * Returns:
  415. * \li ISC_TRUE 'name1' and 'name2' are equal
  416. * \li ISC_FALSE 'name1' and 'name2' are not equal
  417. */
  418. isc_boolean_t
  419. dns_name_caseequal(const dns_name_t *name1, const dns_name_t *name2);
  420. /*%<
  421. * Case sensitive version of dns_name_equal().
  422. */
  423. int
  424. dns_name_rdatacompare(const dns_name_t *name1, const dns_name_t *name2);
  425. /*%<
  426. * Compare two names as if they are part of rdata in DNSSEC canonical
  427. * form.
  428. *
  429. * Requires:
  430. * \li 'name1' is a valid absolute name
  431. *
  432. * \li dns_name_countlabels(name1) > 0
  433. *
  434. * \li 'name2' is a valid absolute name
  435. *
  436. * \li dns_name_countlabels(name2) > 0
  437. *
  438. * Returns:
  439. * \li < 0 'name1' is less than 'name2'
  440. * \li 0 'name1' is equal to 'name2'
  441. * \li > 0 'name1' is greater than 'name2'
  442. */
  443. isc_boolean_t
  444. dns_name_issubdomain(const dns_name_t *name1, const dns_name_t *name2);
  445. /*%<
  446. * Is 'name1' a subdomain of 'name2'?
  447. *
  448. * Notes:
  449. * \li name1 is a subdomain of name2 if name1 is contained in name2, or
  450. * name1 equals name2.
  451. *
  452. * \li It makes no sense for one of the names to be relative and the
  453. * other absolute. If both names are relative, then to be meaningfully
  454. * compared the caller must ensure that they are both relative to the
  455. * same domain.
  456. *
  457. * Requires:
  458. * \li 'name1' is a valid name
  459. *
  460. * \li 'name2' is a valid name
  461. *
  462. * \li Either name1 is absolute and name2 is absolute, or neither is.
  463. *
  464. * Returns:
  465. * \li TRUE 'name1' is a subdomain of 'name2'
  466. * \li FALSE 'name1' is not a subdomain of 'name2'
  467. */
  468. isc_boolean_t
  469. dns_name_matcheswildcard(const dns_name_t *name, const dns_name_t *wname);
  470. /*%<
  471. * Does 'name' match the wildcard specified in 'wname'?
  472. *
  473. * Notes:
  474. * \li name matches the wildcard specified in wname if all labels
  475. * following the wildcard in wname are identical to the same number
  476. * of labels at the end of name.
  477. *
  478. * \li It makes no sense for one of the names to be relative and the
  479. * other absolute. If both names are relative, then to be meaningfully
  480. * compared the caller must ensure that they are both relative to the
  481. * same domain.
  482. *
  483. * Requires:
  484. * \li 'name' is a valid name
  485. *
  486. * \li dns_name_countlabels(name) > 0
  487. *
  488. * \li 'wname' is a valid name
  489. *
  490. * \li dns_name_countlabels(wname) > 0
  491. *
  492. * \li dns_name_iswildcard(wname) is true
  493. *
  494. * \li Either name is absolute and wname is absolute, or neither is.
  495. *
  496. * Returns:
  497. * \li TRUE 'name' matches the wildcard specified in 'wname'
  498. * \li FALSE 'name' does not match the wildcard specified in 'wname'
  499. */
  500. /***
  501. *** Labels
  502. ***/
  503. unsigned int
  504. dns_name_countlabels(const dns_name_t *name);
  505. /*%<
  506. * How many labels does 'name' have?
  507. *
  508. * Notes:
  509. * \li In this case, as in other places, a 'label' is an ordinary label.
  510. *
  511. * Requires:
  512. * \li 'name' is a valid name
  513. *
  514. * Ensures:
  515. * \li The result is <= 128.
  516. *
  517. * Returns:
  518. * \li The number of labels in 'name'.
  519. */
  520. void
  521. dns_name_getlabel(const dns_name_t *name, unsigned int n, dns_label_t *label);
  522. /*%<
  523. * Make 'label' refer to the 'n'th least significant label of 'name'.
  524. *
  525. * Notes:
  526. * \li Numbering starts at 0.
  527. *
  528. * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
  529. * root label.
  530. *
  531. * \li 'label' refers to the same memory as 'name', so 'name' must not
  532. * be changed while 'label' is still in use.
  533. *
  534. * Requires:
  535. * \li n < dns_name_countlabels(name)
  536. */
  537. void
  538. dns_name_getlabelsequence(const dns_name_t *source, unsigned int first,
  539. unsigned int n, dns_name_t *target);
  540. /*%<
  541. * Make 'target' refer to the 'n' labels including and following 'first'
  542. * in 'source'.
  543. *
  544. * Notes:
  545. * \li Numbering starts at 0.
  546. *
  547. * \li Given "rc.vix.com.", the label 0 is "rc", and label 3 is the
  548. * root label.
  549. *
  550. * \li 'target' refers to the same memory as 'source', so 'source'
  551. * must not be changed while 'target' is still in use.
  552. *
  553. * Requires:
  554. * \li 'source' and 'target' are valid names.
  555. *
  556. * \li first < dns_name_countlabels(name)
  557. *
  558. * \li first + n <= dns_name_countlabels(name)
  559. */
  560. void
  561. dns_name_clone(const dns_name_t *source, dns_name_t *target);
  562. /*%<
  563. * Make 'target' refer to the same name as 'source'.
  564. *
  565. * Notes:
  566. *
  567. * \li 'target' refers to the same memory as 'source', so 'source'
  568. * must not be changed while 'target' is still in use.
  569. *
  570. * \li This call is functionally equivalent to:
  571. *
  572. * \code
  573. * dns_name_getlabelsequence(source, 0,
  574. * dns_name_countlabels(source),
  575. * target);
  576. * \endcode
  577. *
  578. * but is more efficient. Also, dns_name_clone() works even if 'source'
  579. * is empty.
  580. *
  581. * Requires:
  582. *
  583. * \li 'source' is a valid name.
  584. *
  585. * \li 'target' is a valid name that is not read-only.
  586. */
  587. /***
  588. *** Conversions
  589. ***/
  590. void
  591. dns_name_fromregion(dns_name_t *name, const isc_region_t *r);
  592. /*%<
  593. * Make 'name' refer to region 'r'.
  594. *
  595. * Note:
  596. * \li If the conversion encounters a root label before the end of the
  597. * region the conversion stops and the length is set to the length
  598. * so far converted. A maximum of 255 bytes is converted.
  599. *
  600. * Requires:
  601. * \li The data in 'r' is a sequence of one or more type 00 or type 01000001
  602. * labels.
  603. */
  604. void
  605. dns_name_toregion(dns_name_t *name, isc_region_t *r);
  606. /*%<
  607. * Make 'r' refer to 'name'.
  608. *
  609. * Requires:
  610. *
  611. * \li 'name' is a valid name.
  612. *
  613. * \li 'r' is a valid region.
  614. */
  615. isc_result_t
  616. dns_name_fromwire(dns_name_t *name, isc_buffer_t *source,
  617. dns_decompress_t *dctx, unsigned int options,
  618. isc_buffer_t *target);
  619. /*%<
  620. * Copy the possibly-compressed name at source (active region) into target,
  621. * decompressing it.
  622. *
  623. * Notes:
  624. * \li Decompression policy is controlled by 'dctx'.
  625. *
  626. * \li If DNS_NAME_DOWNCASE is set, any uppercase letters in 'source' will be
  627. * downcased when they are copied into 'target'.
  628. *
  629. * Security:
  630. *
  631. * \li *** WARNING ***
  632. *
  633. * \li This routine will often be used when 'source' contains raw network
  634. * data. A programming error in this routine could result in a denial
  635. * of service, or in the hijacking of the server.
  636. *
  637. * Requires:
  638. *
  639. * \li 'name' is a valid name.
  640. *
  641. * \li 'source' is a valid buffer and the first byte of the active
  642. * region should be the first byte of a DNS wire format domain name.
  643. *
  644. * \li 'target' is a valid buffer or 'target' is NULL and 'name' has
  645. * a dedicated buffer.
  646. *
  647. * \li 'dctx' is a valid decompression context.
  648. *
  649. * Ensures:
  650. *
  651. * If result is success:
  652. * \li If 'target' is not NULL, 'name' is attached to it.
  653. *
  654. * \li Uppercase letters are downcased in the copy iff
  655. * DNS_NAME_DOWNCASE is set in options.
  656. *
  657. * \li The current location in source is advanced, and the used space
  658. * in target is updated.
  659. *
  660. * Result:
  661. * \li Success
  662. * \li Bad Form: Label Length
  663. * \li Bad Form: Unknown Label Type
  664. * \li Bad Form: Name Length
  665. * \li Bad Form: Compression type not allowed
  666. * \li Bad Form: Bad compression pointer
  667. * \li Bad Form: Input too short
  668. * \li Resource Limit: Too many compression pointers
  669. * \li Resource Limit: Not enough space in buffer
  670. */
  671. isc_result_t
  672. dns_name_towire(const dns_name_t *name, dns_compress_t *cctx,
  673. isc_buffer_t *target);
  674. /*%<
  675. * Convert 'name' into wire format, compressing it as specified by the
  676. * compression context 'cctx', and storing the result in 'target'.
  677. *
  678. * Notes:
  679. * \li If the compression context allows global compression, then the
  680. * global compression table may be updated.
  681. *
  682. * Requires:
  683. * \li 'name' is a valid name
  684. *
  685. * \li dns_name_countlabels(name) > 0
  686. *
  687. * \li dns_name_isabsolute(name) == TRUE
  688. *
  689. * \li target is a valid buffer.
  690. *
  691. * \li Any offsets specified in a global compression table are valid
  692. * for buffer.
  693. *
  694. * Ensures:
  695. *
  696. * If the result is success:
  697. *
  698. * \li The used space in target is updated.
  699. *
  700. * Returns:
  701. * \li Success
  702. * \li Resource Limit: Not enough space in buffer
  703. */
  704. isc_result_t
  705. dns_name_fromtext(dns_name_t *name, isc_buffer_t *source,
  706. const dns_name_t *origin, unsigned int options,
  707. isc_buffer_t *target);
  708. /*%<
  709. * Convert the textual representation of a DNS name at source
  710. * into uncompressed wire form stored in target.
  711. *
  712. * Notes:
  713. * \li Relative domain names will have 'origin' appended to them
  714. * unless 'origin' is NULL, in which case relative domain names
  715. * will remain relative.
  716. *
  717. * \li If DNS_NAME_DOWNCASE is set in 'options', any uppercase letters
  718. * in 'source' will be downcased when they are copied into 'target'.
  719. *
  720. * Requires:
  721. *
  722. * \li 'name' is a valid name.
  723. *
  724. * \li 'source' is a valid buffer.
  725. *
  726. * \li 'target' is a valid buffer or 'target' is NULL and 'name' has
  727. * a dedicated buffer.
  728. *
  729. * Ensures:
  730. *
  731. * If result is success:
  732. * \li If 'target' is not NULL, 'name' is attached to it.
  733. *
  734. * \li Uppercase letters are downcased in the copy iff
  735. * DNS_NAME_DOWNCASE is set in 'options'.
  736. *
  737. * \li The current location in source is advanced, and the used space
  738. * in target is updated.
  739. *
  740. * Result:
  741. *\li #ISC_R_SUCCESS
  742. *\li #DNS_R_EMPTYLABEL
  743. *\li #DNS_R_LABELTOOLONG
  744. *\li #DNS_R_BADESCAPE
  745. *\li (#DNS_R_BADBITSTRING: should not be returned)
  746. *\li (#DNS_R_BITSTRINGTOOLONG: should not be returned)
  747. *\li #DNS_R_BADDOTTEDQUAD
  748. *\li #ISC_R_NOSPACE
  749. *\li #ISC_R_UNEXPECTEDEND
  750. */
  751. #define DNS_NAME_OMITFINALDOT 0x01U
  752. #define DNS_NAME_MASTERFILE 0x02U /* escape $ and @ */
  753. isc_result_t
  754. dns_name_toprincipal(dns_name_t *name, isc_buffer_t *target);
  755. isc_result_t
  756. dns_name_totext(dns_name_t *name, isc_boolean_t omit_final_dot,
  757. isc_buffer_t *target);
  758. isc_result_t
  759. dns_name_totext2(dns_name_t *name, unsigned int options, isc_buffer_t *target);
  760. /*%<
  761. * Convert 'name' into text format, storing the result in 'target'.
  762. *
  763. * Notes:
  764. *\li If 'omit_final_dot' is true, then the final '.' in absolute
  765. * names other than the root name will be omitted.
  766. *
  767. *\li If DNS_NAME_OMITFINALDOT is set in options, then the final '.'
  768. * in absolute names other than the root name will be omitted.
  769. *
  770. *\li If DNS_NAME_MASTERFILE is set in options, '$' and '@' will also
  771. * be escaped.
  772. *
  773. *\li If dns_name_countlabels == 0, the name will be "@", representing the
  774. * current origin as described by RFC1035.
  775. *
  776. *\li The name is not NUL terminated.
  777. *
  778. * Requires:
  779. *
  780. *\li 'name' is a valid name
  781. *
  782. *\li 'target' is a valid buffer.
  783. *
  784. *\li if dns_name_isabsolute == FALSE, then omit_final_dot == FALSE
  785. *
  786. * Ensures:
  787. *
  788. *\li If the result is success:
  789. * the used space in target is updated.
  790. *
  791. * Returns:
  792. *\li #ISC_R_SUCCESS
  793. *\li #ISC_R_NOSPACE
  794. */
  795. #define DNS_NAME_MAXTEXT 1023
  796. /*%<
  797. * The maximum length of the text representation of a domain
  798. * name as generated by dns_name_totext(). This does not
  799. * include space for a terminating NULL.
  800. *
  801. * This definition is conservative - the actual maximum
  802. * is 1004, derived as follows:
  803. *
  804. * A backslash-decimal escaped character takes 4 bytes.
  805. * A wire-encoded name can be up to 255 bytes and each
  806. * label is one length byte + at most 63 bytes of data.
  807. * Maximizing the label lengths gives us a name of
  808. * three 63-octet labels, one 61-octet label, and the
  809. * root label:
  810. *
  811. * 1 + 63 + 1 + 63 + 1 + 63 + 1 + 61 + 1 = 255
  812. *
  813. * When printed, this is (3 * 63 + 61) * 4
  814. * bytes for the escaped label data + 4 bytes for the
  815. * dot terminating each label = 1004 bytes total.
  816. */
  817. isc_result_t
  818. dns_name_tofilenametext(dns_name_t *name, isc_boolean_t omit_final_dot,
  819. isc_buffer_t *target);
  820. /*%<
  821. * Convert 'name' into an alternate text format appropriate for filenames,
  822. * storing the result in 'target'. The name data is downcased, guaranteeing
  823. * that the filename does not depend on the case of the converted name.
  824. *
  825. * Notes:
  826. *\li If 'omit_final_dot' is true, then the final '.' in absolute
  827. * names other than the root name will be omitted.
  828. *
  829. *\li The name is not NUL terminated.
  830. *
  831. * Requires:
  832. *
  833. *\li 'name' is a valid absolute name
  834. *
  835. *\li 'target' is a valid buffer.
  836. *
  837. * Ensures:
  838. *
  839. *\li If the result is success:
  840. * the used space in target is updated.
  841. *
  842. * Returns:
  843. *\li #ISC_R_SUCCESS
  844. *\li #ISC_R_NOSPACE
  845. */
  846. isc_result_t
  847. dns_name_downcase(dns_name_t *source, dns_name_t *name,
  848. isc_buffer_t *target);
  849. /*%<
  850. * Downcase 'source'.
  851. *
  852. * Requires:
  853. *
  854. *\li 'source' and 'name' are valid names.
  855. *
  856. *\li If source == name, then
  857. * 'source' must not be read-only
  858. *
  859. *\li Otherwise,
  860. * 'target' is a valid buffer or 'target' is NULL and
  861. * 'name' has a dedicated buffer.
  862. *
  863. * Returns:
  864. *\li #ISC_R_SUCCESS
  865. *\li #ISC_R_NOSPACE
  866. *
  867. * Note: if source == name, then the result will always be ISC_R_SUCCESS.
  868. */
  869. isc_result_t
  870. dns_name_concatenate(dns_name_t *prefix, dns_name_t *suffix,
  871. dns_name_t *name, isc_buffer_t *target);
  872. /*%<
  873. * Concatenate 'prefix' and 'suffix'.
  874. *
  875. * Requires:
  876. *
  877. *\li 'prefix' is a valid name or NULL.
  878. *
  879. *\li 'suffix' is a valid name or NULL.
  880. *
  881. *\li 'name' is a valid name or NULL.
  882. *
  883. *\li 'target' is a valid buffer or 'target' is NULL and 'name' has
  884. * a dedicated buffer.
  885. *
  886. *\li If 'prefix' is absolute, 'suffix' must be NULL or the empty name.
  887. *
  888. * Ensures:
  889. *
  890. *\li On success,
  891. * If 'target' is not NULL and 'name' is not NULL, then 'name'
  892. * is attached to it.
  893. * The used space in target is updated.
  894. *
  895. * Returns:
  896. *\li #ISC_R_SUCCESS
  897. *\li #ISC_R_NOSPACE
  898. *\li #DNS_R_NAMETOOLONG
  899. */
  900. void
  901. dns_name_split(dns_name_t *name, unsigned int suffixlabels,
  902. dns_name_t *prefix, dns_name_t *suffix);
  903. /*%<
  904. *
  905. * Split 'name' into two pieces on a label boundary.
  906. *
  907. * Notes:
  908. * \li 'name' is split such that 'suffix' holds the most significant
  909. * 'suffixlabels' labels. All other labels are stored in 'prefix'.
  910. *
  911. *\li Copying name data is avoided as much as possible, so 'prefix'
  912. * and 'suffix' will end up pointing at the data for 'name'.
  913. *
  914. *\li It is legitimate to pass a 'prefix' or 'suffix' that has
  915. * its name data stored someplace other than the dedicated buffer.
  916. * This is useful to avoid name copying in the calling function.
  917. *
  918. *\li It is also legitimate to pass a 'prefix' or 'suffix' that is
  919. * the same dns_name_t as 'name'.
  920. *
  921. * Requires:
  922. *\li 'name' is a valid name.
  923. *
  924. *\li 'suffixlabels' cannot exceed the number of labels in 'name'.
  925. *
  926. * \li 'prefix' is a valid name or NULL, and cannot be read-only.
  927. *
  928. *\li 'suffix' is a valid name or NULL, and cannot be read-only.
  929. *
  930. *\li If non-NULL, 'prefix' and 'suffix' must have dedicated buffers.
  931. *
  932. *\li 'prefix' and 'suffix' cannot point to the same buffer.
  933. *
  934. * Ensures:
  935. *
  936. *\li On success:
  937. * If 'prefix' is not NULL it will contain the least significant
  938. * labels.
  939. * If 'suffix' is not NULL it will contain the most significant
  940. * labels. dns_name_countlabels(suffix) will be equal to
  941. * suffixlabels.
  942. *
  943. *\li On failure:
  944. * Either 'prefix' or 'suffix' is invalidated (depending
  945. * on which one the problem was encountered with).
  946. *
  947. * Returns:
  948. *\li #ISC_R_SUCCESS No worries. (This function should always success).
  949. */
  950. isc_result_t
  951. dns_name_dup(const dns_name_t *source, isc_mem_t *mctx,
  952. dns_name_t *target);
  953. /*%<
  954. * Make 'target' a dynamically allocated copy of 'source'.
  955. *
  956. * Requires:
  957. *
  958. *\li 'source' is a valid non-empty name.
  959. *
  960. *\li 'target' is a valid name that is not read-only.
  961. *
  962. *\li 'mctx' is a valid memory context.
  963. */
  964. isc_result_t
  965. dns_name_dupwithoffsets(dns_name_t *source, isc_mem_t *mctx,
  966. dns_name_t *target);
  967. /*%<
  968. * Make 'target' a read-only dynamically allocated copy of 'source'.
  969. * 'target' will also have a dynamically allocated offsets table.
  970. *
  971. * Requires:
  972. *
  973. *\li 'source' is a valid non-empty name.
  974. *
  975. *\li 'target' is a valid name that is not read-only.
  976. *
  977. *\li 'target' has no offsets table.
  978. *
  979. *\li 'mctx' is a valid memory context.
  980. */
  981. void
  982. dns_name_free(dns_name_t *name, isc_mem_t *mctx);
  983. /*%<
  984. * Free 'name'.
  985. *
  986. * Requires:
  987. *
  988. *\li 'name' is a valid name created previously in 'mctx' by dns_name_dup().
  989. *
  990. *\li 'mctx' is a valid memory context.
  991. *
  992. * Ensures:
  993. *
  994. *\li All dynamic resources used by 'name' are freed and the name is
  995. * invalidated.
  996. */
  997. isc_result_t
  998. dns_name_digest(dns_name_t *name, dns_digestfunc_t digest, void *arg);
  999. /*%<
  1000. * Send 'name' in DNSSEC canonical form to 'digest'.
  1001. *
  1002. * Requires:
  1003. *
  1004. *\li 'name' is a valid name.
  1005. *
  1006. *\li 'digest' is a valid dns_digestfunc_t.
  1007. *
  1008. * Ensures:
  1009. *
  1010. *\li If successful, the DNSSEC canonical form of 'name' will have been
  1011. * sent to 'digest'.
  1012. *
  1013. *\li If digest() returns something other than ISC_R_SUCCESS, that result
  1014. * will be returned as the result of dns_name_digest().
  1015. *
  1016. * Returns:
  1017. *
  1018. *\li #ISC_R_SUCCESS
  1019. *
  1020. *\li Many other results are possible if not successful.
  1021. *
  1022. */
  1023. isc_boolean_t
  1024. dns_name_dynamic(dns_name_t *name);
  1025. /*%<
  1026. * Returns whether there is dynamic memory associated with this name.
  1027. *
  1028. * Requires:
  1029. *
  1030. *\li 'name' is a valid name.
  1031. *
  1032. * Returns:
  1033. *
  1034. *\li 'ISC_TRUE' if the name is dynamic otherwise 'ISC_FALSE'.
  1035. */
  1036. isc_result_t
  1037. dns_name_print(dns_name_t *name, FILE *stream);
  1038. /*%<
  1039. * Print 'name' on 'stream'.
  1040. *
  1041. * Requires:
  1042. *
  1043. *\li 'name' is a valid name.
  1044. *
  1045. *\li 'stream' is a valid stream.
  1046. *
  1047. * Returns:
  1048. *
  1049. *\li #ISC_R_SUCCESS
  1050. *
  1051. *\li Any error that dns_name_totext() can return.
  1052. */
  1053. void
  1054. dns_name_format(dns_name_t *name, char *cp, unsigned int size);
  1055. /*%<
  1056. * Format 'name' as text appropriate for use in log messages.
  1057. *
  1058. * Store the formatted name at 'cp', writing no more than
  1059. * 'size' bytes. The resulting string is guaranteed to be
  1060. * null terminated.
  1061. *
  1062. * The formatted name will have a terminating dot only if it is
  1063. * the root.
  1064. *
  1065. * This function cannot fail, instead any errors are indicated
  1066. * in the returned text.
  1067. *
  1068. * Requires:
  1069. *
  1070. *\li 'name' is a valid name.
  1071. *
  1072. *\li 'cp' points a valid character array of size 'size'.
  1073. *
  1074. *\li 'size' > 0.
  1075. *
  1076. */
  1077. isc_result_t
  1078. dns_name_tostring(dns_name_t *source, char **target, isc_mem_t *mctx);
  1079. /*%<
  1080. * Convert 'name' to string format, allocating sufficient memory to
  1081. * hold it (free with isc_mem_free()).
  1082. *
  1083. * Differs from dns_name_format in that it allocates its own memory.
  1084. *
  1085. * Requires:
  1086. *
  1087. *\li 'name' is a valid name.
  1088. *\li 'target' is not NULL.
  1089. *\li '*target' is NULL.
  1090. *
  1091. * Returns:
  1092. *
  1093. *\li ISC_R_SUCCESS
  1094. *
  1095. *\li Any error that dns_name_totext() can return.
  1096. */
  1097. isc_result_t
  1098. dns_name_fromstring(dns_name_t *target, const char *src, unsigned int options,
  1099. isc_mem_t *mctx);
  1100. isc_result_t
  1101. dns_name_fromstring2(dns_name_t *target, const char *src,
  1102. const dns_name_t *origin, unsigned int options,
  1103. isc_mem_t *mctx);
  1104. /*%<
  1105. * Convert a string to a name and place it in target, allocating memory
  1106. * as necessary. 'options' has the same semantics as that of
  1107. * dns_name_fromtext().
  1108. *
  1109. * If 'target' has a buffer then the name will be copied into it rather than
  1110. * memory being allocated.
  1111. *
  1112. * Requires:
  1113. *
  1114. * \li 'target' is a valid name that is not read-only.
  1115. * \li 'src' is not NULL.
  1116. *
  1117. * Returns:
  1118. *
  1119. *\li #ISC_R_SUCCESS
  1120. *
  1121. *\li Any error that dns_name_fromtext() can return.
  1122. *
  1123. *\li Any error that dns_name_dup() can return.
  1124. */
  1125. isc_result_t
  1126. dns_name_settotextfilter(dns_name_totextfilter_t proc);
  1127. /*%<
  1128. * Set / clear a thread specific function 'proc' to be called at the
  1129. * end of dns_name_totext().
  1130. *
  1131. * Note: Under Windows you need to call "dns_name_settotextfilter(NULL);"
  1132. * prior to exiting the thread otherwise memory will be leaked.
  1133. * For other platforms, which are pthreads based, this is still a good
  1134. * idea but not required.
  1135. *
  1136. * Returns
  1137. *\li #ISC_R_SUCCESS
  1138. *\li #ISC_R_UNEXPECTED
  1139. */
  1140. #define DNS_NAME_FORMATSIZE (DNS_NAME_MAXTEXT + 1)
  1141. /*%<
  1142. * Suggested size of buffer passed to dns_name_format().
  1143. * Includes space for the terminating NULL.
  1144. */
  1145. isc_result_t
  1146. dns_name_copy(dns_name_t *source, dns_name_t *dest, isc_buffer_t *target);
  1147. /*%<
  1148. * Makes 'dest' refer to a copy of the name in 'source'. The data are
  1149. * either copied to 'target' or the dedicated buffer in 'dest'.
  1150. *
  1151. * Requires:
  1152. * \li 'source' is a valid name.
  1153. *
  1154. * \li 'dest' is an initialized name with a dedicated buffer.
  1155. *
  1156. * \li 'target' is NULL or an initialized buffer.
  1157. *
  1158. * \li Either dest has a dedicated buffer or target != NULL.
  1159. *
  1160. * Ensures:
  1161. *
  1162. *\li On success, the used space in target is updated.
  1163. *
  1164. * Returns:
  1165. *\li #ISC_R_SUCCESS
  1166. *\li #ISC_R_NOSPACE
  1167. */
  1168. isc_boolean_t
  1169. dns_name_ishostname(const dns_name_t *name, isc_boolean_t wildcard);
  1170. /*%<
  1171. * Return if 'name' is a valid hostname. RFC 952 / RFC 1123.
  1172. * If 'wildcard' is ISC_TRUE then allow the first label of name to
  1173. * be a wildcard.
  1174. * The root is also accepted.
  1175. *
  1176. * Requires:
  1177. * 'name' to be valid.
  1178. */
  1179. isc_boolean_t
  1180. dns_name_ismailbox(const dns_name_t *name);
  1181. /*%<
  1182. * Return if 'name' is a valid mailbox. RFC 821.
  1183. *
  1184. * Requires:
  1185. * \li 'name' to be valid.
  1186. */
  1187. isc_boolean_t
  1188. dns_name_internalwildcard(const dns_name_t *name);
  1189. /*%<
  1190. * Return if 'name' contains a internal wildcard name.
  1191. *
  1192. * Requires:
  1193. * \li 'name' to be valid.
  1194. */
  1195. void
  1196. dns_name_destroy(void);
  1197. /*%<
  1198. * Cleanup dns_name_settotextfilter() / dns_name_totext() state.
  1199. *
  1200. * This should be called as part of the final cleanup process.
  1201. *
  1202. * Note: dns_name_settotextfilter(NULL); should be called for all
  1203. * threads which have called dns_name_settotextfilter() with a
  1204. * non-NULL argument prior to calling dns_name_destroy();
  1205. */
  1206. ISC_LANG_ENDDECLS
  1207. /*
  1208. *** High Performance Macros
  1209. ***/
  1210. /*
  1211. * WARNING: Use of these macros by applications may require recompilation
  1212. * of the application in some situations where calling the function
  1213. * would not.
  1214. *
  1215. * WARNING: No assertion checking is done for these macros.
  1216. */
  1217. #define DNS_NAME_INIT(n, o) \
  1218. do { \
  1219. (n)->magic = DNS_NAME_MAGIC; \
  1220. (n)->ndata = NULL; \
  1221. (n)->length = 0; \
  1222. (n)->labels = 0; \
  1223. (n)->attributes = 0; \
  1224. (n)->offsets = (o); \
  1225. (n)->buffer = NULL; \
  1226. ISC_LINK_INIT((n), link); \
  1227. ISC_LIST_INIT((n)->list); \
  1228. } while (0)
  1229. #define DNS_NAME_RESET(n) \
  1230. do { \
  1231. (n)->ndata = NULL; \
  1232. (n)->length = 0; \
  1233. (n)->labels = 0; \
  1234. (n)->attributes &= ~DNS_NAMEATTR_ABSOLUTE; \
  1235. if ((n)->buffer != NULL) \
  1236. isc_buffer_clear((n)->buffer); \
  1237. } while (0)
  1238. #define DNS_NAME_SETBUFFER(n, b) \
  1239. (n)->buffer = (b)
  1240. #define DNS_NAME_ISABSOLUTE(n) \
  1241. (((n)->attributes & DNS_NAMEATTR_ABSOLUTE) != 0 ? ISC_TRUE : ISC_FALSE)
  1242. #define DNS_NAME_COUNTLABELS(n) \
  1243. ((n)->labels)
  1244. #define DNS_NAME_TOREGION(n, r) \
  1245. do { \
  1246. (r)->base = (n)->ndata; \
  1247. (r)->length = (n)->length; \
  1248. } while (0)
  1249. #define DNS_NAME_SPLIT(n, l, p, s) \
  1250. do { \
  1251. dns_name_t *_n = (n); \
  1252. dns_name_t *_p = (p); \
  1253. dns_name_t *_s = (s); \
  1254. unsigned int _l = (l); \
  1255. if (_p != NULL) \
  1256. dns_name_getlabelsequence(_n, 0, _n->labels - _l, _p); \
  1257. if (_s != NULL) \
  1258. dns_name_getlabelsequence(_n, _n->labels - _l, _l, _s); \
  1259. } while (0)
  1260. #ifdef DNS_NAME_USEINLINE
  1261. #define dns_name_init(n, o) DNS_NAME_INIT(n, o)
  1262. #define dns_name_reset(n) DNS_NAME_RESET(n)
  1263. #define dns_name_setbuffer(n, b) DNS_NAME_SETBUFFER(n, b)
  1264. #define dns_name_countlabels(n) DNS_NAME_COUNTLABELS(n)
  1265. #define dns_name_isabsolute(n) DNS_NAME_ISABSOLUTE(n)
  1266. #define dns_name_toregion(n, r) DNS_NAME_TOREGION(n, r)
  1267. #define dns_name_split(n, l, p, s) DNS_NAME_SPLIT(n, l, p, s)
  1268. #endif /* DNS_NAME_USEINLINE */
  1269. #endif /* DNS_NAME_H */