Mon Aug 31 12:29:57 2015

Asterisk developer's documentation


acl.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2006, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Access Control of various sorts
00021  */
00022 
00023 #ifndef _ASTERISK_ACL_H
00024 #define _ASTERISK_ACL_H
00025 
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 #include "asterisk/network.h"
00032 #include "asterisk/netsock2.h"
00033 #include "asterisk/io.h"
00034 
00035 #define AST_SENSE_DENY                  0
00036 #define AST_SENSE_ALLOW                 1
00037 
00038 /* Host based access control */
00039 
00040 /*! \brief internal representation of acl entries
00041  * In principle user applications would have no need for this,
00042  * but there is sometimes a need to extract individual items,
00043  * e.g. to print them, and rather than defining iterators to
00044  * navigate the list, and an externally visible 'struct ast_ha_entry',
00045  * at least in the short term it is more convenient to make the whole
00046  * thing public and let users play with them.
00047  */
00048 struct ast_ha {
00049    /* Host access rule */
00050    struct ast_sockaddr addr;
00051    struct ast_sockaddr netmask;
00052    int sense;
00053    struct ast_ha *next;
00054 };
00055 
00056 /*!
00057  * \brief Free a list of HAs
00058  *
00059  * \details
00060  * Given the head of a list of HAs, it and all appended
00061  * HAs are freed
00062  *
00063  * \param ha The head of the list of HAs to free
00064  * \retval void
00065  */
00066 void ast_free_ha(struct ast_ha *ha);
00067 
00068 /*!
00069  * \brief Copy the contents of one HA to another
00070  *
00071  * \details
00072  * This copies the internals of the 'from' HA to the 'to'
00073  * HA. It is important that the 'to' HA has been allocated
00074  * prior to calling this function
00075  *
00076  * \param from Source HA to copy
00077  * \param to Destination HA to copy to
00078  * \retval void
00079  */
00080 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
00081 
00082 /*!
00083  * \brief Add a new rule to a list of HAs
00084  *
00085  * \details
00086  * This adds the new host access rule to the end of the list
00087  * whose head is specified by the path parameter. Rules are
00088  * evaluated in a way such that if multiple rules apply to
00089  * a single IP address/subnet mask, then the rule latest
00090  * in the list will be used.
00091  *
00092  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
00093  * in permission, and any other word will result in denial)
00094  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
00095  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
00096  * \param path The head of the HA list to which we wish to append our new rule. If
00097  * NULL is passed, then the new rule will become the head of the list
00098  * \param[out] error The integer error points to will be set non-zero if an error occurs
00099  * \return The head of the HA list
00100  */
00101 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
00102 
00103 /*!
00104  * \brief Apply a set of rules to a given IP address
00105  *
00106  * \details
00107  * The list of host access rules is traversed, beginning with the
00108  * input rule. If the IP address given matches a rule, the "sense"
00109  * of that rule is used as the return value. Note that if an IP
00110  * address matches multiple rules that the last one matched will be
00111  * the one whose sense will be returned.
00112  *
00113  * \param ha The head of the list of host access rules to follow
00114  * \param addr An ast_sockaddr whose address is considered when matching rules
00115  * \retval AST_SENSE_ALLOW The IP address passes our ACL
00116  * \retval AST_SENSE_DENY The IP address fails our ACL
00117  */
00118 int ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr);
00119 
00120 /*!
00121  * \brief Get the IP address given a hostname
00122  *
00123  * \details
00124  * Similar in nature to ast_gethostbyname, except that instead
00125  * of getting an entire hostent structure, you instead are given
00126  * only the IP address inserted into a ast_sockaddr structure.
00127  *
00128  * \param addr The IP address found.  The address family is used
00129  * as an input parameter to filter the returned addresses.  If
00130  * it is 0, both IPv4 and IPv6 addresses can be returned.
00131  * \param hostname The hostname to look up
00132  *
00133  * \retval 0 Success
00134  * \retval -1 Failure
00135  */
00136 int ast_get_ip(struct ast_sockaddr *addr, const char *hostname);
00137 
00138 /*!
00139  * \brief Get the IP address given a hostname and optional service
00140  *
00141  * \details
00142  * If the service parameter is non-NULL, then an SRV lookup will be made by
00143  * prepending the service to the hostname parameter, separated by a '.'
00144  * For example, if hostname is "example.com" and service is "_sip._udp" then
00145  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
00146  * then this function acts exactly like a call to ast_get_ip.
00147  *
00148  * \param addr The IP address found.  The address family is used
00149  * as an input parameter to filter the returned addresses.  If
00150  * it is 0, both IPv4 and IPv6 addresses can be returned.
00151  *
00152  * \param hostname The hostname to look up
00153  * \param service A specific service provided by the host. A NULL service results
00154  * in an A-record lookup instead of an SRV lookup
00155  * \retval 0 Success
00156  * \retval -1 Failure
00157  */
00158 int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *hostname, const char *service);
00159 
00160 /*!
00161  * \brief Get our local IP address when contacting a remote host
00162  *
00163  * \details
00164  * This function will attempt to connect(2) to them over UDP using a source
00165  * port of 5060. If the connect(2) call is successful, then we inspect the
00166  * sockaddr_in output parameter of connect(2) to determine the IP address
00167  * used to connect to them. This IP address is then copied into us.
00168  *
00169  * \param them The IP address to which we wish to attempt to connect
00170  * \param[out] us The source IP address used to connect to them
00171  * \retval -1 Failure
00172  * \retval 0 Success
00173  */
00174 int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
00175 
00176 /*!
00177  * \brief Find an IP address associated with a specific interface
00178  *
00179  * \details
00180  * Given an interface such as "eth0" we find the primary IP address
00181  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
00182  * should fail, we populate address with 0s.
00183  *
00184  * \note
00185  * This function is not actually used anywhere
00186  *
00187  * \param iface The interface name whose IP address we wish to find
00188  * \param[out] address The interface's IP address is placed into this param
00189  * \retval -1 Failure. address is filled with 0s
00190  * \retval 0 Success
00191  */
00192 int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
00193 
00194 /*!
00195  * \brief Duplicate the contents of a list of host access rules
00196  *
00197  * \details
00198  * A deep copy of all ast_has in the list is made. The returned
00199  * value is allocated on the heap and must be freed independently
00200  * of the input parameter when finished.
00201  *
00202  * \note
00203  * This function is not actually used anywhere.
00204  *
00205  * \param original The ast_ha to copy
00206  * \retval The head of the list of duplicated ast_has
00207  */
00208 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
00209 
00210 /*!
00211  * \brief Find our IP address
00212  *
00213  * \details
00214  * This function goes through many iterations in an attempt to find
00215  * our IP address. If any step along the way should fail, we move to the
00216  * next item in the list. Here are the steps taken:
00217  * - If bindaddr has a non-zero IP address, that is copied into ourip
00218  * - We use a combination of gethostname and ast_gethostbyname to find our
00219  *   IP address.
00220  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
00221  * - We try some platform-specific socket operations to find the IP address
00222  *
00223  * \param[out] ourip Our IP address is written here when it is found
00224  * \param bindaddr A hint used for finding our IP. See the steps above for
00225  * more details
00226  * \param family Only addresses of the given family will be returned. Use 0
00227  * or AST_SOCKADDR_UNSPEC to get addresses of all families.
00228  * \retval 0 Success
00229  * \retval -1 Failure
00230  */
00231 int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr, int family);
00232 
00233 /*!
00234  * \brief Convert a string to the appropriate COS value
00235  *
00236  * \param value The COS string to convert
00237  * \param[out] cos The integer representation of that COS value
00238  * \retval -1 Failure
00239  * \retval 0 Success
00240  */
00241 int ast_str2cos(const char *value, unsigned int *cos);
00242 
00243 /*!
00244  * \brief Convert a string to the appropriate TOS value
00245  *
00246  * \param value The TOS string to convert
00247  * \param[out] tos The integer representation of that TOS value
00248  * \retval -1 Failure
00249  * \retval 0 Success
00250  */
00251 int ast_str2tos(const char *value, unsigned int *tos);
00252 
00253 /*!
00254  * \brief Convert a TOS value into its string representation
00255  *
00256  * \param tos The TOS value to look up
00257  * \return The string equivalent of the TOS value
00258  */
00259 const char *ast_tos2str(unsigned int tos);
00260 
00261 #if defined(__cplusplus) || defined(c_plusplus)
00262 }
00263 #endif
00264 
00265 #endif /* _ASTERISK_ACL_H */

Generated on 31 Aug 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1