contrib/bind-9.5.2/lib/dns/include/dns/tkey.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009  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.26.128.2 2009/01/19 23:47:03 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 };
  48
  49 isc_result_t
  50 dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx,
  51                    dns_tkeyctx_t **tctxp);
  52 /*%<
  53  *      Create an empty TKEY context.
  54  *
  55  *      Requires:
  56  *\li           'mctx' is not NULL
  57  *\li           'tctx' is not NULL
  58  *\li           '*tctx' is NULL
  59  *
  60  *      Returns
  61  *\li           #ISC_R_SUCCESS
  62  *\li           #ISC_R_NOMEMORY
  63  *\li           return codes from dns_name_fromtext()
  64  */
  65
  66 void
  67 dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
  68 /*%<
  69  *      Frees all data associated with the TKEY context
  70  *
  71  *      Requires:
  72  *\li           'tctx' is not NULL
  73  *\li           '*tctx' is not NULL
  74  */
  75
  76 isc_result_t
  77 dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
  78                       dns_tsig_keyring_t *ring);
  79 /*%<
  80  *      Processes a query containing a TKEY record, adding or deleting TSIG
  81  *      keys if necessary, and modifies the message to contain the response.
  82  *
  83  *      Requires:
  84  *\li           'msg' is a valid message
  85  *\li           'tctx' is a valid TKEY context
  86  *\li           'ring' is a valid TSIG keyring
  87  *
  88  *      Returns
  89  *\li           #ISC_R_SUCCESS  msg was updated (the TKEY operation succeeded,
  90  *                              or msg now includes a TKEY with an error set)
  91  *              DNS_R_FORMERR   the packet was malformed (missing a TKEY
  92  *                              or KEY).
  93  *\li           other           An error occurred while processing the message
  94  */
  95
  96 isc_result_t
  97 dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name,
  98                       dns_name_t *algorithm, isc_buffer_t *nonce,
  99                       isc_uint32_t lifetime);
 100 /*%<
 101  *      Builds a query containing a TKEY that will generate a shared
 102  *      secret using a Diffie-Hellman key exchange.  The shared key
 103  *      will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
 104  *      is supported), and will be named either 'name',
 105  *      'name' + server chosen domain, or random data + server chosen domain
 106  *      if 'name' == dns_rootname.  If nonce is not NULL, it supplies
 107  *      random data used in the shared secret computation.  The key is
 108  *      requested to have the specified lifetime (in seconds)
 109  *
 110  *
 111  *      Requires:
 112  *\li           'msg' is a valid message
 113  *\li           'key' is a valid Diffie Hellman dst key
 114  *\li           'name' is a valid name
 115  *\li           'algorithm' is a valid name
 116  *
 117  *      Returns:
 118  *\li           #ISC_R_SUCCESS  msg was successfully updated to include the
 119  *                              query to be sent
 120  *\li           other           an error occurred while building the message
 121  */
 122
 123 isc_result_t
 124 dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name, dns_name_t *gname,
 125                        isc_buffer_t *intoken, isc_uint32_t lifetime,
 126                        gss_ctx_id_t *context, isc_boolean_t win2k);
 127 /*%<
 128  *      Builds a query containing a TKEY that will generate a GSSAPI context.
 129  *      The key is requested to have the specified lifetime (in seconds).
 130  *
 131  *      Requires:
 132  *\li           'msg'     is a valid message
 133  *\li           'name'    is a valid name
 134  *\li           'gname'   is a valid name
 135  *\li           'context' is a pointer to a valid gss_ctx_id_t
 136  *                        (which may have the value GSS_C_NO_CONTEXT)
 137  *\li           'win2k'   when true says to turn on some hacks to work
 138  *                        with the non-standard GSS-TSIG of Windows 2000
 139  *
 140  *      Returns:
 141  *\li           ISC_R_SUCCESS   msg was successfully updated to include the
 142  *                              query to be sent
 143  *\li           other           an error occurred while building the message
 144  */
 145
 146
 147 isc_result_t
 148 dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
 149 /*%<
 150  *      Builds a query containing a TKEY record that will delete the
 151  *      specified shared secret from the server.
 152  *
 153  *      Requires:
 154  *\li           'msg' is a valid message
 155  *\li           'key' is a valid TSIG key
 156  *
 157  *      Returns:
 158  *\li           #ISC_R_SUCCESS  msg was successfully updated to include the
 159  *                              query to be sent
 160  *\li           other           an error occurred while building the message
 161  */
 162
 163 isc_result_t
 164 dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 165                            dst_key_t *key, isc_buffer_t *nonce,
 166                            dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
 167 /*%<
 168  *      Processes a response to a query containing a TKEY that was
 169  *      designed to generate a shared secret using a Diffie-Hellman key
 170  *      exchange.  If the query was successful, a new shared key
 171  *      is created and added to the list of shared keys.
 172  *
 173  *      Requires:
 174  *\li           'qmsg' is a valid message (the query)
 175  *\li           'rmsg' is a valid message (the response)
 176  *\li           'key' is a valid Diffie Hellman dst key
 177  *\li           'outkey' is either NULL or a pointer to NULL
 178  *\li           'ring' is a valid keyring or NULL
 179  *
 180  *      Returns:
 181  *\li           #ISC_R_SUCCESS  the shared key was successfully added
 182  *\li           #ISC_R_NOTFOUND an error occurred while looking for a
 183  *                              component of the query or response
 184  */
 185
 186 isc_result_t
 187 dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 188                             dns_name_t *gname, gss_ctx_id_t *context,
 189                             isc_buffer_t *outtoken, dns_tsigkey_t **outkey,
 190                             dns_tsig_keyring_t *ring);
 191 /*%<
 192  * XXX
 193  */
 194
 195 isc_result_t
 196 dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 197                                dns_tsig_keyring_t *ring);
 198 /*%<
 199  *      Processes a response to a query containing a TKEY that was
 200  *      designed to delete a shared secret.  If the query was successful,
 201  *      the shared key is deleted from the list of shared keys.
 202  *
 203  *      Requires:
 204  *\li           'qmsg' is a valid message (the query)
 205  *\li           'rmsg' is a valid message (the response)
 206  *\li           'ring' is not NULL
 207  *
 208  *      Returns:
 209  *\li           #ISC_R_SUCCESS  the shared key was successfully deleted
 210  *\li           #ISC_R_NOTFOUND an error occurred while looking for a
 211  *                              component of the query or response
 212  */
 213
 214
 215 isc_result_t
 216 dns_tkey_gssnegotiate(dns_message_t *qmsg, dns_message_t *rmsg,
 217                       dns_name_t *server, gss_ctx_id_t *context,
 218                       dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring,
 219                       isc_boolean_t win2k);
 220
 221 /*
 222  *      Client side negotiation of GSS-TSIG.  Process the response
 223  *      to a TKEY, and establish a TSIG key if negotiation was successful.
 224  *      Build a response to the input TKEY message.  Can take multiple
 225  *      calls to successfully establish the context.
 226  *
 227  *      Requires:
 228  *              'qmsg'    is a valid message, the original TKEY request;
 229  *                           it will be filled with the new message to send
 230  *              'rmsg'    is a valid message, the incoming TKEY message
 231  *              'server'  is the server name
 232  *              'context' is the input context handle
 233  *              'outkey'  receives the established key, if non-NULL;
 234  *                            if non-NULL must point to NULL
 235  *              'ring'    is the keyring in which to establish the key,
 236  *                            or NULL
 237  *              'win2k'   when true says to turn on some hacks to work
 238  *                            with the non-standard GSS-TSIG of Windows 2000
 239  *
 240  *      Returns:
 241  *              ISC_R_SUCCESS   context was successfully established
 242  *              ISC_R_NOTFOUND  couldn't find a needed part of the query
 243  *                                      or response
 244  *              DNS_R_CONTINUE  additional context negotiation is required;
 245  *                                      send the new qmsg to the server
 246  */
 247
 248 ISC_LANG_ENDDECLS
 249
 250 #endif /* DNS_TKEY_H */