res_pjsip_transport_websocket: save the original contact host
[asterisk/asterisk.git] / 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 */