1 /* $NetBSD: ssu.h,v 1.6 2022/09/23 12:15:30 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 #ifndef DNS_SSU_H 17 #define DNS_SSU_H 1 18 19 /*! \file dns/ssu.h */ 20 21 #include <stdbool.h> 22 23 #include <isc/lang.h> 24 25 #include <dns/acl.h> 26 #include <dns/types.h> 27 28 #include <dst/dst.h> 29 30 ISC_LANG_BEGINDECLS 31 32 typedef enum { 33 dns_ssumatchtype_name = 0, 34 dns_ssumatchtype_subdomain = 1, 35 dns_ssumatchtype_wildcard = 2, 36 dns_ssumatchtype_self = 3, 37 dns_ssumatchtype_selfsub = 4, 38 dns_ssumatchtype_selfwild = 5, 39 dns_ssumatchtype_selfkrb5 = 6, 40 dns_ssumatchtype_selfms = 7, 41 dns_ssumatchtype_subdomainms = 8, 42 dns_ssumatchtype_subdomainkrb5 = 9, 43 dns_ssumatchtype_tcpself = 10, 44 dns_ssumatchtype_6to4self = 11, 45 dns_ssumatchtype_external = 12, 46 dns_ssumatchtype_local = 13, 47 dns_ssumatchtype_selfsubms = 14, 48 dns_ssumatchtype_selfsubkrb5 = 15, 49 dns_ssumatchtype_max = 15, /* max value */ 50 51 dns_ssumatchtype_dlz = 16 /* intentionally higher than _max */ 52 } dns_ssumatchtype_t; 53 54 isc_result_t 55 dns_ssutable_create(isc_mem_t *mctx, dns_ssutable_t **table); 56 /*%< 57 * Creates a table that will be used to store simple-secure-update rules. 58 * Note: all locking must be provided by the client. 59 * 60 * Requires: 61 *\li 'mctx' is a valid memory context 62 *\li 'table' is not NULL, and '*table' is NULL 63 * 64 * Returns: 65 *\li ISC_R_SUCCESS 66 *\li ISC_R_NOMEMORY 67 */ 68 69 isc_result_t 70 dns_ssutable_createdlz(isc_mem_t *mctx, dns_ssutable_t **tablep, 71 dns_dlzdb_t *dlzdatabase); 72 /*%< 73 * Create an SSU table that contains a dlzdatabase pointer, and a 74 * single rule with matchtype dns_ssumatchtype_dlz. This type of SSU 75 * table is used by writeable DLZ drivers to offload authorization for 76 * updates to the driver. 77 */ 78 79 void 80 dns_ssutable_attach(dns_ssutable_t *source, dns_ssutable_t **targetp); 81 /*%< 82 * Attach '*targetp' to 'source'. 83 * 84 * Requires: 85 *\li 'source' is a valid SSU table 86 *\li 'targetp' points to a NULL dns_ssutable_t *. 87 * 88 * Ensures: 89 *\li *targetp is attached to source. 90 */ 91 92 void 93 dns_ssutable_detach(dns_ssutable_t **tablep); 94 /*%< 95 * Detach '*tablep' from its simple-secure-update rule table. 96 * 97 * Requires: 98 *\li 'tablep' points to a valid dns_ssutable_t 99 * 100 * Ensures: 101 *\li *tablep is NULL 102 *\li If '*tablep' is the last reference to the SSU table, all 103 * resources used by the table will be freed. 104 */ 105 106 isc_result_t 107 dns_ssutable_addrule(dns_ssutable_t *table, bool grant, 108 const dns_name_t *identity, dns_ssumatchtype_t matchtype, 109 const dns_name_t *name, unsigned int ntypes, 110 dns_rdatatype_t *types); 111 /*%< 112 * Adds a new rule to a simple-secure-update rule table. The rule 113 * either grants or denies update privileges of an identity (or set of 114 * identities) to modify a name (or set of names) or certain types present 115 * at that name. 116 * 117 * Notes: 118 *\li If 'matchtype' is of SELF type, this rule only matches if the 119 * name to be updated matches the signing identity. 120 * 121 *\li If 'ntypes' is 0, this rule applies to all types except 122 * NS, SOA, RRSIG, and NSEC. 123 * 124 *\li If 'types' includes ANY, this rule applies to all types 125 * except NSEC. 126 * 127 * Requires: 128 *\li 'table' is a valid SSU table 129 *\li 'identity' is a valid absolute name 130 *\li 'matchtype' must be one of the defined constants. 131 *\li 'name' is a valid absolute name 132 *\li If 'ntypes' > 0, 'types' must not be NULL 133 * 134 * Returns: 135 *\li ISC_R_SUCCESS 136 *\li ISC_R_NOMEMORY 137 */ 138 139 bool 140 dns_ssutable_checkrules(dns_ssutable_t *table, const dns_name_t *signer, 141 const dns_name_t *name, const isc_netaddr_t *addr, 142 bool tcp, const dns_aclenv_t *env, dns_rdatatype_t type, 143 const dst_key_t *key); 144 /*%< 145 * Checks that the attempted update of (name, type) is allowed according 146 * to the rules specified in the simple-secure-update rule table. If 147 * no rules are matched, access is denied. 148 * 149 * Notes: 150 * In dns_ssutable_checkrules(), 'addr' should only be 151 * set if the request received via TCP. This provides a 152 * weak assurance that the request was not spoofed. 153 * 'addr' is to to validate dns_ssumatchtype_tcpself 154 * and dns_ssumatchtype_6to4self rules. 155 * 156 * In dns_ssutable_checkrules2(), 'addr' can also be passed for 157 * UDP requests and TCP is specified via the 'tcp' parameter. 158 * In addition to dns_ssumatchtype_tcpself and 159 * tcp_ssumatchtype_6to4self rules, the address 160 * also be used to check dns_ssumatchtype_local rules. 161 * If 'addr' is set then 'env' must also be set so that 162 * requests from non-localhost addresses can be rejected. 163 * 164 * For dns_ssumatchtype_tcpself the addresses are mapped to 165 * the standard reverse names under IN-ADDR.ARPA and IP6.ARPA. 166 * RFC 1035, Section 3.5, "IN-ADDR.ARPA domain" and RFC 3596, 167 * Section 2.5, "IP6.ARPA Domain". 168 * 169 * For dns_ssumatchtype_6to4self, IPv4 address are converted 170 * to a 6to4 prefix (48 bits) per the rules in RFC 3056. Only 171 * the top 48 bits of the IPv6 address are mapped to the reverse 172 * name. This is independent of whether the most significant 16 173 * bits match 2002::/16, assigned for 6to4 prefixes, or not. 174 * 175 * Requires: 176 *\li 'table' is a valid SSU table 177 *\li 'signer' is NULL or a valid absolute name 178 *\li 'addr' is NULL or a valid network address. 179 *\li 'aclenv' is NULL or a valid ACL environment. 180 *\li 'name' is a valid absolute name 181 *\li if 'addr' is not NULL, 'env' is not NULL. 182 */ 183 184 /*% Accessor functions to extract rule components */ 185 bool 186 dns_ssurule_isgrant(const dns_ssurule_t *rule); 187 /*% Accessor functions to extract rule components */ 188 dns_name_t * 189 dns_ssurule_identity(const dns_ssurule_t *rule); 190 /*% Accessor functions to extract rule components */ 191 unsigned int 192 dns_ssurule_matchtype(const dns_ssurule_t *rule); 193 /*% Accessor functions to extract rule components */ 194 dns_name_t * 195 dns_ssurule_name(const dns_ssurule_t *rule); 196 /*% Accessor functions to extract rule components */ 197 unsigned int 198 dns_ssurule_types(const dns_ssurule_t *rule, dns_rdatatype_t **types); 199 200 isc_result_t 201 dns_ssutable_firstrule(const dns_ssutable_t *table, dns_ssurule_t **rule); 202 /*%< 203 * Initiates a rule iterator. There is no need to maintain any state. 204 * 205 * Returns: 206 *\li #ISC_R_SUCCESS 207 *\li #ISC_R_NOMORE 208 */ 209 210 isc_result_t 211 dns_ssutable_nextrule(dns_ssurule_t *rule, dns_ssurule_t **nextrule); 212 /*%< 213 * Returns the next rule in the table. 214 * 215 * Returns: 216 *\li #ISC_R_SUCCESS 217 *\li #ISC_R_NOMORE 218 */ 219 220 bool 221 dns_ssu_external_match(const dns_name_t *identity, const dns_name_t *signer, 222 const dns_name_t *name, const isc_netaddr_t *tcpaddr, 223 dns_rdatatype_t type, const dst_key_t *key, 224 isc_mem_t *mctx); 225 /*%< 226 * Check a policy rule via an external application 227 */ 228 229 isc_result_t 230 dns_ssu_mtypefromstring(const char *str, dns_ssumatchtype_t *mtype); 231 /*%< 232 * Set 'mtype' from 'str' 233 * 234 * Requires: 235 *\li 'str' is not NULL. 236 *\li 'mtype' is not NULL, 237 * 238 * Returns: 239 *\li #ISC_R_SUCCESS 240 *\li #ISC_R_NOTFOUND 241 */ 242 243 ISC_LANG_ENDDECLS 244 245 #endif /* DNS_SSU_H */ 246