1 /* $NetBSD: master.h,v 1.8 2025/01/26 16:25:27 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 /*! \file dns/master.h */ 19 20 /*** 21 *** Imports 22 ***/ 23 24 #include <inttypes.h> 25 #include <stdio.h> 26 27 #include <isc/lang.h> 28 29 #include <dns/types.h> 30 31 /* 32 * Flags to be passed in the 'options' argument in the functions below. 33 */ 34 #define DNS_MASTER_AGETTL 0x00000001 /*%< Age the ttl based on $DATE. */ 35 #define DNS_MASTER_MANYERRORS \ 36 0x00000002 /*%< Continue processing on errors. \ 37 */ 38 #define DNS_MASTER_NOINCLUDE 0x00000004 /*%< Disallow $INCLUDE directives. */ 39 #define DNS_MASTER_ZONE 0x00000008 /*%< Loading a zone master file. */ 40 #define DNS_MASTER_HINT 0x00000010 /*%< Loading a hint master file. */ 41 #define DNS_MASTER_SECONDARY 0x00000020 /*%< Secondary master file. */ 42 #define DNS_MASTER_CHECKNS \ 43 0x00000040 /*%< \ 44 * Check NS records to see \ 45 * if they are an address \ 46 */ 47 #define DNS_MASTER_FATALNS \ 48 0x00000080 /*%< \ 49 * Treat DNS_MASTER_CHECKNS \ 50 * matches as fatal \ 51 */ 52 #define DNS_MASTER_CHECKNAMES 0x00000100 53 #define DNS_MASTER_CHECKNAMESFAIL 0x00000200 54 #define DNS_MASTER_CHECKWILDCARD \ 55 0x00000400 /* Check for internal wildcards. \ 56 */ 57 #define DNS_MASTER_CHECKMX 0x00000800 58 #define DNS_MASTER_CHECKMXFAIL 0x00001000 59 60 #define DNS_MASTER_RESIGN 0x00002000 61 #define DNS_MASTER_KEY 0x00004000 /*%< Loading a key zone master file. */ 62 #define DNS_MASTER_NOTTL 0x00008000 /*%< Don't require ttl. */ 63 #define DNS_MASTER_CHECKTTL 0x00010000 /*%< Check max-zone-ttl */ 64 #define DNS_MASTER_CHECKSVCB 0x00020000 /*%< Check SVBC records */ 65 66 ISC_LANG_BEGINDECLS 67 68 /* 69 * Structures that implement the "raw" format for master dump. 70 * These are provided for a reference purpose only; in the actual 71 * encoding, we directly read/write each field so that the encoded data 72 * is always "packed", regardless of the hardware architecture. 73 */ 74 #define DNS_RAWFORMAT_VERSION 1 75 76 /* 77 * Flags to indicate the status of the data in the raw file header 78 */ 79 #define DNS_MASTERRAW_COMPAT 0x01 80 #define DNS_MASTERRAW_SOURCESERIALSET 0x02 81 #define DNS_MASTERRAW_LASTXFRINSET 0x04 82 83 /* Common header */ 84 struct dns_masterrawheader { 85 uint32_t format; /* must be 86 * dns_masterformat_raw */ 87 uint32_t version; /* compatibility for future 88 * extensions */ 89 uint32_t dumptime; /* timestamp on creation 90 * (currently unused) */ 91 uint32_t flags; /* Flags */ 92 uint32_t sourceserial; /* Source serial number (used 93 * by inline-signing zones) */ 94 uint32_t lastxfrin; /* timestamp of last transfer 95 * (used by secondary zones) */ 96 }; 97 98 /* The structure for each RRset */ 99 typedef struct { 100 uint32_t totallen; /* length of the data for this 101 * RRset, including the 102 * "header" part */ 103 dns_rdataclass_t rdclass; /* 16-bit class */ 104 dns_rdatatype_t type; /* 16-bit type */ 105 dns_rdatatype_t covers; /* same as type */ 106 dns_ttl_t ttl; /* 32-bit TTL */ 107 uint32_t nrdata; /* number of RRs in this set */ 108 /* followed by encoded owner name, and then rdata */ 109 } dns_masterrawrdataset_t; 110 111 /* 112 * Method prototype: a callback to register each include file as 113 * it is encountered. 114 */ 115 typedef void (*dns_masterincludecb_t)(const char *file, void *arg); 116 117 /*** 118 *** Function 119 ***/ 120 121 isc_result_t 122 dns_master_loadfile(const char *master_file, dns_name_t *top, 123 dns_name_t *origin, dns_rdataclass_t zclass, 124 unsigned int options, uint32_t resign, 125 dns_rdatacallbacks_t *callbacks, 126 dns_masterincludecb_t include_cb, void *include_arg, 127 isc_mem_t *mctx, dns_masterformat_t format, 128 dns_ttl_t maxttl); 129 130 isc_result_t 131 dns_master_loadstream(FILE *stream, dns_name_t *top, dns_name_t *origin, 132 dns_rdataclass_t zclass, unsigned int options, 133 dns_rdatacallbacks_t *callbacks, isc_mem_t *mctx); 134 135 isc_result_t 136 dns_master_loadbuffer(isc_buffer_t *buffer, dns_name_t *top, dns_name_t *origin, 137 dns_rdataclass_t zclass, unsigned int options, 138 dns_rdatacallbacks_t *callbacks, isc_mem_t *mctx); 139 140 isc_result_t 141 dns_master_loadfileasync(const char *master_file, dns_name_t *top, 142 dns_name_t *origin, dns_rdataclass_t zclass, 143 unsigned int options, uint32_t resign, 144 dns_rdatacallbacks_t *callbacks, isc_loop_t *loop, 145 dns_loaddonefunc_t done, void *done_arg, 146 dns_loadctx_t **ctxp, dns_masterincludecb_t include_cb, 147 void *include_arg, isc_mem_t *mctx, 148 dns_masterformat_t format, uint32_t maxttl); 149 150 /*%< 151 * Loads a RFC1035 master file from a file, stream, or buffer 152 * into rdatasets and then calls 'callbacks->commit' to commit the 153 * rdatasets. Rdata memory belongs to dns_master_load and will be 154 * reused / released when the callback completes. dns_load_master will 155 * abort if callbacks->commit returns any value other than ISC_R_SUCCESS. 156 * 157 * If 'DNS_MASTER_AGETTL' is set and the master file contains one or more 158 * $DATE directives, the TTLs of the data will be aged accordingly. 159 * 160 * 'callbacks->commit' is assumed to call 'callbacks->error' or 161 * 'callbacks->warn' to generate any error messages required. 162 * 163 * 'done' is called with 'done_arg' and a result code when the loading 164 * is completed or has failed. If the initial setup fails 'done' is 165 * not called. 166 * 167 * 'resign' the number of seconds before a RRSIG expires that it should 168 * be re-signed. 0 is used if not provided. 169 * 170 * Requires: 171 *\li 'master_file' points to a valid string. 172 *\li 'top' points to a valid name. 173 *\li 'origin' points to a valid name. 174 *\li 'callbacks->commit' points to a valid function. 175 *\li 'callbacks->error' points to a valid function. 176 *\li 'callbacks->warn' points to a valid function. 177 *\li 'mctx' points to a valid memory context. 178 *\li 'loop' and 'done' to be valid. 179 *\li 'lmgr' to be valid. 180 *\li 'ctxp != NULL && ctxp == NULL'. 181 * 182 * Returns: 183 *\li ISC_R_SUCCESS upon successfully loading the master file. 184 *\li ISC_R_SEENINCLUDE upon successfully loading the master file with 185 * a $INCLUDE statement. 186 *\li ISC_R_NOMEMORY out of memory. 187 *\li ISC_R_UNEXPECTEDEND expected to be able to read a input token and 188 * there was not one. 189 *\li ISC_R_UNEXPECTED 190 *\li DNS_R_NOOWNER failed to specify a ownername. 191 *\li DNS_R_NOTTL failed to specify a ttl. 192 *\li DNS_R_BADCLASS record class did not match zone class. 193 *\li Any dns_rdata_fromtext() error code. 194 *\li Any error code from callbacks->commit(). 195 */ 196 197 void 198 dns_loadctx_detach(dns_loadctx_t **ctxp); 199 /*%< 200 * Detach from the load context. 201 * 202 * Requires: 203 *\li '*ctxp' to be valid. 204 * 205 * Ensures: 206 *\li '*ctxp == NULL' 207 */ 208 209 void 210 dns_loadctx_attach(dns_loadctx_t *source, dns_loadctx_t **target); 211 /*%< 212 * Attach to the load context. 213 * 214 * Requires: 215 *\li 'source' to be valid. 216 *\li 'target != NULL && *target == NULL'. 217 */ 218 219 void 220 dns_loadctx_cancel(dns_loadctx_t *ctx); 221 /*%< 222 * Cancel loading the zone file associated with this load context. 223 * 224 * Requires: 225 *\li 'ctx' to be valid 226 */ 227 228 void 229 dns_master_initrawheader(dns_masterrawheader_t *header); 230 /*%< 231 * Initializes the header for a raw master file, setting all 232 * values to zero. 233 */ 234 ISC_LANG_ENDDECLS 235