acl.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 1999 - 2012, 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/linkedlists.h"
00033 #include "asterisk/netsock2.h"
00034 #include "asterisk/io.h"
00035 
00036 enum ast_acl_sense {
00037    AST_SENSE_DENY,
00038    AST_SENSE_ALLOW
00039 };
00040 
00041 /* Host based access control */
00042 
00043 /*! \brief internal representation of ACL entries
00044  * In principle user applications would have no need for this,
00045  * but there is sometimes a need to extract individual items,
00046  * e.g. to print them, and rather than defining iterators to
00047  * navigate the list, and an externally visible 'struct ast_ha_entry',
00048  * at least in the short term it is more convenient to make the whole
00049  * thing public and let users play with them.
00050  */
00051 struct ast_ha {
00052    /* Host access rule */
00053    struct ast_sockaddr addr;
00054    struct ast_sockaddr netmask;
00055    enum ast_acl_sense sense;
00056    struct ast_ha *next;
00057 };
00058 
00059 #define ACL_NAME_LENGTH 80
00060 
00061 /*!
00062  * \brief an ast_acl is a linked list node of ast_ha structs which may have names.
00063  *
00064  * \note These shouldn't be used directly by ACL consumers. Consumers should handle
00065  *       ACLs via ast_acl_list structs.
00066  */
00067 struct ast_acl {
00068    struct ast_ha *acl;             /*!< Rules contained by the ACL */
00069    int is_realtime;                /*!< If raised, this named ACL was retrieved from realtime storage */
00070    int is_invalid;                 /*!< If raised, this is an invalid ACL which will automatically reject everything. */
00071    char name[ACL_NAME_LENGTH];     /*!< If this was retrieved from the named ACL subsystem, this is the name of the ACL. */
00072    AST_LIST_ENTRY(ast_acl) list;
00073 };
00074 
00075 /*! \brief Wrapper for an ast_acl linked list. */
00076 AST_LIST_HEAD(ast_acl_list, ast_acl);
00077 
00078 /*!
00079  * \brief Free a list of HAs
00080  *
00081  * \details
00082  * Given the head of a list of HAs, it and all appended
00083  * HAs are freed
00084  *
00085  * \param ha The head of the list of HAs to free
00086  * \retval void
00087  */
00088 void ast_free_ha(struct ast_ha *ha);
00089 
00090 /*!
00091  * \brief Free a list of ACLs
00092  *
00093  * \details
00094  * Given the head of a list of ast_acl structs, it and all appended
00095  * acl structs will be freed. This includes the ast_ha structs within
00096  * the individual nodes.
00097  * \param acl The list of ACLs to free
00098  * \retval NULL
00099  */
00100 struct ast_acl_list *ast_free_acl_list(struct ast_acl_list *acl);
00101 
00102 /*!
00103  * \brief Copy the contents of one HA to another
00104  *
00105  * \details
00106  * This copies the internals of the 'from' HA to the 'to'
00107  * HA. It is important that the 'to' HA has been allocated
00108  * prior to calling this function
00109  *
00110  * \param from Source HA to copy
00111  * \param to Destination HA to copy to
00112  * \retval void
00113  */
00114 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
00115 
00116 /*!
00117  * \brief Add a new rule to a list of HAs
00118  *
00119  * \details
00120  * This adds the new host access rule to the end of the list
00121  * whose head is specified by the path parameter. Rules are
00122  * evaluated in a way such that if multiple rules apply to
00123  * a single IP address/subnet mask, then the rule latest
00124  * in the list will be used.
00125  *
00126  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
00127  * in permission, and any other word will result in denial)
00128  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
00129  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
00130  * \param path The head of the HA list to which we wish to append our new rule. If
00131  * NULL is passed, then the new rule will become the head of the list
00132  * \param[out] error The integer error points to will be set non-zero if an error occurs
00133  * \return The head of the HA list
00134  */
00135 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
00136 
00137 /*!
00138  * \brief Convert HAs to a comma separated string value
00139  * \param ha the starting ha head
00140  * \param buf string buffer to convert data to
00141  */
00142 void ast_ha_join(const struct ast_ha *ha, struct ast_str **buf);
00143 
00144 /*!
00145  * \brief Convert HAs to a comma separated string value using CIDR notation
00146  * \param ha the starting ha head
00147  * \param buf string buffer to convert data to
00148  */
00149 void ast_ha_join_cidr(const struct ast_ha *ha, struct ast_str **buf);
00150 
00151 /*!
00152  * \brief Add a rule to an ACL struct
00153  *
00154  * \details
00155  * This adds a named ACL or an ACL rule to an ast_acl container.
00156  * It works in a similar way to ast_append_ha.
00157  *
00158  * \param sense Can be any among "permit", "deny", or "acl"
00159  *        this controls whether the rule being added will simply modify the unnamed ACL at the head of the list
00160  *        or if a new named ACL will be added to that ast_acl.
00161  * \param stuff If sense is 'permit'/'deny', this is the ip address and subnet mask separated with a '/' like in ast_append ha.
00162  *        If it sense is 'acl', then this will be the name of the ACL being appended to the container.
00163  * \param path Address of the ACL list being appended
00164  * \param[out] error The int that error points to will be set to 1 if an error occurs.
00165  * \param[out] named_acl_flag This will raise a flag under certain conditions to indicate that a named ACL has been added by this
00166  *        operation. This may be used to indicate that an event subscription should be made against the named ACL subsystem.
00167  *        Note: This flag may be raised by this function, but it will never be lowered by it.
00168  */
00169 void ast_append_acl(const char *sense, const char *stuff, struct ast_acl_list **path, int *error, int *named_acl_flag);
00170 
00171 /*!
00172  * \brief Determines if an ACL is empty or if it contains entries
00173  *
00174  * \param acl_list The ACL list being checked
00175  * \retval 0 - the list is not empty
00176  * \retval 1 - the list is empty
00177  */
00178 int ast_acl_list_is_empty(struct ast_acl_list *acl_list);
00179 
00180 /*!
00181  * \brief Apply a set of rules to a given IP address
00182  *
00183  * \details
00184  * The list of host access rules is traversed, beginning with the
00185  * input rule. If the IP address given matches a rule, the "sense"
00186  * of that rule is used as the return value. Note that if an IP
00187  * address matches multiple rules that the last one matched will be
00188  * the one whose sense will be returned.
00189  *
00190  * \param ha The head of the list of host access rules to follow
00191  * \param addr An ast_sockaddr whose address is considered when matching rules
00192  * \retval AST_SENSE_ALLOW The IP address passes our ACL
00193  * \retval AST_SENSE_DENY The IP address fails our ACL
00194  */
00195 enum ast_acl_sense ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr);
00196 
00197 /*!
00198  * \brief Apply a set of rules to a given IP address
00199  *
00200  * \details
00201  * Similar to the above, only uses an acl container, which is a whole slew
00202  * of ast_ha lists. It runs ast_apply_ha on each of the ast_ha structs
00203  * contained in the acl container. It will deny if any of the ast_ha lists
00204  * fail, and it will pass only if all of the rules pass.
00205  *
00206  * \param acl_list The head of the list of ACLs to evaluate
00207  * \param addr An ast_sockaddr whose address is considered when matching rules
00208  * \param purpose Context for which the ACL is being applied - Establishes purpose of a notice when rejected
00209  *
00210  * \retval AST_SENSE_ALLOW The IP address passes our ACLs
00211  * \retval AST_SENSE_DENY The IP address fails our ACLs
00212  */
00213 enum ast_acl_sense ast_apply_acl(struct ast_acl_list *acl_list, const struct ast_sockaddr *addr, const char *purpose);
00214 
00215 /*!
00216  * \brief Get the IP address given a hostname
00217  *
00218  * \details
00219  * Similar in nature to ast_gethostbyname, except that instead
00220  * of getting an entire hostent structure, you instead are given
00221  * only the IP address inserted into a ast_sockaddr structure.
00222  *
00223  * \param addr The IP address found.  The address family is used
00224  * as an input parameter to filter the returned addresses.  If
00225  * it is AST_AF_UNSPEC, both IPv4 and IPv6 addresses can be returned.
00226  * \param hostname The hostname to look up
00227  *
00228  * \retval 0 Success
00229  * \retval -1 Failure
00230  */
00231 int ast_get_ip(struct ast_sockaddr *addr, const char *hostname);
00232 
00233 /*!
00234  * \brief Get the IP address given a hostname and optional service
00235  *
00236  * \details
00237  * If the service parameter is non-NULL, then an SRV lookup will be made by
00238  * prepending the service to the hostname parameter, separated by a '.'
00239  * For example, if hostname is "example.com" and service is "_sip._udp" then
00240  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
00241  * then this function acts exactly like a call to ast_get_ip.
00242  *
00243  * \param addr The IP address found.  The address family is used
00244  * as an input parameter to filter the returned addresses.  If
00245  * it is 0, both IPv4 and IPv6 addresses can be returned.
00246  *
00247  * \param hostname The hostname to look up
00248  * \param service A specific service provided by the host. A NULL service results
00249  * in an A-record lookup instead of an SRV lookup
00250  * \retval 0 Success
00251  * \retval -1 Failure
00252  */
00253 int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *hostname, const char *service);
00254 
00255 /*!
00256  * \brief Get our local IP address when contacting a remote host
00257  *
00258  * \details
00259  * This function will attempt to connect(2) to them over UDP using a source
00260  * port of 5060. If the connect(2) call is successful, then we inspect the
00261  * sockaddr_in output parameter of connect(2) to determine the IP address
00262  * used to connect to them. This IP address is then copied into us.
00263  *
00264  * \param them The IP address to which we wish to attempt to connect
00265  * \param[out] us The source IP address used to connect to them
00266  * \retval -1 Failure
00267  * \retval 0 Success
00268  */
00269 int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
00270 
00271 /*!
00272  * \brief Find an IP address associated with a specific interface
00273  *
00274  * \details
00275  * Given an interface such as "eth0" we find the primary IP address
00276  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
00277  * should fail, we populate address with 0s.
00278  *
00279  * \note
00280  * This function is not actually used anywhere
00281  *
00282  * \param iface The interface name whose IP address we wish to find
00283  * \param[out] address The interface's IP address is placed into this param
00284  * \retval -1 Failure. address is filled with 0s
00285  * \retval 0 Success
00286  */
00287 int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
00288 
00289 /*!
00290  * \brief Duplicate the contents of a list of host access rules
00291  *
00292  * \details
00293  * A deep copy of all ast_has in the list is made. The returned
00294  * value is allocated on the heap and must be freed independently
00295  * of the input parameter when finished.
00296  *
00297  * \param original The ast_ha to copy
00298  * \retval The head of the list of duplicated ast_has
00299  */
00300 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
00301 
00302 /*!
00303  * \brief Duplicates the contests of a list of lists of host access rules.
00304  *
00305  * \details
00306  * A deep copy of an ast_acl list is made (which in turn means a deep copy of
00307  * each of the ast_ha structs contained within). The returned value is allocated
00308  * on the heap and must be freed independently of the input paramater when
00309  * finished.
00310  *
00311  * \param original The ast_acl_list to copy
00312  * \retval The new duplicated ast_acl_list
00313  */
00314 struct ast_acl_list *ast_duplicate_acl_list(struct ast_acl_list *original);
00315 
00316 /*!
00317  * \brief Find our IP address
00318  *
00319  * \details
00320  * This function goes through many iterations in an attempt to find
00321  * our IP address. If any step along the way should fail, we move to the
00322  * next item in the list. Here are the steps taken:
00323  * - If bindaddr has a non-zero IP address, that is copied into ourip
00324  * - We use a combination of gethostname and ast_gethostbyname to find our
00325  *   IP address.
00326  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
00327  * - We try some platform-specific socket operations to find the IP address
00328  *
00329  * \param[out] ourip Our IP address is written here when it is found
00330  * \param bindaddr A hint used for finding our IP. See the steps above for
00331  * more details
00332  * \param family Only addresses of the given family will be returned. Use 0
00333  * or AST_SOCKADDR_UNSPEC to get addresses of all families.
00334  * \retval 0 Success
00335  * \retval -1 Failure
00336  */
00337 int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr, int family);
00338 
00339 /*!
00340  * \brief Convert a string to the appropriate COS value
00341  *
00342  * \param value The COS string to convert
00343  * \param[out] cos The integer representation of that COS value
00344  * \retval -1 Failure
00345  * \retval 0 Success
00346  */
00347 int ast_str2cos(const char *value, unsigned int *cos);
00348 
00349 /*!
00350  * \brief Convert a string to the appropriate TOS value
00351  *
00352  * \param value The TOS string to convert
00353  * \param[out] tos The integer representation of that TOS value
00354  * \retval -1 Failure
00355  * \retval 0 Success
00356  */
00357 int ast_str2tos(const char *value, unsigned int *tos);
00358 
00359 /*!
00360  * \brief Convert a TOS value into its string representation
00361  *
00362  * \param tos The TOS value to look up
00363  * \return The string equivalent of the TOS value
00364  */
00365 const char *ast_tos2str(unsigned int tos);
00366 
00367 /*!
00368  * \brief Retrieve a named ACL
00369  *
00370  * \details
00371  * This function attempts to find a named ACL. If found, a copy
00372  * of the requested ACL will be made which must be freed by
00373  * the caller.
00374  *
00375  * \param name Name of the ACL sought
00376  * \param[out] is_realtime will be true if the ACL being returned is from realtime
00377  * \param[out] is_undefined will be true if no ACL profile can be found for the requested name
00378  *
00379  * \retval A copy of the named ACL as an ast_ha
00380  * \retval NULL if no ACL could be found.
00381  */
00382 struct ast_ha *ast_named_acl_find(const char *name, int *is_realtime, int *is_undefined);
00383 
00384 /*!
00385  * \brief Initialize and configure the named ACL system.
00386  *
00387  * \details
00388  * This function will prepare the named ACL system for use.
00389  * For this reason, it needs to be called before other things that use ACLs are initialized.
00390  */
00391 int ast_named_acl_init(void);
00392 
00393 /*!
00394  * \brief reload/reconfigure the named ACL system.
00395  *
00396  * \details
00397  * This function is designed to trigger an event upon a successful reload that may update
00398  * ACL consumers.
00399  */
00400 int ast_named_acl_reload(void);
00401 
00402 /*!
00403  * \brief a \ref stasis_message_type for changes against a named ACL or the set of all named ACLs
00404  * \since 12
00405  *
00406  * \retval NULL on error
00407  * \retval \ref stasis_message_type for named ACL changes
00408  *
00409  * \note Messages of this type should always be issued on and expected from the
00410  *       \ref ast_security_topic \ref stasis_topic
00411  */
00412 struct stasis_message_type *ast_named_acl_change_type(void);
00413 
00414 #if defined(__cplusplus) || defined(c_plusplus)
00415 }
00416 #endif
00417 
00418 #endif /* _ASTERISK_ACL_H */

Generated on Thu Apr 16 06:27:05 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6