contrib/bind9/lib/dns/include/dns/acl.h

   1 /*
   2  * Copyright (C) 2004-2006  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 1999-2002  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and distribute this software for any
   6  * purpose with or without fee is hereby granted, provided that the above
   7  * copyright notice and this permission notice appear in all copies.
   8  *
   9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
  10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
  12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
  13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
  14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  15  * PERFORMANCE OF THIS SOFTWARE.
  16  */
  17
  18 /* $Id: acl.h,v 1.22.18.4 2006/03/02 00:37:21 marka Exp $ */
  19
  20 #ifndef DNS_ACL_H
  21 #define DNS_ACL_H 1
  22
  23 /*****
  24  ***** Module Info
  25  *****/
  26
  27 /*! \file
  28  * \brief
  29  * Address match list handling.
  30  */
  31
  32 /***
  33  *** Imports
  34  ***/
  35
  36 #include <isc/lang.h>
  37 #include <isc/magic.h>
  38 #include <isc/netaddr.h>
  39 #include <isc/refcount.h>
  40
  41 #include <dns/name.h>
  42 #include <dns/types.h>
  43
  44 /***
  45  *** Types
  46  ***/
  47
  48 typedef enum {
  49         dns_aclelementtype_ipprefix,
  50         dns_aclelementtype_keyname,
  51         dns_aclelementtype_nestedacl,
  52         dns_aclelementtype_localhost,
  53         dns_aclelementtype_localnets,
  54         dns_aclelementtype_any
  55 } dns_aclelemettype_t;
  56
  57 typedef struct dns_aclipprefix dns_aclipprefix_t;
  58
  59 struct dns_aclipprefix {
  60         isc_netaddr_t address; /* IP4/IP6 */
  61         unsigned int prefixlen;
  62 };
  63
  64 struct dns_aclelement {
  65         dns_aclelemettype_t type;
  66         isc_boolean_t negative;
  67         union {
  68                 dns_aclipprefix_t ip_prefix;
  69                 dns_name_t        keyname;
  70                 dns_acl_t         *nestedacl;
  71         } u;
  72 };
  73
  74 struct dns_acl {
  75         unsigned int            magic;
  76         isc_mem_t               *mctx;
  77         isc_refcount_t          refcount;
  78         dns_aclelement_t        *elements;
  79         unsigned int            alloc;          /*%< Elements allocated */
  80         unsigned int            length;         /*%< Elements initialized */
  81         char                    *name;          /*%< Temporary use only */
  82         ISC_LINK(dns_acl_t)     nextincache;    /*%< Ditto */
  83 };
  84
  85 struct dns_aclenv {
  86         dns_acl_t *localhost;
  87         dns_acl_t *localnets;
  88         isc_boolean_t match_mapped;
  89 };
  90
  91 #define DNS_ACL_MAGIC           ISC_MAGIC('D','a','c','l')
  92 #define DNS_ACL_VALID(a)        ISC_MAGIC_VALID(a, DNS_ACL_MAGIC)
  93
  94 /***
  95  *** Functions
  96  ***/
  97
  98 ISC_LANG_BEGINDECLS
  99
 100 isc_result_t
 101 dns_acl_create(isc_mem_t *mctx, int n, dns_acl_t **target);
 102 /*%<
 103  * Create a new ACL with room for 'n' elements.
 104  * The elements are uninitialized and the length is 0.
 105  */
 106
 107 isc_result_t
 108 dns_acl_appendelement(dns_acl_t *acl, const dns_aclelement_t *elt);
 109 /*%<
 110  * Append an element to an existing ACL.
 111  */
 112
 113 isc_result_t
 114 dns_acl_any(isc_mem_t *mctx, dns_acl_t **target);
 115 /*%<
 116  * Create a new ACL that matches everything.
 117  */
 118
 119 isc_result_t
 120 dns_acl_none(isc_mem_t *mctx, dns_acl_t **target);
 121 /*%<
 122  * Create a new ACL that matches nothing.
 123  */
 124
 125 void
 126 dns_acl_attach(dns_acl_t *source, dns_acl_t **target);
 127
 128 void
 129 dns_acl_detach(dns_acl_t **aclp);
 130
 131 isc_boolean_t
 132 dns_aclelement_equal(const dns_aclelement_t *ea, const dns_aclelement_t *eb);
 133
 134 isc_boolean_t
 135 dns_acl_equal(const dns_acl_t *a, const dns_acl_t *b);
 136
 137 isc_boolean_t
 138 dns_acl_isinsecure(const dns_acl_t *a);
 139 /*%<
 140  * Return #ISC_TRUE iff the acl 'a' is considered insecure, that is,
 141  * if it contains IP addresses other than those of the local host.
 142  * This is intended for applications such as printing warning
 143  * messages for suspect ACLs; it is not intended for making access
 144  * control decisions.  We make no guarantee that an ACL for which
 145  * this function returns #ISC_FALSE is safe.
 146  */
 147
 148 isc_result_t
 149 dns_aclenv_init(isc_mem_t *mctx, dns_aclenv_t *env);
 150
 151 void
 152 dns_aclenv_copy(dns_aclenv_t *t, dns_aclenv_t *s);
 153
 154 void
 155 dns_aclenv_destroy(dns_aclenv_t *env);
 156
 157 isc_result_t
 158 dns_acl_match(const isc_netaddr_t *reqaddr,
 159               const dns_name_t *reqsigner,
 160               const dns_acl_t *acl,
 161               const dns_aclenv_t *env,
 162               int *match,
 163               const dns_aclelement_t **matchelt);
 164 /*%<
 165  * General, low-level ACL matching.  This is expected to
 166  * be useful even for weird stuff like the topology and sortlist statements.
 167  *
 168  * Match the address 'reqaddr', and optionally the key name 'reqsigner',
 169  * against 'acl'.  'reqsigner' may be NULL.
 170  *
 171  * If there is a positive match, '*match' will be set to a positive value
 172  * indicating the distance from the beginning of the list.
 173  *
 174  * If there is a negative match, '*match' will be set to a negative value
 175  * whose absolute value indicates the distance from the beginning of
 176  * the list.
 177  *
 178  * If there is a match (either positive or negative) and 'matchelt' is
 179  * non-NULL, *matchelt will be attached to the primitive
 180  * (non-indirect) address match list element that matched.
 181  *
 182  * If there is no match, *match will be set to zero.
 183  *
 184  * Returns:
 185  *\li   #ISC_R_SUCCESS          Always succeeds.
 186  */
 187
 188 isc_boolean_t
 189 dns_aclelement_match(const isc_netaddr_t *reqaddr,
 190                      const dns_name_t *reqsigner,
 191                      const dns_aclelement_t *e,
 192                      const dns_aclenv_t *env,
 193                      const dns_aclelement_t **matchelt);
 194 /*%<
 195  * Like dns_acl_match, but matches against the single ACL element 'e'
 196  * rather than a complete list and returns ISC_TRUE iff it matched.
 197  * To determine whether the match was prositive or negative, the
 198  * caller should examine e->negative.  Since the element 'e' may be
 199  * a reference to a named ACL or a nested ACL, the matching element
 200  * returned through 'matchelt' is not necessarily 'e' itself.
 201  */
 202
 203 isc_result_t
 204 dns_acl_elementmatch(const dns_acl_t *acl,
 205                      const dns_aclelement_t *elt,
 206                      const dns_aclelement_t **matchelt);
 207 /*%<
 208  * Search for an ACL element in 'acl' which is exactly the same as 'elt'.
 209  * If there is one, and 'matchelt' is non NULL, then '*matchelt' will point
 210  * to the entry.
 211  *
 212  * This function is intended to be used for avoiding duplicated ACL entries
 213  * before adding an entry.
 214  *
 215  * Returns:
 216  *\li   #ISC_R_SUCCESS          Match succeeds.
 217  *\li   #ISC_R_NOTFOUND         Match fails.
 218  */
 219
 220 ISC_LANG_ENDDECLS
 221
 222 #endif /* DNS_ACL_H */