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

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2001  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and 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.18.206.1 2004/03/06 08:14:00 marka Exp $ */
  19
  20 #ifndef DNS_TKEY_H
  21 #define DNS_TKEY_H 1
  22
  23 #include <isc/lang.h>
  24
  25 #include <dns/types.h>
  26
  27 #include <dst/dst.h>
  28
  29 ISC_LANG_BEGINDECLS
  30
  31 /* Key agreement modes */
  32 #define DNS_TKEYMODE_SERVERASSIGNED             1
  33 #define DNS_TKEYMODE_DIFFIEHELLMAN              2
  34 #define DNS_TKEYMODE_GSSAPI                     3
  35 #define DNS_TKEYMODE_RESOLVERASSIGNED           4
  36 #define DNS_TKEYMODE_DELETE                     5
  37
  38 struct dns_tkeyctx {
  39         dst_key_t *dhkey;
  40         dns_name_t *domain;
  41         void *gsscred;
  42         isc_mem_t *mctx;
  43         isc_entropy_t *ectx;
  44 };
  45
  46 isc_result_t
  47 dns_tkeyctx_create(isc_mem_t *mctx, isc_entropy_t *ectx, dns_tkeyctx_t **tctxp);
  48 /*
  49  *      Create an empty TKEY context.
  50  *
  51  *      Requires:
  52  *              'mctx' is not NULL
  53  *              'tctx' is not NULL
  54  *              '*tctx' is NULL
  55  *
  56  *      Returns
  57  *              ISC_R_SUCCESS
  58  *              ISC_R_NOMEMORY
  59  *              return codes from dns_name_fromtext()
  60  */
  61
  62 void
  63 dns_tkeyctx_destroy(dns_tkeyctx_t **tctxp);
  64 /*
  65  *      Frees all data associated with the TKEY context
  66  *
  67  *      Requires:
  68  *              'tctx' is not NULL
  69  *              '*tctx' is not NULL
  70  */
  71
  72 isc_result_t
  73 dns_tkey_processquery(dns_message_t *msg, dns_tkeyctx_t *tctx,
  74                       dns_tsig_keyring_t *ring);
  75 /*
  76  *      Processes a query containing a TKEY record, adding or deleting TSIG
  77  *      keys if necessary, and modifies the message to contain the response.
  78  *
  79  *      Requires:
  80  *              'msg' is a valid message
  81  *              'tctx' is a valid TKEY context
  82  *              'ring' is a valid TSIG keyring
  83  *
  84  *      Returns
  85  *              ISC_R_SUCCESS   msg was updated (the TKEY operation succeeded,
  86  *                              or msg now includes a TKEY with an error set)
  87  *              DNS_R_FORMERR   the packet was malformed (missing a TKEY
  88  *                              or KEY).
  89  *              other           An error occurred while processing the message
  90  */
  91
  92 isc_result_t
  93 dns_tkey_builddhquery(dns_message_t *msg, dst_key_t *key, dns_name_t *name,
  94                       dns_name_t *algorithm, isc_buffer_t *nonce,
  95                       isc_uint32_t lifetime);
  96 /*
  97  *      Builds a query containing a TKEY that will generate a shared
  98  *      secret using a Diffie-Hellman key exchange.  The shared key
  99  *      will be of the specified algorithm (only DNS_TSIG_HMACMD5_NAME
 100  *      is supported), and will be named either 'name',
 101  *      'name' + server chosen domain, or random data + server chosen domain
 102  *      if 'name' == dns_rootname.  If nonce is not NULL, it supplies
 103  *      random data used in the shared secret computation.  The key is
 104  *      requested to have the specified lifetime (in seconds)
 105  *
 106  *
 107  *      Requires:
 108  *              'msg' is a valid message
 109  *              'key' is a valid Diffie Hellman dst key
 110  *              'name' is a valid name
 111  *              'algorithm' is a valid name
 112  *
 113  *      Returns:
 114  *              ISC_R_SUCCESS   msg was successfully updated to include the
 115  *                              query to be sent
 116  *              other           an error occurred while building the message
 117  */
 118
 119 isc_result_t
 120 dns_tkey_buildgssquery(dns_message_t *msg, dns_name_t *name,
 121                        dns_name_t *gname, void *cred,
 122                        isc_uint32_t lifetime, void **context);
 123 /*
 124  * XXX
 125  */
 126
 127 isc_result_t
 128 dns_tkey_builddeletequery(dns_message_t *msg, dns_tsigkey_t *key);
 129 /*
 130  *      Builds a query containing a TKEY record that will delete the
 131  *      specified shared secret from the server.
 132  *
 133  *      Requires:
 134  *              'msg' is a valid message
 135  *              'key' is a valid TSIG key
 136  *
 137  *      Returns:
 138  *              ISC_R_SUCCESS   msg was successfully updated to include the
 139  *                              query to be sent
 140  *              other           an error occurred while building the message
 141  */
 142
 143 isc_result_t
 144 dns_tkey_processdhresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 145                            dst_key_t *key, isc_buffer_t *nonce,
 146                            dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
 147 /*
 148  *      Processes a response to a query containing a TKEY that was
 149  *      designed to generate a shared secret using a Diffie-Hellman key
 150  *      exchange.  If the query was successful, a new shared key
 151  *      is created and added to the list of shared keys.
 152  *
 153  *      Requires:
 154  *              'qmsg' is a valid message (the query)
 155  *              'rmsg' is a valid message (the response)
 156  *              'key' is a valid Diffie Hellman dst key
 157  *              'outkey' is either NULL or a pointer to NULL
 158  *              'ring' is a valid keyring or NULL
 159  *
 160  *      Returns:
 161  *              ISC_R_SUCCESS   the shared key was successfully added
 162  *              ISC_R_NOTFOUND  an error occurred while looking for a
 163  *                              component of the query or response
 164  */
 165
 166 isc_result_t
 167 dns_tkey_processgssresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 168                             dns_name_t *gname, void *cred, void **context,
 169                             dns_tsigkey_t **outkey, dns_tsig_keyring_t *ring);
 170 /*
 171  * XXX
 172  */
 173
 174 isc_result_t
 175 dns_tkey_processdeleteresponse(dns_message_t *qmsg, dns_message_t *rmsg,
 176                                dns_tsig_keyring_t *ring);
 177 /*
 178  *      Processes a response to a query containing a TKEY that was
 179  *      designed to delete a shared secret.  If the query was successful,
 180  *      the shared key is deleted from the list of shared keys.
 181  *
 182  *      Requires:
 183  *              'qmsg' is a valid message (the query)
 184  *              'rmsg' is a valid message (the response)
 185  *              'ring' is not NULL
 186  *
 187  *      Returns:
 188  *              ISC_R_SUCCESS   the shared key was successfully deleted
 189  *              ISC_R_NOTFOUND  an error occurred while looking for a
 190  *                              component of the query or response
 191  */
 192
 193
 194 ISC_LANG_ENDDECLS
 195
 196 #endif /* DNS_TKEY_H */