Initial vendor import of ldns-1.6.4 into contrib.
[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
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 */
58ldns_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 */
71ldns_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 */
80ldns_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 */
88ldns_rdf *
89ldns_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 */
96bool
97ldns_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 */
103ldns_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 */
108ldns_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 */
116uint16_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 */
124uint16_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 */
133DSA *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 */
140DSA *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 */
150int 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 */
160EVP_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 */
171RSA *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 */
179RSA *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 */
189ldns_rr *ldns_key_rr2ds(const ldns_rr *key, ldns_hash h);
190
191/**
192 * Create the type bitmap for an NSEC(3) record
193 */
194ldns_rdf *
195ldns_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 */
202ldns_rr *
203ldns_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 */
211ldns_rr *
212ldns_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 */
228ldns_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 */
239ldns_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 */
251void 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! */
260ldns_rr *
261ldns_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 */
276uint8_t ldns_nsec3_algorithm(const ldns_rr *nsec3_rr);
277
278/**
279 * Returns flags field
280 */
281uint8_t
282ldns_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 */
289bool 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 */
296uint16_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 */
303ldns_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 */
310uint8_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 */
317uint8_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 */
324ldns_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 */
331ldns_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 */
339ldns_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 */
347bool 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 */
359bool 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 */
373ldns_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 */
379ldns_status
380ldns_dnssec_chain_nsec3_list(ldns_rr_list *nsec3_rrs);
381
382/**
383 * compare for nsec3 sort
384 */
385int
386qsort_rr_compare_nsec3(const void *a, const void *b);
387
388/**
389 * sort nsec3 list
390 */
391void
392ldns_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 */
401int 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 */
409int 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 */
417int 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 */
425int 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 */
436ldns_rdf *
437ldns_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 */
448ldns_status
449ldns_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 */