tsig.h revision 218384 
157434Smarkm/*
257434Smarkm * Copyright (C) 2004-2007, 2010  Internet Systems Consortium, Inc. ("ISC")
3263970Sdes * Copyright (C) 1999-2002  Internet Software Consortium.
4263970Sdes *
557434Smarkm * Permission to use, copy, modify, and/or distribute this software for any
6197679Sdes * purpose with or without fee is hereby granted, provided that the above
7158519Sdes * copyright notice and this permission notice appear in all copies.
857434Smarkm *
9263970Sdes * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10263970Sdes * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11197679Sdes * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12263970Sdes * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13197679Sdes * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14263970Sdes * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15263970Sdes * PERFORMANCE OF THIS SOFTWARE.
16263421Sdes */
1774818Sru
18263970Sdes/* $Id: tsig.h,v 1.51.332.4 2010-12-09 01:12:55 marka Exp $ */
19263970Sdes
20263970Sdes#ifndef DNS_TSIG_H
2157434Smarkm#define DNS_TSIG_H 1
2257434Smarkm
2374818Sru/*! \file dns/tsig.h */
24158529Sdes
25158529Sdes#include <isc/lang.h>
26#include <isc/refcount.h>
27#include <isc/rwlock.h>
28#include <isc/stdtime.h>
29
30#include <dns/types.h>
31#include <dns/name.h>
32
33#include <dst/dst.h>
34
35/*
36 * Algorithms.
37 */
38LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name;
39#define DNS_TSIG_HMACMD5_NAME		dns_tsig_hmacmd5_name
40LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name;
41#define DNS_TSIG_GSSAPI_NAME		dns_tsig_gssapi_name
42LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name;
43#define DNS_TSIG_GSSAPIMS_NAME		dns_tsig_gssapims_name
44LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha1_name;
45#define DNS_TSIG_HMACSHA1_NAME		dns_tsig_hmacsha1_name
46LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha224_name;
47#define DNS_TSIG_HMACSHA224_NAME	dns_tsig_hmacsha224_name
48LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha256_name;
49#define DNS_TSIG_HMACSHA256_NAME	dns_tsig_hmacsha256_name
50LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha384_name;
51#define DNS_TSIG_HMACSHA384_NAME	dns_tsig_hmacsha384_name
52LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha512_name;
53#define DNS_TSIG_HMACSHA512_NAME	dns_tsig_hmacsha512_name
54
55/*%
56 * Default fudge value.
57 */
58#define DNS_TSIG_FUDGE			300
59
60struct dns_tsig_keyring {
61	dns_rbt_t *keys;
62	unsigned int writecount;
63	isc_rwlock_t lock;
64	isc_mem_t *mctx;
65	/*
66	 * LRU list of generated key along with a count of the keys on the
67	 * list and a maximum size.
68	 */
69	unsigned int generated;
70	unsigned int maxgenerated;
71	ISC_LIST(dns_tsigkey_t) lru;
72};
73
74struct dns_tsigkey {
75	/* Unlocked */
76	unsigned int		magic;		/*%< Magic number. */
77	isc_mem_t		*mctx;
78	dst_key_t		*key;		/*%< Key */
79	dns_name_t		name;		/*%< Key name */
80	dns_name_t		*algorithm;	/*%< Algorithm name */
81	dns_name_t		*creator;	/*%< name that created secret */
82	isc_boolean_t		generated;	/*%< was this generated? */
83	isc_stdtime_t		inception;	/*%< start of validity period */
84	isc_stdtime_t		expire;		/*%< end of validity period */
85	dns_tsig_keyring_t	*ring;		/*%< the enclosing keyring */
86	isc_refcount_t		refs;		/*%< reference counter */
87	ISC_LINK(dns_tsigkey_t) link;
88};
89
90#define dns_tsigkey_identity(tsigkey) \
91	((tsigkey) == NULL ? NULL : \
92	 (tsigkey)->generated ? ((tsigkey)->creator) : \
93	 (&((tsigkey)->name)))
94
95ISC_LANG_BEGINDECLS
96
97isc_result_t
98dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm,
99		   unsigned char *secret, int length, isc_boolean_t generated,
100		   dns_name_t *creator, isc_stdtime_t inception,
101		   isc_stdtime_t expire, isc_mem_t *mctx,
102		   dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
103
104isc_result_t
105dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm,
106			  dst_key_t *dstkey, isc_boolean_t generated,
107			  dns_name_t *creator, isc_stdtime_t inception,
108			  isc_stdtime_t expire, isc_mem_t *mctx,
109			  dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
110/*%<
111 *	Creates a tsig key structure and saves it in the keyring.  If key is
112 *	not NULL, *key will contain a copy of the key.  The keys validity
113 *	period is specified by (inception, expire), and will not expire if
114 *	inception == expire.  If the key was generated, the creating identity,
115 *	if there is one, should be in the creator parameter.  Specifying an
116 *	unimplemented algorithm will cause failure only if dstkey != NULL; this
117 *	allows a transient key with an invalid algorithm to exist long enough
118 *	to generate a BADKEY response.
119 *
120 *	If dns_tsigkey_createfromkey is successful a new reference to 'dstkey'
121 *	will have been made.
122 *
123 *	Requires:
124 *\li		'name' is a valid dns_name_t
125 *\li		'algorithm' is a valid dns_name_t
126 *\li		'secret' is a valid pointer
127 *\li		'length' is an integer >= 0
128 *\li		'dstkey' is a valid dst key or NULL
129 *\li		'creator' points to a valid dns_name_t or is NULL
130 *\li		'mctx' is a valid memory context
131 *\li		'ring' is a valid TSIG keyring or NULL
132 *\li		'key' or '*key' must be NULL
133 *
134 *	Returns:
135 *\li		#ISC_R_SUCCESS
136 *\li		#ISC_R_EXISTS - a key with this name already exists
137 *\li		#ISC_R_NOTIMPLEMENTED - algorithm is not implemented
138 *\li		#ISC_R_NOMEMORY
139 */
140
141void
142dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
143/*%<
144 *	Attach '*targetp' to 'source'.
145 *
146 *	Requires:
147 *\li		'key' is a valid TSIG key
148 *
149 *	Ensures:
150 *\li		*targetp is attached to source.
151 */
152
153void
154dns_tsigkey_detach(dns_tsigkey_t **keyp);
155/*%<
156 *	Detaches from the tsig key structure pointed to by '*key'.
157 *
158 *	Requires:
159 *\li		'keyp' is not NULL and '*keyp' is a valid TSIG key
160 *
161 *	Ensures:
162 *\li		'keyp' points to NULL
163 */
164
165void
166dns_tsigkey_setdeleted(dns_tsigkey_t *key);
167/*%<
168 *	Prevents this key from being used again.  It will be deleted when
169 *	no references exist.
170 *
171 *	Requires:
172 *\li		'key' is a valid TSIG key on a keyring
173 */
174
175isc_result_t
176dns_tsig_sign(dns_message_t *msg);
177/*%<
178 *	Generates a TSIG record for this message
179 *
180 *	Requires:
181 *\li		'msg' is a valid message
182 *\li		'msg->tsigkey' is a valid TSIG key
183 *\li		'msg->tsig' is NULL
184 *
185 *	Returns:
186 *\li		#ISC_R_SUCCESS
187 *\li		#ISC_R_NOMEMORY
188 *\li		#ISC_R_NOSPACE
189 *\li		#DNS_R_EXPECTEDTSIG
190 *			- this is a response & msg->querytsig is NULL
191 */
192
193isc_result_t
194dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
195		dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
196/*%<
197 *	Verifies the TSIG record in this message
198 *
199 *	Requires:
200 *\li		'source' is a valid buffer containing the unparsed message
201 *\li		'msg' is a valid message
202 *\li		'msg->tsigkey' is a valid TSIG key if this is a response
203 *\li		'msg->tsig' is NULL
204 *\li		'msg->querytsig' is not NULL if this is a response
205 *\li		'ring1' and 'ring2' are each either a valid keyring or NULL
206 *
207 *	Returns:
208 *\li		#ISC_R_SUCCESS
209 *\li		#ISC_R_NOMEMORY
210 *\li		#DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen
211 *\li		#DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected
212 *\li		#DNS_R_TSIGERRORSET - the TSIG verified but ->error was set
213 *				     and this is a query
214 *\li		#DNS_R_CLOCKSKEW - the TSIG failed to verify because of
215 *				  the time was out of the allowed range.
216 *\li		#DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify
217 *\li		#DNS_R_EXPECTEDRESPONSE - the message was set over TCP and
218 *					 should have been a response,
219 *					 but was not.
220 */
221
222isc_result_t
223dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
224		 dns_name_t *algorithm, dns_tsig_keyring_t *ring);
225/*%<
226 *	Returns the TSIG key corresponding to this name and (possibly)
227 *	algorithm.  Also increments the key's reference counter.
228 *
229 *	Requires:
230 *\li		'tsigkey' is not NULL
231 *\li		'*tsigkey' is NULL
232 *\li		'name' is a valid dns_name_t
233 *\li		'algorithm' is a valid dns_name_t or NULL
234 *\li		'ring' is a valid keyring
235 *
236 *	Returns:
237 *\li		#ISC_R_SUCCESS
238 *\li		#ISC_R_NOTFOUND
239 */
240
241
242isc_result_t
243dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
244/*%<
245 *	Create an empty TSIG key ring.
246 *
247 *	Requires:
248 *\li		'mctx' is not NULL
249 *\li		'ringp' is not NULL, and '*ringp' is NULL
250 *
251 *	Returns:
252 *\li		#ISC_R_SUCCESS
253 *\li		#ISC_R_NOMEMORY
254 */
255
256
257void
258dns_tsigkeyring_destroy(dns_tsig_keyring_t **ringp);
259/*%<
260 *	Destroy a TSIG key ring.
261 *
262 *	Requires:
263 *\li		'ringp' is not NULL
264 */
265
266ISC_LANG_ENDDECLS
267
268#endif /* DNS_TSIG_H */
269