include/asterisk/acl.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2012, 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/linkedlists.h"
  33 #include "asterisk/netsock2.h"
  34 #include "asterisk/io.h"
  35
  36 enum ast_acl_sense {
  37         AST_SENSE_DENY,
  38         AST_SENSE_ALLOW
  39 };
  40
  41 /* Host based access control */
  42
  43 /*! \brief internal representation of ACL entries
  44  * In principle user applications would have no need for this,
  45  * but there is sometimes a need to extract individual items,
  46  * e.g. to print them, and rather than defining iterators to
  47  * navigate the list, and an externally visible 'struct ast_ha_entry',
  48  * at least in the short term it is more convenient to make the whole
  49  * thing public and let users play with them.
  50  */
  51 struct ast_ha {
  52         /* Host access rule */
  53         struct ast_sockaddr addr;
  54         struct ast_sockaddr netmask;
  55         enum ast_acl_sense sense;
  56         struct ast_ha *next;
  57 };
  58
  59 #define ACL_NAME_LENGTH 80
  60
  61 /*!
  62  * \brief an ast_acl is a linked list node of ast_ha structs which may have names.
  63  *
  64  * \note These shouldn't be used directly by ACL consumers. Consumers should handle
  65  *       ACLs via ast_acl_list structs.
  66  */
  67 struct ast_acl {
  68         struct ast_ha *acl;             /*!< Rules contained by the ACL */
  69         int is_realtime;                /*!< If raised, this named ACL was retrieved from realtime storage */
  70         int is_invalid;                 /*!< If raised, this is an invalid ACL which will automatically reject everything. */
  71         char name[ACL_NAME_LENGTH];     /*!< If this was retrieved from the named ACL subsystem, this is the name of the ACL. */
  72         AST_LIST_ENTRY(ast_acl) list;
  73 };
  74
  75 /*! \brief Wrapper for an ast_acl linked list. */
  76 AST_LIST_HEAD(ast_acl_list, ast_acl);
  77
  78 /*!
  79  * \brief Free a list of HAs
  80  *
  81  * \details
  82  * Given the head of a list of HAs, it and all appended
  83  * HAs are freed
  84  *
  85  * \param ha The head of the list of HAs to free
  86  */
  87 void ast_free_ha(struct ast_ha *ha);
  88
  89 /*!
  90  * \brief Free a list of ACLs
  91  *
  92  * \details
  93  * Given the head of a list of ast_acl structs, it and all appended
  94  * acl structs will be freed. This includes the ast_ha structs within
  95  * the individual nodes.
  96  * \param acl The list of ACLs to free
  97  * \retval NULL
  98  */
  99 struct ast_acl_list *ast_free_acl_list(struct ast_acl_list *acl);
 100
 101 /*!
 102  * \brief Copy the contents of one HA to another
 103  *
 104  * \details
 105  * This copies the internals of the 'from' HA to the 'to'
 106  * HA. It is important that the 'to' HA has been allocated
 107  * prior to calling this function
 108  *
 109  * \param from Source HA to copy
 110  * \param to Destination HA to copy to
 111  */
 112 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
 113
 114 /*!
 115  * \brief Add a new rule to a list of HAs
 116  *
 117  * \details
 118  * This adds the new host access rule to the end of the list
 119  * whose head is specified by the path parameter. Rules are
 120  * evaluated in a way such that if multiple rules apply to
 121  * a single IP address/subnet mask, then the rule latest
 122  * in the list will be used.
 123  *
 124  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
 125  * in permission, and any other word will result in denial)
 126  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
 127  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
 128  * \param path The head of the HA list to which we wish to append our new rule. If
 129  * NULL is passed, then the new rule will become the head of the list
 130  * \param[out] error The integer error points to will be set non-zero if an error occurs
 131  * \return The head of the HA list
 132  */
 133 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
 134
 135 /*!
 136  * \brief Add a new rule with optional port to a list of HAs
 137  * \since 13.31.0, 16.8.0, 17.2.0
 138  *
 139  * \details
 140  * This adds the new host access rule to the end of the list
 141  * whose head is specified by the path parameter. Rules are
 142  * evaluated in a way such that if multiple rules apply to
 143  * a single IP address/subnet mask, then the rule latest
 144  * in the list will be used.
 145  *
 146  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
 147  * in permission, and any other word will result in denial)
 148  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
 149  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32). A
 150  * port can be provided by placing it after the IP address, separated with a ':'.
 151  * \param path The head of the HA list to which we wish to append our new rule. If
 152  * NULL is passed, then the new rule will become the head of the list
 153  * \param[out] error The integer error points to will be set non-zero if an error occurs
 154  * \return The head of the HA list
 155  */
 156 struct ast_ha *ast_append_ha_with_port(const char *sense, const char *stuff, struct ast_ha *path, int *error);
 157
 158 /*!
 159  * \brief Convert HAs to a comma separated string value
 160  * \param ha the starting ha head
 161  * \param buf string buffer to convert data to
 162  */
 163 void ast_ha_join(const struct ast_ha *ha, struct ast_str **buf);
 164
 165 /*!
 166  * \brief Convert HAs to a comma separated string value using CIDR notation
 167  * \param ha the starting ha head
 168  * \param buf string buffer to convert data to
 169  */
 170 void ast_ha_join_cidr(const struct ast_ha *ha, struct ast_str **buf);
 171
 172 /*!
 173  * \brief Add a rule to an ACL struct
 174  *
 175  * \details
 176  * This adds a named ACL or an ACL rule to an ast_acl container.
 177  * It works in a similar way to ast_append_ha.
 178  *
 179  * \param sense Can be any among "permit", "deny", or "acl"
 180  *        this controls whether the rule being added will simply modify the unnamed ACL at the head of the list
 181  *        or if a new named ACL will be added to that ast_acl.
 182  * \param stuff If sense is 'permit'/'deny', this is the ip address and subnet mask separated with a '/' like in ast_append ha.
 183  *        If it sense is 'acl', then this will be the name of the ACL being appended to the container.
 184  * \param path Address of the ACL list being appended
 185  * \param[out] error The int that error points to will be set to 1 if an error occurs.
 186  * \param[out] named_acl_flag This will raise a flag under certain conditions to indicate that a named ACL has been added by this
 187  *        operation. This may be used to indicate that an event subscription should be made against the named ACL subsystem.
 188  *        Note: This flag may be raised by this function, but it will never be lowered by it.
 189  */
 190 void ast_append_acl(const char *sense, const char *stuff, struct ast_acl_list **path, int *error, int *named_acl_flag);
 191
 192 /*!
 193  * \brief Determines if an ACL is empty or if it contains entries
 194  *
 195  * \param acl_list The ACL list being checked
 196  * \retval 0 the list is not empty
 197  * \retval 1 the list is empty
 198  */
 199 int ast_acl_list_is_empty(struct ast_acl_list *acl_list);
 200
 201 /*!
 202  * \brief Apply a set of rules to a given IP address
 203  *
 204  * \details
 205  * The list of host access rules is traversed, beginning with the
 206  * input rule. If the IP address given matches a rule, the "sense"
 207  * of that rule is used as the return value. Note that if an IP
 208  * address matches multiple rules that the last one matched will be
 209  * the one whose sense will be returned.
 210  *
 211  * \param ha The head of the list of host access rules to follow
 212  * \param addr An ast_sockaddr whose address is considered when matching rules
 213  * \retval AST_SENSE_ALLOW The IP address passes our ACL
 214  * \retval AST_SENSE_DENY The IP address fails our ACL
 215  */
 216 enum ast_acl_sense ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr);
 217
 218 /*!
 219  * \brief Apply a set of rules to a given IP address
 220  *
 221  * \details
 222  * Similar to the above, only uses an acl container, which is a whole slew
 223  * of ast_ha lists. It runs ast_apply_ha on each of the ast_ha structs
 224  * contained in the acl container. It will deny if any of the ast_ha lists
 225  * fail, and it will pass only if all of the rules pass.
 226  *
 227  * \param acl_list The head of the list of ACLs to evaluate
 228  * \param addr An ast_sockaddr whose address is considered when matching rules
 229  * \param purpose Context for which the ACL is being applied - Establishes purpose of a notice when rejected
 230  *
 231  * \retval AST_SENSE_ALLOW The IP address passes our ACLs
 232  * \retval AST_SENSE_DENY The IP address fails our ACLs
 233  */
 234 enum ast_acl_sense ast_apply_acl(struct ast_acl_list *acl_list, const struct ast_sockaddr *addr, const char *purpose);
 235
 236 /*!
 237  * \brief Apply a set of rules to a given IP address, don't log failure.
 238  *
 239  * \details
 240  * Exactly like ast_apply_acl, except that it will never log anything.
 241  *
 242  * \param acl_list The head of the list of ACLs to evaluate
 243  * \param addr An ast_sockaddr whose address is considered when matching rules
 244  *
 245  * \retval AST_SENSE_ALLOW The IP address passes our ACLs
 246  * \retval AST_SENSE_DENY The IP address fails our ACLs
 247  */
 248 enum ast_acl_sense ast_apply_acl_nolog(struct ast_acl_list *acl_list, const struct ast_sockaddr *addr);
 249
 250 /*!
 251  * \brief Get the IP address given a hostname
 252  *
 253  * \details
 254  * Similar in nature to ast_gethostbyname, except that instead
 255  * of getting an entire hostent structure, you instead are given
 256  * only the IP address inserted into a ast_sockaddr structure.
 257  *
 258  * \param addr The IP address found.  The address family is used
 259  * as an input parameter to filter the returned addresses.  If
 260  * it is AST_AF_UNSPEC, both IPv4 and IPv6 addresses can be returned.
 261  * \param hostname The hostname to look up
 262  *
 263  * \retval 0 Success
 264  * \retval -1 Failure
 265  */
 266 int ast_get_ip(struct ast_sockaddr *addr, const char *hostname);
 267
 268 /*!
 269  * \brief Get the IP address given a hostname and optional service
 270  *
 271  * \details
 272  * If the service parameter is non-NULL, then an SRV lookup will be made by
 273  * prepending the service to the hostname parameter, separated by a '.'
 274  * For example, if hostname is "example.com" and service is "_sip._udp" then
 275  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
 276  * then this function acts exactly like a call to ast_get_ip.
 277  *
 278  * \param addr The IP address found.  The address family is used
 279  * as an input parameter to filter the returned addresses.  If
 280  * it is 0, both IPv4 and IPv6 addresses can be returned.
 281  *
 282  * \param hostname The hostname to look up
 283  * \param service A specific service provided by the host. A NULL service results
 284  * in an A-record lookup instead of an SRV lookup
 285  * \retval 0 Success
 286  * \retval -1 Failure
 287  */
 288 int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *hostname, const char *service);
 289
 290 /*!
 291  * \brief Get our local IP address when contacting a remote host
 292  *
 293  * \details
 294  * This function will attempt to connect(2) to them over UDP using a source
 295  * port of 5060. If the connect(2) call is successful, then we inspect the
 296  * sockaddr_in output parameter of connect(2) to determine the IP address
 297  * used to connect to them. This IP address is then copied into us.
 298  *
 299  * \param them The IP address to which we wish to attempt to connect
 300  * \param[out] us The source IP address used to connect to them
 301  * \retval -1 Failure
 302  * \retval 0 Success
 303  */
 304 int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
 305
 306 /*!
 307  * \brief Find an IP address associated with a specific interface
 308  *
 309  * \details
 310  * Given an interface such as "eth0" we find the primary IP address
 311  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
 312  * should fail, we populate address with 0s.
 313  *
 314  * \note
 315  * This function is not actually used anywhere
 316  *
 317  * \param iface The interface name whose IP address we wish to find
 318  * \param[out] address The interface's IP address is placed into this param
 319  * \retval -1 Failure, address is filled with 0s
 320  * \retval 0 Success
 321  */
 322 int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
 323
 324 /*!
 325  * \brief Duplicate the contents of a list of host access rules
 326  *
 327  * \details
 328  * A deep copy of all ast_has in the list is made. The returned
 329  * value is allocated on the heap and must be freed independently
 330  * of the input parameter when finished.
 331  *
 332  * \param original The ast_ha to copy
 333  * \return The head of the list of duplicated ast_has
 334  */
 335 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
 336
 337 /*!
 338  * \brief Duplicates the contests of a list of lists of host access rules.
 339  *
 340  * \details
 341  * A deep copy of an ast_acl list is made (which in turn means a deep copy of
 342  * each of the ast_ha structs contained within). The returned value is allocated
 343  * on the heap and must be freed independently of the input paramater when
 344  * finished.
 345  *
 346  * \param original The ast_acl_list to copy
 347  * \return The new duplicated ast_acl_list
 348  */
 349 struct ast_acl_list *ast_duplicate_acl_list(struct ast_acl_list *original);
 350
 351 /*!
 352  * \brief Find our IP address
 353  *
 354  * \details
 355  * This function goes through many iterations in an attempt to find
 356  * our IP address. If any step along the way should fail, we move to the
 357  * next item in the list. Here are the steps taken:
 358  * - If bindaddr has a non-zero IP address, that is copied into ourip
 359  * - We use a combination of gethostname and ast_gethostbyname to find our
 360  *   IP address.
 361  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
 362  * - We try some platform-specific socket operations to find the IP address
 363  *
 364  * \param[out] ourip Our IP address is written here when it is found
 365  * \param bindaddr A hint used for finding our IP. See the steps above for
 366  * more details
 367  * \param family Only addresses of the given family will be returned. Use 0
 368  * or AST_SOCKADDR_UNSPEC to get addresses of all families.
 369  * \retval 0 Success
 370  * \retval -1 Failure
 371  */
 372 int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr, int family);
 373
 374 /*!
 375  * \brief Convert a string to the appropriate COS value
 376  *
 377  * \param value The COS string to convert
 378  * \param[out] cos The integer representation of that COS value
 379  * \retval -1 Failure
 380  * \retval 0 Success
 381  */
 382 int ast_str2cos(const char *value, unsigned int *cos);
 383
 384 /*!
 385  * \brief Convert a string to the appropriate TOS value
 386  *
 387  * \param value The TOS string to convert
 388  * \param[out] tos The integer representation of that TOS value
 389  * \retval -1 Failure
 390  * \retval 0 Success
 391  */
 392 int ast_str2tos(const char *value, unsigned int *tos);
 393
 394 /*!
 395  * \brief Convert a TOS value into its string representation
 396  *
 397  * \param tos The TOS value to look up
 398  * \return The string equivalent of the TOS value
 399  */
 400 const char *ast_tos2str(unsigned int tos);
 401
 402 /*!
 403  * \brief Retrieve a named ACL
 404  *
 405  * \details
 406  * This function attempts to find a named ACL. If found, a copy
 407  * of the requested ACL will be made which must be freed by
 408  * the caller.
 409  *
 410  * \param name Name of the ACL sought
 411  * \param[out] is_realtime will be true if the ACL being returned is from realtime
 412  * \param[out] is_undefined will be true if no ACL profile can be found for the requested name
 413  *
 414  * \return A copy of the named ACL as an ast_ha
 415  * \retval NULL if no ACL could be found.
 416  */
 417 struct ast_ha *ast_named_acl_find(const char *name, int *is_realtime, int *is_undefined);
 418
 419 /*!
 420  * \brief a \ref stasis_message_type for changes against a named ACL or the set of all named ACLs
 421  * \since 12
 422  *
 423  * \retval NULL on error
 424  * \return \ref stasis_message_type for named ACL changes
 425  *
 426  * \note Messages of this type should always be issued on and expected from the
 427  *       \ref ast_security_topic \ref stasis_topic
 428  */
 429 struct stasis_message_type *ast_named_acl_change_type(void);
 430
 431 /*!
 432  * \brief output an HA to the provided fd
 433  *
 434  * \details
 435  * This function can be used centrally to output HAs as used in ACLs from other
 436  * modules.  It follows the format as originally used for named ACLs in
 437  * named_acl.c.
 438  *
 439  * \param fd The file-descriptor to which to output the HA.
 440  * \param ha The HA to output.
 441  * \param prefix If you need a specific prefix output on each line, give it here, may be NULL.
 442  *
 443  * \since 13.33.0, 16.10.0, 17.4.0
 444  */
 445 void ast_ha_output(int fd, const struct ast_ha *ha, const char *prefix);
 446
 447 /*!
 448  * \brief output an ACL to the provided fd
 449  *
 450  * \details
 451  * This function can be used centrally to output HAs as used in ACLs from other
 452  * modules.  It follows the format as originally used for named ACLs in
 453  * named_acl.c.
 454  *
 455  * \param fd The file-descriptor to which to output the ACL.
 456  * \param acl The ACL to output.
 457  * \param prefix If you need a specific prefix output on each line, give it here, may be NULL.
 458  *
 459  * \since 13.33.0, 16.10.0, 17.4.0
 460  */
 461 void ast_acl_output(int fd, struct ast_acl_list *acl, const char *prefix);
 462
 463 #if defined(__cplusplus) || defined(c_plusplus)
 464 }
 465 #endif
 466
 467 #endif /* _ASTERISK_ACL_H */