1 /* 2 * dnssec.h -- defines for the Domain Name System (SEC) (DNSSEC) 3 * 4 * Copyright (c) 2005-2008, NLnet Labs. All rights reserved. 5 * 6 * See LICENSE for the license. 7 * 8 * A bunch of defines that are used in the DNS 9 */ 10 11 /** 12 * \file dnssec.h 13 * 14 * This module contains base functions for DNSSEC operations 15 * (RFC4033 t/m RFC4035). 16 * 17 * Since those functions heavily rely op cryptographic operations, 18 * this module is dependent on openssl. 19 * 20 */ 21 22 23 #ifndef LDNS_DNSSEC_H 24 #define LDNS_DNSSEC_H 25 26 #ifdef HAVE_SSL 27 #include <openssl/ssl.h> 28 #include <openssl/evp.h> 29 #endif /* HAVE_SSL */ 30 #include <ldns/common.h> 31 #include <ldns/packet.h> 32 #include <ldns/keys.h> 33 #include <ldns/zone.h> 34 #include <ldns/resolver.h> 35 #include <ldns/dnssec_zone.h> 36 37 #define LDNS_MAX_KEYLEN 2048 38 #define LDNS_DNSSEC_KEYPROTO 3 39 /* default time before sigs expire */ 40 #define LDNS_DEFAULT_EXP_TIME 2419200 /* 4 weeks */ 41 42 /** return values for the old-signature callback */ 43 #define LDNS_SIGNATURE_LEAVE_ADD_NEW 0 44 #define LDNS_SIGNATURE_LEAVE_NO_ADD 1 45 #define LDNS_SIGNATURE_REMOVE_ADD_NEW 2 46 #define LDNS_SIGNATURE_REMOVE_NO_ADD 3 47 48 /** 49 * Returns the first RRSIG rr that corresponds to the rrset 50 * with the given name and type 51 * 52 * \param[in] name The dname of the RRset covered by the RRSIG to find 53 * \param[in] type The type of the RRset covered by the RRSIG to find 54 * \param[in] rrs List of rrs to search in 55 * \returns Pointer to the first RRsig ldns_rr found, or NULL if it is 56 * not present 57 */ 58 ldns_rr *ldns_dnssec_get_rrsig_for_name_and_type(const ldns_rdf *name, 59 const ldns_rr_type type, 60 const ldns_rr_list *rrs); 61 62 /** 63 * Returns the DNSKEY that corresponds to the given RRSIG rr from the list, if 64 * any 65 * 66 * \param[in] rrsig The rrsig to find the DNSKEY for 67 * \param[in] rrs The rr list to find the key in 68 * \return The DNSKEY that corresponds to the given RRSIG, or NULL if it was 69 * not found. 70 */ 71 ldns_rr *ldns_dnssec_get_dnskey_for_rrsig(const ldns_rr *rrsig, const ldns_rr_list *rrs); 72 73 /** 74 * Returns the rdata field that contains the bitmap of the covered types of 75 * the given NSEC record 76 * 77 * \param[in] nsec The nsec to get the covered type bitmap of 78 * \return An ldns_rdf containing the bitmap, or NULL on error 79 */ 80 ldns_rdf *ldns_nsec_get_bitmap(ldns_rr *nsec); 81 82 83 #define LDNS_NSEC3_MAX_ITERATIONS 65535 84 85 /** 86 * Returns the dname of the closest (provable) encloser 87 */ 88 ldns_rdf * 89 ldns_dnssec_nsec3_closest_encloser(ldns_rdf *qname, 90 ldns_rr_type qtype, 91 ldns_rr_list *nsec3s); 92 93 /** 94 * Checks whether the packet contains rrsigs 95 */ 96 bool 97 ldns_dnssec_pkt_has_rrsigs(const ldns_pkt *pkt); 98 99 /** 100 * Returns a ldns_rr_list containing the signatures covering the given name 101 * and type 102 */ 103 ldns_rr_list *ldns_dnssec_pkt_get_rrsigs_for_name_and_type(const ldns_pkt *pkt, ldns_rdf *name, ldns_rr_type type); 104 105 /** 106 * Returns a ldns_rr_list containing the signatures covering the given type 107 */ 108 ldns_rr_list *ldns_dnssec_pkt_get_rrsigs_for_type(const ldns_pkt *pkt, ldns_rr_type type); 109 110 /** 111 * calculates a keytag of a key for use in DNSSEC. 112 * 113 * \param[in] key the key as an RR to use for the calc. 114 * \return the keytag 115 */ 116 uint16_t ldns_calc_keytag(const ldns_rr *key); 117 118 /** 119 * Calculates keytag of DNSSEC key, operates on wireformat rdata. 120 * \param[in] key the key as uncompressed wireformat rdata. 121 * \param[in] keysize length of key data. 122 * \return the keytag 123 */ 124 uint16_t ldns_calc_keytag_raw(uint8_t* key, size_t keysize); 125 126 #ifdef HAVE_SSL 127 /** 128 * converts a buffer holding key material to a DSA key in openssl. 129 * 130 * \param[in] key the key to convert 131 * \return a DSA * structure with the key material 132 */ 133 DSA *ldns_key_buf2dsa(ldns_buffer *key); 134 /** 135 * Like ldns_key_buf2dsa, but uses raw buffer. 136 * \param[in] key the uncompressed wireformat of the key. 137 * \param[in] len length of key data 138 * \return a DSA * structure with the key material 139 */ 140 DSA *ldns_key_buf2dsa_raw(unsigned char* key, size_t len); 141 142 /** 143 * Utility function to calculate hash using generic EVP_MD pointer. 144 * \param[in] data the data to hash. 145 * \param[in] len length of data. 146 * \param[out] dest the destination of the hash, must be large enough. 147 * \param[in] md the message digest to use. 148 * \return true if worked, false on failure. 149 */ 150 int ldns_digest_evp(unsigned char* data, unsigned int len, 151 unsigned char* dest, const EVP_MD* md); 152 153 /** 154 * Converts a holding buffer with key material to EVP PKEY in openssl. 155 * Only available if ldns was compiled with GOST. 156 * \param[in] key data to convert 157 * \param[in] keylen length of the key data 158 * \return the key or NULL on error. 159 */ 160 EVP_PKEY* ldns_gost2pkey_raw(unsigned char* key, size_t keylen); 161 162 #endif /* HAVE_SSL */ 163 164 #ifdef HAVE_SSL 165 /** 166 * converts a buffer holding key material to a RSA key in openssl. 167 * 168 * \param[in] key the key to convert 169 * \return a RSA * structure with the key material 170 */ 171 RSA *ldns_key_buf2rsa(ldns_buffer *key); 172 173 /** 174 * Like ldns_key_buf2rsa, but uses raw buffer. 175 * \param[in] key the uncompressed wireformat of the key. 176 * \param[in] len length of key data 177 * \return a RSA * structure with the key material 178 */ 179 RSA *ldns_key_buf2rsa_raw(unsigned char* key, size_t len); 180 #endif /* HAVE_SSL */ 181 182 /** 183 * returns a new DS rr that represents the given key rr. 184 * 185 * \param[in] *key the key to convert 186 * \param[in] h the hash to use LDNS_SHA1/LDNS_SHA256 187 * \return ldns_rr* a new rr pointer to a DS 188 */ 189 ldns_rr *ldns_key_rr2ds(const ldns_rr *key, ldns_hash h); 190 191 /** 192 * Create the type bitmap for an NSEC(3) record 193 */ 194 ldns_rdf * 195 ldns_dnssec_create_nsec_bitmap(ldns_rr_type rr_type_list[], 196 size_t size, 197 ldns_rr_type nsec_type); 198 199 /** 200 * Creates NSEC 201 */ 202 ldns_rr * 203 ldns_dnssec_create_nsec(ldns_dnssec_name *from, 204 ldns_dnssec_name *to, 205 ldns_rr_type nsec_type); 206 207 208 /** 209 * Creates NSEC3 210 */ 211 ldns_rr * 212 ldns_dnssec_create_nsec3(ldns_dnssec_name *from, 213 ldns_dnssec_name *to, 214 ldns_rdf *zone_name, 215 uint8_t algorithm, 216 uint8_t flags, 217 uint16_t iterations, 218 uint8_t salt_length, 219 uint8_t *salt); 220 221 /** 222 * Create a NSEC record 223 * \param[in] cur_owner the current owner which should be taken as the starting point 224 * \param[in] next_owner the rrlist which the nsec rr should point to 225 * \param[in] rrs all rrs from the zone, to find all RR types of cur_owner in 226 * \return a ldns_rr with the nsec record in it 227 */ 228 ldns_rr * ldns_create_nsec(ldns_rdf *cur_owner, ldns_rdf *next_owner, ldns_rr_list *rrs); 229 230 /** 231 * Calculates the hashed name using the given parameters 232 * \param[in] *name The owner name to calculate the hash for 233 * \param[in] algorithm The hash algorithm to use 234 * \param[in] iterations The number of hash iterations to use 235 * \param[in] salt_length The length of the salt in bytes 236 * \param[in] salt The salt to use 237 * \return The hashed owner name rdf, without the domain name 238 */ 239 ldns_rdf *ldns_nsec3_hash_name(ldns_rdf *name, uint8_t algorithm, uint16_t iterations, uint8_t salt_length, uint8_t *salt); 240 241 /** 242 * Sets all the NSEC3 options. The rr to set them in must be initialized with _new() and 243 * type LDNS_RR_TYPE_NSEC3 244 * \param[in] *rr The RR to set the values in 245 * \param[in] algorithm The NSEC3 hash algorithm 246 * \param[in] flags The flags field 247 * \param[in] iterations The number of hash iterations 248 * \param[in] salt_length The length of the salt in bytes 249 * \param[in] salt The salt bytes 250 */ 251 void ldns_nsec3_add_param_rdfs(ldns_rr *rr, 252 uint8_t algorithm, 253 uint8_t flags, 254 uint16_t iterations, 255 uint8_t salt_length, 256 uint8_t *salt); 257 258 /* this will NOT return the NSEC3 completed, you will have to run the 259 finalize function on the rrlist later! */ 260 ldns_rr * 261 ldns_create_nsec3(ldns_rdf *cur_owner, 262 ldns_rdf *cur_zone, 263 ldns_rr_list *rrs, 264 uint8_t algorithm, 265 uint8_t flags, 266 uint16_t iterations, 267 uint8_t salt_length, 268 uint8_t *salt, 269 bool emptynonterminal); 270 271 /** 272 * Returns the hash algorithm used in the given NSEC3 RR 273 * \param[in] *nsec3_rr The RR to read from 274 * \return The algorithm identifier, or 0 on error 275 */ 276 uint8_t ldns_nsec3_algorithm(const ldns_rr *nsec3_rr); 277 278 /** 279 * Returns flags field 280 */ 281 uint8_t 282 ldns_nsec3_flags(const ldns_rr *nsec3_rr); 283 284 /** 285 * Returns true if the opt-out flag has been set in the given NSEC3 RR 286 * \param[in] *nsec3_rr The RR to read from 287 * \return true if the RR has type NSEC3 and the opt-out bit has been set, false otherwise 288 */ 289 bool ldns_nsec3_optout(const ldns_rr *nsec3_rr); 290 291 /** 292 * Returns the number of hash iterations used in the given NSEC3 RR 293 * \param[in] *nsec3_rr The RR to read from 294 * \return The number of iterations 295 */ 296 uint16_t ldns_nsec3_iterations(const ldns_rr *nsec3_rr); 297 298 /** 299 * Returns the salt used in the given NSEC3 RR 300 * \param[in] *nsec3_rr The RR to read from 301 * \return The salt rdf, or NULL on error 302 */ 303 ldns_rdf *ldns_nsec3_salt(const ldns_rr *nsec3_rr); 304 305 /** 306 * Returns the length of the salt used in the given NSEC3 RR 307 * \param[in] *nsec3_rr The RR to read from 308 * \return The length of the salt in bytes 309 */ 310 uint8_t ldns_nsec3_salt_length(const ldns_rr *nsec3_rr); 311 312 /** 313 * Returns the salt bytes used in the given NSEC3 RR 314 * \param[in] *nsec3_rr The RR to read from 315 * \return The salt in bytes, this is alloced, so you need to free it 316 */ 317 uint8_t *ldns_nsec3_salt_data(const ldns_rr *nsec3_rr); 318 319 /** 320 * Returns the first label of the next ownername in the NSEC3 chain (ie. without the domain) 321 * \param[in] nsec3_rr The RR to read from 322 * \return The first label of the next owner name in the NSEC3 chain, or NULL on error 323 */ 324 ldns_rdf *ldns_nsec3_next_owner(const ldns_rr *nsec3_rr); 325 326 /** 327 * Returns the bitmap specifying the covered types of the given NSEC3 RR 328 * \param[in] *nsec3_rr The RR to read from 329 * \return The covered type bitmap rdf 330 */ 331 ldns_rdf *ldns_nsec3_bitmap(const ldns_rr *nsec3_rr); 332 333 /** 334 * Calculates the hashed name using the parameters of the given NSEC3 RR 335 * \param[in] *nsec The RR to use the parameters from 336 * \param[in] *name The owner name to calculate the hash for 337 * \return The hashed owner name rdf, without the domain name 338 */ 339 ldns_rdf *ldns_nsec3_hash_name_frm_nsec3(const ldns_rr *nsec, ldns_rdf *name); 340 341 /** 342 * Checks coverage of NSEC RR type bitmap 343 * \param[in] nsec_bitmap The NSEC bitmap rdata field to check 344 * \param[in] type The type to check 345 * \return true if the NSEC RR covers the type 346 */ 347 bool ldns_nsec_bitmap_covers_type(const ldns_rdf *nsec_bitmap, ldns_rr_type type); 348 349 /** 350 * Checks coverage of NSEC(3) RR name span 351 * Remember that nsec and name must both be in canonical form (ie use 352 * \ref ldns_rr2canonical and \ref ldns_dname2canonical prior to calling this 353 * function) 354 * 355 * \param[in] nsec The NSEC RR to check 356 * \param[in] name The owner dname to check, if the nsec record is a NSEC3 record, this should be the hashed name 357 * \return true if the NSEC RR covers the owner name 358 */ 359 bool ldns_nsec_covers_name(const ldns_rr *nsec, const ldns_rdf *name); 360 361 #ifdef HAVE_SSL 362 /** 363 * verify a packet 364 * \param[in] p the packet 365 * \param[in] t the rr set type to check 366 * \param[in] o the rr set name to ckeck 367 * \param[in] k list of keys 368 * \param[in] s list of sigs (may be null) 369 * \param[out] good_keys keys which validated the packet 370 * \return status 371 * 372 */ 373 ldns_status ldns_pkt_verify(ldns_pkt *p, ldns_rr_type t, ldns_rdf *o, ldns_rr_list *k, ldns_rr_list *s, ldns_rr_list *good_keys); 374 #endif 375 376 /** 377 * chains nsec3 list 378 */ 379 ldns_status 380 ldns_dnssec_chain_nsec3_list(ldns_rr_list *nsec3_rrs); 381 382 /** 383 * compare for nsec3 sort 384 */ 385 int 386 qsort_rr_compare_nsec3(const void *a, const void *b); 387 388 /** 389 * sort nsec3 list 390 */ 391 void 392 ldns_rr_list_sort_nsec3(ldns_rr_list *unsorted); 393 394 /** 395 * Default callback function to always leave present signatures, and 396 * add new ones 397 * \param[in] sig The signature to check for removal (unused) 398 * \param[in] n Optional argument (unused) 399 * \return LDNS_SIGNATURE_LEAVE_ADD_NEW 400 */ 401 int ldns_dnssec_default_add_to_signatures(ldns_rr *sig, void *n); 402 /** 403 * Default callback function to always leave present signatures, and 404 * add no new ones for the keys of these signatures 405 * \param[in] sig The signature to check for removal (unused) 406 * \param[in] n Optional argument (unused) 407 * \return LDNS_SIGNATURE_LEAVE_NO_ADD 408 */ 409 int ldns_dnssec_default_leave_signatures(ldns_rr *sig, void *n); 410 /** 411 * Default callback function to always remove present signatures, but 412 * add no new ones 413 * \param[in] sig The signature to check for removal (unused) 414 * \param[in] n Optional argument (unused) 415 * \return LDNS_SIGNATURE_REMOVE_NO_ADD 416 */ 417 int ldns_dnssec_default_delete_signatures(ldns_rr *sig, void *n); 418 /** 419 * Default callback function to always leave present signatures, and 420 * add new ones 421 * \param[in] sig The signature to check for removal (unused) 422 * \param[in] n Optional argument (unused) 423 * \return LDNS_SIGNATURE_REMOVE_ADD_NEW 424 */ 425 int ldns_dnssec_default_replace_signatures(ldns_rr *sig, void *n); 426 427 #ifdef HAVE_SSL 428 /** 429 * Converts the DSA signature from ASN1 representation (RFC2459, as 430 * used by OpenSSL) to raw signature data as used in DNS (rfc2536) 431 * 432 * \param[in] sig The signature in RFC2459 format 433 * \param[in] sig_len The length of the signature 434 * \return a new rdf with the signature 435 */ 436 ldns_rdf * 437 ldns_convert_dsa_rrsig_asn12rdf(const ldns_buffer *sig, 438 const long sig_len); 439 440 /** 441 * Converts the RRSIG signature RDF (in rfc2536 format) to a buffer 442 * with the signature in rfc2459 format 443 * 444 * \param[out] target_buffer buffer to place the signature data 445 * \param[in] sig_rdf The signature rdf to convert 446 * \return LDNS_STATUS_OK on success, error code otherwise 447 */ 448 ldns_status 449 ldns_convert_dsa_rrsig_rdf2asn1(ldns_buffer *target_buffer, 450 const ldns_rdf *sig_rdf); 451 452 #endif /* HAVE_SSL */ 453 454 #endif /* LDNS_DNSSEC_H */ 455