00001 /* 00002 * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC") 00003 * Copyright (C) 1999-2001 Internet Software Consortium. 00004 * 00005 * Permission to use, copy, modify, and/or distribute this software for any 00006 * purpose with or without fee is hereby granted, provided that the above 00007 * copyright notice and this permission notice appear in all copies. 00008 * 00009 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 00010 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 00011 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 00012 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 00013 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 00014 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 00015 * PERFORMANCE OF THIS SOFTWARE. 00016 */ 00017 00018 /* $Id: tkey.h,v 1.32 2011/01/08 23:47:01 tbox Exp $ */ 00019 00020 #ifndef DNS_TKEY_H 00021 #define DNS_TKEY_H 1 00022 00023 /*! \file dns/tkey.h */ 00024 00025 #include <isc/lang.h> 00026 00027 #include <dns/types.h> 00028 00029 #include <dst/dst.h> 00030 #include <dst/gssapi.h> 00031 00032 ISC_LANG_BEGINDECLS 00033 00034 /* Key agreement modes */ 00035 #define DNS_TKEYMODE_SERVERASSIGNED 1 00036 #define DNS_TKEYMODE_DIFFIEHELLMAN 2 00037 #define DNS_TKEYMODE_GSSAPI 3 00038 #define DNS_TKEYMODE_RESOLVERASSIGNED 4 00039 #define DNS_TKEYMODE_DELETE 5 00040 00041 struct dns_tkeyctx { 00042 dst_key_t *dhkey; 00043 dns_name_t *domain; 00044 gss_cred_id_t gsscred; 00045 isc_mem_t *mctx; 00046 isc_entropy_t *ectx; 00047 char *gssapi_keytab; 00048 }; 00049 00050 isc_result_t 00051 dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx, 00052 dns_tkeyctx_t **tctxp); 00053 /*%< 00054 * Create an empty TKEY context. 00055 * 00056 * Requires: 00057 *\li 'mctx' is not NULL 00058 *\li 'tctx' is not NULL 00059 *\li '*tctx' is NULL 00060 * 00061 * Returns 00062 *\li #ISC_R_SUCCESS 00063 *\li #ISC_R_NOMEMORY 00064 *\li return codes from dns_name_fromtext() 00065 */ 00066 00067 void 00068 dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp); 00069 /*%< 00070 * Frees all data associated with the TKEY context 00071 * 00072 * Requires: 00073 *\li 'tctx' is not NULL 00074 *\li '*tctx' is not NULL 00075 */ 00076 00077 isc_result_t 00078 dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx, 00079 dns_tsig_keyring_t *ring); 00080 /*%< 00081 * Processes a query containing a TKEY record, adding or deleting TSIG 00082 * keys if necessary, and modifies the message to contain the response. 00083 * 00084 * Requires: 00085 *\li 'msg' is a valid message 00086 *\li 'tctx' is a valid TKEY context 00087 *\li 'ring' is a valid TSIG keyring 00088 * 00089 * Returns 00090 *\li #ISC_R_SUCCESS msg was updated (the TKEY operation succeeded, 00091 * or msg now includes a TKEY with an error set) 00092 * DNS_R_FORMERR the packet was malformed (missing a TKEY 00093 * or KEY). 00094 *\li other An error occurred while processing the message 00095 */ 00096 00097 isc_result_t 00098 dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name, 00099 dns_name_t *algorithm, isc_buffer_t *nonce, 00100 isc_uint32_t lifetime); 00101 /*%< 00102 * Builds a query containing a TKEY that will generate a shared 00103 * secret using a Diffie-Hellman key exchange. The shared key 00104 * will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME 00105 * is supported), and will be named either 'name', 00106 * 'name' + server chosen domain, or random data + server chosen domain 00107 * if 'name' == dns_rootname. If nonce is not NULL, it supplies 00108 * random data used in the shared secret computation. The key is 00109 * requested to have the specified lifetime (in seconds) 00110 * 00111 * 00112 * Requires: 00113 *\li 'msg' is a valid message 00114 *\li 'key' is a valid Diffie Hellman dst key 00115 *\li 'name' is a valid name 00116 *\li 'algorithm' is a valid name 00117 * 00118 * Returns: 00119 *\li #ISC_R_SUCCESS msg was successfully updated to include the 00120 * query to be sent 00121 *\li other an error occurred while building the message 00122 */ 00123 00124 isc_result_t 00125 dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name, dns_name_t *gname, 00126 isc_buffer_t *intoken, isc_uint32_t lifetime, 00127 gss_ctx_id_t *context, isc_boolean_t win2k, 00128 isc_mem_t *mctx, char **err_message); 00129 /*%< 00130 * Builds a query containing a TKEY that will generate a GSSAPI context. 00131 * The key is requested to have the specified lifetime (in seconds). 00132 * 00133 * Requires: 00134 *\li 'msg' is a valid message 00135 *\li 'name' is a valid name 00136 *\li 'gname' is a valid name 00137 *\li 'context' is a pointer to a valid gss_ctx_id_t 00138 * (which may have the value GSS_C_NO_CONTEXT) 00139 *\li 'win2k' when true says to turn on some hacks to work 00140 * with the non-standard GSS-TSIG of Windows 2000 00141 * 00142 * Returns: 00143 *\li ISC_R_SUCCESS msg was successfully updated to include the 00144 * query to be sent 00145 *\li other an error occurred while building the message 00146 *\li *err_message optional error message 00147 */ 00148 00149 00150 isc_result_t 00151 dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key); 00152 /*%< 00153 * Builds a query containing a TKEY record that will delete the 00154 * specified shared secret from the server. 00155 * 00156 * Requires: 00157 *\li 'msg' is a valid message 00158 *\li 'key' is a valid TSIG key 00159 * 00160 * Returns: 00161 *\li #ISC_R_SUCCESS msg was successfully updated to include the 00162 * query to be sent 00163 *\li other an error occurred while building the message 00164 */ 00165 00166 isc_result_t 00167 dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg, 00168 dst_key_t *key, isc_buffer_t *nonce, 00169 dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring); 00170 /*%< 00171 * Processes a response to a query containing a TKEY that was 00172 * designed to generate a shared secret using a Diffie-Hellman key 00173 * exchange. If the query was successful, a new shared key 00174 * is created and added to the list of shared keys. 00175 * 00176 * Requires: 00177 *\li 'qmsg' is a valid message (the query) 00178 *\li 'rmsg' is a valid message (the response) 00179 *\li 'key' is a valid Diffie Hellman dst key 00180 *\li 'outkey' is either NULL or a pointer to NULL 00181 *\li 'ring' is a valid keyring or NULL 00182 * 00183 * Returns: 00184 *\li #ISC_R_SUCCESS the shared key was successfully added 00185 *\li #ISC_R_NOTFOUND an error occurred while looking for a 00186 * component of the query or response 00187 */ 00188 00189 isc_result_t 00190 dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg, 00191 dns_name_t *gname, gss_ctx_id_t *context, 00192 isc_buffer_t *outtoken, dns_tsigkey_t **outkey, 00193 dns_tsig_keyring_t *ring, char **err_message); 00194 /*%< 00195 * XXX 00196 */ 00197 00198 isc_result_t 00199 dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg, 00200 dns_tsig_keyring_t *ring); 00201 /*%< 00202 * Processes a response to a query containing a TKEY that was 00203 * designed to delete a shared secret. If the query was successful, 00204 * the shared key is deleted from the list of shared keys. 00205 * 00206 * Requires: 00207 *\li 'qmsg' is a valid message (the query) 00208 *\li 'rmsg' is a valid message (the response) 00209 *\li 'ring' is not NULL 00210 * 00211 * Returns: 00212 *\li #ISC_R_SUCCESS the shared key was successfully deleted 00213 *\li #ISC_R_NOTFOUND an error occurred while looking for a 00214 * component of the query or response 00215 */ 00216 00217 isc_result_t 00218 dns_tkey_gssnegotiate(dns_message_t *qmsg, dns_message_t *rmsg, 00219 dns_name_t *server, gss_ctx_id_t *context, 00220 dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring, 00221 isc_boolean_t win2k, char **err_message); 00222 00223 /* 00224 * Client side negotiation of GSS-TSIG. Process the response 00225 * to a TKEY, and establish a TSIG key if negotiation was successful. 00226 * Build a response to the input TKEY message. Can take multiple 00227 * calls to successfully establish the context. 00228 * 00229 * Requires: 00230 * 'qmsg' is a valid message, the original TKEY request; 00231 * it will be filled with the new message to send 00232 * 'rmsg' is a valid message, the incoming TKEY message 00233 * 'server' is the server name 00234 * 'context' is the input context handle 00235 * 'outkey' receives the established key, if non-NULL; 00236 * if non-NULL must point to NULL 00237 * 'ring' is the keyring in which to establish the key, 00238 * or NULL 00239 * 'win2k' when true says to turn on some hacks to work 00240 * with the non-standard GSS-TSIG of Windows 2000 00241 * 00242 * Returns: 00243 * ISC_R_SUCCESS context was successfully established 00244 * ISC_R_NOTFOUND couldn't find a needed part of the query 00245 * or response 00246 * DNS_R_CONTINUE additional context negotiation is required; 00247 * send the new qmsg to the server 00248 */ 00249 00250 ISC_LANG_ENDDECLS 00251 00252 #endif /* DNS_TKEY_H */