Sat Aug 6 00:39:19 2011

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 <netinet/in.h>
00032 #include "asterisk/io.h"
00033 
00034 #define AST_SENSE_DENY                  0
00035 #define AST_SENSE_ALLOW                 1
00036 
00037 /* Host based access control */
00038 struct ast_ha {
00039    /* Host access rule */
00040    struct in_addr netaddr;
00041    struct in_addr netmask;
00042    int sense;
00043    struct ast_ha *next;
00044 };
00045 
00046 /*!
00047  * \brief Free a list of HAs
00048  *
00049  * \details
00050  * Given the head of a list of HAs, it and all appended
00051  * HAs are freed
00052  *
00053  * \param ha The head of the list of HAs to free
00054  * \retval void
00055  */
00056 void ast_free_ha(struct ast_ha *ha);
00057 
00058 /*!
00059  * \brief Copy the contents of one HA to another
00060  *
00061  * \details
00062  * This copies the internals of the 'from' HA to the 'to'
00063  * HA. It is important that the 'to' HA has been allocated
00064  * prior to calling this function
00065  *
00066  * \param from Source HA to copy
00067  * \param to Destination HA to copy to
00068  * \retval void
00069  */
00070 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
00071 
00072 /*!
00073  * \brief Add a new rule to a list of HAs
00074  *
00075  * \details
00076  * This adds the new host access rule to the end of the list
00077  * whose head is specified by the path parameter. Rules are
00078  * evaluated in a way such that if multiple rules apply to
00079  * a single IP address/subnet mask, then the rule latest
00080  * in the list will be used.
00081  *
00082  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
00083  * in permission, and any other word will result in denial)
00084  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
00085  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
00086  * \param path The head of the HA list to which we wish to append our new rule. If
00087  * NULL is passed, then the new rule will become the head of the list
00088  * \return The head of the HA list
00089  */
00090 struct ast_ha *ast_append_ha(char *sense, const char *stuff, struct ast_ha *path);
00091 
00092 /*!
00093  * \brief Apply a set of rules to a given IP address
00094  *
00095  * \details
00096  * The list of host access rules is traversed, beginning with the
00097  * input rule. If the IP address given matches a rule, the "sense"
00098  * of that rule is used as the return value. Note that if an IP
00099  * address matches multiple rules that the last one matched will be
00100  * the one whose sense will be returned.
00101  *
00102  * \param ha The head of the list of host access rules to follow
00103  * \param sin A sockaddr_in whose address is considered when matching rules
00104  * \retval AST_SENSE_ALLOW The IP address passes our ACL
00105  * \retval AST_SENSE_DENY The IP address fails our ACL
00106  */
00107 int ast_apply_ha(struct ast_ha *ha, struct sockaddr_in *sin);
00108 
00109 /*!
00110  * \brief Get the IP address given a hostname
00111  *
00112  * \details
00113  * Similar in nature to ast_gethostbyname, except that instead
00114  * of getting an entire hostent structure, you instead are given
00115  * only the IP address inserted into a sockaddr_in structure.
00116  *
00117  * \param[out] sin The IP address is written into sin->sin_addr
00118  * \param value The hostname to look up
00119  * \retval 0 Success
00120  * \retval -1 Failure
00121  */
00122 int ast_get_ip(struct sockaddr_in *sin, const char *value);
00123 
00124 /*!
00125  * \brief Get the IP address given a hostname and optional service
00126  *
00127  * \details
00128  * If the service parameter is non-NULL, then an SRV lookup will be made by
00129  * prepending the service to the value parameter, separated by a '.'
00130  * For example, if value is "example.com" and service is "_sip._udp" then
00131  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
00132  * then this function acts exactly like a call to ast_get_ip.
00133  *
00134  * \param[out] sin The IP address is written into sin->sin_addr
00135  * \param value The hostname to look up
00136  * \param service A specific service provided by the host. A NULL service results
00137  * in an A-record lookup instead of an SRV lookup
00138  * \retval 0 Success
00139  * \retval -1 Failure
00140  */
00141 int ast_get_ip_or_srv(struct sockaddr_in *sin, const char *value, const char *service);
00142 
00143 /*!
00144  * \brief Get our local IP address when contacting a remote host
00145  *
00146  * \details
00147  * This function will attempt to connect(2) to them over UDP using a source
00148  * port of 5060. If the connect(2) call is successful, then we inspect the
00149  * sockaddr_in output parameter of connect(2) to determine the IP address
00150  * used to connect to them. This IP address is then copied into us.
00151  *
00152  * \param them The IP address to which we wish to attempt to connect
00153  * \param[out] us The source IP address used to connect to them
00154  * \retval -1 Failure
00155  * \retval 0 Success
00156  */
00157 int ast_ouraddrfor(struct in_addr *them, struct in_addr *us);
00158 
00159 /*!
00160  * \brief Find an IP address associated with a specific interface
00161  *
00162  * \details
00163  * Given an interface such as "eth0" we find the primary IP address
00164  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
00165  * should fail, we populate address with 0s.
00166  *
00167  * \note
00168  * This function is not actually used anywhere
00169  *
00170  * \param iface The interface name whose IP address we wish to find
00171  * \param[out] address The interface's IP address is placed into this param
00172  * \retval -1 Failure. address is filled with 0s
00173  * \retval 0 Success
00174  */
00175 int ast_lookup_iface(char *iface, struct in_addr *address);
00176 
00177 /*!
00178  * \brief Duplicate the contents of a list of host access rules
00179  *
00180  * \details
00181  * A deep copy of all ast_has in the list is made. The returned
00182  * value is allocated on the heap and must be freed independently
00183  * of the input parameter when finished.
00184  *
00185  * \note
00186  * This function is not actually used anywhere.
00187  *
00188  * \param original The ast_ha to copy
00189  * \retval The head of the list of duplicated ast_has
00190  */
00191 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
00192 
00193 /*!
00194  * \brief Find our IP address
00195  *
00196  * \details
00197  * This function goes through many iterations in an attempt to find
00198  * our IP address. If any step along the way should fail, we move to the
00199  * next item in the list. Here are the steps taken:
00200  * - If bindaddr has a non-zero IP address, that is copied into ourip
00201  * - We use a combination of gethostname and ast_gethostbyname to find our
00202  *   IP address.
00203  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
00204  * - We try some platform-specific socket operations to find the IP address
00205  *
00206  * \param[out] ourip Our IP address is written here when it is found
00207  * \param bindaddr A hint used for finding our IP. See the steps above for
00208  * more details
00209  * \retval 0 Success
00210  * \retval -1 Failure
00211  */
00212 int ast_find_ourip(struct in_addr *ourip, struct sockaddr_in bindaddr);
00213 
00214 /*!
00215  * \brief Convert a string to the appropriate TOS value
00216  *
00217  * \param value The TOS string to convert
00218  * \param[out] The integer representation of that TOS value
00219  * \retval -1 Failure
00220  * \retval 0 Success
00221  */
00222 int ast_str2tos(const char *value, unsigned int *tos);
00223 
00224 /*!
00225  * \brief Convert a TOS value into its string representation
00226  *
00227  * \param tos The TOS value to look up
00228  * \return The string equivalent of the TOS value
00229  */
00230 const char *ast_tos2str(unsigned int tos);
00231 
00232 #if defined(__cplusplus) || defined(c_plusplus)
00233 }
00234 #endif
00235 
00236 #endif /* _ASTERISK_ACL_H */

Generated on Sat Aug 6 00:39:19 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7