contrib/bind9/lib/dns/include/dns/tkey.h

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