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

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