2 * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC")
3 * Copyright (C) 1999-2001 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: tkey.h,v 1.32 2011/01/08 23:47:01 tbox Exp $ */
23 /*! \file dns/tkey.h */
27 #include <dns/types.h>
30 #include <dst/gssapi.h>
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
44 gss_cred_id_t gsscred;
51 dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx,
52 dns_tkeyctx_t **tctxp);
54 * Create an empty TKEY context.
57 *\li 'mctx' is not NULL
58 *\li 'tctx' is not NULL
64 *\li return codes from dns_name_fromtext()
68 dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
70 * Frees all data associated with the TKEY context
73 *\li 'tctx' is not NULL
74 *\li '*tctx' is not NULL
78 dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
79 dns_tsig_keyring_t *ring);
81 * Processes a query containing a TKEY record, adding or deleting TSIG
82 * keys if necessary, and modifies the message to contain the response.
85 *\li 'msg' is a valid message
86 *\li 'tctx' is a valid TKEY context
87 *\li 'ring' is a valid TSIG keyring
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
94 *\li other An error occurred while processing the message
98 dns_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);
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)
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
119 *\li #ISC_R_SUCCESS msg was successfully updated to include the
121 *\li other an error occurred while building the message
125 dns_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);
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).
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
143 *\li ISC_R_SUCCESS msg was successfully updated to include the
145 *\li other an error occurred while building the message
146 *\li *err_message optional error message
151 dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
153 * Builds a query containing a TKEY record that will delete the
154 * specified shared secret from the server.
157 *\li 'msg' is a valid message
158 *\li 'key' is a valid TSIG key
161 *\li #ISC_R_SUCCESS msg was successfully updated to include the
163 *\li other an error occurred while building the message
167 dns_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);
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.
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
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
190 dns_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);
199 dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
200 dns_tsig_keyring_t *ring);
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.
207 *\li 'qmsg' is a valid message (the query)
208 *\li 'rmsg' is a valid message (the response)
209 *\li 'ring' is not NULL
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
218 dns_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);
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.
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,
239 * 'win2k' when true says to turn on some hacks to work
240 * with the non-standard GSS-TSIG of Windows 2000
243 * ISC_R_SUCCESS context was successfully established
244 * ISC_R_NOTFOUND couldn't find a needed part of the query
246 * DNS_R_CONTINUE additional context negotiation is required;
247 * send the new qmsg to the server
252 #endif /* DNS_TKEY_H */