contrib/ldns/ldns/dname.h

   1 /*
   2  * dname.h
   3  *
   4  * dname definitions
   5  *
   6  * a Net::DNS like library for C
   7  *
   8  * (c) NLnet Labs, 2004-2006
   9  *
  10  * See the file LICENSE for the license
  11  */
  12
  13 /**
  14  * \file dname.h
  15  *
  16  * dname contains function to read and manipulate domain names.
  17  *
  18  * Example domain names are "www.nlnetlabs.nl." and "." (the root)
  19  *
  20  * If a domain name ends with a dot ("."), it is called a Fully Qualified
  21  * Domain Name (FQDN). In certain places (for instance when reading a zone
  22  * file), an origin (which is just another domain name) non-FQDNs will be
  23  * placed after the current. For instance, if i have a zone file where the
  24  * origin has been set to "nl.", and my file contains the name
  25  * "www.nlnetlabs", it will result in "www.nlnetlabs.nl.". Internally, dnames are
  26  * always absolute (the dot is added when it is missing and there is no origin).
  27  *
  28  * An FQDN is also
  29  * known as an absolute domain name, therefore the function to check this is
  30  * called \ref ldns_dname_str_absolute
  31  *
  32  * Domain names are stored in \ref ldns_rdf structures, with the type
  33  * \ref LDNS_RDF_TYPE_DNAME
  34  *
  35  * This module is *NOT* about the RR type called DNAME.
  36  */
  37
  38
  39 #ifndef LDNS_DNAME_H
  40 #define LDNS_DNAME_H
  41
  42 #include <ldns/common.h>
  43 #include <ldns/rdata.h>
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif
  48
  49 #define LDNS_DNAME_NORMALIZE        tolower
  50
  51 /**
  52  * concatenates two dnames together
  53  * \param[in] rd1 the leftside
  54  * \param[in] rd2 the rightside
  55  * \return a new rdf with leftside/rightside
  56  */
  57 ldns_rdf *ldns_dname_cat_clone(const ldns_rdf *rd1, const ldns_rdf *rd2);
  58
  59 /**
  60  * concatenates rd2 after rd1 (rd2 is copied, rd1 is modified)
  61  * \param[in] rd1 the leftside
  62  * \param[in] rd2 the rightside
  63  * \return LDNS_STATUS_OK on success
  64  */
  65 ldns_status     ldns_dname_cat(ldns_rdf *rd1, const ldns_rdf *rd2);
  66
  67 /**
  68  * Returns a clone of the given dname with the labels
  69  * reversed
  70  * \param[in] d the dname to reverse
  71  * \return clone of the dname with the labels reversed.
  72  */
  73 ldns_rdf *ldns_dname_reverse(const ldns_rdf *d);
  74
  75 /**
  76  * Clones the given dname from the nth label on
  77  * \param[in] d The dname to clone
  78  * \param[in] n the label nr to clone from, if this is 0, the complete
  79  *              dname is cloned
  80  * \return A newly allocated *rdf structure, containing the cloned dname,
  81  *         or NULL if either d was NULL, not a dname, or if n >=
  82  *         label_count
  83  */
  84 ldns_rdf *
  85 ldns_dname_clone_from(const ldns_rdf *d, uint16_t n);
  86
  87 /**
  88  * chop one label off the left side of a dname. so
  89  * wwww.nlnetlabs.nl, becomes nlnetlabs.nl
  90  * This new name is a clone and must be freed with ldns_deep_free()
  91  * \param[in] d the dname to chop
  92  * \return the remaining dname
  93  */
  94 ldns_rdf *ldns_dname_left_chop(const ldns_rdf *d);
  95
  96 /**
  97  * count the number of labels inside a LDNS_RDF_DNAME type rdf.
  98  * \param[in] *r the rdf
  99  * \return the number of labels
 100  */
 101 uint8_t  ldns_dname_label_count(const ldns_rdf *r);
 102
 103 /**
 104  * creates a new dname rdf from a string.
 105  * \param[in] str string to use
 106  * \return ldns_rdf* or NULL in case of an error
 107  */
 108 ldns_rdf *ldns_dname_new_frm_str(const char *str);
 109
 110 /**
 111  * Create a new dname rdf from a string. The data pointer
 112  * is stored in the rdf, not a copy of the data
 113  * \param[in] s the size of the new dname
 114  * \param[in] *data pointer to the actual data
 115  *
 116  * \return ldns_rdf*
 117  */
 118 ldns_rdf *ldns_dname_new(uint16_t s, void *data);
 119
 120 /**
 121  * Create a new dname rdf from data (the data is copied)
 122  * \param[in] size the size of the data
 123  * \param[in] *data pointer to the actual data
 124  *
 125  * \return ldns_rdf*
 126  */
 127 ldns_rdf *ldns_dname_new_frm_data(uint16_t size, const void *data);
 128
 129 /**
 130  * Put a dname into canonical fmt - ie. lowercase it
 131  * \param[in] rdf the dname to lowercase
 132  * \return void
 133  */
 134 void ldns_dname2canonical(const ldns_rdf *rdf);
 135
 136 /**
 137  * test wether the name sub falls under parent (i.e. is a subdomain
 138  * of parent). This function will return false if the given dnames are
 139  * equal.
 140  * \param[in] sub the name to test
 141  * \param[in] parent the parent's name
 142  * \return true if sub falls under parent, otherwise false
 143  */
 144 bool ldns_dname_is_subdomain(const ldns_rdf *sub, const ldns_rdf *parent);
 145
 146 /**
 147  * Compares the two dname rdf's according to the algorithm for ordering
 148  * in RFC4034 Section 6.
 149  * \param[in] dname1 First dname rdf to compare
 150  * \param[in] dname2 Second dname rdf to compare
 151  * \return -1 if dname1 comes before dname2, 1 if dname1 comes after dname2, and 0 if they are equal.
 152  */
 153 int ldns_dname_compare(const ldns_rdf *dname1, const ldns_rdf *dname2);
 154 int ldns_dname_compare_v(const void *, const void *);
 155
 156 /**
 157  * Checks whether the dname matches the given wildcard
 158  * \param[in] dname The dname to check
 159  * \param[in] wildcard The wildcard to check with
 160  * \return 1 If the wildcard matches, OR if 'wildcard' is not a wildcard and
 161  *           the names are *exactly* the same
 162  *         0 If the wildcard does not match, or if it is not a wildcard and
 163  *           the names are not the same
 164  */
 165 int ldns_dname_match_wildcard(const ldns_rdf *dname, const ldns_rdf *wildcard);
 166
 167 /**
 168  * check if middle lays in the interval defined by prev and next
 169  * prev <= middle < next. This is useful for nsec checking
 170  * \param[in] prev the previous dname
 171  * \param[in] middle the dname to check
 172  * \param[in] next the next dname
 173  * return 0 on error or unknown, -1 when middle is in the interval, +1 when not
 174  */
 175 int ldns_dname_interval(const ldns_rdf *prev, const ldns_rdf *middle, const ldns_rdf *next);
 176
 177 /**
 178  * Checks whether the given dname string is absolute (i.e. ends with a '.')
 179  * \param[in] *dname_str a string representing the dname
 180  * \return true or false
 181  */
 182 bool ldns_dname_str_absolute(const char *dname_str);
 183
 184 /**
 185  * Checks whether the given dname is absolute (i.e. ends with a '.')
 186  * \param[in] *dname a rdf representing the dname
 187  * \return true or false
 188  */
 189 bool ldns_dname_absolute(const ldns_rdf *dname);
 190
 191 /**
 192  * look inside the rdf and if it is an LDNS_RDF_TYPE_DNAME
 193  * try and retrieve a specific label. The labels are numbered
 194  * starting from 0 (left most).
 195  * \param[in] rdf the rdf to look in
 196  * \param[in] labelpos return the label with this number
 197  * \return a ldns_rdf* with the label as name or NULL on error
 198  */
 199 ldns_rdf * ldns_dname_label(const ldns_rdf *rdf, uint8_t labelpos);
 200
 201 /**
 202  * Check if dname is a wildcard, starts with *.
 203  * \param[in] dname: the rdf to look in
 204  * \return true if a wildcard, false if not.
 205  */
 206 int ldns_dname_is_wildcard(const ldns_rdf* dname);
 207
 208 #ifdef __cplusplus
 209 }
 210 #endif
 211
 212 #endif  /* LDNS_DNAME_H */