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, 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 112 * \param[in] s the size of the new dname 113 * \param[in] *data pointer to the actual data 114 * 115 * \return ldns_rdf* 116 */ 117 ldns_rdf *ldns_dname_new(uint16_t s, void *data); 118 119 /** 120 * Create a new dname rdf from data (the data is copied) 121 * \param[in] size the size of the data 122 * \param[in] *data pointer to the actual data 123 * 124 * \return ldns_rdf* 125 */ 126 ldns_rdf *ldns_dname_new_frm_data(uint16_t size, const void *data); 127 128 /** 129 * Put a dname into canonical fmt - ie. lowercase it 130 * \param[in] rdf the dname to lowercase 131 * \return void 132 */ 133 void ldns_dname2canonical(const ldns_rdf *rdf); 134 135 /** 136 * test wether the name sub falls under parent (i.e. is a subdomain 137 * of parent). This function will return false if the given dnames are 138 * equal. 139 * \param[in] sub the name to test 140 * \param[in] parent the parent's name 141 * \return true if sub falls under parent, otherwise false 142 */ 143 bool ldns_dname_is_subdomain(const ldns_rdf *sub, const ldns_rdf *parent); 144 145 /** 146 * Compares the two dname rdf's according to the algorithm for ordering 147 * in RFC4034 Section 6. 148 * \param[in] dname1 First dname rdf to compare 149 * \param[in] dname2 Second dname rdf to compare 150 * \return -1 if dname1 comes before dname2, 1 if dname1 comes after dname2, and 0 if they are equal. 151 */ 152 int ldns_dname_compare(const ldns_rdf *dname1, const ldns_rdf *dname2); 153 154 /** 155 * Checks whether the dname matches the given wildcard 156 * \param[in] dname The dname to check 157 * \param[in] wildcard The wildcard to check with 158 * \return 1 If the wildcard matches, OR if 'wildcard' is not a wildcard and 159 * the names are *exactly* the same 160 * 0 If the wildcard does not match, or if it is not a wildcard and 161 * the names are not the same 162 */ 163 int ldns_dname_match_wildcard(const ldns_rdf *dname, const ldns_rdf *wildcard); 164 165 /** 166 * check if middle lays in the interval defined by prev and next 167 * prev <= middle < next. This is usefull for nsec checking 168 * \param[in] prev the previous dname 169 * \param[in] middle the dname to check 170 * \param[in] next the next dname 171 * return 0 on error or unknown, -1 when middle is in the interval, +1 when not 172 */ 173 int ldns_dname_interval(const ldns_rdf *prev, const ldns_rdf *middle, const ldns_rdf *next); 174 175 /** 176 * Checks whether the given dname string is absolute (i.e. ends with a '.') 177 * \param[in] *dname_str a string representing the dname 178 * \return true or false 179 */ 180 bool ldns_dname_str_absolute(const char *dname_str); 181 182 /** 183 * Checks whether the given dname is absolute (i.e. ends with a '.') 184 * \param[in] *dname a rdf representing the dname 185 * \return true or false 186 */ 187 bool ldns_dname_absolute(const ldns_rdf *dname); 188 189 /** 190 * look inside the rdf and if it is an LDNS_RDF_TYPE_DNAME 191 * try and retrieve a specific label. The labels are numbered 192 * starting from 0 (left most). 193 * \param[in] rdf the rdf to look in 194 * \param[in] labelpos return the label with this number 195 * \return a ldns_rdf* with the label as name or NULL on error 196 */ 197 ldns_rdf * ldns_dname_label(const ldns_rdf *rdf, uint8_t labelpos); 198 199 /** 200 * Check if dname is a wildcard, starts with *. 201 * \param[in] dname: the rdf to look in 202 * \return true if a wildcard, false if not. 203 */ 204 int ldns_dname_is_wildcard(const ldns_rdf* dname); 205 206 #ifdef __cplusplus 207 } 208 #endif 209 210 #endif /* LDNS_DNAME_H */ 211