Update to ldns-1.6.7
[dragonfly.git] / contrib / ldns / ldns / dnssec.h
CommitLineData
825eb42b
JL
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
ac996e71
JL
37#ifdef __cplusplus
38extern "C" {
39#endif
40
825eb42b
JL
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 */
62ldns_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 */
75ldns_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 */
84ldns_rdf *ldns_nsec_get_bitmap(ldns_rr *nsec);
85
86
87#define LDNS_NSEC3_MAX_ITERATIONS 65535
88
89/**
90 * Returns the dname of the closest (provable) encloser
91 */
92ldns_rdf *
93ldns_dnssec_nsec3_closest_encloser(ldns_rdf *qname,
94 ldns_rr_type qtype,
95 ldns_rr_list *nsec3s);
96
97/**
98 * Checks whether the packet contains rrsigs
99 */
100bool
101ldns_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 */
107ldns_rr_list *ldns_dnssec_pkt_get_rrsigs_for_name_and_type(const ldns_pkt *pkt, ldns_rdf *name, ldns_rr_type type);
108
109/**
110 * Returns a ldns_rr_list containing the signatures covering the given type
111 */
112ldns_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 */
120uint16_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 */
128uint16_t ldns_calc_keytag_raw(uint8_t* key, size_t keysize);
129
130#ifdef 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 */
137DSA *ldns_key_buf2dsa(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 */
144DSA *ldns_key_buf2dsa_raw(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 */
154int ldns_digest_evp(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 */
164EVP_PKEY* ldns_gost2pkey_raw(unsigned char* key, size_t keylen);
165
ac996e71
JL
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 */
174EVP_PKEY* ldns_ecdsa2pkey_raw(unsigned char* key, size_t keylen, uint8_t algo);
175
825eb42b
JL
176#endif /* HAVE_SSL */
177
178#ifdef HAVE_SSL
179/**
180 * converts a buffer holding key material to a RSA key in openssl.
181 *
182 * \param[in] key the key to convert
183 * \return a RSA * structure with the key material
184 */
185RSA *ldns_key_buf2rsa(ldns_buffer *key);
186
187/**
188 * Like ldns_key_buf2rsa, but uses raw buffer.
189 * \param[in] key the uncompressed wireformat of the key.
190 * \param[in] len length of key data
191 * \return a RSA * structure with the key material
192 */
193RSA *ldns_key_buf2rsa_raw(unsigned char* key, size_t len);
194#endif /* HAVE_SSL */
195
196/**
197 * returns a new DS rr that represents the given key rr.
198 *
199 * \param[in] *key the key to convert
200 * \param[in] h the hash to use LDNS_SHA1/LDNS_SHA256
201 * \return ldns_rr* a new rr pointer to a DS
202 */
203ldns_rr *ldns_key_rr2ds(const ldns_rr *key, ldns_hash h);
204
205/**
206 * Create the type bitmap for an NSEC(3) record
207 */
208ldns_rdf *
209ldns_dnssec_create_nsec_bitmap(ldns_rr_type rr_type_list[],
210 size_t size,
211 ldns_rr_type nsec_type);
212
213/**
214 * Creates NSEC
215 */
216ldns_rr *
217ldns_dnssec_create_nsec(ldns_dnssec_name *from,
218 ldns_dnssec_name *to,
219 ldns_rr_type nsec_type);
220
221
222/**
223 * Creates NSEC3
224 */
225ldns_rr *
226ldns_dnssec_create_nsec3(ldns_dnssec_name *from,
227 ldns_dnssec_name *to,
228 ldns_rdf *zone_name,
229 uint8_t algorithm,
230 uint8_t flags,
231 uint16_t iterations,
232 uint8_t salt_length,
233 uint8_t *salt);
234
235/**
236 * Create a NSEC record
237 * \param[in] cur_owner the current owner which should be taken as the starting point
238 * \param[in] next_owner the rrlist which the nsec rr should point to
239 * \param[in] rrs all rrs from the zone, to find all RR types of cur_owner in
240 * \return a ldns_rr with the nsec record in it
241 */
242ldns_rr * ldns_create_nsec(ldns_rdf *cur_owner, ldns_rdf *next_owner, ldns_rr_list *rrs);
243
244/**
245 * Calculates the hashed name using the given parameters
246 * \param[in] *name The owner name to calculate the hash for
247 * \param[in] algorithm The hash algorithm to use
248 * \param[in] iterations The number of hash iterations to use
249 * \param[in] salt_length The length of the salt in bytes
250 * \param[in] salt The salt to use
251 * \return The hashed owner name rdf, without the domain name
252 */
253ldns_rdf *ldns_nsec3_hash_name(ldns_rdf *name, uint8_t algorithm, uint16_t iterations, uint8_t salt_length, uint8_t *salt);
254
255/**
256 * Sets all the NSEC3 options. The rr to set them in must be initialized with _new() and
257 * type LDNS_RR_TYPE_NSEC3
258 * \param[in] *rr The RR to set the values in
259 * \param[in] algorithm The NSEC3 hash algorithm
260 * \param[in] flags The flags field
261 * \param[in] iterations The number of hash iterations
262 * \param[in] salt_length The length of the salt in bytes
263 * \param[in] salt The salt bytes
264 */
265void ldns_nsec3_add_param_rdfs(ldns_rr *rr,
266 uint8_t algorithm,
267 uint8_t flags,
268 uint16_t iterations,
269 uint8_t salt_length,
270 uint8_t *salt);
271
272/* this will NOT return the NSEC3 completed, you will have to run the
273 finalize function on the rrlist later! */
274ldns_rr *
275ldns_create_nsec3(ldns_rdf *cur_owner,
276 ldns_rdf *cur_zone,
277 ldns_rr_list *rrs,
278 uint8_t algorithm,
279 uint8_t flags,
280 uint16_t iterations,
281 uint8_t salt_length,
282 uint8_t *salt,
283 bool emptynonterminal);
284
285/**
286 * Returns the hash algorithm used in the given NSEC3 RR
287 * \param[in] *nsec3_rr The RR to read from
288 * \return The algorithm identifier, or 0 on error
289 */
290uint8_t ldns_nsec3_algorithm(const ldns_rr *nsec3_rr);
291
292/**
293 * Returns flags field
294 */
295uint8_t
296ldns_nsec3_flags(const ldns_rr *nsec3_rr);
297
298/**
299 * Returns true if the opt-out flag has been set in the given NSEC3 RR
300 * \param[in] *nsec3_rr The RR to read from
301 * \return true if the RR has type NSEC3 and the opt-out bit has been set, false otherwise
302 */
303bool ldns_nsec3_optout(const ldns_rr *nsec3_rr);
304
305/**
306 * Returns the number of hash iterations used in the given NSEC3 RR
307 * \param[in] *nsec3_rr The RR to read from
308 * \return The number of iterations
309 */
310uint16_t ldns_nsec3_iterations(const ldns_rr *nsec3_rr);
311
312/**
313 * Returns the salt used in the given NSEC3 RR
314 * \param[in] *nsec3_rr The RR to read from
315 * \return The salt rdf, or NULL on error
316 */
317ldns_rdf *ldns_nsec3_salt(const ldns_rr *nsec3_rr);
318
319/**
320 * Returns the length of the salt used in the given NSEC3 RR
321 * \param[in] *nsec3_rr The RR to read from
322 * \return The length of the salt in bytes
323 */
324uint8_t ldns_nsec3_salt_length(const ldns_rr *nsec3_rr);
325
326/**
327 * Returns the salt bytes used in the given NSEC3 RR
328 * \param[in] *nsec3_rr The RR to read from
329 * \return The salt in bytes, this is alloced, so you need to free it
330 */
331uint8_t *ldns_nsec3_salt_data(const ldns_rr *nsec3_rr);
332
333/**
334 * Returns the first label of the next ownername in the NSEC3 chain (ie. without the domain)
335 * \param[in] nsec3_rr The RR to read from
336 * \return The first label of the next owner name in the NSEC3 chain, or NULL on error
337 */
338ldns_rdf *ldns_nsec3_next_owner(const ldns_rr *nsec3_rr);
339
340/**
341 * Returns the bitmap specifying the covered types of the given NSEC3 RR
342 * \param[in] *nsec3_rr The RR to read from
343 * \return The covered type bitmap rdf
344 */
345ldns_rdf *ldns_nsec3_bitmap(const ldns_rr *nsec3_rr);
346
347/**
348 * Calculates the hashed name using the parameters of the given NSEC3 RR
349 * \param[in] *nsec The RR to use the parameters from
350 * \param[in] *name The owner name to calculate the hash for
351 * \return The hashed owner name rdf, without the domain name
352 */
353ldns_rdf *ldns_nsec3_hash_name_frm_nsec3(const ldns_rr *nsec, ldns_rdf *name);
354
355/**
356 * Checks coverage of NSEC RR type bitmap
357 * \param[in] nsec_bitmap The NSEC bitmap rdata field to check
358 * \param[in] type The type to check
359 * \return true if the NSEC RR covers the type
360 */
361bool ldns_nsec_bitmap_covers_type(const ldns_rdf *nsec_bitmap, ldns_rr_type type);
362
363/**
364 * Checks coverage of NSEC(3) RR name span
365 * Remember that nsec and name must both be in canonical form (ie use
366 * \ref ldns_rr2canonical and \ref ldns_dname2canonical prior to calling this
367 * function)
368 *
369 * \param[in] nsec The NSEC RR to check
370 * \param[in] name The owner dname to check, if the nsec record is a NSEC3 record, this should be the hashed name
371 * \return true if the NSEC RR covers the owner name
372 */
373bool ldns_nsec_covers_name(const ldns_rr *nsec, const ldns_rdf *name);
374
375#ifdef HAVE_SSL
376/**
377 * verify a packet
378 * \param[in] p the packet
379 * \param[in] t the rr set type to check
ac996e71 380 * \param[in] o the rr set name to check
825eb42b
JL
381 * \param[in] k list of keys
382 * \param[in] s list of sigs (may be null)
383 * \param[out] good_keys keys which validated the packet
384 * \return status
385 *
386 */
387ldns_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);
388#endif
389
390/**
391 * chains nsec3 list
392 */
393ldns_status
394ldns_dnssec_chain_nsec3_list(ldns_rr_list *nsec3_rrs);
395
396/**
397 * compare for nsec3 sort
398 */
399int
400qsort_rr_compare_nsec3(const void *a, const void *b);
401
402/**
403 * sort nsec3 list
404 */
405void
406ldns_rr_list_sort_nsec3(ldns_rr_list *unsorted);
407
408/**
409 * Default callback function to always leave present signatures, and
410 * add new ones
411 * \param[in] sig The signature to check for removal (unused)
412 * \param[in] n Optional argument (unused)
413 * \return LDNS_SIGNATURE_LEAVE_ADD_NEW
414 */
415int ldns_dnssec_default_add_to_signatures(ldns_rr *sig, void *n);
416/**
417 * Default callback function to always leave present signatures, and
418 * add no new ones for the keys of these signatures
419 * \param[in] sig The signature to check for removal (unused)
420 * \param[in] n Optional argument (unused)
421 * \return LDNS_SIGNATURE_LEAVE_NO_ADD
422 */
423int ldns_dnssec_default_leave_signatures(ldns_rr *sig, void *n);
424/**
425 * Default callback function to always remove present signatures, but
426 * add no new ones
427 * \param[in] sig The signature to check for removal (unused)
428 * \param[in] n Optional argument (unused)
429 * \return LDNS_SIGNATURE_REMOVE_NO_ADD
430 */
431int ldns_dnssec_default_delete_signatures(ldns_rr *sig, void *n);
432/**
433 * Default callback function to always leave present signatures, and
434 * add new ones
435 * \param[in] sig The signature to check for removal (unused)
436 * \param[in] n Optional argument (unused)
437 * \return LDNS_SIGNATURE_REMOVE_ADD_NEW
438 */
439int ldns_dnssec_default_replace_signatures(ldns_rr *sig, void *n);
440
441#ifdef HAVE_SSL
442/**
443 * Converts the DSA signature from ASN1 representation (RFC2459, as
444 * used by OpenSSL) to raw signature data as used in DNS (rfc2536)
445 *
446 * \param[in] sig The signature in RFC2459 format
447 * \param[in] sig_len The length of the signature
448 * \return a new rdf with the signature
449 */
450ldns_rdf *
451ldns_convert_dsa_rrsig_asn12rdf(const ldns_buffer *sig,
452 const long sig_len);
453
454/**
455 * Converts the RRSIG signature RDF (in rfc2536 format) to a buffer
456 * with the signature in rfc2459 format
457 *
458 * \param[out] target_buffer buffer to place the signature data
459 * \param[in] sig_rdf The signature rdf to convert
460 * \return LDNS_STATUS_OK on success, error code otherwise
461 */
462ldns_status
463ldns_convert_dsa_rrsig_rdf2asn1(ldns_buffer *target_buffer,
464 const ldns_rdf *sig_rdf);
465
ac996e71
JL
466/**
467 * Converts the ECDSA signature from ASN1 representation (as
468 * used by OpenSSL) to raw signature data as used in DNS
469 * This routine is only present if ldns is compiled with ecdsa support.
470 *
471 * \param[in] sig The signature in ASN1 format
472 * \param[in] sig_len The length of the signature
473 * \return a new rdf with the signature
474 */
475ldns_rdf *
476ldns_convert_ecdsa_rrsig_asn12rdf(const ldns_buffer *sig, const long sig_len);
477
478/**
479 * Converts the RRSIG signature RDF (from DNS) to a buffer with the
480 * signature in ASN1 format as openssl uses it.
481 * This routine is only present if ldns is compiled with ecdsa support.
482 *
483 * \param[out] target_buffer buffer to place the signature data in ASN1.
484 * \param[in] sig_rdf The signature rdf to convert
485 * \return LDNS_STATUS_OK on success, error code otherwise
486 */
487ldns_status
488ldns_convert_ecdsa_rrsig_rdf2asn1(ldns_buffer *target_buffer,
489 const ldns_rdf *sig_rdf);
490
825eb42b
JL
491#endif /* HAVE_SSL */
492
ac996e71
JL
493#ifdef __cplusplus
494}
495#endif
496
825eb42b 497#endif /* LDNS_DNSSEC_H */