Asterisk - The Open Source Telephony Project GIT-master-d856a3e
acl.h
Go to the documentation of this file.
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)
28extern "C" {
29#endif
30
31#include "asterisk/network.h"
33#include "asterisk/netsock2.h"
34#include "asterisk/io.h"
35
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 */
51struct ast_ha {
52 /* Host access rule */
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 */
67struct 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. */
73};
74
75/*! \brief Wrapper for an ast_acl linked list. */
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 */
87void 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 */
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 */
112void 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 */
133struct 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 */
156struct 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 */
163void 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 */
170void 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 */
190void 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 */
199int 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 */
216enum 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 */
234enum 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 */
248enum 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 */
266int 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 */
288int 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 */
304int 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 */
322int 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 */
335struct 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 */
349struct 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 */
372int 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 */
382int 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 */
392int 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 */
400const 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 */
417struct 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 */
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 */
445void 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 */
461void 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 */
int ast_lookup_iface(char *iface, struct ast_sockaddr *address)
Find an IP address associated with a specific interface.
enum ast_acl_sense ast_apply_acl(struct ast_acl_list *acl_list, const struct ast_sockaddr *addr, const char *purpose)
Apply a set of rules to a given IP address.
Definition: acl.c:799
void ast_free_ha(struct ast_ha *ha)
Free a list of HAs.
Definition: acl.c:222
int ast_str2tos(const char *value, unsigned int *tos)
Convert a string to the appropriate TOS value.
Definition: acl.c:966
struct stasis_message_type * ast_named_acl_change_type(void)
a stasis_message_type for changes against a named ACL or the set of all named ACLs
void ast_acl_output(int fd, struct ast_acl_list *acl, const char *prefix)
output an ACL to the provided fd
Definition: acl.c:1098
void ast_ha_output(int fd, const struct ast_ha *ha, const char *prefix)
output an HA to the provided fd
Definition: acl.c:1086
struct ast_ha * ast_duplicate_ha_list(struct ast_ha *original)
Duplicate the contents of a list of host access rules.
Definition: acl.c:276
void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to)
Copy the contents of one HA to another.
Definition: acl.c:255
int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us)
Get our local IP address when contacting a remote host.
Definition: acl.c:1004
void ast_append_acl(const char *sense, const char *stuff, struct ast_acl_list **path, int *error, int *named_acl_flag)
Add a rule to an ACL struct.
Definition: acl.c:429
int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr, int family)
Find our IP address.
Definition: acl.c:1051
ast_acl_sense
Definition: acl.h:36
@ AST_SENSE_ALLOW
Definition: acl.h:38
@ AST_SENSE_DENY
Definition: acl.h:37
int ast_get_ip(struct ast_sockaddr *addr, const char *hostname)
Get the IP address given a hostname.
Definition: acl.c:999
struct ast_ha * ast_named_acl_find(const char *name, int *is_realtime, int *is_undefined)
Retrieve a named ACL.
Definition: named_acl.c:293
enum ast_acl_sense ast_apply_acl_nolog(struct ast_acl_list *acl_list, const struct ast_sockaddr *addr)
Apply a set of rules to a given IP address, don't log failure.
Definition: acl.c:803
const char * ast_tos2str(unsigned int tos)
Convert a TOS value into its string representation.
Definition: acl.c:986
enum ast_acl_sense ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr)
Apply a set of rules to a given IP address.
Definition: acl.c:807
int ast_acl_list_is_empty(struct ast_acl_list *acl_list)
Determines if an ACL is empty or if it contains entries.
Definition: acl.c:540
void ast_ha_join(const struct ast_ha *ha, struct ast_str **buf)
Convert HAs to a comma separated string value.
Definition: acl.c:722
struct ast_ha * ast_append_ha_with_port(const char *sense, const char *stuff, struct ast_ha *path, int *error)
Add a new rule with optional port to a list of HAs.
Definition: acl.c:717
#define ACL_NAME_LENGTH
Definition: acl.h:59
int ast_str2cos(const char *value, unsigned int *cos)
Convert a string to the appropriate COS value.
Definition: acl.c:952
struct ast_acl_list * ast_free_acl_list(struct ast_acl_list *acl)
Free a list of ACLs.
Definition: acl.c:233
struct ast_acl_list * ast_duplicate_acl_list(struct ast_acl_list *original)
Duplicates the contests of a list of lists of host access rules.
Definition: acl.c:315
void ast_ha_join_cidr(const struct ast_ha *ha, struct ast_str **buf)
Convert HAs to a comma separated string value using CIDR notation.
Definition: acl.c:744
struct ast_ha * ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error)
Add a new rule to a list of HAs.
Definition: acl.c:712
int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *hostname, const char *service)
Get the IP address given a hostname and optional service.
Definition: acl.c:896
enum ast_cc_service_type service
Definition: ccss.c:383
unsigned int tos
Definition: chan_iax2.c:355
unsigned int cos
Definition: chan_iax2.c:356
struct ast_sockaddr bindaddr
Definition: chan_ooh323.c:353
char buf[BUFSIZE]
Definition: eagi_proxy.c:66
char * address
Definition: f2c.h:59
static const char name[]
Definition: format_mp3.c:68
static char prefix[MAX_PREFIX]
Definition: http.c:144
I/O Management (derived from Cheops-NG)
A set of macros to manage forward-linked lists.
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:410
#define AST_LIST_HEAD(name, type)
Defines a structure to be used to hold a list of specified type.
Definition: linkedlists.h:173
static char hostname[MAXHOSTNAMELEN]
Definition: logger.c:119
Network socket handling.
Wrapper for network related headers, masking differences between various operating systems....
Definition: test_acl.c:111
Wrapper for an ast_acl linked list.
Definition: acl.h:76
an ast_acl is a linked list node of ast_ha structs which may have names.
Definition: acl.h:67
struct ast_ha * acl
Definition: acl.h:68
int is_invalid
Definition: acl.h:70
struct ast_acl::@180 list
int is_realtime
Definition: acl.h:69
char name[ACL_NAME_LENGTH]
Definition: acl.h:71
internal representation of ACL entries In principle user applications would have no need for this,...
Definition: acl.h:51
struct ast_sockaddr addr
Definition: acl.h:53
struct ast_sockaddr netmask
Definition: acl.h:54
struct ast_ha * next
Definition: acl.h:56
enum ast_acl_sense sense
Definition: acl.h:55
Socket address structure.
Definition: netsock2.h:97
Support for dynamic strings.
Definition: strings.h:623
int value
Definition: syslog.c:37
int error(const char *format,...)
Definition: utils/frame.c:999