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

   1 /*
   2  * Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  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: tsig.h,v 1.40.2.2.8.3 2004/03/08 09:04:39 marka Exp $ */
  19
  20 #ifndef DNS_TSIG_H
  21 #define DNS_TSIG_H 1
  22
  23 #include <isc/lang.h>
  24 #include <isc/refcount.h>
  25 #include <isc/rwlock.h>
  26 #include <isc/stdtime.h>
  27
  28 #include <dns/types.h>
  29 #include <dns/name.h>
  30
  31 #include <dst/dst.h>
  32
  33 /*
  34  * Algorithms.
  35  */
  36 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name;
  37 #define DNS_TSIG_HMACMD5_NAME           dns_tsig_hmacmd5_name
  38 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name;
  39 #define DNS_TSIG_GSSAPI_NAME            dns_tsig_gssapi_name
  40 LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name;
  41 #define DNS_TSIG_GSSAPIMS_NAME          dns_tsig_gssapims_name
  42
  43 /*
  44  * Default fudge value.
  45  */
  46 #define DNS_TSIG_FUDGE                  300
  47
  48 struct dns_tsig_keyring {
  49         dns_rbt_t *keys;
  50         isc_rwlock_t lock;
  51         isc_mem_t *mctx;
  52 };
  53
  54 struct dns_tsigkey {
  55         /* Unlocked */
  56         unsigned int            magic;          /* Magic number. */
  57         isc_mem_t               *mctx;
  58         dst_key_t               *key;           /* Key */
  59         dns_name_t              name;           /* Key name */
  60         dns_name_t              *algorithm;     /* Algorithm name */
  61         dns_name_t              *creator;       /* name that created secret */
  62         isc_boolean_t           generated;      /* was this generated? */
  63         isc_stdtime_t           inception;      /* start of validity period */
  64         isc_stdtime_t           expire;         /* end of validity period */
  65         dns_tsig_keyring_t      *ring;          /* the enclosing keyring */
  66         isc_refcount_t          refs;           /* reference counter */
  67 };
  68
  69 #define dns_tsigkey_identity(tsigkey) \
  70         ((tsigkey)->generated ? ((tsigkey)->creator) : (&((tsigkey)->name)))
  71
  72 ISC_LANG_BEGINDECLS
  73
  74 isc_result_t
  75 dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm,
  76                    unsigned char *secret, int length, isc_boolean_t generated,
  77                    dns_name_t *creator, isc_stdtime_t inception,
  78                    isc_stdtime_t expire, isc_mem_t *mctx,
  79                    dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
  80
  81 isc_result_t
  82 dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm,
  83                           dst_key_t *dstkey, isc_boolean_t generated,
  84                           dns_name_t *creator, isc_stdtime_t inception,
  85                           isc_stdtime_t expire, isc_mem_t *mctx,
  86                           dns_tsig_keyring_t *ring, dns_tsigkey_t **key);
  87 /*
  88  *      Creates a tsig key structure and saves it in the keyring.  If key is
  89  *      not NULL, *key will contain a copy of the key.  The keys validity
  90  *      period is specified by (inception, expire), and will not expire if
  91  *      inception == expire.  If the key was generated, the creating identity,
  92  *      if there is one, should be in the creator parameter.  Specifying an
  93  *      unimplemented algorithm will cause failure only if dstkey != NULL; this
  94  *      allows a transient key with an invalid algorithm to exist long enough
  95  *      to generate a BADKEY response.
  96  *
  97  *      Requires:
  98  *              'name' is a valid dns_name_t
  99  *              'algorithm' is a valid dns_name_t
 100  *              'secret' is a valid pointer
 101  *              'length' is an integer >= 0
 102  *              'key' is a valid dst key or NULL
 103  *              'creator' points to a valid dns_name_t or is NULL
 104  *              'mctx' is a valid memory context
 105  *              'ring' is a valid TSIG keyring or NULL
 106  *              'key' or '*key' must be NULL
 107  *
 108  *      Returns:
 109  *              ISC_R_SUCCESS
 110  *              ISC_R_EXISTS - a key with this name already exists
 111  *              ISC_R_NOTIMPLEMENTED - algorithm is not implemented
 112  *              ISC_R_NOMEMORY
 113  */
 114
 115 void
 116 dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp);
 117 /*
 118  *      Attach '*targetp' to 'source'.
 119  *
 120  *      Requires:
 121  *              'key' is a valid TSIG key
 122  *
 123  *      Ensures:
 124  *              *targetp is attached to source.
 125  */
 126
 127 void
 128 dns_tsigkey_detach(dns_tsigkey_t **keyp);
 129 /*
 130  *      Detaches from the tsig key structure pointed to by '*key'.
 131  *
 132  *      Requires:
 133  *              'keyp' is not NULL and '*keyp' is a valid TSIG key
 134  *
 135  *      Ensures:
 136  *              'keyp' points to NULL
 137  */
 138
 139 void
 140 dns_tsigkey_setdeleted(dns_tsigkey_t *key);
 141 /*
 142  *      Prevents this key from being used again.  It will be deleted when
 143  *      no references exist.
 144  *
 145  *      Requires:
 146  *              'key' is a valid TSIG key on a keyring
 147  */
 148
 149 isc_result_t
 150 dns_tsig_sign(dns_message_t *msg);
 151 /*
 152  *      Generates a TSIG record for this message
 153  *
 154  *      Requires:
 155  *              'msg' is a valid message
 156  *              'msg->tsigkey' is a valid TSIG key
 157  *              'msg->tsig' is NULL
 158  *
 159  *      Returns:
 160  *              ISC_R_SUCCESS
 161  *              ISC_R_NOMEMORY
 162  *              ISC_R_NOSPACE
 163  *              DNS_R_EXPECTEDTSIG
 164  *                      - this is a response & msg->querytsig is NULL
 165  */
 166
 167 isc_result_t
 168 dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg,
 169                 dns_tsig_keyring_t *ring1, dns_tsig_keyring_t *ring2);
 170 /*
 171  *      Verifies the TSIG record in this message
 172  *
 173  *      Requires:
 174  *              'source' is a valid buffer containing the unparsed message
 175  *              'msg' is a valid message
 176  *              'msg->tsigkey' is a valid TSIG key if this is a response
 177  *              'msg->tsig' is NULL
 178  *              'msg->querytsig' is not NULL if this is a response
 179  *              'ring1' and 'ring2' are each either a valid keyring or NULL
 180  *
 181  *      Returns:
 182  *              ISC_R_SUCCESS
 183  *              ISC_R_NOMEMORY
 184  *              DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen
 185  *              DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected
 186  *              DNS_R_TSIGERRORSET - the TSIG verified but ->error was set
 187  *                                   and this is a query
 188  *              DNS_R_CLOCKSKEW - the TSIG failed to verify because of
 189  *                                the time was out of the allowed range.
 190  *              DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify
 191  *              DNS_R_EXPECTEDRESPONSE - the message was set over TCP and
 192  *                                       should have been a response,
 193  *                                       but was not.
 194  */
 195
 196 isc_result_t
 197 dns_tsigkey_find(dns_tsigkey_t **tsigkey, dns_name_t *name,
 198                  dns_name_t *algorithm, dns_tsig_keyring_t *ring);
 199 /*
 200  *      Returns the TSIG key corresponding to this name and (possibly)
 201  *      algorithm.  Also increments the key's reference counter.
 202  *
 203  *      Requires:
 204  *              'tsigkey' is not NULL
 205  *              '*tsigkey' is NULL
 206  *              'name' is a valid dns_name_t
 207  *              'algorithm' is a valid dns_name_t or NULL
 208  *              'ring' is a valid keyring
 209  *
 210  *      Returns:
 211  *              ISC_R_SUCCESS
 212  *              ISC_R_NOTFOUND
 213  */
 214
 215
 216 isc_result_t
 217 dns_tsigkeyring_create(isc_mem_t *mctx, dns_tsig_keyring_t **ringp);
 218 /*
 219  *      Create an empty TSIG key ring.
 220  *
 221  *      Requires:
 222  *              'mctx' is not NULL
 223  *              'ringp' is not NULL, and '*ringp' is NULL
 224  *
 225  *      Returns:
 226  *              ISC_R_SUCCESS
 227  *              ISC_R_NOMEMORY
 228  */
 229
 230
 231 void
 232 dns_tsigkeyring_destroy(dns_tsig_keyring_t **ringp);
 233 /*
 234  *      Destroy a TSIG key ring.
 235  *
 236  *      Requires:
 237  *              'ringp' is not NULL
 238  */
 239
 240 ISC_LANG_ENDDECLS
 241
 242 #endif /* DNS_TSIG_H */