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

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