Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / dns / include / dns / tsig.h
1 /*
2  * Copyright (C) 2004-2007  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.51 2007/06/19 23:47:17 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/stdtime.h>
29
30 #include <dns/types.h>
31 #include <dns/name.h>
32
33 #include <dst/dst.h>
34
35 /*
36  * Algorithms.
37  */
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
54
55 /*%
56  * Default fudge value.
57  */
58 #define DNS_TSIG_FUDGE                  300
59
60 struct dns_tsig_keyring {
61         dns_rbt_t *keys;
62         unsigned int writecount;
63         isc_rwlock_t lock;
64         isc_mem_t *mctx;
65 };
66
67 struct dns_tsigkey {
68         /* Unlocked */
69         unsigned int            magic;          /*%< Magic number. */
70         isc_mem_t               *mctx;
71         dst_key_t               *key;           /*%< Key */
72         dns_name_t              name;           /*%< Key name */
73         dns_name_t              *algorithm;     /*%< Algorithm name */
74         dns_name_t              *creator;       /*%< name that created secret */
75         isc_boolean_t           generated;      /*%< was this generated? */
76         isc_stdtime_t           inception;      /*%< start of validity period */
77         isc_stdtime_t           expire;         /*%< end of validity period */
78         dns_tsig_keyring_t      *ring;          /*%< the enclosing keyring */
79         isc_refcount_t          refs;           /*%< reference counter */
80 };
81
82 #define dns_tsigkey_identity(tsigkey) \
83         ((tsigkey) == NULL ? NULL : \
84          (tsigkey)->generated ? ((tsigkey)->creator) : \
85          (&((tsigkey)->name)))
86
87 ISC_LANG_BEGINDECLS
88
89 isc_result_t
90 dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm,
91                    unsigned char *secret, int length, isc_boolean_t generated,
92                    dns_name_t *creator, isc_stdtime_t inception,
93                    isc_stdtime_t expire, isc_mem_t *mctx,
94                    dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
95
96 isc_result_t
97 dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm,
98                           dst_key_t *dstkey, isc_boolean_t generated,
99                           dns_name_t *creator, isc_stdtime_t inception,
100                           isc_stdtime_t expire, isc_mem_t *mctx,
101                           dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
102 /*%<
103  *      Creates a tsig key structure and saves it in the keyring.  If key is
104  *      not NULL, *key will contain a copy of the key.  The keys validity
105  *      period is specified by (inception, expire), and will not expire if
106  *      inception == expire.  If the key was generated, the creating identity,
107  *      if there is one, should be in the creator parameter.  Specifying an
108  *      unimplemented algorithm will cause failure only if dstkey != NULL; this
109  *      allows a transient key with an invalid algorithm to exist long enough
110  *      to generate a BADKEY response.
111  *
112  *      Requires:
113  *\li           'name' is a valid dns_name_t
114  *\li           'algorithm' is a valid dns_name_t
115  *\li           'secret' is a valid pointer
116  *\li           'length' is an integer >= 0
117  *\li           'key' is a valid dst key or NULL
118  *\li           'creator' points to a valid dns_name_t or is NULL
119  *\li           'mctx' is a valid memory context
120  *\li           'ring' is a valid TSIG keyring or NULL
121  *\li           'key' or '*key' must be NULL
122  *
123  *      Returns:
124  *\li           #ISC_R_SUCCESS
125  *\li           #ISC_R_EXISTS - a key with this name already exists
126  *\li           #ISC_R_NOTIMPLEMENTED - algorithm is not implemented
127  *\li           #ISC_R_NOMEMORY
128  */
129
130 void
131 dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
132 /*%<
133  *      Attach '*targetp' to 'source'.
134  *
135  *      Requires:
136  *\li           'key' is a valid TSIG key
137  *
138  *      Ensures:
139  *\li           *targetp is attached to source.
140  */
141
142 void
143 dns_tsigkey_detach(dns_tsigkey_t **keyp);
144 /*%<
145  *      Detaches from the tsig key structure pointed to by '*key'.
146  *
147  *      Requires:
148  *\li           'keyp' is not NULL and '*keyp' is a valid TSIG key
149  *
150  *      Ensures:
151  *\li           'keyp' points to NULL
152  */
153
154 void
155 dns_tsigkey_setdeleted(dns_tsigkey_t *key);
156 /*%<
157  *      Prevents this key from being used again.  It will be deleted when
158  *      no references exist.
159  *
160  *      Requires:
161  *\li           'key' is a valid TSIG key on a keyring
162  */
163
164 isc_result_t
165 dns_tsig_sign(dns_message_t *msg);
166 /*%<
167  *      Generates a TSIG record for this message
168  *
169  *      Requires:
170  *\li           'msg' is a valid message
171  *\li           'msg->tsigkey' is a valid TSIG key
172  *\li           'msg->tsig' is NULL
173  *
174  *      Returns:
175  *\li           #ISC_R_SUCCESS
176  *\li           #ISC_R_NOMEMORY
177  *\li           #ISC_R_NOSPACE
178  *\li           #DNS_R_EXPECTEDTSIG
179  *                      - this is a response & msg->querytsig is NULL
180  */
181
182 isc_result_t
183 dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
184                 dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
185 /*%<
186  *      Verifies the TSIG record in this message
187  *
188  *      Requires:
189  *\li           'source' is a valid buffer containing the unparsed message
190  *\li           'msg' is a valid message
191  *\li           'msg->tsigkey' is a valid TSIG key if this is a response
192  *\li           'msg->tsig' is NULL
193  *\li           'msg->querytsig' is not NULL if this is a response
194  *\li           'ring1' and 'ring2' are each either a valid keyring or NULL
195  *
196  *      Returns:
197  *\li           #ISC_R_SUCCESS
198  *\li           #ISC_R_NOMEMORY
199  *\li           #DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen
200  *\li           #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected
201  *\li           #DNS_R_TSIGERRORSET - the TSIG verified but ->error was set
202  *                                   and this is a query
203  *\li           #DNS_R_CLOCKSKEW - the TSIG failed to verify because of
204  *                                the time was out of the allowed range.
205  *\li           #DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify
206  *\li           #DNS_R_EXPECTEDRESPONSE - the message was set over TCP and
207  *                                       should have been a response,
208  *                                       but was not.
209  */
210
211 isc_result_t
212 dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
213                  dns_name_t *algorithm, dns_tsig_keyring_t *ring);
214 /*%<
215  *      Returns the TSIG key corresponding to this name and (possibly)
216  *      algorithm.  Also increments the key's reference counter.
217  *
218  *      Requires:
219  *\li           'tsigkey' is not NULL
220  *\li           '*tsigkey' is NULL
221  *\li           'name' is a valid dns_name_t
222  *\li           'algorithm' is a valid dns_name_t or NULL
223  *\li           'ring' is a valid keyring
224  *
225  *      Returns:
226  *\li           #ISC_R_SUCCESS
227  *\li           #ISC_R_NOTFOUND
228  */
229
230
231 isc_result_t
232 dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
233 /*%<
234  *      Create an empty TSIG key ring.
235  *
236  *      Requires:
237  *\li           'mctx' is not NULL
238  *\li           'ringp' is not NULL, and '*ringp' is NULL
239  *
240  *      Returns:
241  *\li           #ISC_R_SUCCESS
242  *\li           #ISC_R_NOMEMORY
243  */
244
245
246 void
247 dns_tsigkeyring_destroy(dns_tsig_keyring_t **ringp);
248 /*%<
249  *      Destroy a TSIG key ring.
250  *
251  *      Requires:
252  *\li           'ringp' is not NULL
253  */
254
255 ISC_LANG_ENDDECLS
256
257 #endif /* DNS_TSIG_H */