include/asterisk/acl.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2006, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Access Control of various sorts
  21  */
  22
  23 #ifndef _ASTERISK_ACL_H
  24 #define _ASTERISK_ACL_H
  25
  26
  27 #if defined(__cplusplus) || defined(c_plusplus)
  28 extern "C" {
  29 #endif
  30
  31 #include "asterisk/network.h"
  32 #include "asterisk/netsock2.h"
  33 #include "asterisk/io.h"
  34
  35 #define AST_SENSE_DENY                  0
  36 #define AST_SENSE_ALLOW                 1
  37
  38 /* Host based access control */
  39
  40 /*! \brief internal representation of acl entries
  41  * In principle user applications would have no need for this,
  42  * but there is sometimes a need to extract individual items,
  43  * e.g. to print them, and rather than defining iterators to
  44  * navigate the list, and an externally visible 'struct ast_ha_entry',
  45  * at least in the short term it is more convenient to make the whole
  46  * thing public and let users play with them.
  47  */
  48 struct ast_ha {
  49         /* Host access rule */
  50         struct ast_sockaddr addr;
  51         struct ast_sockaddr netmask;
  52         int sense;
  53         struct ast_ha *next;
  54 };
  55
  56 /*!
  57  * \brief Free a list of HAs
  58  *
  59  * \details
  60  * Given the head of a list of HAs, it and all appended
  61  * HAs are freed
  62  *
  63  * \param ha The head of the list of HAs to free
  64  * \retval void
  65  */
  66 void ast_free_ha(struct ast_ha *ha);
  67
  68 /*!
  69  * \brief Copy the contents of one HA to another
  70  *
  71  * \details
  72  * This copies the internals of the 'from' HA to the 'to'
  73  * HA. It is important that the 'to' HA has been allocated
  74  * prior to calling this function
  75  *
  76  * \param from Source HA to copy
  77  * \param to Destination HA to copy to
  78  * \retval void
  79  */
  80 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
  81
  82 /*!
  83  * \brief Add a new rule to a list of HAs
  84  *
  85  * \details
  86  * This adds the new host access rule to the end of the list
  87  * whose head is specified by the path parameter. Rules are
  88  * evaluated in a way such that if multiple rules apply to
  89  * a single IP address/subnet mask, then the rule latest
  90  * in the list will be used.
  91  *
  92  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
  93  * in permission, and any other word will result in denial)
  94  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
  95  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
  96  * \param path The head of the HA list to which we wish to append our new rule. If
  97  * NULL is passed, then the new rule will become the head of the list
  98  * \param[out] error The integer error points to will be set non-zero if an error occurs
  99  * \return The head of the HA list
 100  */
 101 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
 102
 103 /*!
 104  * \brief Apply a set of rules to a given IP address
 105  *
 106  * \details
 107  * The list of host access rules is traversed, beginning with the
 108  * input rule. If the IP address given matches a rule, the "sense"
 109  * of that rule is used as the return value. Note that if an IP
 110  * address matches multiple rules that the last one matched will be
 111  * the one whose sense will be returned.
 112  *
 113  * \param ha The head of the list of host access rules to follow
 114  * \param addr An ast_sockaddr whose address is considered when matching rules
 115  * \retval AST_SENSE_ALLOW The IP address passes our ACL
 116  * \retval AST_SENSE_DENY The IP address fails our ACL
 117  */
 118 int ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr);
 119
 120 /*!
 121  * \brief Get the IP address given a hostname
 122  *
 123  * \details
 124  * Similar in nature to ast_gethostbyname, except that instead
 125  * of getting an entire hostent structure, you instead are given
 126  * only the IP address inserted into a ast_sockaddr structure.
 127  *
 128  * \param addr The IP address found.  The address family is used
 129  * as an input parameter to filter the returned addresses.  If
 130  * it is 0, both IPv4 and IPv6 addresses can be returned.
 131  * \param hostname The hostname to look up
 132  *
 133  * \retval 0 Success
 134  * \retval -1 Failure
 135  */
 136 int ast_get_ip(struct ast_sockaddr *addr, const char *hostname);
 137
 138 /*!
 139  * \brief Get the IP address given a hostname and optional service
 140  *
 141  * \details
 142  * If the service parameter is non-NULL, then an SRV lookup will be made by
 143  * prepending the service to the hostname parameter, separated by a '.'
 144  * For example, if hostname is "example.com" and service is "_sip._udp" then
 145  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
 146  * then this function acts exactly like a call to ast_get_ip.
 147  *
 148  * \param addr The IP address found.  The address family is used
 149  * as an input parameter to filter the returned addresses.  If
 150  * it is 0, both IPv4 and IPv6 addresses can be returned.
 151  *
 152  * \param hostname The hostname to look up
 153  * \param service A specific service provided by the host. A NULL service results
 154  * in an A-record lookup instead of an SRV lookup
 155  * \retval 0 Success
 156  * \retval -1 Failure
 157  */
 158 int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *hostname, const char *service);
 159
 160 /*!
 161  * \brief Get our local IP address when contacting a remote host
 162  *
 163  * \details
 164  * This function will attempt to connect(2) to them over UDP using a source
 165  * port of 5060. If the connect(2) call is successful, then we inspect the
 166  * sockaddr_in output parameter of connect(2) to determine the IP address
 167  * used to connect to them. This IP address is then copied into us.
 168  *
 169  * \param them The IP address to which we wish to attempt to connect
 170  * \param[out] us The source IP address used to connect to them
 171  * \retval -1 Failure
 172  * \retval 0 Success
 173  */
 174 int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
 175
 176 /*!
 177  * \brief Find an IP address associated with a specific interface
 178  *
 179  * \details
 180  * Given an interface such as "eth0" we find the primary IP address
 181  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
 182  * should fail, we populate address with 0s.
 183  *
 184  * \note
 185  * This function is not actually used anywhere
 186  *
 187  * \param iface The interface name whose IP address we wish to find
 188  * \param[out] address The interface's IP address is placed into this param
 189  * \retval -1 Failure. address is filled with 0s
 190  * \retval 0 Success
 191  */
 192 int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
 193
 194 /*!
 195  * \brief Duplicate the contents of a list of host access rules
 196  *
 197  * \details
 198  * A deep copy of all ast_has in the list is made. The returned
 199  * value is allocated on the heap and must be freed independently
 200  * of the input parameter when finished.
 201  *
 202  * \note
 203  * This function is not actually used anywhere.
 204  *
 205  * \param original The ast_ha to copy
 206  * \retval The head of the list of duplicated ast_has
 207  */
 208 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
 209
 210 /*!
 211  * \brief Find our IP address
 212  *
 213  * \details
 214  * This function goes through many iterations in an attempt to find
 215  * our IP address. If any step along the way should fail, we move to the
 216  * next item in the list. Here are the steps taken:
 217  * - If bindaddr has a non-zero IP address, that is copied into ourip
 218  * - We use a combination of gethostname and ast_gethostbyname to find our
 219  *   IP address.
 220  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
 221  * - We try some platform-specific socket operations to find the IP address
 222  *
 223  * \param[out] ourip Our IP address is written here when it is found
 224  * \param bindaddr A hint used for finding our IP. See the steps above for
 225  * more details
 226  * \param family Only addresses of the given family will be returned. Use 0
 227  * or AST_SOCKADDR_UNSPEC to get addresses of all families.
 228  * \retval 0 Success
 229  * \retval -1 Failure
 230  */
 231 int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr, int family);
 232
 233 /*!
 234  * \brief Convert a string to the appropriate COS value
 235  *
 236  * \param value The COS string to convert
 237  * \param[out] cos The integer representation of that COS value
 238  * \retval -1 Failure
 239  * \retval 0 Success
 240  */
 241 int ast_str2cos(const char *value, unsigned int *cos);
 242
 243 /*!
 244  * \brief Convert a string to the appropriate TOS value
 245  *
 246  * \param value The TOS string to convert
 247  * \param[out] tos The integer representation of that TOS value
 248  * \retval -1 Failure
 249  * \retval 0 Success
 250  */
 251 int ast_str2tos(const char *value, unsigned int *tos);
 252
 253 /*!
 254  * \brief Convert a TOS value into its string representation
 255  *
 256  * \param tos The TOS value to look up
 257  * \return The string equivalent of the TOS value
 258  */
 259 const char *ast_tos2str(unsigned int tos);
 260
 261 #if defined(__cplusplus) || defined(c_plusplus)
 262 }
 263 #endif
 264
 265 #endif /* _ASTERISK_ACL_H */