/contrib/bind9/lib/dns/include/dns/tsig.h

  1/*
  2 * Copyright (C) 2004-2007, 2009-2011  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: tsig.h,v 1.59 2011/01/11 23:47:13 tbox Exp $ */
 19
 20#ifndef DNS_TSIG_H
 21#define DNS_TSIG_H 1
 22
 23/*! \file dns/tsig.h */
 24
 25#include <isc/lang.h>
 26#include <isc/refcount.h>
 27#include <isc/rwlock.h>
 28#include <isc/stdio.h>
 29#include <isc/stdtime.h>
 30
 31#include <dns/types.h>
 32#include <dns/name.h>
 33
 34#include <dst/dst.h>
 35
 36/*
 37 * Algorithms.
 38 */
 39LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name;
 40#define DNS_TSIG_HMACMD5_NAME		dns_tsig_hmacmd5_name
 41LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name;
 42#define DNS_TSIG_GSSAPI_NAME		dns_tsig_gssapi_name
 43LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name;
 44#define DNS_TSIG_GSSAPIMS_NAME		dns_tsig_gssapims_name
 45LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha1_name;
 46#define DNS_TSIG_HMACSHA1_NAME		dns_tsig_hmacsha1_name
 47LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha224_name;
 48#define DNS_TSIG_HMACSHA224_NAME	dns_tsig_hmacsha224_name
 49LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha256_name;
 50#define DNS_TSIG_HMACSHA256_NAME	dns_tsig_hmacsha256_name
 51LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha384_name;
 52#define DNS_TSIG_HMACSHA384_NAME	dns_tsig_hmacsha384_name
 53LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha512_name;
 54#define DNS_TSIG_HMACSHA512_NAME	dns_tsig_hmacsha512_name
 55
 56/*%
 57 * Default fudge value.
 58 */
 59#define DNS_TSIG_FUDGE			300
 60
 61struct dns_tsig_keyring {
 62	dns_rbt_t *keys;
 63	unsigned int writecount;
 64	isc_rwlock_t lock;
 65	isc_mem_t *mctx;
 66	/*
 67	 * LRU list of generated key along with a count of the keys on the
 68	 * list and a maximum size.
 69	 */
 70	unsigned int generated;
 71	unsigned int maxgenerated;
 72	ISC_LIST(dns_tsigkey_t) lru;
 73	unsigned int references;
 74};
 75
 76struct dns_tsigkey {
 77	/* Unlocked */
 78	unsigned int		magic;		/*%< Magic number. */
 79	isc_mem_t		*mctx;
 80	dst_key_t		*key;		/*%< Key */
 81	dns_name_t		name;		/*%< Key name */
 82	dns_name_t		*algorithm;	/*%< Algorithm name */
 83	dns_name_t		*creator;	/*%< name that created secret */
 84	isc_boolean_t		generated;	/*%< was this generated? */
 85	isc_stdtime_t		inception;	/*%< start of validity period */
 86	isc_stdtime_t		expire;		/*%< end of validity period */
 87	dns_tsig_keyring_t	*ring;		/*%< the enclosing keyring */
 88	isc_refcount_t		refs;		/*%< reference counter */
 89	ISC_LINK(dns_tsigkey_t) link;
 90};
 91
 92#define dns_tsigkey_identity(tsigkey) \
 93	((tsigkey) == NULL ? NULL : \
 94	 (tsigkey)->generated ? ((tsigkey)->creator) : \
 95	 (&((tsigkey)->name)))
 96
 97ISC_LANG_BEGINDECLS
 98
 99isc_result_t
100dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm,
101		   unsigned char *secret, int length, isc_boolean_t generated,
102		   dns_name_t *creator, isc_stdtime_t inception,
103		   isc_stdtime_t expire, isc_mem_t *mctx,
104		   dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
105
106isc_result_t
107dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm,
108			  dst_key_t *dstkey, isc_boolean_t generated,
109			  dns_name_t *creator, isc_stdtime_t inception,
110			  isc_stdtime_t expire, isc_mem_t *mctx,
111			  dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
112/*%<
113 *	Creates a tsig key structure and saves it in the keyring.  If key is
114 *	not NULL, *key will contain a copy of the key.  The keys validity
115 *	period is specified by (inception, expire), and will not expire if
116 *	inception == expire.  If the key was generated, the creating identity,
117 *	if there is one, should be in the creator parameter.  Specifying an
118 *	unimplemented algorithm will cause failure only if dstkey != NULL; this
119 *	allows a transient key with an invalid algorithm to exist long enough
120 *	to generate a BADKEY response.
121 *
122 *	If dns_tsigkey_createfromkey is successful a new reference to 'dstkey'
123 *	will have been made.
124 *
125 *	Requires:
126 *\li		'name' is a valid dns_name_t
127 *\li		'algorithm' is a valid dns_name_t
128 *\li		'secret' is a valid pointer
129 *\li		'length' is an integer >= 0
130 *\li		'dstkey' is a valid dst key or NULL
131 *\li		'creator' points to a valid dns_name_t or is NULL
132 *\li		'mctx' is a valid memory context
133 *\li		'ring' is a valid TSIG keyring or NULL
134 *\li		'key' or '*key' must be NULL
135 *
136 *	Returns:
137 *\li		#ISC_R_SUCCESS
138 *\li		#ISC_R_EXISTS - a key with this name already exists
139 *\li		#ISC_R_NOTIMPLEMENTED - algorithm is not implemented
140 *\li		#ISC_R_NOMEMORY
141 */
142
143void
144dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
145/*%<
146 *	Attach '*targetp' to 'source'.
147 *
148 *	Requires:
149 *\li		'key' is a valid TSIG key
150 *
151 *	Ensures:
152 *\li		*targetp is attached to source.
153 */
154
155void
156dns_tsigkey_detach(dns_tsigkey_t **keyp);
157/*%<
158 *	Detaches from the tsig key structure pointed to by '*key'.
159 *
160 *	Requires:
161 *\li		'keyp' is not NULL and '*keyp' is a valid TSIG key
162 *
163 *	Ensures:
164 *\li		'keyp' points to NULL
165 */
166
167void
168dns_tsigkey_setdeleted(dns_tsigkey_t *key);
169/*%<
170 *	Prevents this key from being used again.  It will be deleted when
171 *	no references exist.
172 *
173 *	Requires:
174 *\li		'key' is a valid TSIG key on a keyring
175 */
176
177isc_result_t
178dns_tsig_sign(dns_message_t *msg);
179/*%<
180 *	Generates a TSIG record for this message
181 *
182 *	Requires:
183 *\li		'msg' is a valid message
184 *\li		'msg->tsigkey' is a valid TSIG key
185 *\li		'msg->tsig' is NULL
186 *
187 *	Returns:
188 *\li		#ISC_R_SUCCESS
189 *\li		#ISC_R_NOMEMORY
190 *\li		#ISC_R_NOSPACE
191 *\li		#DNS_R_EXPECTEDTSIG
192 *			- this is a response & msg->querytsig is NULL
193 */
194
195isc_result_t
196dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
197		dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
198/*%<
199 *	Verifies the TSIG record in this message
200 *
201 *	Requires:
202 *\li		'source' is a valid buffer containing the unparsed message
203 *\li		'msg' is a valid message
204 *\li		'msg->tsigkey' is a valid TSIG key if this is a response
205 *\li		'msg->tsig' is NULL
206 *\li		'msg->querytsig' is not NULL if this is a response
207 *\li		'ring1' and 'ring2' are each either a valid keyring or NULL
208 *
209 *	Returns:
210 *\li		#ISC_R_SUCCESS
211 *\li		#ISC_R_NOMEMORY
212 *\li		#DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen
213 *\li		#DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected
214 *\li		#DNS_R_TSIGERRORSET - the TSIG verified but ->error was set
215 *				     and this is a query
216 *\li		#DNS_R_CLOCKSKEW - the TSIG failed to verify because of
217 *				  the time was out of the allowed range.
218 *\li		#DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify
219 *\li		#DNS_R_EXPECTEDRESPONSE - the message was set over TCP and
220 *					 should have been a response,
221 *					 but was not.
222 */
223
224isc_result_t
225dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
226		 dns_name_t *algorithm, dns_tsig_keyring_t *ring);
227/*%<
228 *	Returns the TSIG key corresponding to this name and (possibly)
229 *	algorithm.  Also increments the key's reference counter.
230 *
231 *	Requires:
232 *\li		'tsigkey' is not NULL
233 *\li		'*tsigkey' is NULL
234 *\li		'name' is a valid dns_name_t
235 *\li		'algorithm' is a valid dns_name_t or NULL
236 *\li		'ring' is a valid keyring
237 *
238 *	Returns:
239 *\li		#ISC_R_SUCCESS
240 *\li		#ISC_R_NOTFOUND
241 */
242
243
244isc_result_t
245dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
246/*%<
247 *	Create an empty TSIG key ring.
248 *
249 *	Requires:
250 *\li		'mctx' is not NULL
251 *\li		'ringp' is not NULL, and '*ringp' is NULL
252 *
253 *	Returns:
254 *\li		#ISC_R_SUCCESS
255 *\li		#ISC_R_NOMEMORY
256 */
257
258isc_result_t
259dns_tsigkeyring_add(dns_tsig_keyring_t *ring, dns_name_t *name,
260		    dns_tsigkey_t *tkey);
261/*%<
262 *      Place a TSIG key onto a key ring.
263 *
264 *	Requires:
265 *\li		'ring', 'name' and 'tkey' are not NULL
266 *
267 *	Returns:
268 *\li		#ISC_R_SUCCESS
269 *\li		Any other value indicates failure.
270 */
271
272
273void
274dns_tsigkeyring_attach(dns_tsig_keyring_t *source, dns_tsig_keyring_t **target);
275
276void
277dns_tsigkeyring_detach(dns_tsig_keyring_t **ringp);
278
279isc_result_t
280dns_tsigkeyring_dumpanddetach(dns_tsig_keyring_t **ringp, FILE *fp);
281
282/*%<
283 *	Destroy a TSIG key ring.
284 *
285 *	Requires:
286 *\li		'ringp' is not NULL
287 */
288
289void
290dns_keyring_restore(dns_tsig_keyring_t *ring, FILE *fp);
291
292ISC_LANG_ENDDECLS
293
294#endif /* DNS_TSIG_H */