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

   1 /*
   2  * Copyright (C) 2004-2008, 2010, 2011  Internet Systems Consortium, Inc. ("ISC")
   3  * Copyright (C) 2000, 2001, 2003  Internet Software Consortium.
   4  *
   5  * Permission to use, copy, modify, and/or 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: ssu.h,v 1.28 2011/01/06 23:47:00 tbox Exp $ */
  19
  20 #ifndef DNS_SSU_H
  21 #define DNS_SSU_H 1
  22
  23 /*! \file dns/ssu.h */
  24
  25 #include <isc/lang.h>
  26
  27 #include <dns/types.h>
  28 #include <dst/dst.h>
  29
  30 ISC_LANG_BEGINDECLS
  31
  32 #define DNS_SSUMATCHTYPE_NAME           0
  33 #define DNS_SSUMATCHTYPE_SUBDOMAIN      1
  34 #define DNS_SSUMATCHTYPE_WILDCARD       2
  35 #define DNS_SSUMATCHTYPE_SELF           3
  36 #define DNS_SSUMATCHTYPE_SELFSUB        4
  37 #define DNS_SSUMATCHTYPE_SELFWILD       5
  38 #define DNS_SSUMATCHTYPE_SELFKRB5       6
  39 #define DNS_SSUMATCHTYPE_SELFMS         7
  40 #define DNS_SSUMATCHTYPE_SUBDOMAINMS    8
  41 #define DNS_SSUMATCHTYPE_SUBDOMAINKRB5  9
  42 #define DNS_SSUMATCHTYPE_TCPSELF        10
  43 #define DNS_SSUMATCHTYPE_6TO4SELF       11
  44 #define DNS_SSUMATCHTYPE_EXTERNAL       12
  45 #define DNS_SSUMATCHTYPE_DLZ            13
  46 #define DNS_SSUMATCHTYPE_MAX            12  /* max value */
  47
  48 isc_result_t
  49 dns_ssutable_create(isc_mem_t *mctx, dns_ssutable_t **table);
  50 /*%<
  51  *      Creates a table that will be used to store simple-secure-update rules.
  52  *      Note: all locking must be provided by the client.
  53  *
  54  *      Requires:
  55  *\li           'mctx' is a valid memory context
  56  *\li           'table' is not NULL, and '*table' is NULL
  57  *
  58  *      Returns:
  59  *\li           ISC_R_SUCCESS
  60  *\li           ISC_R_NOMEMORY
  61  */
  62
  63 isc_result_t
  64 dns_ssutable_createdlz(isc_mem_t *mctx, dns_ssutable_t **tablep,
  65                        dns_dlzdb_t *dlzdatabase);
  66 /*%<
  67  * Create an SSU table that contains a dlzdatabase pointer, and a
  68  * single rule with matchtype DNS_SSUMATCHTYPE_DLZ. This type of SSU
  69  * table is used by writeable DLZ drivers to offload authorization for
  70  * updates to the driver.
  71  */
  72
  73 void
  74 dns_ssutable_attach(dns_ssutable_t *source, dns_ssutable_t **targetp);
  75 /*%<
  76  *      Attach '*targetp' to 'source'.
  77  *
  78  *      Requires:
  79  *\li           'source' is a valid SSU table
  80  *\li           'targetp' points to a NULL dns_ssutable_t *.
  81  *
  82  *      Ensures:
  83  *\li           *targetp is attached to source.
  84  */
  85
  86 void
  87 dns_ssutable_detach(dns_ssutable_t **tablep);
  88 /*%<
  89  *      Detach '*tablep' from its simple-secure-update rule table.
  90  *
  91  *      Requires:
  92  *\li           'tablep' points to a valid dns_ssutable_t
  93  *
  94  *      Ensures:
  95  *\li           *tablep is NULL
  96  *\li           If '*tablep' is the last reference to the SSU table, all
  97  *                      resources used by the table will be freed.
  98  */
  99
 100 isc_result_t
 101 dns_ssutable_addrule(dns_ssutable_t *table, isc_boolean_t grant,
 102                      dns_name_t *identity, unsigned int matchtype,
 103                      dns_name_t *name, unsigned int ntypes,
 104                      dns_rdatatype_t *types);
 105 /*%<
 106  *      Adds a new rule to a simple-secure-update rule table.  The rule
 107  *      either grants or denies update privileges of an identity (or set of
 108  *      identities) to modify a name (or set of names) or certain types present
 109  *      at that name.
 110  *
 111  *      Notes:
 112  *\li           If 'matchtype' is of SELF type, this rule only matches if the
 113  *              name to be updated matches the signing identity.
 114  *
 115  *\li           If 'ntypes' is 0, this rule applies to all types except
 116  *              NS, SOA, RRSIG, and NSEC.
 117  *
 118  *\li           If 'types' includes ANY, this rule applies to all types
 119  *              except NSEC.
 120  *
 121  *      Requires:
 122  *\li           'table' is a valid SSU table
 123  *\li           'identity' is a valid absolute name
 124  *\li           'matchtype' must be one of the defined constants.
 125  *\li           'name' is a valid absolute name
 126  *\li           If 'ntypes' > 0, 'types' must not be NULL
 127  *
 128  *      Returns:
 129  *\li           ISC_R_SUCCESS
 130  *\li           ISC_R_NOMEMORY
 131  */
 132
 133 isc_boolean_t
 134 dns_ssutable_checkrules(dns_ssutable_t *table, dns_name_t *signer,
 135                         dns_name_t *name, isc_netaddr_t *tcpaddr,
 136                         dns_rdatatype_t type, const dst_key_t *key);
 137 /*%<
 138  *      Checks that the attempted update of (name, type) is allowed according
 139  *      to the rules specified in the simple-secure-update rule table.  If
 140  *      no rules are matched, access is denied.
 141  *
 142  *      Notes:
 143  *              'tcpaddr' should only be set if the request received
 144  *              via TCP.  This provides a weak assurance that the
 145  *              request was not spoofed.  'tcpaddr' is to to validate
 146  *              DNS_SSUMATCHTYPE_TCPSELF and DNS_SSUMATCHTYPE_6TO4SELF
 147  *              rules.
 148  *
 149  *              For DNS_SSUMATCHTYPE_TCPSELF the addresses are mapped to
 150  *              the standard reverse names under IN-ADDR.ARPA and IP6.ARPA.
 151  *              RFC 1035, Section 3.5, "IN-ADDR.ARPA domain" and RFC 3596,
 152  *              Section 2.5, "IP6.ARPA Domain".
 153  *
 154  *              For DNS_SSUMATCHTYPE_6TO4SELF, IPv4 address are converted
 155  *              to a 6to4 prefix (48 bits) per the rules in RFC 3056.  Only
 156  *              the top 48 bits of the IPv6 address are mapped to the reverse
 157  *              name. This is independent of whether the most significant 16
 158  *              bits match 2002::/16, assigned for 6to4 prefixes, or not.
 159  *
 160  *      Requires:
 161  *\li           'table' is a valid SSU table
 162  *\li           'signer' is NULL or a valid absolute name
 163  *\li           'tcpaddr' is NULL or a valid network address.
 164  *\li           'name' is a valid absolute name
 165  */
 166
 167
 168 /*% Accessor functions to extract rule components */
 169 isc_boolean_t   dns_ssurule_isgrant(const dns_ssurule_t *rule);
 170 /*% Accessor functions to extract rule components */
 171 dns_name_t *    dns_ssurule_identity(const dns_ssurule_t *rule);
 172 /*% Accessor functions to extract rule components */
 173 unsigned int    dns_ssurule_matchtype(const dns_ssurule_t *rule);
 174 /*% Accessor functions to extract rule components */
 175 dns_name_t *    dns_ssurule_name(const dns_ssurule_t *rule);
 176 /*% Accessor functions to extract rule components */
 177 unsigned int    dns_ssurule_types(const dns_ssurule_t *rule,
 178                                   dns_rdatatype_t **types);
 179
 180 isc_result_t    dns_ssutable_firstrule(const dns_ssutable_t *table,
 181                                        dns_ssurule_t **rule);
 182 /*%<
 183  * Initiates a rule iterator.  There is no need to maintain any state.
 184  *
 185  * Returns:
 186  *\li   #ISC_R_SUCCESS
 187  *\li   #ISC_R_NOMORE
 188  */
 189
 190 isc_result_t    dns_ssutable_nextrule(dns_ssurule_t *rule,
 191                                       dns_ssurule_t **nextrule);
 192 /*%<
 193  * Returns the next rule in the table.
 194  *
 195  * Returns:
 196  *\li   #ISC_R_SUCCESS
 197  *\li   #ISC_R_NOMORE
 198  */
 199
 200
 201 /*%<
 202  * Check a policy rule via an external application
 203  */
 204 isc_boolean_t
 205 dns_ssu_external_match(dns_name_t *identity, dns_name_t *signer,
 206                        dns_name_t *name, isc_netaddr_t *tcpaddr,
 207                        dns_rdatatype_t type, const dst_key_t *key,
 208                        isc_mem_t *mctx);
 209
 210 ISC_LANG_ENDDECLS
 211
 212 #endif /* DNS_SSU_H */