contrib/ldns/ldns/rr_functions.h

   1 /*
   2  * rr_functions.h
   3  *
   4  * the .h file with defs for the per rr
   5  * functions
   6  *
   7  * a Net::DNS like library for C
   8  *
   9  * (c) NLnet Labs, 2005-2006
  10  *
  11  * See the file LICENSE for the license
  12  */
  13 #ifndef LDNS_RR_FUNCTIONS_H
  14 #define LDNS_RR_FUNCTIONS_H
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /**
  21  * \file
  22  *
  23  * Defines some extra convenience functions for ldns_rr structures
  24  */
  25
  26 /* A / AAAA */
  27 /**
  28  * returns the address of a LDNS_RR_TYPE_A rr
  29  * \param[in] r the resource record
  30  * \return a ldns_rdf* with the address or NULL on failure
  31  */
  32 ldns_rdf* ldns_rr_a_address(const ldns_rr *r);
  33
  34 /**
  35  * sets the address of a LDNS_RR_TYPE_A rr
  36  * \param[in] r the rr to use
  37  * \param[in] f the address to set
  38  * \return true on success, false otherwise
  39  */
  40 bool ldns_rr_a_set_address(ldns_rr *r, ldns_rdf *f);
  41
  42 /* NS */
  43 /**
  44  * returns the name of a LDNS_RR_TYPE_NS rr
  45  * \param[in] r the resource record
  46  * \return a ldns_rdf* with the name or NULL on failure
  47  */
  48 ldns_rdf* ldns_rr_ns_nsdname(const ldns_rr *r);
  49
  50 /* MX */
  51 /**
  52  * returns the mx pref. of a LDNS_RR_TYPE_MX rr
  53  * \param[in] r the resource record
  54  * \return a ldns_rdf* with the preference or NULL on failure
  55  */
  56 ldns_rdf* ldns_rr_mx_preference(const ldns_rr *r);
  57 /**
  58  * returns the mx host of a LDNS_RR_TYPE_MX rr
  59  * \param[in] r the resource record
  60  * \return a ldns_rdf* with the name of the MX host or NULL on failure
  61  */
  62 ldns_rdf* ldns_rr_mx_exchange(const ldns_rr *r);
  63
  64 /* RRSIG */
  65 /**
  66  * returns the type covered of a LDNS_RR_TYPE_RRSIG rr
  67  * \param[in] r the resource record
  68  * \return a ldns_rdf* with the type covered or NULL on failure
  69  */
  70 ldns_rdf* ldns_rr_rrsig_typecovered(const ldns_rr *r);
  71 /**
  72  * sets the typecovered of a LDNS_RR_TYPE_RRSIG rr
  73  * \param[in] r the rr to use
  74  * \param[in] f the typecovered to set
  75  * \return true on success, false otherwise
  76  */
  77 bool ldns_rr_rrsig_set_typecovered(ldns_rr *r, ldns_rdf *f);
  78 /**
  79  * returns the algorithm of a LDNS_RR_TYPE_RRSIG RR
  80  * \param[in] r the resource record
  81  * \return a ldns_rdf* with the algorithm or NULL on failure
  82  */
  83 ldns_rdf* ldns_rr_rrsig_algorithm(const ldns_rr *r);
  84 /**
  85  * sets the algorithm of a LDNS_RR_TYPE_RRSIG rr
  86  * \param[in] r the rr to use
  87  * \param[in] f the algorithm to set
  88  * \return true on success, false otherwise
  89  */
  90 bool ldns_rr_rrsig_set_algorithm(ldns_rr *r, ldns_rdf *f);
  91 /**
  92  * returns the number of labels of a LDNS_RR_TYPE_RRSIG RR
  93  * \param[in] r the resource record
  94  * \return a ldns_rdf* with the number of labels or NULL on failure
  95  */
  96 ldns_rdf *ldns_rr_rrsig_labels(const ldns_rr *r);
  97 /**
  98  * sets the number of labels of a LDNS_RR_TYPE_RRSIG rr
  99  * \param[in] r the rr to use
 100  * \param[in] f the number of labels to set
 101  * \return true on success, false otherwise
 102  */
 103 bool ldns_rr_rrsig_set_labels(ldns_rr *r, ldns_rdf *f);
 104 /**
 105  * returns the original TTL of a LDNS_RR_TYPE_RRSIG RR
 106  * \param[in] r the resource record
 107  * \return a ldns_rdf* with the original TTL or NULL on failure
 108  */
 109 ldns_rdf* ldns_rr_rrsig_origttl(const ldns_rr *r);
 110 /**
 111  * sets the original TTL of a LDNS_RR_TYPE_RRSIG rr
 112  * \param[in] r the rr to use
 113  * \param[in] f the original TTL to set
 114  * \return true on success, false otherwise
 115  */
 116 bool ldns_rr_rrsig_set_origttl(ldns_rr *r, ldns_rdf *f);
 117 /**
 118  * returns the expiration time of a LDNS_RR_TYPE_RRSIG RR
 119  * \param[in] r the resource record
 120  * \return a ldns_rdf* with the expiration time or NULL on failure
 121  */
 122 ldns_rdf* ldns_rr_rrsig_expiration(const ldns_rr *r);
 123 /**
 124  * sets the expireation date of a LDNS_RR_TYPE_RRSIG rr
 125  * \param[in] r the rr to use
 126  * \param[in] f the expireation date to set
 127  * \return true on success, false otherwise
 128  */
 129 bool ldns_rr_rrsig_set_expiration(ldns_rr *r, ldns_rdf *f);
 130 /**
 131  * returns the inception time of a LDNS_RR_TYPE_RRSIG RR
 132  * \param[in] r the resource record
 133  * \return a ldns_rdf* with the inception time or NULL on failure
 134  */
 135 ldns_rdf* ldns_rr_rrsig_inception(const ldns_rr *r);
 136 /**
 137  * sets the inception date of a LDNS_RR_TYPE_RRSIG rr
 138  * \param[in] r the rr to use
 139  * \param[in] f the inception date to set
 140  * \return true on success, false otherwise
 141  */
 142 bool ldns_rr_rrsig_set_inception(ldns_rr *r, ldns_rdf *f);
 143 /**
 144  * returns the keytag of a LDNS_RR_TYPE_RRSIG RR
 145  * \param[in] r the resource record
 146  * \return a ldns_rdf* with the keytag or NULL on failure
 147  */
 148 ldns_rdf* ldns_rr_rrsig_keytag(const ldns_rr *r);
 149 /**
 150  * sets the keytag of a LDNS_RR_TYPE_RRSIG rr
 151  * \param[in] r the rr to use
 152  * \param[in] f the keytag to set
 153  * \return true on success, false otherwise
 154  */
 155 bool ldns_rr_rrsig_set_keytag(ldns_rr *r, ldns_rdf *f);
 156 /**
 157  * returns the signers name of a LDNS_RR_TYPE_RRSIG RR
 158  * \param[in] r the resource record
 159  * \return a ldns_rdf* with the signers name or NULL on failure
 160  */
 161 ldns_rdf* ldns_rr_rrsig_signame(const ldns_rr *r);
 162 /**
 163  * sets the signers name of a LDNS_RR_TYPE_RRSIG rr
 164  * \param[in] r the rr to use
 165  * \param[in] f the signers name to set
 166  * \return true on success, false otherwise
 167  */
 168 bool ldns_rr_rrsig_set_signame(ldns_rr *r, ldns_rdf *f);
 169 /**
 170  * returns the signature data of a LDNS_RR_TYPE_RRSIG RR
 171  * \param[in] r the resource record
 172  * \return a ldns_rdf* with the signature data or NULL on failure
 173  */
 174 ldns_rdf* ldns_rr_rrsig_sig(const ldns_rr *r);
 175 /**
 176  * sets the signature data of a LDNS_RR_TYPE_RRSIG rr
 177  * \param[in] r the rr to use
 178  * \param[in] f the signature data to set
 179  * \return true on success, false otherwise
 180  */
 181 bool ldns_rr_rrsig_set_sig(ldns_rr *r, ldns_rdf *f);
 182
 183 /* DNSKEY */
 184 /**
 185  * returns the flags of a LDNS_RR_TYPE_DNSKEY rr
 186  * \param[in] r the resource record
 187  * \return a ldns_rdf* with the flags or NULL on failure
 188  */
 189 ldns_rdf* ldns_rr_dnskey_flags(const ldns_rr *r);
 190 /**
 191  * sets the flags of a LDNS_RR_TYPE_DNSKEY rr
 192  * \param[in] r the rr to use
 193  * \param[in] f the flags to set
 194  * \return true on success, false otherwise
 195  */
 196 bool ldns_rr_dnskey_set_flags(ldns_rr *r, ldns_rdf *f);
 197 /**
 198  * returns the protocol of a LDNS_RR_TYPE_DNSKEY rr
 199  * \param[in] r the resource record
 200  * \return a ldns_rdf* with the protocol or NULL on failure
 201  */
 202 ldns_rdf* ldns_rr_dnskey_protocol(const ldns_rr *r);
 203 /**
 204  * sets the protocol of a LDNS_RR_TYPE_DNSKEY rr
 205  * \param[in] r the rr to use
 206  * \param[in] f the protocol to set
 207  * \return true on success, false otherwise
 208  */
 209 bool ldns_rr_dnskey_set_protocol(ldns_rr *r, ldns_rdf *f);
 210 /**
 211  * returns the algorithm of a LDNS_RR_TYPE_DNSKEY rr
 212  * \param[in] r the resource record
 213  * \return a ldns_rdf* with the algorithm or NULL on failure
 214  */
 215 ldns_rdf* ldns_rr_dnskey_algorithm(const ldns_rr *r);
 216 /**
 217  * sets the algorithm of a LDNS_RR_TYPE_DNSKEY rr
 218  * \param[in] r the rr to use
 219  * \param[in] f the algorithm to set
 220  * \return true on success, false otherwise
 221  */
 222 bool ldns_rr_dnskey_set_algorithm(ldns_rr *r, ldns_rdf *f);
 223 /**
 224  * returns the key data of a LDNS_RR_TYPE_DNSKEY rr
 225  * \param[in] r the resource record
 226  * \return a ldns_rdf* with the key data or NULL on failure
 227  */
 228 ldns_rdf* ldns_rr_dnskey_key(const ldns_rr *r);
 229 /**
 230  * sets the key data of a LDNS_RR_TYPE_DNSKEY rr
 231  * \param[in] r the rr to use
 232  * \param[in] f the key data to set
 233  * \return true on success, false otherwise
 234  */
 235 bool ldns_rr_dnskey_set_key(ldns_rr *r, ldns_rdf *f);
 236
 237 /**
 238  * get the length of the keydata in bits
 239  * \param[in] keydata the raw key data
 240  * \param[in] len the length of the keydata
 241  * \param[in] alg the cryptographic algorithm this is a key for
 242  * \return the keysize in bits, or 0 on error
 243  */
 244 size_t ldns_rr_dnskey_key_size_raw(const unsigned char *keydata,
 245                                    const size_t len,
 246                                    const ldns_algorithm alg);
 247
 248 /**
 249  * get the length of the keydata in bits
 250  * \param[in] key the key rr to use
 251  * \return the keysize in bits
 252  */
 253 size_t ldns_rr_dnskey_key_size(const ldns_rr *key);
 254
 255 /**
 256  * The type of function to be passed to ldns_rr_soa_increment_func,
 257  * ldns_rr_soa_increment_func_data or ldns_rr_soa_increment_int.
 258  * The function will be called with as the first argument the current serial
 259  * number of the SOA RR to be updated, and as the second argument a value
 260  * given when calling ldns_rr_soa_increment_func_data or
 261  * ldns_rr_soa_increment_int. With ldns_rr_soa_increment_int the pointer
 262  * value holds the integer value passed to ldns_rr_soa_increment_int,
 263  * and it should be cast to intptr_t to be used as an integer by the
 264  * serial modifying function.
 265  */
 266 typedef uint32_t (*ldns_soa_serial_increment_func_t)(uint32_t, void*);
 267
 268 /**
 269  * Function to be used with dns_rr_soa_increment_func_int, to set the soa
 270  * serial number.
 271  * \param[in] unused the (unused) current serial number.
 272  * \param[in] data the serial number to be set.
 273  */
 274 uint32_t ldns_soa_serial_identity(uint32_t unused, void *data);
 275
 276 /**
 277  * Function to be used with dns_rr_soa_increment_func, to increment the soa
 278  * serial number with one.
 279  * \param[in] s the current serial number.
 280  * \param[in] unused unused.
 281  */
 282 uint32_t ldns_soa_serial_increment(uint32_t s, void *unused);
 283
 284 /**
 285  * Function to be used with dns_rr_soa_increment_func_int, to increment the soa
 286  * serial number with a certain amount.
 287  * \param[in] s the current serial number.
 288  * \param[in] data the amount to add to the current serial number.
 289  */
 290 uint32_t ldns_soa_serial_increment_by(uint32_t s, void *data);
 291
 292 /**
 293  * Function to be used with ldns_rr_soa_increment_func or
 294  * ldns_rr_soa_increment_func_int to set the soa serial to the number of
 295  * seconds since unix epoch (1-1-1970 00:00).
 296  * When data is given (i.e. the function is called via
 297  * ldns_rr_soa_increment_func_int), it is used as the current time.
 298  * When the resulting serial number is smaller than the current serial number,
 299  * the current serial number is increased by one.
 300  * \param[in] s the current serial number.
 301  * \param[in] data the time in seconds since 1-1-1970 00:00
 302  */
 303 uint32_t ldns_soa_serial_unixtime(uint32_t s, void *data);
 304
 305 /**
 306  * Function to be used with ldns_rr_soa_increment_func or
 307  * ldns_rr_soa_increment_func_int to set the soa serial to the current date
 308  * succeeded by a two digit iteration (datecounter).
 309  * When data is given (i.e. the function is called via
 310  * ldns_rr_soa_increment_func_int), it is used as the current time.
 311  * When the resulting serial number is smaller than the current serial number,
 312  * the current serial number is increased by one.
 313  * \param[in] s the current serial number.
 314  * \param[in] data the time in seconds since 1-1-1970 00:00
 315  */
 316 uint32_t ldns_soa_serial_datecounter(uint32_t s, void *data);
 317
 318 /**
 319  * Increment the serial number of the given SOA by one.
 320  * \param[in] soa The soa rr to be incremented
 321  */
 322 void ldns_rr_soa_increment(
 323                 ldns_rr *soa);
 324
 325 /**
 326  * Increment the serial number of the given SOA with the given function.
 327  * Included functions to be used here are: ldns_rr_soa_increment,
 328  * ldns_soa_serial_unixtime and ldns_soa_serial_datecounter.
 329  * \param[in] soa The soa rr to be incremented
 330  * \param[in] f the function to use to increment the soa rr.
 331  */
 332 void ldns_rr_soa_increment_func(
 333                 ldns_rr *soa, ldns_soa_serial_increment_func_t f);
 334
 335 /**
 336  * Increment the serial number of the given SOA with the given function
 337  * passing it the given data argument.
 338  * \param[in] soa The soa rr to be incremented
 339  * \param[in] f the function to use to increment the soa rr.
 340  * \param[in] data this argument will be passed to f as the second argument.
 341  */
 342 void ldns_rr_soa_increment_func_data(
 343                 ldns_rr *soa, ldns_soa_serial_increment_func_t f, void *data);
 344
 345 /**
 346  * Increment the serial number of the given SOA with the given function
 347  * using data as an argument for the function.
 348  * Included functions to be used here are: ldns_soa_serial_identity,
 349  * ldns_rr_soa_increment_by, ldns_soa_serial_unixtime and
 350  * ldns_soa_serial_datecounter.
 351  * \param[in] soa The soa rr to be incremented
 352  * \param[in] f the function to use to increment the soa rr.
 353  * \param[in] data this argument will be passed to f as the second argument
 354  *                 (by casting it to void*).
 355  */
 356 void ldns_rr_soa_increment_func_int(
 357                 ldns_rr *soa, ldns_soa_serial_increment_func_t f, int data);
 358
 359 #ifdef __cplusplus
 360 }
 361 #endif
 362
 363 #endif /* LDNS_RR_FUNCTIONS_H */