contrib/ldns/ldns/dnssec.h

   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 */