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 */ 253