1 /* $NetBSD: xfrin.h,v 1.9 2025/05/21 14:48:04 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #pragma once 17 18 /***** 19 ***** Module Info 20 *****/ 21 22 /*! \file dns/xfrin.h 23 * \brief 24 * Incoming zone transfers (AXFR + IXFR). 25 */ 26 27 /*** 28 *** Imports 29 ***/ 30 31 #include <isc/lang.h> 32 #include <isc/refcount.h> 33 #include <isc/sockaddr.h> 34 #include <isc/tls.h> 35 36 #include <dns/transport.h> 37 #include <dns/types.h> 38 39 /* Add -DDNS_XFRIN_TRACE=1 to CFLAGS for detailed reference tracing */ 40 41 /*** 42 *** Types 43 ***/ 44 45 /*% 46 * A transfer in progress. This is an opaque type. 47 */ 48 typedef struct dns_xfrin dns_xfrin_t; 49 50 /*** 51 *** Functions 52 ***/ 53 54 ISC_LANG_BEGINDECLS 55 56 void 57 dns_xfrin_create(dns_zone_t *zone, dns_rdatatype_t xfrtype, 58 const isc_sockaddr_t *primaryaddr, 59 const isc_sockaddr_t *sourceaddr, dns_tsigkey_t *tsigkey, 60 dns_transport_type_t soa_transport_type, 61 dns_transport_t *transport, isc_tlsctx_cache_t *tlsctx_cache, 62 isc_mem_t *mctx, dns_xfrin_t **xfrp); 63 /*%< 64 * Create an incoming zone transfer object of 'zone' from 65 * 'primaryaddr'. Attach '*xfrp' to the newly created object. 66 * 67 * Requires: 68 *\li 'xfrp' != NULL and '*xfrp' == NULL. 69 * 70 *\li 'primaryaddr' has a non-zero port number. 71 * 72 *\li 'zone' is a valid zone and is associated with a view. 73 * 74 *\li 'xfrtype' is dns_rdatatype_axfr, dns_rdatatype_ixfr 75 * or dns_rdatatype_soa (soa query followed by axfr if 76 * serial is greater than current serial). 77 * 78 *\li If 'xfrtype' is dns_rdatatype_ixfr or dns_rdatatype_soa, 79 * the zone has a database. 80 * 81 *\li 'soa_transport_type' is DNS_TRANSPORT_NONE if 'xfrtype' 82 * is dns_rdatatype_soa (because in that case the SOA request 83 * will use the same transport as the XFR), or when there is no 84 * preceding SOA request. Otherwise, it should indicate the 85 * transport type used for the SOA request performed by the 86 * caller itself. 87 */ 88 89 isc_result_t 90 dns_xfrin_start(dns_xfrin_t *xfr, dns_xfrindone_t done); 91 /*%< 92 * Attempt to start an incoming zone transfer of 'xfr->zone' 93 * using the previously created '*xfr' object. 94 * 95 * Iff ISC_R_SUCCESS is returned, '*done' is called with 96 * 'zone' and a result code as arguments when the transfer finishes. 97 * 98 * Requires: 99 *\li 'xfr' is a valid dns_xfrin_t object and is associated with a zone. 100 * 101 *\li 'done' != NULL. 102 * 103 */ 104 105 isc_time_t 106 dns_xfrin_getstarttime(dns_xfrin_t *xfr); 107 /*%< 108 * Get the start time of the xfrin object. 109 * 110 * Requires: 111 *\li 'xfr' is a valid dns_xfrin_t. 112 * 113 * Returns: 114 *\li Transfer start time 115 * 116 */ 117 118 void 119 dns_xfrin_getstate(const dns_xfrin_t *xfr, const char **statestr, 120 bool *is_first_data_received, bool *is_ixfr); 121 /*%< 122 * Get the current state of the xfrin object as a character string, and whether 123 * it's currently known to be an IXFR transfer as a boolean value. 124 * 125 * Notes: 126 *\li The 'is_ixfr' value is valid only if 'is_first_data_received' is true. 127 * 128 * Requires: 129 *\li 'xfr' is a valid dns_xfrin_t. 130 * 131 */ 132 133 uint32_t 134 dns_xfrin_getendserial(dns_xfrin_t *xfr); 135 /*%< 136 * Get the 'end_serial' of the xfrin object. 137 * 138 * Requires: 139 *\li 'xfr' is a valid dns_xfrin_t. 140 * 141 * Returns: 142 *\li Serial number of the new version zone (if it's already known), or 0. 143 * 144 */ 145 146 void 147 dns_xfrin_getstats(dns_xfrin_t *xfr, unsigned int *nmsgp, unsigned int *nrecsp, 148 uint64_t *nbytesp, uint64_t *ratep); 149 /*%< 150 * Get various statistics values of the xfrin object: number of the received 151 * messages, number of the received records, number of the received bytes, 152 * and the average transfer rate (in bytes-per-second) during the last full 153 * 'min-transfer-rate-in <bytes> <minutes>' minutes interval. If no such 154 * interval has passed yet, then the overall average rate is reported instead. 155 * 156 * Requires: 157 *\li 'xfr' is a valid dns_xfrin_t. 158 * 159 */ 160 161 const isc_sockaddr_t * 162 dns_xfrin_getsourceaddr(const dns_xfrin_t *xfr); 163 /*%< 164 * Get the source socket address of the xfrin object. 165 * 166 * Requires: 167 *\li 'xfr' is a valid dns_xfrin_t. 168 * 169 * Returns: 170 *\li const pointer to the zone transfer's source socket address 171 */ 172 173 const isc_sockaddr_t * 174 dns_xfrin_getprimaryaddr(const dns_xfrin_t *xfr); 175 /*%< 176 * Get the socket address of the primary server of the xfrin object. 177 * 178 * Requires: 179 *\li 'xfr' is a valid dns_xfrin_t. 180 * 181 * Returns: 182 *\li const pointer to the zone transfer's primary server's socket address 183 */ 184 185 dns_transport_type_t 186 dns_xfrin_gettransporttype(const dns_xfrin_t *xfr); 187 /*%< 188 * Get the zone transfer's trnasport type of the xfrin object. 189 * 190 * Requires: 191 *\li 'xfr' is a valid dns_xfrin_t. 192 * 193 * Returns: 194 *\li const pointer to the zone transfer's transport 195 * 196 */ 197 198 dns_transport_type_t 199 dns_xfrin_getsoatransporttype(dns_xfrin_t *xfr); 200 /*%< 201 * Get the SOA request's trnasport type of the xfrin object. 202 * 203 * Requires: 204 *\li 'xfr' is a valid dns_xfrin_t. 205 * 206 * Returns: 207 *\li const pointer to the zone transfer's transport 208 * 209 */ 210 211 const dns_name_t * 212 dns_xfrin_gettsigkeyname(const dns_xfrin_t *xfr); 213 /*%< 214 * Get the name of the xfrin object's TSIG key. 215 * 216 * Requires: 217 *\li 'xfr' is a valid dns_xfrin_t. 218 * 219 * Returns: 220 *\li const pointer to the zone transfer's TSIG key's name or NULL 221 * 222 */ 223 224 void 225 dns_xfrin_shutdown(dns_xfrin_t *xfr); 226 /*%< 227 * If the zone transfer 'xfr' has already finished, 228 * do nothing. Otherwise, abort it and cause it to call 229 * its done callback with a status of ISC_R_CANCELED. 230 */ 231 232 #if DNS_XFRIN_TRACE 233 #define dns_xfrin_ref(ptr) dns_xfrin__ref(ptr, __func__, __FILE__, __LINE__) 234 #define dns_xfrin_unref(ptr) dns_xfrin__unref(ptr, __func__, __FILE__, __LINE__) 235 #define dns_xfrin_attach(ptr, ptrp) \ 236 dns_xfrin__attach(ptr, ptrp, __func__, __FILE__, __LINE__) 237 #define dns_xfrin_detach(ptrp) \ 238 dns_xfrin__detach(ptrp, __func__, __FILE__, __LINE__) 239 ISC_REFCOUNT_TRACE_DECL(dns_xfrin); 240 #else 241 ISC_REFCOUNT_DECL(dns_xfrin); 242 #endif 243 ISC_LANG_ENDDECLS 244
Indexes created Mon Mar 02 05:31:46 UTC 2026