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

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