e39cf312d79291cd98b22946b595af9d911d61c5
[asterisk/asterisk.git] / include / asterisk / security_events_defs.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2009, Digium, Inc.
5  *
6  * Russell Bryant <russell@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 /*!
20  * \file
21  *
22  * \brief Security Event Reporting Data Structures
23  *
24  * \author Russell Bryant <russell@digium.com>
25  */
26
27 #ifndef __AST_SECURITY_EVENTS_DEFS_H__
28 #define __AST_SECURITY_EVENTS_DEFS_H__
29
30 #include "asterisk/network.h"
31
32 #if defined(__cplusplus) || defined(c_plusplus)
33 extern "C" {
34 #endif
35
36 /*!
37  * \brief Security event types
38  *
39  * AST_EVENT_SECURITY is the event type of an ast_event generated as a security
40  * event.  The event will have an information element of type
41  * AST_EVENT_IE_SECURITY_EVENT which identifies the security event sub-type.
42  * This enum defines the possible values for this sub-type.
43  */
44 enum ast_security_event_type {
45         /*!
46          * \brief Failed ACL
47          *
48          * This security event should be generated when an incoming request
49          * was made, but was denied due to configured IP address access control
50          * lists.
51          */
52         AST_SECURITY_EVENT_FAILED_ACL,
53         /*!
54          * \brief Invalid Account ID
55          *
56          * This event is used when an invalid account identifier is supplied
57          * during authentication.  For example, if an invalid username is given,
58          * this event should be used.
59          */
60         AST_SECURITY_EVENT_INVAL_ACCT_ID,
61         /*!
62          * \brief Session limit reached
63          *
64          * A request has been denied because a configured session limit has been
65          * reached, such as a call limit.
66          */
67         AST_SECURITY_EVENT_SESSION_LIMIT,
68         /*!
69          * \brief Memory limit reached
70          *
71          * A request has been denied because a configured memory limit has been
72          * reached.
73          */
74         AST_SECURITY_EVENT_MEM_LIMIT,
75         /*!
76          * \brief Load Average limit reached
77          *
78          * A request has been denied because a configured load average limit has been
79          * reached.
80          */
81         AST_SECURITY_EVENT_LOAD_AVG,
82         /*!
83          * \brief A request was made that we understand, but do not support
84          */
85         AST_SECURITY_EVENT_REQ_NO_SUPPORT,
86         /*!
87          * \brief A request was made that is not allowed
88          */
89         AST_SECURITY_EVENT_REQ_NOT_ALLOWED,
90         /*!
91          * \brief The attempted authentication method is not allowed
92          */
93         AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED,
94         /*!
95          * \brief Request received with bad formatting
96          */
97         AST_SECURITY_EVENT_REQ_BAD_FORMAT,
98         /*!
99          * \brief FYI FWIW, Successful authentication has occurred
100          */
101         AST_SECURITY_EVENT_SUCCESSFUL_AUTH,
102         /*!
103          * \brief An unexpected source address was seen for a session in progress
104          */
105         AST_SECURITY_EVENT_UNEXPECTED_ADDR,
106         /*!
107          * \brief An attempt at challenge/response authentication failed
108          */
109         AST_SECURITY_EVENT_CHAL_RESP_FAILED,
110         /*!
111          * \brief An attempt at basic password authentication failed
112          */
113         AST_SECURITY_EVENT_INVAL_PASSWORD,
114         /* \brief This _must_ stay at the end. */
115         AST_SECURITY_EVENT_NUM_TYPES
116 };
117
118 /*!
119  * \brief the severity of a security event
120  *
121  * This is defined as a bit field to make it easy for consumers of the API to
122  * subscribe to any combination of the defined severity levels.
123  *
124  * XXX \todo Do we need any more levels here?
125  */
126 enum ast_security_event_severity {
127         /*! \brief Informational event, not something that has gone wrong */
128         AST_SECURITY_EVENT_SEVERITY_INFO  = (1 << 0),
129         /*! \brief Something has gone wrong */
130         AST_SECURITY_EVENT_SEVERITY_ERROR = (1 << 1),
131 };
132
133 /*!
134  * \brief Transport types
135  */
136 enum ast_security_event_transport_type {
137         AST_SECURITY_EVENT_TRANSPORT_UDP,
138         AST_SECURITY_EVENT_TRANSPORT_TCP,
139         AST_SECURITY_EVENT_TRANSPORT_TLS,
140 };
141
142 #define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)
143
144 struct ast_security_event_ipv4_addr {
145         const struct sockaddr_in *sin;
146         enum ast_security_event_transport_type transport;
147 };
148
149 /*!
150  * \brief Common structure elements
151  *
152  * This is the structure header for all event descriptor structures defined
153  * below.  The contents of this structure are very important and must not
154  * change.  Even though these structures are exposed via a public API, we have
155  * a version field that can be used to ensure ABI safety.  If the event
156  * descriptors need to be changed or updated in the future, we can safely do
157  * so and can detect ABI changes at runtime.
158  */
159 struct ast_security_event_common {
160         /*! \brief The security event sub-type */
161         enum ast_security_event_type event_type;
162         /*! \brief security event version */
163         uint32_t version;
164         /*!
165          * \brief Service that generated the event
166          * \note Always required
167          *
168          * Examples: "SIP", "AMI"
169          */
170         const char *service;
171         /*!
172          * \brief Module, Normally the AST_MODULE define
173          * \note Always optional
174          */
175         const char *module;
176         /*!
177          * \brief Account ID, specific to the service type
178          * \note optional/required, depending on event type
179          */
180         const char *account_id;
181         /*!
182          * \brief Session ID, specific to the service type
183          * \note Always required
184          */
185         const char *session_id;
186         /*!
187          * \brief Session timeval, when the session started
188          * \note Always optional
189          */
190         const struct timeval *session_tv;
191         /*!
192          * \brief Local address the request came in on
193          * \note Always required
194          */
195         struct ast_security_event_ipv4_addr local_addr;
196         /*!
197          * \brief Remote address the request came from
198          * \note Always required
199          */
200         struct ast_security_event_ipv4_addr remote_addr;
201 };
202
203 /*!
204  * \brief Checking against an IP access control list failed
205  */
206 struct ast_security_event_failed_acl {
207         /*!
208          * \brief Event descriptor version
209          * \note This _must_ be changed if this event descriptor is changed.
210          */
211         #define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1
212         /*!
213          * \brief Common security event descriptor elements
214          * \note Account ID required
215          */
216         struct ast_security_event_common common;
217         /*!
218          * \brief ACL name, identifies which ACL was hit
219          * \note optional
220          */
221         const char *acl_name;
222 };
223
224 /*!
225  * \brief Invalid account ID specified (invalid username, for example)
226  */
227 struct ast_security_event_inval_acct_id {
228         /*!
229          * \brief Event descriptor version
230          * \note This _must_ be changed if this event descriptor is changed.
231          */
232         #define AST_SECURITY_EVENT_INVAL_ACCT_ID_VERSION 1
233         /*!
234          * \brief Common security event descriptor elements
235          * \note Account ID required
236          */
237         struct ast_security_event_common common;
238 };
239
240 /*!
241  * \brief Request denied because of a session limit
242  */
243 struct ast_security_event_session_limit {
244         /*!
245          * \brief Event descriptor version
246          * \note This _must_ be changed if this event descriptor is changed.
247          */
248         #define AST_SECURITY_EVENT_SESSION_LIMIT_VERSION 1
249         /*!
250          * \brief Common security event descriptor elements
251          * \note Account ID required
252          */
253         struct ast_security_event_common common;
254 };
255
256 /*!
257  * \brief Request denied because of a memory limit
258  */
259 struct ast_security_event_mem_limit {
260         /*!
261          * \brief Event descriptor version
262          * \note This _must_ be changed if this event descriptor is changed.
263          */
264         #define AST_SECURITY_EVENT_MEM_LIMIT_VERSION 1
265         /*!
266          * \brief Common security event descriptor elements
267          * \note Account ID required
268          */
269         struct ast_security_event_common common;
270 };
271
272 /*!
273  * \brief Request denied because of a load average limit
274  */
275 struct ast_security_event_load_avg {
276         /*!
277          * \brief Event descriptor version
278          * \note This _must_ be changed if this event descriptor is changed.
279          */
280         #define AST_SECURITY_EVENT_LOAD_AVG_VERSION 1
281         /*!
282          * \brief Common security event descriptor elements
283          * \note Account ID required
284          */
285         struct ast_security_event_common common;
286 };
287
288 /*!
289  * \brief Request denied because we don't support it
290  */
291 struct ast_security_event_req_no_support {
292         /*!
293          * \brief Event descriptor version
294          * \note This _must_ be changed if this event descriptor is changed.
295          */
296         #define AST_SECURITY_EVENT_REQ_NO_SUPPORT_VERSION 1
297         /*!
298          * \brief Common security event descriptor elements
299          * \note Account ID required
300          */
301         struct ast_security_event_common common;
302         /*!
303          * \brief Request type that was made
304          * \note required
305          */
306         const char *request_type;
307 };
308
309 /*!
310  * \brief Request denied because it's not allowed
311  */
312 struct ast_security_event_req_not_allowed {
313         /*!
314          * \brief Event descriptor version
315          * \note This _must_ be changed if this event descriptor is changed.
316          */
317         #define AST_SECURITY_EVENT_REQ_NOT_ALLOWED_VERSION 1
318         /*!
319          * \brief Common security event descriptor elements
320          * \note Account ID required
321          */
322         struct ast_security_event_common common;
323         /*!
324          * \brief Request type that was made
325          * \note required
326          */
327         const char *request_type;
328         /*!
329          * \brief Request type that was made
330          * \note optional
331          */
332         const char *request_params;
333 };
334
335 /*!
336  * \brief Auth method used not allowed
337  */
338 struct ast_security_event_auth_method_not_allowed {
339         /*!
340          * \brief Event descriptor version
341          * \note This _must_ be changed if this event descriptor is changed.
342          */
343         #define AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED_VERSION 1
344         /*!
345          * \brief Common security event descriptor elements
346          * \note Account ID required
347          */
348         struct ast_security_event_common common;
349         /*!
350          * \brief Auth method attempted
351          * \note required
352          */
353         const char *auth_method;
354 };
355
356 /*!
357  * \brief Invalid formatting of request
358  */
359 struct ast_security_event_req_bad_format {
360         /*!
361          * \brief Event descriptor version
362          * \note This _must_ be changed if this event descriptor is changed.
363          */
364         #define AST_SECURITY_EVENT_REQ_BAD_FORMAT_VERSION 1
365         /*!
366          * \brief Common security event descriptor elements
367          * \note Account ID optional
368          */
369         struct ast_security_event_common common;
370         /*!
371          * \brief Request type that was made
372          * \note required
373          */
374         const char *request_type;
375         /*!
376          * \brief Request type that was made
377          * \note optional
378          */
379         const char *request_params;
380 };
381
382 /*!
383  * \brief Successful authentication
384  */
385 struct ast_security_event_successful_auth {
386         /*!
387          * \brief Event descriptor version
388          * \note This _must_ be changed if this event descriptor is changed.
389          */
390         #define AST_SECURITY_EVENT_SUCCESSFUL_AUTH_VERSION 1
391         /*!
392          * \brief Common security event descriptor elements
393          * \note Account ID required
394          */
395         struct ast_security_event_common common;
396 };
397
398 /*!
399  * \brief Unexpected source address for a session in progress
400  */
401 struct ast_security_event_unexpected_addr {
402         /*!
403          * \brief Event descriptor version
404          * \note This _must_ be changed if this event descriptor is changed.
405          */
406         #define AST_SECURITY_EVENT_UNEXPECTED_ADDR_VERSION 1
407         /*!
408          * \brief Common security event descriptor elements
409          * \note Account ID required
410          */
411         struct ast_security_event_common common;
412         /*!
413          * \brief Expected remote address
414          * \note required
415          */
416         struct ast_security_event_ipv4_addr expected_addr;
417 };
418
419 /*!
420  * \brief An attempt at challenge/response auth failed
421  */
422 struct ast_security_event_chal_resp_failed {
423         /*!
424          * \brief Event descriptor version
425          * \note This _must_ be changed if this event descriptor is changed.
426          */
427         #define AST_SECURITY_EVENT_CHAL_RESP_FAILED_VERSION 1
428         /*!
429          * \brief Common security event descriptor elements
430          * \note Account ID required
431          */
432         struct ast_security_event_common common;
433         /*!
434          * \brief Challenge provided
435          * \note required
436          */
437         const char *challenge;
438         /*!
439          * \brief Response received
440          * \note required
441          */
442         const char *response;
443         /*!
444          * \brief Response expected to be received
445          * \note required
446          */
447         const char *expected_response;
448 };
449
450 /*!
451  * \brief An attempt at basic password auth failed
452  */
453 struct ast_security_event_inval_password {
454         /*!
455          * \brief Event descriptor version
456          * \note This _must_ be changed if this event descriptor is changed.
457          */
458         #define AST_SECURITY_EVENT_INVAL_PASSWORD_VERSION 1
459         /*!
460          * \brief Common security event descriptor elements
461          * \note Account ID required
462          */
463         struct ast_security_event_common common;
464 };
465
466 #if defined(__cplusplus) || defined(c_plusplus)
467 }
468 #endif
469
470 #endif /* __AST_SECURITY_EVENTS_DEFS_H__ */