1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * Permission to use, copy, modify, and/or distribute this software for any 5 * purpose with or without fee is hereby granted, provided that the above 6 * copyright notice and this permission notice appear in all copies. 7 * 8 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 9 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 10 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 11 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 12 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 13 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 14 * PERFORMANCE OF THIS SOFTWARE. 15 */ 16 17 /* $Id: tsig.h,v 1.6 2020/09/14 08:40:43 florian Exp $ */ 18 19 #ifndef DNS_TSIG_H 20 #define DNS_TSIG_H 1 21 22 /*! \file dns/tsig.h */ 23 24 #include <isc/refcount.h> 25 26 #include <dns/types.h> 27 #include <dns/name.h> 28 29 #include <dst/dst.h> 30 31 /* 32 * Algorithms. 33 */ 34 extern dns_name_t *dns_tsig_hmacsha1_name; 35 #define DNS_TSIG_HMACSHA1_NAME dns_tsig_hmacsha1_name 36 extern dns_name_t *dns_tsig_hmacsha224_name; 37 #define DNS_TSIG_HMACSHA224_NAME dns_tsig_hmacsha224_name 38 extern dns_name_t *dns_tsig_hmacsha256_name; 39 #define DNS_TSIG_HMACSHA256_NAME dns_tsig_hmacsha256_name 40 extern dns_name_t *dns_tsig_hmacsha384_name; 41 #define DNS_TSIG_HMACSHA384_NAME dns_tsig_hmacsha384_name 42 extern dns_name_t *dns_tsig_hmacsha512_name; 43 #define DNS_TSIG_HMACSHA512_NAME dns_tsig_hmacsha512_name 44 45 /*% 46 * Default fudge value. 47 */ 48 #define DNS_TSIG_FUDGE 300 49 50 struct dns_tsigkey { 51 /* Unlocked */ 52 dst_key_t *key; /*%< Key */ 53 dns_name_t name; /*%< Key name */ 54 dns_name_t *algorithm; /*%< Algorithm name */ 55 dns_name_t *creator; /*%< name that created secret */ 56 int generated; /*%< was this generated? */ 57 time_t inception; /*%< start of validity period */ 58 time_t expire; /*%< end of validity period */ 59 isc_refcount_t refs; /*%< reference counter */ 60 ISC_LINK(dns_tsigkey_t) link; 61 }; 62 63 #define dns_tsigkey_identity(tsigkey) \ 64 ((tsigkey) == NULL ? NULL : \ 65 (tsigkey)->generated ? ((tsigkey)->creator) : \ 66 (&((tsigkey)->name))) 67 68 isc_result_t 69 dns_tsigkey_create(dns_name_t *name, dns_name_t *algorithm, 70 unsigned char *secret, int length, int generated, 71 dns_name_t *creator, time_t inception, 72 time_t expire, 73 dns_tsigkey_t **key); 74 75 isc_result_t 76 dns_tsigkey_createfromkey(dns_name_t *name, dns_name_t *algorithm, 77 dst_key_t *dstkey, int generated, 78 dns_name_t *creator, time_t inception, 79 time_t expire, 80 dns_tsigkey_t **key); 81 /*%< 82 * Creates a tsig key structure and saves it in the keyring. If key is 83 * not NULL, *key will contain a copy of the key. The keys validity 84 * period is specified by (inception, expire), and will not expire if 85 * inception == expire. If the key was generated, the creating identity, 86 * if there is one, should be in the creator parameter. Specifying an 87 * unimplemented algorithm will cause failure only if dstkey != NULL; this 88 * allows a transient key with an invalid algorithm to exist long enough 89 * to generate a BADKEY response. 90 * 91 * If dns_tsigkey_createfromkey is successful a new reference to 'dstkey' 92 * will have been made. 93 * 94 * Requires: 95 *\li 'name' is a valid dns_name_t 96 *\li 'algorithm' is a valid dns_name_t 97 *\li 'secret' is a valid pointer 98 *\li 'length' is an integer >= 0 99 *\li 'dstkey' is a valid dst key or NULL 100 *\li 'creator' points to a valid dns_name_t or is NULL 101 *\li 'mctx' is a valid memory context 102 *\li 'key' or '*key' must be NULL 103 * 104 * Returns: 105 *\li #ISC_R_SUCCESS 106 *\li #ISC_R_EXISTS - a key with this name already exists 107 *\li #ISC_R_NOTIMPLEMENTED - algorithm is not implemented 108 *\li #ISC_R_NOMEMORY 109 */ 110 111 void 112 dns_tsigkey_attach(dns_tsigkey_t *source, dns_tsigkey_t **targetp); 113 /*%< 114 * Attach '*targetp' to 'source'. 115 * 116 * Requires: 117 *\li 'key' is a valid TSIG key 118 * 119 * Ensures: 120 *\li *targetp is attached to source. 121 */ 122 123 void 124 dns_tsigkey_detach(dns_tsigkey_t **keyp); 125 /*%< 126 * Detaches from the tsig key structure pointed to by '*key'. 127 * 128 * Requires: 129 *\li 'keyp' is not NULL and '*keyp' is a valid TSIG key 130 * 131 * Ensures: 132 *\li 'keyp' points to NULL 133 */ 134 135 isc_result_t 136 dns_tsig_sign(dns_message_t *msg); 137 /*%< 138 * Generates a TSIG record for this message 139 * 140 * Requires: 141 *\li 'msg' is a valid message 142 *\li 'msg->tsigkey' is a valid TSIG key 143 *\li 'msg->tsig' is NULL 144 * 145 * Returns: 146 *\li #ISC_R_SUCCESS 147 *\li #ISC_R_NOMEMORY 148 *\li #ISC_R_NOSPACE 149 *\li #DNS_R_EXPECTEDTSIG 150 * - this is a response & msg->querytsig is NULL 151 */ 152 153 isc_result_t 154 dns_tsig_verify(isc_buffer_t *source, dns_message_t *msg); 155 /*%< 156 * Verifies the TSIG record in this message 157 * 158 * Requires: 159 *\li 'source' is a valid buffer containing the unparsed message 160 *\li 'msg' is a valid message 161 *\li 'msg->tsigkey' is a valid TSIG key if this is a response 162 *\li 'msg->tsig' is NULL 163 *\li 'msg->querytsig' is not NULL if this is a response 164 * 165 * Returns: 166 *\li #ISC_R_SUCCESS 167 *\li #ISC_R_NOMEMORY 168 *\li #DNS_R_EXPECTEDTSIG - A TSIG was expected but not seen 169 *\li #DNS_R_UNEXPECTEDTSIG - A TSIG was seen but not expected 170 *\li #DNS_R_TSIGERRORSET - the TSIG verified but ->error was set 171 * and this is a query 172 *\li #DNS_R_CLOCKSKEW - the TSIG failed to verify because of 173 * the time was out of the allowed range. 174 *\li #DNS_R_TSIGVERIFYFAILURE - the TSIG failed to verify 175 *\li #DNS_R_EXPECTEDRESPONSE - the message was set over TCP and 176 * should have been a response, 177 * but was not. 178 */ 179 180 #endif /* DNS_TSIG_H */ 181