Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / dns / include / dns / tkey.h
1 /*
2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 1999-2001  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: tkey.h,v 1.26.128.2 2009/01/19 23:47:03 tbox Exp $ */
19
20 #ifndef DNS_TKEY_H
21 #define DNS_TKEY_H 1
22
23 /*! \file dns/tkey.h */
24
25 #include <isc/lang.h>
26
27 #include <dns/types.h>
28
29 #include <dst/dst.h>
30 #include <dst/gssapi.h>
31
32 ISC_LANG_BEGINDECLS
33
34 /* Key agreement modes */
35 #define DNS_TKEYMODE_SERVERASSIGNED             1
36 #define DNS_TKEYMODE_DIFFIEHELLMAN              2
37 #define DNS_TKEYMODE_GSSAPI                     3
38 #define DNS_TKEYMODE_RESOLVERASSIGNED           4
39 #define DNS_TKEYMODE_DELETE                     5
40
41 struct dns_tkeyctx {
42         dst_key_t *dhkey;
43         dns_name_t *domain;
44         gss_cred_id_t gsscred;
45         isc_mem_t *mctx;
46         isc_entropy_t *ectx;
47 };
48
49 isc_result_t
50 dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx,
51                    dns_tkeyctx_t **tctxp);
52 /*%<
53  *      Create an empty TKEY context.
54  *
55  *      Requires:
56  *\li           'mctx' is not NULL
57  *\li           'tctx' is not NULL
58  *\li           '*tctx' is NULL
59  *
60  *      Returns
61  *\li           #ISC_R_SUCCESS
62  *\li           #ISC_R_NOMEMORY
63  *\li           return codes from dns_name_fromtext()
64  */
65
66 void
67 dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
68 /*%<
69  *      Frees all data associated with the TKEY context
70  *
71  *      Requires:
72  *\li           'tctx' is not NULL
73  *\li           '*tctx' is not NULL
74  */
75
76 isc_result_t
77 dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
78                       dns_tsig_keyring_t *ring);
79 /*%<
80  *      Processes a query containing a TKEY record, adding or deleting TSIG
81  *      keys if necessary, and modifies the message to contain the response.
82  *
83  *      Requires:
84  *\li           'msg' is a valid message
85  *\li           'tctx' is a valid TKEY context
86  *\li           'ring' is a valid TSIG keyring
87  *
88  *      Returns
89  *\li           #ISC_R_SUCCESS  msg was updated (the TKEY operation succeeded,
90  *                              or msg now includes a TKEY with an error set)
91  *              DNS_R_FORMERR   the packet was malformed (missing a TKEY
92  *                              or KEY).
93  *\li           other           An error occurred while processing the message
94  */
95
96 isc_result_t
97 dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name,
98                       dns_name_t *algorithm, isc_buffer_t *nonce,
99                       isc_uint32_t lifetime);
100 /*%<
101  *      Builds a query containing a TKEY that will generate a shared
102  *      secret using a Diffie-Hellman key exchange.  The shared key
103  *      will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
104  *      is supported), and will be named either 'name',
105  *      'name' + server chosen domain, or random data + server chosen domain
106  *      if 'name' == dns_rootname.  If nonce is not NULL, it supplies
107  *      random data used in the shared secret computation.  The key is
108  *      requested to have the specified lifetime (in seconds)
109  *
110  *
111  *      Requires:
112  *\li           'msg' is a valid message
113  *\li           'key' is a valid Diffie Hellman dst key
114  *\li           'name' is a valid name
115  *\li           'algorithm' is a valid name
116  *
117  *      Returns:
118  *\li           #ISC_R_SUCCESS  msg was successfully updated to include the
119  *                              query to be sent
120  *\li           other           an error occurred while building the message
121  */
122
123 isc_result_t
124 dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name, dns_name_t *gname,
125                        isc_buffer_t *intoken, isc_uint32_t lifetime,
126                        gss_ctx_id_t *context, isc_boolean_t win2k);
127 /*%<
128  *      Builds a query containing a TKEY that will generate a GSSAPI context.
129  *      The key is requested to have the specified lifetime (in seconds).
130  *
131  *      Requires:
132  *\li           'msg'     is a valid message
133  *\li           'name'    is a valid name
134  *\li           'gname'   is a valid name
135  *\li           'context' is a pointer to a valid gss_ctx_id_t
136  *                        (which may have the value GSS_C_NO_CONTEXT)
137  *\li           'win2k'   when true says to turn on some hacks to work
138  *                        with the non-standard GSS-TSIG of Windows 2000
139  *
140  *      Returns:
141  *\li           ISC_R_SUCCESS   msg was successfully updated to include the
142  *                              query to be sent
143  *\li           other           an error occurred while building the message
144  */
145
146
147 isc_result_t
148 dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
149 /*%<
150  *      Builds a query containing a TKEY record that will delete the
151  *      specified shared secret from the server.
152  *
153  *      Requires:
154  *\li           'msg' is a valid message
155  *\li           'key' is a valid TSIG key
156  *
157  *      Returns:
158  *\li           #ISC_R_SUCCESS  msg was successfully updated to include the
159  *                              query to be sent
160  *\li           other           an error occurred while building the message
161  */
162
163 isc_result_t
164 dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
165                            dst_key_t *key, isc_buffer_t *nonce,
166                            dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
167 /*%<
168  *      Processes a response to a query containing a TKEY that was
169  *      designed to generate a shared secret using a Diffie-Hellman key
170  *      exchange.  If the query was successful, a new shared key
171  *      is created and added to the list of shared keys.
172  *
173  *      Requires:
174  *\li           'qmsg' is a valid message (the query)
175  *\li           'rmsg' is a valid message (the response)
176  *\li           'key' is a valid Diffie Hellman dst key
177  *\li           'outkey' is either NULL or a pointer to NULL
178  *\li           'ring' is a valid keyring or NULL
179  *
180  *      Returns:
181  *\li           #ISC_R_SUCCESS  the shared key was successfully added
182  *\li           #ISC_R_NOTFOUND an error occurred while looking for a
183  *                              component of the query or response
184  */
185
186 isc_result_t
187 dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
188                             dns_name_t *gname, gss_ctx_id_t *context,
189                             isc_buffer_t *outtoken, dns_tsigkey_t **outkey,
190                             dns_tsig_keyring_t *ring);
191 /*%<
192  * XXX
193  */
194
195 isc_result_t
196 dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
197                                dns_tsig_keyring_t *ring);
198 /*%<
199  *      Processes a response to a query containing a TKEY that was
200  *      designed to delete a shared secret.  If the query was successful,
201  *      the shared key is deleted from the list of shared keys.
202  *
203  *      Requires:
204  *\li           'qmsg' is a valid message (the query)
205  *\li           'rmsg' is a valid message (the response)
206  *\li           'ring' is not NULL
207  *
208  *      Returns:
209  *\li           #ISC_R_SUCCESS  the shared key was successfully deleted
210  *\li           #ISC_R_NOTFOUND an error occurred while looking for a
211  *                              component of the query or response
212  */
213
214
215 isc_result_t
216 dns_tkey_gssnegotiate(dns_message_t *qmsg, dns_message_t *rmsg,
217                       dns_name_t *server, gss_ctx_id_t *context,
218                       dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring,
219                       isc_boolean_t win2k);
220
221 /*
222  *      Client side negotiation of GSS-TSIG.  Process the response
223  *      to a TKEY, and establish a TSIG key if negotiation was successful.
224  *      Build a response to the input TKEY message.  Can take multiple
225  *      calls to successfully establish the context.
226  *
227  *      Requires:
228  *              'qmsg'    is a valid message, the original TKEY request;
229  *                           it will be filled with the new message to send
230  *              'rmsg'    is a valid message, the incoming TKEY message
231  *              'server'  is the server name
232  *              'context' is the input context handle
233  *              'outkey'  receives the established key, if non-NULL;
234  *                            if non-NULL must point to NULL
235  *              'ring'    is the keyring in which to establish the key,
236  *                            or NULL
237  *              'win2k'   when true says to turn on some hacks to work
238  *                            with the non-standard GSS-TSIG of Windows 2000
239  *
240  *      Returns:
241  *              ISC_R_SUCCESS   context was successfully established
242  *              ISC_R_NOTFOUND  couldn't find a needed part of the query
243  *                                      or response
244  *              DNS_R_CONTINUE  additional context negotiation is required;
245  *                                      send the new qmsg to the server
246  */
247
248 ISC_LANG_ENDDECLS
249
250 #endif /* DNS_TKEY_H */