1/*
2 * Copyright (C) 2004-2010  Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2002  Internet Software Consortium.
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any
6 * purpose with or without fee is hereby granted, provided that the above
7 * copyright notice and this permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15 * PERFORMANCE OF THIS SOFTWARE.
16 */
17
18/* $Id: ncache.h,v 1.29 2010/05/14 23:50:40 tbox Exp $ */
19
20#ifndef DNS_NCACHE_H
21#define DNS_NCACHE_H 1
22
23/*****
24 ***** Module Info
25 *****/
26
27/*! \file dns/ncache.h
28 *\brief
29 * DNS Ncache
30 *
31 * XXX TBS XXX
32 *
33 * MP:
34 *\li	The caller must ensure any required synchronization.
35 *
36 * Reliability:
37 *\li	No anticipated impact.
38 *
39 * Resources:
40 *\li	TBS
41 *
42 * Security:
43 *\li	No anticipated impact.
44 *
45 * Standards:
46 *\li	RFC2308
47 */
48
49#include <isc/lang.h>
50#include <isc/stdtime.h>
51
52#include <dns/types.h>
53
54ISC_LANG_BEGINDECLS
55
56/*%
57 * _OMITDNSSEC:
58 *      Omit DNSSEC records when rendering.
59 */
60#define DNS_NCACHETOWIRE_OMITDNSSEC   0x0001
61
62isc_result_t
63dns_ncache_add(dns_message_t *message, dns_db_t *cache, dns_dbnode_t *node,
64	       dns_rdatatype_t covers, isc_stdtime_t now, dns_ttl_t maxttl,
65	       dns_rdataset_t *addedrdataset);
66isc_result_t
67dns_ncache_addoptout(dns_message_t *message, dns_db_t *cache,
68		     dns_dbnode_t *node, dns_rdatatype_t covers,
69		     isc_stdtime_t now, dns_ttl_t maxttl,
70		     isc_boolean_t optout, dns_rdataset_t *addedrdataset);
71/*%<
72 * Convert the authority data from 'message' into a negative cache
73 * rdataset, and store it in 'cache' at 'node' with a TTL limited to
74 * 'maxttl'.
75 *
76 * The 'covers' argument is the RR type whose nonexistence we are caching,
77 * or dns_rdatatype_any when caching a NXDOMAIN response.
78 *
79 * 'optout' indicates a DNS_RDATASETATTR_OPTOUT should be set.
80 *
81 * Note:
82 *\li	If 'addedrdataset' is not NULL, then it will be attached to the added
83 *	rdataset.  See dns_db_addrdataset() for more details.
84 *
85 * Requires:
86 *\li	'message' is a valid message with a properly formatting negative cache
87 *	authority section.
88 *
89 *\li	The requirements of dns_db_addrdataset() apply to 'cache', 'node',
90 *	'now', and 'addedrdataset'.
91 *
92 * Returns:
93 *\li	#ISC_R_SUCCESS
94 *\li	#ISC_R_NOSPACE
95 *
96 *\li	Any result code of dns_db_addrdataset() is a possible result code
97 *	of dns_ncache_add().
98 */
99
100isc_result_t
101dns_ncache_towire(dns_rdataset_t *rdataset, dns_compress_t *cctx,
102		  isc_buffer_t *target, unsigned int options,
103		  unsigned int *countp);
104/*%<
105 * Convert the negative caching rdataset 'rdataset' to wire format,
106 * compressing names as specified in 'cctx', and storing the result in
107 * 'target'.  If 'omit_dnssec' is set, DNSSEC records will not
108 * be added to 'target'.
109 *
110 * Notes:
111 *\li	The number of RRs added to target will be added to *countp.
112 *
113 * Requires:
114 *\li	'rdataset' is a valid negative caching rdataset.
115 *
116 *\li	'rdataset' is not empty.
117 *
118 *\li	'countp' is a valid pointer.
119 *
120 * Ensures:
121 *\li	On a return of ISC_R_SUCCESS, 'target' contains a wire format
122 *	for the data contained in 'rdataset'.  Any error return leaves
123 *	the buffer unchanged.
124 *
125 *\li	*countp has been incremented by the number of RRs added to
126 *	target.
127 *
128 * Returns:
129 *\li	#ISC_R_SUCCESS		- all ok
130 *\li	#ISC_R_NOSPACE		- 'target' doesn't have enough room
131 *
132 *\li	Any error returned by dns_rdata_towire(), dns_rdataset_next(),
133 *	dns_name_towire().
134 */
135
136isc_result_t
137dns_ncache_getrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
138		       dns_rdatatype_t type, dns_rdataset_t *rdataset);
139/*%<
140 * Search the negative caching rdataset for an rdataset with the
141 * specified name and type.
142 *
143 * Requires:
144 *\li	'ncacherdataset' is a valid negative caching rdataset.
145 *
146 *\li	'ncacherdataset' is not empty.
147 *
148 *\li	'name' is a valid name.
149 *
150 *\li	'type' is not SIG, or a meta-RR type.
151 *
152 *\li	'rdataset' is a valid disassociated rdataset.
153 *
154 * Ensures:
155 *\li	On a return of ISC_R_SUCCESS, 'rdataset' is bound to the found
156 *	rdataset.
157 *
158 * Returns:
159 *\li	#ISC_R_SUCCESS		- the rdataset was found.
160 *\li	#ISC_R_NOTFOUND		- the rdataset was not found.
161 *
162 */
163
164isc_result_t
165dns_ncache_getsigrdataset(dns_rdataset_t *ncacherdataset, dns_name_t *name,
166			  dns_rdatatype_t covers, dns_rdataset_t *rdataset);
167/*%<
168 * Similar to dns_ncache_getrdataset() but get the rrsig that matches.
169 */
170
171void
172dns_ncache_current(dns_rdataset_t *ncacherdataset, dns_name_t *found,
173		   dns_rdataset_t *rdataset);
174
175/*%<
176 * Extract the current rdataset and name from a ncache entry.
177 *
178 * Requires:
179 * \li	'ncacherdataset' to be valid and to be a negative cache entry
180 * \li	'found' to be valid.
181 * \li	'rdataset' to be unassociated.
182 */
183
184ISC_LANG_ENDDECLS
185
186#endif /* DNS_NCACHE_H */
187