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