Make ACLs IPv6-capable.
[asterisk/asterisk.git] / include / asterisk / acl.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, 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/netsock2.h"
33 #include "asterisk/io.h"
34
35 #define AST_SENSE_DENY                  0
36 #define AST_SENSE_ALLOW                 1
37
38 /* Host based access control */
39
40 /*! \brief internal representation of acl entries
41  * In principle user applications would have no need for this,
42  * but there is sometimes a need to extract individual items,
43  * e.g. to print them, and rather than defining iterators to
44  * navigate the list, and an externally visible 'struct ast_ha_entry',
45  * at least in the short term it is more convenient to make the whole
46  * thing public and let users play with them.
47  */
48 struct ast_ha {
49         /* Host access rule */
50         struct ast_sockaddr addr;
51         struct ast_sockaddr netmask;
52         int sense;
53         struct ast_ha *next;
54 };
55
56 /*!
57  * \brief Free a list of HAs
58  *
59  * \details
60  * Given the head of a list of HAs, it and all appended
61  * HAs are freed
62  *
63  * \param ha The head of the list of HAs to free
64  * \retval void
65  */
66 void ast_free_ha(struct ast_ha *ha);
67
68 /*!
69  * \brief Copy the contents of one HA to another
70  *
71  * \details
72  * This copies the internals of the 'from' HA to the 'to'
73  * HA. It is important that the 'to' HA has been allocated
74  * prior to calling this function
75  *
76  * \param from Source HA to copy
77  * \param to Destination HA to copy to
78  * \retval void
79  */
80 void ast_copy_ha(const struct ast_ha *from, struct ast_ha *to);
81
82 /*!
83  * \brief Add a new rule to a list of HAs
84  *
85  * \details
86  * This adds the new host access rule to the end of the list
87  * whose head is specified by the path parameter. Rules are
88  * evaluated in a way such that if multiple rules apply to
89  * a single IP address/subnet mask, then the rule latest
90  * in the list will be used.
91  *
92  * \param sense Either "permit" or "deny" (Actually any 'p' word will result
93  * in permission, and any other word will result in denial)
94  * \param stuff The IP address and subnet mask, separated with a '/'. The subnet
95  * mask can either be in dotted-decimal format or in CIDR notation (i.e. 0-32).
96  * \param path The head of the HA list to which we wish to append our new rule. If
97  * NULL is passed, then the new rule will become the head of the list
98  * \param[out] error The integer error points to will be set non-zero if an error occurs
99  * \return The head of the HA list
100  */
101 struct ast_ha *ast_append_ha(const char *sense, const char *stuff, struct ast_ha *path, int *error);
102
103 /*!
104  * \brief Apply a set of rules to a given IP address
105  *
106  * \details
107  * The list of host access rules is traversed, beginning with the
108  * input rule. If the IP address given matches a rule, the "sense"
109  * of that rule is used as the return value. Note that if an IP
110  * address matches multiple rules that the last one matched will be
111  * the one whose sense will be returned.
112  *
113  * \param ha The head of the list of host access rules to follow
114  * \param addr An ast_sockaddr whose address is considered when matching rules
115  * \retval AST_SENSE_ALLOW The IP address passes our ACL
116  * \retval AST_SENSE_DENY The IP address fails our ACL
117  */
118 int ast_apply_ha(const struct ast_ha *ha, const struct ast_sockaddr *addr);
119
120 /*!
121  * \brief Get the IP address given a hostname
122  *
123  * \details
124  * Similar in nature to ast_gethostbyname, except that instead
125  * of getting an entire hostent structure, you instead are given
126  * only the IP address inserted into a sockaddr_in structure.
127  *
128  * \param[out] addr The IP address is written into sin->sin_addr
129  * \param value The hostname to look up
130  * \retval 0 Success
131  * \retval -1 Failure
132  */
133 int ast_get_ip(struct ast_sockaddr *addr, const char *value);
134
135 /*!
136  * \brief Get the IP address given a hostname and optional service
137  *
138  * \details
139  * If the service parameter is non-NULL, then an SRV lookup will be made by
140  * prepending the service to the value parameter, separated by a '.'
141  * For example, if value is "example.com" and service is "_sip._udp" then
142  * an SRV lookup will be done for "_sip._udp.example.com". If service is NULL,
143  * then this function acts exactly like a call to ast_get_ip.
144  *
145  * \param addr The IP address found.  The address family is used as an input parameter to
146  * filter the returned adresses. if it is 0, both IPv4 and IPv6 addresses
147  * can be returned.
148  *
149  * \param value The hostname to look up
150  * \param service A specific service provided by the host. A NULL service results
151  * in an A-record lookup instead of an SRV lookup
152  * \retval 0 Success
153  * \retval -1 Failure
154  */
155 int ast_get_ip_or_srv(struct ast_sockaddr *addr, const char *value, const char *service);
156
157 /*!
158  * \brief Get our local IP address when contacting a remote host
159  *
160  * \details
161  * This function will attempt to connect(2) to them over UDP using a source
162  * port of 5060. If the connect(2) call is successful, then we inspect the
163  * sockaddr_in output parameter of connect(2) to determine the IP address
164  * used to connect to them. This IP address is then copied into us.
165  *
166  * \param them The IP address to which we wish to attempt to connect
167  * \param[out] us The source IP address used to connect to them
168  * \retval -1 Failure
169  * \retval 0 Success
170  */
171 int ast_ouraddrfor(const struct ast_sockaddr *them, struct ast_sockaddr *us);
172
173 /*!
174  * \brief Find an IP address associated with a specific interface
175  *
176  * \details
177  * Given an interface such as "eth0" we find the primary IP address
178  * associated with it using the SIOCGIFADDR ioctl. If the ioctl call
179  * should fail, we populate address with 0s.
180  *
181  * \note
182  * This function is not actually used anywhere
183  *
184  * \param iface The interface name whose IP address we wish to find
185  * \param[out] address The interface's IP address is placed into this param
186  * \retval -1 Failure. address is filled with 0s
187  * \retval 0 Success
188  */
189 int ast_lookup_iface(char *iface, struct ast_sockaddr *address);
190
191 /*!
192  * \brief Duplicate the contents of a list of host access rules
193  *
194  * \details
195  * A deep copy of all ast_has in the list is made. The returned
196  * value is allocated on the heap and must be freed independently
197  * of the input parameter when finished.
198  *
199  * \note
200  * This function is not actually used anywhere.
201  *
202  * \param original The ast_ha to copy
203  * \retval The head of the list of duplicated ast_has
204  */
205 struct ast_ha *ast_duplicate_ha_list(struct ast_ha *original);
206
207 /*!
208  * \brief Find our IP address
209  *
210  * \details
211  * This function goes through many iterations in an attempt to find
212  * our IP address. If any step along the way should fail, we move to the
213  * next item in the list. Here are the steps taken:
214  * - If bindaddr has a non-zero IP address, that is copied into ourip
215  * - We use a combination of gethostname and ast_gethostbyname to find our
216  *   IP address.
217  * - We use ast_ouraddrfor with 198.41.0.4 as the destination IP address
218  * - We try some platform-specific socket operations to find the IP address
219  *
220  * \param[out] ourip Our IP address is written here when it is found
221  * \param bindaddr A hint used for finding our IP. See the steps above for
222  * more details
223  * \retval 0 Success
224  * \retval -1 Failure
225  */
226 int ast_find_ourip(struct ast_sockaddr *ourip, const struct ast_sockaddr *bindaddr);
227
228 /*!
229  * \brief Convert a string to the appropriate COS value
230  *
231  * \param value The COS string to convert
232  * \param[out] cos The integer representation of that COS value
233  * \retval -1 Failure
234  * \retval 0 Success
235  */
236 int ast_str2cos(const char *value, unsigned int *cos);
237
238 /*!
239  * \brief Convert a string to the appropriate TOS value
240  *
241  * \param value The TOS string to convert
242  * \param[out] tos The integer representation of that TOS value
243  * \retval -1 Failure
244  * \retval 0 Success
245  */
246 int ast_str2tos(const char *value, unsigned int *tos);
247
248 /*!
249  * \brief Convert a TOS value into its string representation
250  *
251  * \param tos The TOS value to look up
252  * \return The string equivalent of the TOS value
253  */
254 const char *ast_tos2str(unsigned int tos);
255
256 #if defined(__cplusplus) || defined(c_plusplus)
257 }
258 #endif
259
260 #endif /* _ASTERISK_ACL_H */