1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * SPDX-License-Identifier: MPL-2.0 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 #ifndef DNS_SDB_H 15 #define DNS_SDB_H 1 16 17 /***** 18 ***** Module Info 19 *****/ 20 21 /*! \file dns/sdb.h 22 * \brief 23 * Simple database API. 24 */ 25 26 /*** 27 *** Imports 28 ***/ 29 30 #include <inttypes.h> 31 32 #include <isc/lang.h> 33 34 #include <dns/clientinfo.h> 35 #include <dns/types.h> 36 37 /*** 38 *** Types 39 ***/ 40 41 /*% 42 * A simple database. This is an opaque type. 43 */ 44 typedef struct dns_sdb dns_sdb_t; 45 46 /*% 47 * A simple database lookup in progress. This is an opaque type. 48 */ 49 typedef struct dns_sdblookup dns_sdblookup_t; 50 51 /*% 52 * A simple database traversal in progress. This is an opaque type. 53 */ 54 typedef struct dns_sdballnodes dns_sdballnodes_t; 55 56 typedef isc_result_t (*dns_sdblookupfunc_t)(const char *zone, const char *name, 57 void *dbdata, 58 dns_sdblookup_t *lookup, 59 dns_clientinfomethods_t *methods, 60 dns_clientinfo_t *clientinfo); 61 typedef isc_result_t (*dns_sdblookup2func_t)(const dns_name_t *zone, 62 const dns_name_t *name, 63 void *dbdata, 64 dns_sdblookup_t *lookup, 65 dns_clientinfomethods_t *methods, 66 dns_clientinfo_t *clientinfo); 67 68 typedef isc_result_t (*dns_sdbauthorityfunc_t)(const char *zone, void *dbdata, 69 dns_sdblookup_t *); 70 71 typedef isc_result_t (*dns_sdballnodesfunc_t)(const char *zone, void *dbdata, 72 dns_sdballnodes_t *allnodes); 73 74 typedef isc_result_t (*dns_sdbcreatefunc_t)(const char *zone, int argc, 75 char **argv, void *driverdata, 76 void **dbdata); 77 78 typedef void (*dns_sdbdestroyfunc_t)(const char *zone, void *driverdata, 79 void **dbdata); 80 81 typedef struct dns_sdbmethods { 82 dns_sdblookupfunc_t lookup; 83 dns_sdbauthorityfunc_t authority; 84 dns_sdballnodesfunc_t allnodes; 85 dns_sdbcreatefunc_t create; 86 dns_sdbdestroyfunc_t destroy; 87 dns_sdblookup2func_t lookup2; 88 } dns_sdbmethods_t; 89 90 /*** 91 *** Functions 92 ***/ 93 94 ISC_LANG_BEGINDECLS 95 96 #define DNS_SDBFLAG_RELATIVEOWNER 0x00000001U 97 #define DNS_SDBFLAG_RELATIVERDATA 0x00000002U 98 #define DNS_SDBFLAG_THREADSAFE 0x00000004U 99 #define DNS_SDBFLAG_DNS64 0x00000008U 100 101 isc_result_t 102 dns_sdb_register(const char *drivername, const dns_sdbmethods_t *methods, 103 void *driverdata, unsigned int flags, isc_mem_t *mctx, 104 dns_sdbimplementation_t **sdbimp); 105 /*%< 106 * Register a simple database driver for the database type 'drivername', 107 * implemented by the functions in '*methods'. 108 * 109 * sdbimp must point to a NULL dns_sdbimplementation_t pointer. That is, 110 * sdbimp != NULL && *sdbimp == NULL. It will be assigned a value that 111 * will later be used to identify the driver when deregistering it. 112 * 113 * The name server will perform lookups in the database by calling the 114 * function 'lookup', passing it a printable zone name 'zone', a printable 115 * domain name 'name', and a copy of the argument 'dbdata' that 116 * was potentially returned by the create function. The 'dns_sdblookup_t' 117 * argument to 'lookup' and 'authority' is an opaque pointer to be passed to 118 * ns_sdb_putrr(). 119 * 120 * The lookup function returns the lookup results to the name server 121 * by calling ns_sdb_putrr() once for each record found. On success, 122 * the return value of the lookup function should be ISC_R_SUCCESS. 123 * If the domain name 'name' does not exist, the lookup function should 124 * ISC_R_NOTFOUND. Any other return value is treated as an error. 125 * 126 * Lookups at the zone apex will cause the server to also call the 127 * function 'authority' (if non-NULL), which must provide an SOA record 128 * and NS records for the zone by calling ns_sdb_putrr() once for each of 129 * these records. The 'authority' function may be NULL if invoking 130 * the 'lookup' function on the zone apex will return SOA and NS records. 131 * 132 * The allnodes function, if non-NULL, fills in an opaque structure to be 133 * used by a database iterator. This allows the zone to be transferred. 134 * This may use a considerable amount of memory for large zones, and the 135 * zone transfer may not be fully RFC1035 compliant if the zone is 136 * frequently changed. 137 * 138 * The create function will be called for each zone configured 139 * into the name server using this database type. It can be used 140 * to create a "database object" containing zone specific data, 141 * which can make use of the database arguments specified in the 142 * name server configuration. 143 * 144 * The destroy function will be called to free the database object 145 * when its zone is destroyed. 146 * 147 * The create and destroy functions may be NULL. 148 * 149 * If flags includes DNS_SDBFLAG_RELATIVEOWNER, the lookup and authority 150 * functions will be called with relative names rather than absolute names. 151 * The string "@" represents the zone apex in this case. 152 * 153 * If flags includes DNS_SDBFLAG_RELATIVERDATA, the rdata strings may 154 * include relative names. Otherwise, all names in the rdata string must 155 * be absolute. Be aware that if relative names are allowed, any 156 * absolute names must contain a trailing dot. 157 * 158 * If flags includes DNS_SDBFLAG_THREADSAFE, the driver must be able to 159 * handle multiple lookups in parallel. Otherwise, calls into the driver 160 * are serialized. 161 */ 162 163 void 164 dns_sdb_unregister(dns_sdbimplementation_t **sdbimp); 165 /*%< 166 * Removes the simple database driver from the list of registered database 167 * types. There must be no active databases of this type when this function 168 * is called. 169 */ 170 171 /*% See dns_sdb_putradata() */ 172 isc_result_t 173 dns_sdb_putrr(dns_sdblookup_t *lookup, const char *type, dns_ttl_t ttl, 174 const char *data); 175 isc_result_t 176 dns_sdb_putrdata(dns_sdblookup_t *lookup, dns_rdatatype_t type, dns_ttl_t ttl, 177 const unsigned char *rdata, unsigned int rdlen); 178 /*%< 179 * Add a single resource record to the lookup structure to be 180 * returned in the query response. dns_sdb_putrr() takes the 181 * resource record in master file text format as a null-terminated 182 * string, and dns_sdb_putrdata() takes the raw RDATA in 183 * uncompressed wire format. 184 */ 185 186 /*% See dns_sdb_putnamerdata() */ 187 isc_result_t 188 dns_sdb_putnamedrr(dns_sdballnodes_t *allnodes, const char *name, 189 const char *type, dns_ttl_t ttl, const char *data); 190 isc_result_t 191 dns_sdb_putnamedrdata(dns_sdballnodes_t *allnodes, const char *name, 192 dns_rdatatype_t type, dns_ttl_t ttl, const void *rdata, 193 unsigned int rdlen); 194 /*%< 195 * Add a single resource record to the allnodes structure to be 196 * included in a zone transfer response, in text or wire 197 * format as above. 198 */ 199 200 isc_result_t 201 dns_sdb_putsoa(dns_sdblookup_t *lookup, const char *mname, const char *rname, 202 uint32_t serial); 203 /*%< 204 * This function may optionally be called from the 'authority' callback 205 * to simplify construction of the SOA record for 'zone'. It will 206 * provide a SOA listing 'mname' as as the master server and 'rname' as 207 * the responsible person mailbox. It is the responsibility of the 208 * driver to increment the serial number between responses if necessary. 209 * All other SOA fields will have reasonable default values. 210 */ 211 212 ISC_LANG_ENDDECLS 213 214 #endif /* DNS_SDB_H */ 215