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 #include <ldns/common.h> 27 #if LDNS_BUILD_CONFIG_HAVE_SSL 28 #include <openssl/ssl.h> 29 #include <openssl/evp.h> 30 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 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 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 #define LDNS_MAX_KEYLEN 2048 42 #define LDNS_DNSSEC_KEYPROTO 3 43 /* default time before sigs expire */ 44 #define LDNS_DEFAULT_EXP_TIME 2419200 /* 4 weeks */ 45 46 /** return values for the old-signature callback */ 47 #define LDNS_SIGNATURE_LEAVE_ADD_NEW 0 48 #define LDNS_SIGNATURE_LEAVE_NO_ADD 1 49 #define LDNS_SIGNATURE_REMOVE_ADD_NEW 2 50 #define LDNS_SIGNATURE_REMOVE_NO_ADD 3 51 52 /** 53 * Returns the first RRSIG rr that corresponds to the rrset 54 * with the given name and type 55 * 56 * \param[in] name The dname of the RRset covered by the RRSIG to find 57 * \param[in] type The type of the RRset covered by the RRSIG to find 58 * \param[in] rrs List of rrs to search in 59 * \returns Pointer to the first RRsig ldns_rr found, or NULL if it is 60 * not present 61 */ 62 ldns_rr *ldns_dnssec_get_rrsig_for_name_and_type(const ldns_rdf *name, 63 const ldns_rr_type type, 64 const ldns_rr_list *rrs); 65 66 /** 67 * Returns the DNSKEY that corresponds to the given RRSIG rr from the list, if 68 * any 69 * 70 * \param[in] rrsig The rrsig to find the DNSKEY for 71 * \param[in] rrs The rr list to find the key in 72 * \return The DNSKEY that corresponds to the given RRSIG, or NULL if it was 73 * not found. 74 */ 75 ldns_rr *ldns_dnssec_get_dnskey_for_rrsig(const ldns_rr *rrsig, const ldns_rr_list *rrs); 76 77 /** 78 * Returns the rdata field that contains the bitmap of the covered types of 79 * the given NSEC record 80 * 81 * \param[in] nsec The nsec to get the covered type bitmap of 82 * \return An ldns_rdf containing the bitmap, or NULL on error 83 */ 84 ldns_rdf *ldns_nsec_get_bitmap(const ldns_rr *nsec); 85 86 87 #define LDNS_NSEC3_MAX_ITERATIONS 65535 88 89 /** 90 * Returns the dname of the closest (provable) encloser 91 */ 92 ldns_rdf * 93 ldns_dnssec_nsec3_closest_encloser(const ldns_rdf *qname, 94 ldns_rr_type qtype, 95 const ldns_rr_list *nsec3s); 96 97 /** 98 * Checks whether the packet contains rrsigs 99 */ 100 bool 101 ldns_dnssec_pkt_has_rrsigs(const ldns_pkt *pkt); 102 103 /** 104 * Returns a ldns_rr_list containing the signatures covering the given name 105 * and type 106 */ 107 ldns_rr_list *ldns_dnssec_pkt_get_rrsigs_for_name_and_type(const ldns_pkt *pkt, const ldns_rdf *name, ldns_rr_type type); 108 109 /** 110 * Returns a ldns_rr_list containing the signatures covering the given type 111 */ 112 ldns_rr_list *ldns_dnssec_pkt_get_rrsigs_for_type(const ldns_pkt *pkt, ldns_rr_type type); 113 114 /** 115 * calculates a keytag of a key for use in DNSSEC. 116 * 117 * \param[in] key the key as an RR to use for the calc. 118 * \return the keytag 119 */ 120 uint16_t ldns_calc_keytag(const ldns_rr *key); 121 122 /** 123 * Calculates keytag of DNSSEC key, operates on wireformat rdata. 124 * \param[in] key the key as uncompressed wireformat rdata. 125 * \param[in] keysize length of key data. 126 * \return the keytag 127 */ 128 uint16_t ldns_calc_keytag_raw(const uint8_t* key, size_t keysize); 129 130 #if LDNS_BUILD_CONFIG_HAVE_SSL 131 /** 132 * converts a buffer holding key material to a DSA key in openssl. 133 * 134 * \param[in] key the key to convert 135 * \return a DSA * structure with the key material 136 */ 137 DSA *ldns_key_buf2dsa(const ldns_buffer *key); 138 /** 139 * Like ldns_key_buf2dsa, but uses raw buffer. 140 * \param[in] key the uncompressed wireformat of the key. 141 * \param[in] len length of key data 142 * \return a DSA * structure with the key material 143 */ 144 DSA *ldns_key_buf2dsa_raw(const unsigned char* key, size_t len); 145 146 /** 147 * Utility function to calculate hash using generic EVP_MD pointer. 148 * \param[in] data the data to hash. 149 * \param[in] len length of data. 150 * \param[out] dest the destination of the hash, must be large enough. 151 * \param[in] md the message digest to use. 152 * \return true if worked, false on failure. 153 */ 154 int ldns_digest_evp(const unsigned char* data, unsigned int len, 155 unsigned char* dest, const EVP_MD* md); 156 157 /** 158 * Converts a holding buffer with key material to EVP PKEY in openssl. 159 * Only available if ldns was compiled with GOST. 160 * \param[in] key data to convert 161 * \param[in] keylen length of the key data 162 * \return the key or NULL on error. 163 */ 164 EVP_PKEY* ldns_gost2pkey_raw(const unsigned char* key, size_t keylen); 165 166 /** 167 * Converts a holding buffer with key material to EVP PKEY in openssl. 168 * Only available if ldns was compiled with ECDSA. 169 * \param[in] key data to convert 170 * \param[in] keylen length of the key data 171 * \param[in] algo precise algorithm to initialize ECC group values. 172 * \return the key or NULL on error. 173 */ 174 EVP_PKEY* ldns_ecdsa2pkey_raw(const unsigned char* key, size_t keylen, uint8_t algo); 175 176 /** 177 * Converts a holding buffer with key material to EVP PKEY in openssl. 178 * Only available if ldns was compiled with ED25519. 179 * \param[in] key data to convert 180 * \param[in] keylen length of the key data 181 * \return the key or NULL on error. 182 */ 183 EVP_PKEY* ldns_ed255192pkey_raw(const unsigned char* key, size_t keylen); 184 185 /** 186 * Converts a holding buffer with key material to EVP PKEY in openssl. 187 * Only available if ldns was compiled with ED448. 188 * \param[in] key data to convert 189 * \param[in] keylen length of the key data 190 * \return the key or NULL on error. 191 */ 192 EVP_PKEY* ldns_ed4482pkey_raw(const unsigned char* key, size_t keylen); 193 194 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 195 196 #if LDNS_BUILD_CONFIG_HAVE_SSL 197 /** 198 * converts a buffer holding key material to a RSA key in openssl. 199 * 200 * \param[in] key the key to convert 201 * \return a RSA * structure with the key material 202 */ 203 RSA *ldns_key_buf2rsa(const ldns_buffer *key); 204 205 /** 206 * Like ldns_key_buf2rsa, but uses raw buffer. 207 * \param[in] key the uncompressed wireformat of the key. 208 * \param[in] len length of key data 209 * \return a RSA * structure with the key material 210 */ 211 RSA *ldns_key_buf2rsa_raw(const unsigned char* key, size_t len); 212 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 213 214 /** 215 * returns a new DS rr that represents the given key rr. 216 * 217 * \param[in] *key the key to convert 218 * \param[in] h the hash to use LDNS_SHA1/LDNS_SHA256 219 * 220 * \return ldns_rr* a new rr pointer to a DS 221 */ 222 ldns_rr *ldns_key_rr2ds(const ldns_rr *key, ldns_hash h); 223 224 /** 225 * Create the type bitmap for an NSEC(3) record 226 */ 227 ldns_rdf * 228 ldns_dnssec_create_nsec_bitmap(ldns_rr_type rr_type_list[], 229 size_t size, 230 ldns_rr_type nsec_type); 231 232 /** 233 * returns whether a rrset of the given type is found in the rrsets. 234 * 235 * \param[in] rrsets the rrsets to be tested 236 * \param[in] type the type to test for 237 * \return int 1 if the type was found, 0 otherwise. 238 */ 239 int 240 ldns_dnssec_rrsets_contains_type(const ldns_dnssec_rrsets *rrsets, ldns_rr_type type); 241 242 /** 243 * Creates NSEC 244 */ 245 ldns_rr * 246 ldns_dnssec_create_nsec(const ldns_dnssec_name *from, 247 const ldns_dnssec_name *to, 248 ldns_rr_type nsec_type); 249 250 251 /** 252 * Creates NSEC3 253 */ 254 ldns_rr * 255 ldns_dnssec_create_nsec3(const ldns_dnssec_name *from, 256 const ldns_dnssec_name *to, 257 const ldns_rdf *zone_name, 258 uint8_t algorithm, 259 uint8_t flags, 260 uint16_t iterations, 261 uint8_t salt_length, 262 const uint8_t *salt); 263 264 /** 265 * Create a NSEC record 266 * \param[in] cur_owner the current owner which should be taken as the starting point 267 * \param[in] next_owner the rrlist which the nsec rr should point to 268 * \param[in] rrs all rrs from the zone, to find all RR types of cur_owner in 269 * \return a ldns_rr with the nsec record in it 270 */ 271 ldns_rr * ldns_create_nsec(ldns_rdf *cur_owner, ldns_rdf *next_owner, ldns_rr_list *rrs); 272 273 /** 274 * Calculates the hashed name using the given parameters 275 * \param[in] *name The owner name to calculate the hash for 276 * \param[in] algorithm The hash algorithm to use 277 * \param[in] iterations The number of hash iterations to use 278 * \param[in] salt_length The length of the salt in bytes 279 * \param[in] salt The salt to use 280 * \return The hashed owner name rdf, without the domain name 281 */ 282 ldns_rdf *ldns_nsec3_hash_name(const ldns_rdf *name, uint8_t algorithm, uint16_t iterations, uint8_t salt_length, const uint8_t *salt); 283 284 /** 285 * Sets all the NSEC3 options. The rr to set them in must be initialized with _new() and 286 * type LDNS_RR_TYPE_NSEC3 287 * \param[in] *rr The RR to set the values in 288 * \param[in] algorithm The NSEC3 hash algorithm 289 * \param[in] flags The flags field 290 * \param[in] iterations The number of hash iterations 291 * \param[in] salt_length The length of the salt in bytes 292 * \param[in] salt The salt bytes 293 */ 294 void ldns_nsec3_add_param_rdfs(ldns_rr *rr, 295 uint8_t algorithm, 296 uint8_t flags, 297 uint16_t iterations, 298 uint8_t salt_length, 299 const uint8_t *salt); 300 301 /* this will NOT return the NSEC3 completed, you will have to run the 302 finalize function on the rrlist later! */ 303 ldns_rr * 304 ldns_create_nsec3(const ldns_rdf *cur_owner, 305 const ldns_rdf *cur_zone, 306 const ldns_rr_list *rrs, 307 uint8_t algorithm, 308 uint8_t flags, 309 uint16_t iterations, 310 uint8_t salt_length, 311 const uint8_t *salt, 312 bool emptynonterminal); 313 314 /** 315 * Returns the hash algorithm used in the given NSEC3 RR 316 * \param[in] *nsec3_rr The RR to read from 317 * \return The algorithm identifier, or 0 on error 318 */ 319 uint8_t ldns_nsec3_algorithm(const ldns_rr *nsec3_rr); 320 321 /** 322 * Returns flags field 323 */ 324 uint8_t 325 ldns_nsec3_flags(const ldns_rr *nsec3_rr); 326 327 /** 328 * Returns true if the opt-out flag has been set in the given NSEC3 RR 329 * \param[in] *nsec3_rr The RR to read from 330 * \return true if the RR has type NSEC3 and the opt-out bit has been set, false otherwise 331 */ 332 bool ldns_nsec3_optout(const ldns_rr *nsec3_rr); 333 334 /** 335 * Returns the number of hash iterations used in the given NSEC3 RR 336 * \param[in] *nsec3_rr The RR to read from 337 * \return The number of iterations 338 */ 339 uint16_t ldns_nsec3_iterations(const ldns_rr *nsec3_rr); 340 341 /** 342 * Returns the salt used in the given NSEC3 RR 343 * \param[in] *nsec3_rr The RR to read from 344 * \return The salt rdf, or NULL on error 345 */ 346 ldns_rdf *ldns_nsec3_salt(const ldns_rr *nsec3_rr); 347 348 /** 349 * Returns the length of the salt used in the given NSEC3 RR 350 * \param[in] *nsec3_rr The RR to read from 351 * \return The length of the salt in bytes 352 */ 353 uint8_t ldns_nsec3_salt_length(const ldns_rr *nsec3_rr); 354 355 /** 356 * Returns the salt bytes used in the given NSEC3 RR 357 * \param[in] *nsec3_rr The RR to read from 358 * \return The salt in bytes, this is alloced, so you need to free it 359 */ 360 uint8_t *ldns_nsec3_salt_data(const ldns_rr *nsec3_rr); 361 362 /** 363 * Returns the first label of the next ownername in the NSEC3 chain (ie. without the domain) 364 * \param[in] nsec3_rr The RR to read from 365 * \return The first label of the next owner name in the NSEC3 chain, or NULL on error 366 */ 367 ldns_rdf *ldns_nsec3_next_owner(const ldns_rr *nsec3_rr); 368 369 /** 370 * Returns the bitmap specifying the covered types of the given NSEC3 RR 371 * \param[in] *nsec3_rr The RR to read from 372 * \return The covered type bitmap rdf 373 */ 374 ldns_rdf *ldns_nsec3_bitmap(const ldns_rr *nsec3_rr); 375 376 /** 377 * Calculates the hashed name using the parameters of the given NSEC3 RR 378 * \param[in] *nsec The RR to use the parameters from 379 * \param[in] *name The owner name to calculate the hash for 380 * \return The hashed owner name rdf, without the domain name 381 */ 382 ldns_rdf *ldns_nsec3_hash_name_frm_nsec3(const ldns_rr *nsec, const ldns_rdf *name); 383 384 /** 385 * Check if RR type t is enumerated and set in the RR type bitmap rdf. 386 * \param[in] bitmap the RR type bitmap rdf to look in 387 * \param[in] type the type to check for 388 * \return true when t is found and set, otherwise return false 389 */ 390 bool ldns_nsec_bitmap_covers_type(const ldns_rdf* bitmap, ldns_rr_type type); 391 392 /** 393 * Checks if RR type t is enumerated in the type bitmap rdf and sets the bit. 394 * \param[in] bitmap the RR type bitmap rdf to look in 395 * \param[in] type the type to for which the bit to set 396 * \return LDNS_STATUS_OK on success. LDNS_STATUS_TYPE_NOT_IN_BITMAP is 397 * returned when the bitmap does not contain the bit to set. 398 */ 399 ldns_status ldns_nsec_bitmap_set_type(ldns_rdf* bitmap, ldns_rr_type type); 400 401 /** 402 * Checks if RR type t is enumerated in the type bitmap rdf and clears the bit. 403 * \param[in] bitmap the RR type bitmap rdf to look in 404 * \param[in] type the type to for which the bit to clear 405 * \return LDNS_STATUS_OK on success. LDNS_STATUS_TYPE_NOT_IN_BITMAP is 406 * returned when the bitmap does not contain the bit to clear. 407 */ 408 ldns_status ldns_nsec_bitmap_clear_type(ldns_rdf* bitmap, ldns_rr_type type); 409 410 /** 411 * Checks coverage of NSEC(3) RR name span 412 * Remember that nsec and name must both be in canonical form (ie use 413 * \ref ldns_rr2canonical and \ref ldns_dname2canonical prior to calling this 414 * function) 415 * 416 * \param[in] nsec The NSEC RR to check 417 * \param[in] name The owner dname to check, if the nsec record is a NSEC3 record, this should be the hashed name 418 * \return true if the NSEC RR covers the owner name 419 */ 420 bool ldns_nsec_covers_name(const ldns_rr *nsec, const ldns_rdf *name); 421 422 #if LDNS_BUILD_CONFIG_HAVE_SSL 423 /** 424 * verify a packet 425 * \param[in] p the packet 426 * \param[in] t the rr set type to check 427 * \param[in] o the rr set name to check 428 * \param[in] k list of keys 429 * \param[in] s list of sigs (may be null) 430 * \param[out] good_keys keys which validated the packet 431 * \return status 432 * 433 */ 434 ldns_status ldns_pkt_verify(const ldns_pkt *p, ldns_rr_type t, const ldns_rdf *o, const ldns_rr_list *k, const ldns_rr_list *s, ldns_rr_list *good_keys); 435 436 /** 437 * verify a packet 438 * \param[in] p the packet 439 * \param[in] t the rr set type to check 440 * \param[in] o the rr set name to check 441 * \param[in] k list of keys 442 * \param[in] s list of sigs (may be null) 443 * \param[in] check_time the time for which the validation is performed 444 * \param[out] good_keys keys which validated the packet 445 * \return status 446 * 447 */ 448 ldns_status ldns_pkt_verify_time(const ldns_pkt *p, ldns_rr_type t, const ldns_rdf *o, const ldns_rr_list *k, const ldns_rr_list *s, time_t check_time, ldns_rr_list *good_keys); 449 450 #endif 451 452 /** 453 * chains nsec3 list 454 */ 455 ldns_status 456 ldns_dnssec_chain_nsec3_list(ldns_rr_list *nsec3_rrs); 457 458 /** 459 * compare for nsec3 sort 460 */ 461 int 462 qsort_rr_compare_nsec3(const void *a, const void *b); 463 464 /** 465 * sort nsec3 list 466 */ 467 void 468 ldns_rr_list_sort_nsec3(ldns_rr_list *unsorted); 469 470 /** 471 * Default callback function to always leave present signatures, and 472 * add new ones 473 * \param[in] sig The signature to check for removal (unused) 474 * \param[in] n Optional argument (unused) 475 * \return LDNS_SIGNATURE_LEAVE_ADD_NEW 476 */ 477 int ldns_dnssec_default_add_to_signatures(ldns_rr *sig, void *n); 478 /** 479 * Default callback function to always leave present signatures, and 480 * add no new ones for the keys of these signatures 481 * \param[in] sig The signature to check for removal (unused) 482 * \param[in] n Optional argument (unused) 483 * \return LDNS_SIGNATURE_LEAVE_NO_ADD 484 */ 485 int ldns_dnssec_default_leave_signatures(ldns_rr *sig, void *n); 486 /** 487 * Default callback function to always remove present signatures, but 488 * add no new ones 489 * \param[in] sig The signature to check for removal (unused) 490 * \param[in] n Optional argument (unused) 491 * \return LDNS_SIGNATURE_REMOVE_NO_ADD 492 */ 493 int ldns_dnssec_default_delete_signatures(ldns_rr *sig, void *n); 494 /** 495 * Default callback function to always leave present signatures, and 496 * add new ones 497 * \param[in] sig The signature to check for removal (unused) 498 * \param[in] n Optional argument (unused) 499 * \return LDNS_SIGNATURE_REMOVE_ADD_NEW 500 */ 501 int ldns_dnssec_default_replace_signatures(ldns_rr *sig, void *n); 502 503 #if LDNS_BUILD_CONFIG_HAVE_SSL 504 /** 505 * Converts the DSA signature from ASN1 representation (RFC2459, as 506 * used by OpenSSL) to raw signature data as used in DNS (rfc2536) 507 * 508 * \param[in] sig The signature in RFC2459 format 509 * \param[in] sig_len The length of the signature 510 * \return a new rdf with the signature 511 */ 512 ldns_rdf * 513 ldns_convert_dsa_rrsig_asn12rdf(const ldns_buffer *sig, 514 const long sig_len); 515 516 /** 517 * Converts the RRSIG signature RDF (in rfc2536 format) to a buffer 518 * with the signature in rfc2459 format 519 * 520 * \param[out] target_buffer buffer to place the signature data 521 * \param[in] sig_rdf The signature rdf to convert 522 * \return LDNS_STATUS_OK on success, error code otherwise 523 */ 524 ldns_status 525 ldns_convert_dsa_rrsig_rdf2asn1(ldns_buffer *target_buffer, 526 const ldns_rdf *sig_rdf); 527 528 /** 529 * Converts the ECDSA signature from ASN1 representation (as 530 * used by OpenSSL) to raw signature data as used in DNS 531 * This routine is only present if ldns is compiled with ecdsa support. 532 * The older ldns_convert_ecdsa_rrsig_asn12rdf routine could not (always) 533 * construct a valid rdf because it did not have the num_bytes parameter. 534 * The num_bytes parameter is 32 for p256 and 48 for p384 (bits/8). 535 * 536 * \param[in] sig The signature in ASN1 format 537 * \param[in] sig_len The length of the signature 538 * \param[in] num_bytes number of bytes for values in the curve, the curve 539 * size divided by 8. 540 * \return a new rdf with the signature 541 */ 542 ldns_rdf * 543 ldns_convert_ecdsa_rrsig_asn1len2rdf(const ldns_buffer *sig, 544 const long sig_len, int num_bytes); 545 546 /** 547 * Converts the RRSIG signature RDF (from DNS) to a buffer with the 548 * signature in ASN1 format as openssl uses it. 549 * This routine is only present if ldns is compiled with ecdsa support. 550 * 551 * \param[out] target_buffer buffer to place the signature data in ASN1. 552 * \param[in] sig_rdf The signature rdf to convert 553 * \return LDNS_STATUS_OK on success, error code otherwise 554 */ 555 ldns_status 556 ldns_convert_ecdsa_rrsig_rdf2asn1(ldns_buffer *target_buffer, 557 const ldns_rdf *sig_rdf); 558 559 #endif /* LDNS_BUILD_CONFIG_HAVE_SSL */ 560 561 #ifdef __cplusplus 562 } 563 #endif 564 565 #endif /* LDNS_DNSSEC_H */ 566