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 */ 39LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacmd5_name; 40#define DNS_TSIG_HMACMD5_NAME dns_tsig_hmacmd5_name 41LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapi_name; 42#define DNS_TSIG_GSSAPI_NAME dns_tsig_gssapi_name 43LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_gssapims_name; 44#define DNS_TSIG_GSSAPIMS_NAME dns_tsig_gssapims_name 45LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha1_name; 46#define DNS_TSIG_HMACSHA1_NAME dns_tsig_hmacsha1_name 47LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha224_name; 48#define DNS_TSIG_HMACSHA224_NAME dns_tsig_hmacsha224_name 49LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha256_name; 50#define DNS_TSIG_HMACSHA256_NAME dns_tsig_hmacsha256_name 51LIBDNS_EXTERNAL_DATA extern dns_name_t *dns_tsig_hmacsha384_name; 52#define DNS_TSIG_HMACSHA384_NAME dns_tsig_hmacsha384_name 53LIBDNS_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 61struct 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 76struct 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 97ISC_LANG_BEGINDECLS 98 99isc_result_t 100dns_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 106isc_result_t 107dns_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 143void 144dns_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 155void 156dns_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 167void 168dns_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 177isc_result_t 178dns_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 195isc_result_t 196dns_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 224isc_result_t 225dns_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 244isc_result_t 245dns_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 258isc_result_t 259dns_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 273void 274dns_tsigkeyring_attach(dns_tsig_keyring_t *source, dns_tsig_keyring_t **target); 275 276void 277dns_tsigkeyring_detach(dns_tsig_keyring_t **ringp); 278 279isc_result_t 280dns_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 289void 290dns_keyring_restore(dns_tsig_keyring_t *ring, FILE *fp); 291 292ISC_LANG_ENDDECLS 293 294#endif /* DNS_TSIG_H */ 295