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
  32 ISC_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
  41 struct 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
  50 isc_result_t
  51 dns_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
  67 void
  68 dns_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
  77 isc_result_t
  78 dns_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
  97 isc_result_t
  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);
 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
 124 isc_result_t
 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);
 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
 150 isc_result_t
 151 dns_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
 166 isc_result_t
 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);
 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
 189 isc_result_t
 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);
 194 /*%<
 195  * XXX
 196  */
 197
 198 isc_result_t
 199 dns_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
 217 isc_result_t
 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);
 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
 250 ISC_LANG_ENDDECLS
 251
 252 #endif /* DNS_TKEY_H */