2 * Copyright (C) 2004-2007, 2010 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2002 Internet Software Consortium.
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.
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.
18 /* $Id: tsig.h,v 1.51.332.4 2010-12-09 01:12:55 marka Exp $ */
23 /*! \file dns/tsig.h */
26 #include <isc/refcount.h>
27 #include <isc/rwlock.h>
28 #include <isc/stdtime.h>
30 #include <dns/types.h>
38 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name;
39 #define DNS_TSIG_HMACMD5_NAME dns_tsig_hmacmd5_name
40 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name;
41 #define DNS_TSIG_GSSAPI_NAME dns_tsig_gssapi_name
42 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name;
43 #define DNS_TSIG_GSSAPIMS_NAME dns_tsig_gssapims_name
44 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha1_name;
45 #define DNS_TSIG_HMACSHA1_NAME dns_tsig_hmacsha1_name
46 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha224_name;
47 #define DNS_TSIG_HMACSHA224_NAME dns_tsig_hmacsha224_name
48 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha256_name;
49 #define DNS_TSIG_HMACSHA256_NAME dns_tsig_hmacsha256_name
50 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha384_name;
51 #define DNS_TSIG_HMACSHA384_NAME dns_tsig_hmacsha384_name
52 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha512_name;
53 #define DNS_TSIG_HMACSHA512_NAME dns_tsig_hmacsha512_name
56 * Default fudge value.
58 #define DNS_TSIG_FUDGE 300
60 struct dns_tsig_keyring {
62 unsigned int writecount;
66 * LRU list of generated key along with a count of the keys on the
67 * list and a maximum size.
69 unsigned int generated;
70 unsigned int maxgenerated;
71 ISC_LIST(dns_tsigkey_t) lru;
76 unsigned int magic; /*%< Magic number. */
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;
90 #define dns_tsigkey_identity(tsigkey) \
91 ((tsigkey) == NULL ? NULL : \
92 (tsigkey)->generated ? ((tsigkey)->creator) : \
98 dns_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);
105 dns_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);
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.
120 * If dns_tsigkey_createfromkey is successful a new reference to 'dstkey'
121 * will have been made.
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
136 *\li #ISC_R_EXISTS - a key with this name already exists
137 *\li #ISC_R_NOTIMPLEMENTED - algorithm is not implemented
142 dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
144 * Attach '*targetp' to 'source'.
147 *\li 'key' is a valid TSIG key
150 *\li *targetp is attached to source.
154 dns_tsigkey_detach(dns_tsigkey_t **keyp);
156 * Detaches from the tsig key structure pointed to by '*key'.
159 *\li 'keyp' is not NULL and '*keyp' is a valid TSIG key
162 *\li 'keyp' points to NULL
166 dns_tsigkey_setdeleted(dns_tsigkey_t *key);
168 * Prevents this key from being used again. It will be deleted when
169 * no references exist.
172 *\li 'key' is a valid TSIG key on a keyring
176 dns_tsig_sign(dns_message_t *msg);
178 * Generates a TSIG record for this message
181 *\li 'msg' is a valid message
182 *\li 'msg->tsigkey' is a valid TSIG key
183 *\li 'msg->tsig' is NULL
189 *\li #DNS_R_EXPECTEDTSIG
190 * - this is a response & msg->querytsig is NULL
194 dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
195 dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
197 * Verifies the TSIG record in this message
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
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,
223 dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
224 dns_name_t *algorithm, dns_tsig_keyring_t *ring);
226 * Returns the TSIG key corresponding to this name and (possibly)
227 * algorithm. Also increments the key's reference counter.
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
243 dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
245 * Create an empty TSIG key ring.
248 *\li 'mctx' is not NULL
249 *\li 'ringp' is not NULL, and '*ringp' is NULL
258 dns_tsigkeyring_destroy(dns_tsig_keyring_t **ringp);
260 * Destroy a TSIG key ring.
263 *\li 'ringp' is not NULL
268 #endif /* DNS_TSIG_H */