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 */