Merged revisions 337595,337597 via svnmerge from
[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         /*!
115          * \brief Challenge was sent out, informational
116          */
117         AST_SECURITY_EVENT_CHAL_SENT,
118         /*!
119          * \brief An attempt to contact a peer on an invalid transport.
120          */
121         AST_SECURITY_EVENT_INVAL_TRANSPORT,
122         /*!
123          * \brief This _must_ stay at the end.
124          */
125         AST_SECURITY_EVENT_NUM_TYPES
126 };
127
128 /*!
129  * \brief the severity of a security event
130  *
131  * This is defined as a bit field to make it easy for consumers of the API to
132  * subscribe to any combination of the defined severity levels.
133  *
134  * XXX \todo Do we need any more levels here?
135  */
136 enum ast_security_event_severity {
137         /*! \brief Informational event, not something that has gone wrong */
138         AST_SECURITY_EVENT_SEVERITY_INFO  = (1 << 0),
139         /*! \brief Something has gone wrong */
140         AST_SECURITY_EVENT_SEVERITY_ERROR = (1 << 1),
141 };
142
143 /*!
144  * \brief Transport types
145  */
146 enum ast_security_event_transport_type {
147         AST_SECURITY_EVENT_TRANSPORT_UDP,
148         AST_SECURITY_EVENT_TRANSPORT_TCP,
149         AST_SECURITY_EVENT_TRANSPORT_TLS,
150 };
151
152 #define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)
153
154 struct ast_security_event_ipv4_addr {
155         const struct sockaddr_in *sin;
156         enum ast_security_event_transport_type transport;
157 };
158
159 /*!
160  * \brief Common structure elements
161  *
162  * This is the structure header for all event descriptor structures defined
163  * below.  The contents of this structure are very important and must not
164  * change.  Even though these structures are exposed via a public API, we have
165  * a version field that can be used to ensure ABI safety.  If the event
166  * descriptors need to be changed or updated in the future, we can safely do
167  * so and can detect ABI changes at runtime.
168  */
169 struct ast_security_event_common {
170         /*! \brief The security event sub-type */
171         enum ast_security_event_type event_type;
172         /*! \brief security event version */
173         uint32_t version;
174         /*!
175          * \brief Service that generated the event
176          * \note Always required
177          *
178          * Examples: "SIP", "AMI"
179          */
180         const char *service;
181         /*!
182          * \brief Module, Normally the AST_MODULE define
183          * \note Always optional
184          */
185         const char *module;
186         /*!
187          * \brief Account ID, specific to the service type
188          * \note optional/required, depending on event type
189          */
190         const char *account_id;
191         /*!
192          * \brief Session ID, specific to the service type
193          * \note Always required
194          */
195         const char *session_id;
196         /*!
197          * \brief Session timeval, when the session started
198          * \note Always optional
199          */
200         const struct timeval *session_tv;
201         /*!
202          * \brief Local address the request came in on
203          * \note Always required
204          */
205         struct ast_security_event_ipv4_addr local_addr;
206         /*!
207          * \brief Remote address the request came from
208          * \note Always required
209          */
210         struct ast_security_event_ipv4_addr remote_addr;
211 };
212
213 /*!
214  * \brief Checking against an IP access control list failed
215  */
216 struct ast_security_event_failed_acl {
217         /*!
218          * \brief Event descriptor version
219          * \note This _must_ be changed if this event descriptor is changed.
220          */
221         #define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1
222         /*!
223          * \brief Common security event descriptor elements
224          * \note Account ID required
225          */
226         struct ast_security_event_common common;
227         /*!
228          * \brief ACL name, identifies which ACL was hit
229          * \note optional
230          */
231         const char *acl_name;
232 };
233
234 /*!
235  * \brief Invalid account ID specified (invalid username, for example)
236  */
237 struct ast_security_event_inval_acct_id {
238         /*!
239          * \brief Event descriptor version
240          * \note This _must_ be changed if this event descriptor is changed.
241          */
242         #define AST_SECURITY_EVENT_INVAL_ACCT_ID_VERSION 1
243         /*!
244          * \brief Common security event descriptor elements
245          * \note Account ID required
246          */
247         struct ast_security_event_common common;
248 };
249
250 /*!
251  * \brief Request denied because of a session limit
252  */
253 struct ast_security_event_session_limit {
254         /*!
255          * \brief Event descriptor version
256          * \note This _must_ be changed if this event descriptor is changed.
257          */
258         #define AST_SECURITY_EVENT_SESSION_LIMIT_VERSION 1
259         /*!
260          * \brief Common security event descriptor elements
261          * \note Account ID required
262          */
263         struct ast_security_event_common common;
264 };
265
266 /*!
267  * \brief Request denied because of a memory limit
268  */
269 struct ast_security_event_mem_limit {
270         /*!
271          * \brief Event descriptor version
272          * \note This _must_ be changed if this event descriptor is changed.
273          */
274         #define AST_SECURITY_EVENT_MEM_LIMIT_VERSION 1
275         /*!
276          * \brief Common security event descriptor elements
277          * \note Account ID required
278          */
279         struct ast_security_event_common common;
280 };
281
282 /*!
283  * \brief Request denied because of a load average limit
284  */
285 struct ast_security_event_load_avg {
286         /*!
287          * \brief Event descriptor version
288          * \note This _must_ be changed if this event descriptor is changed.
289          */
290         #define AST_SECURITY_EVENT_LOAD_AVG_VERSION 1
291         /*!
292          * \brief Common security event descriptor elements
293          * \note Account ID required
294          */
295         struct ast_security_event_common common;
296 };
297
298 /*!
299  * \brief Request denied because we don't support it
300  */
301 struct ast_security_event_req_no_support {
302         /*!
303          * \brief Event descriptor version
304          * \note This _must_ be changed if this event descriptor is changed.
305          */
306         #define AST_SECURITY_EVENT_REQ_NO_SUPPORT_VERSION 1
307         /*!
308          * \brief Common security event descriptor elements
309          * \note Account ID required
310          */
311         struct ast_security_event_common common;
312         /*!
313          * \brief Request type that was made
314          * \note required
315          */
316         const char *request_type;
317 };
318
319 /*!
320  * \brief Request denied because it's not allowed
321  */
322 struct ast_security_event_req_not_allowed {
323         /*!
324          * \brief Event descriptor version
325          * \note This _must_ be changed if this event descriptor is changed.
326          */
327         #define AST_SECURITY_EVENT_REQ_NOT_ALLOWED_VERSION 1
328         /*!
329          * \brief Common security event descriptor elements
330          * \note Account ID required
331          */
332         struct ast_security_event_common common;
333         /*!
334          * \brief Request type that was made
335          * \note required
336          */
337         const char *request_type;
338         /*!
339          * \brief Request type that was made
340          * \note optional
341          */
342         const char *request_params;
343 };
344
345 /*!
346  * \brief Auth method used not allowed
347  */
348 struct ast_security_event_auth_method_not_allowed {
349         /*!
350          * \brief Event descriptor version
351          * \note This _must_ be changed if this event descriptor is changed.
352          */
353         #define AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED_VERSION 1
354         /*!
355          * \brief Common security event descriptor elements
356          * \note Account ID required
357          */
358         struct ast_security_event_common common;
359         /*!
360          * \brief Auth method attempted
361          * \note required
362          */
363         const char *auth_method;
364 };
365
366 /*!
367  * \brief Invalid formatting of request
368  */
369 struct ast_security_event_req_bad_format {
370         /*!
371          * \brief Event descriptor version
372          * \note This _must_ be changed if this event descriptor is changed.
373          */
374         #define AST_SECURITY_EVENT_REQ_BAD_FORMAT_VERSION 1
375         /*!
376          * \brief Common security event descriptor elements
377          * \note Account ID optional
378          */
379         struct ast_security_event_common common;
380         /*!
381          * \brief Request type that was made
382          * \note required
383          */
384         const char *request_type;
385         /*!
386          * \brief Request type that was made
387          * \note optional
388          */
389         const char *request_params;
390 };
391
392 /*!
393  * \brief Successful authentication
394  */
395 struct ast_security_event_successful_auth {
396         /*!
397          * \brief Event descriptor version
398          * \note This _must_ be changed if this event descriptor is changed.
399          */
400         #define AST_SECURITY_EVENT_SUCCESSFUL_AUTH_VERSION 1
401         /*!
402          * \brief Common security event descriptor elements
403          * \note Account ID required
404          */
405         struct ast_security_event_common common;
406         /*!
407          * \brief Using password - if a password was used or not
408          * \note required, 0 = no, 1 = yes
409          */
410         uint32_t *using_password;
411 };
412
413 /*!
414  * \brief Unexpected source address for a session in progress
415  */
416 struct ast_security_event_unexpected_addr {
417         /*!
418          * \brief Event descriptor version
419          * \note This _must_ be changed if this event descriptor is changed.
420          */
421         #define AST_SECURITY_EVENT_UNEXPECTED_ADDR_VERSION 1
422         /*!
423          * \brief Common security event descriptor elements
424          * \note Account ID required
425          */
426         struct ast_security_event_common common;
427         /*!
428          * \brief Expected remote address
429          * \note required
430          */
431         struct ast_security_event_ipv4_addr expected_addr;
432 };
433
434 /*!
435  * \brief An attempt at challenge/response auth failed
436  */
437 struct ast_security_event_chal_resp_failed {
438         /*!
439          * \brief Event descriptor version
440          * \note This _must_ be changed if this event descriptor is changed.
441          */
442         #define AST_SECURITY_EVENT_CHAL_RESP_FAILED_VERSION 1
443         /*!
444          * \brief Common security event descriptor elements
445          * \note Account ID required
446          */
447         struct ast_security_event_common common;
448         /*!
449          * \brief Challenge provided
450          * \note required
451          */
452         const char *challenge;
453         /*!
454          * \brief Response received
455          * \note required
456          */
457         const char *response;
458         /*!
459          * \brief Response expected to be received
460          * \note required
461          */
462         const char *expected_response;
463 };
464
465 /*!
466  * \brief An attempt at basic password auth failed
467  */
468 struct ast_security_event_inval_password {
469         /*!
470          * \brief Event descriptor version
471          * \note This _must_ be changed if this event descriptor is changed.
472          */
473         #define AST_SECURITY_EVENT_INVAL_PASSWORD_VERSION 2
474         /*!
475          * \brief Common security event descriptor elements
476          * \note Account ID required
477          */
478         struct ast_security_event_common common;
479         /*!
480          * \brief Challenge provided
481          * \note required
482          */
483         const char *challenge;
484         /*!
485          * \brief Challenge received
486          * \note required
487          */
488         const char *received_challenge;
489         /*!
490          * \brief Hash received
491          * \note required
492          */
493         const char *received_hash;
494 };
495
496 /*!
497  * \brief A challenge was sent out
498  */
499 struct ast_security_event_chal_sent {
500         /*!
501          * \brief Event descriptor version
502          * \note This _must_ be changed if this event descriptor is changed.
503          */
504         #define AST_SECURITY_EVENT_CHAL_SENT_VERSION 1
505         /*!
506          * \brief Common security event descriptor elements
507          * \note Account ID required
508          */
509         struct ast_security_event_common common;
510         /*!
511          * \brief Challenge sent
512          * \note required
513          */
514         const char *challenge;
515 };
516
517 /*!
518  * \brief Attempt to contact peer on invalid transport
519  */
520 struct ast_security_event_inval_transport {
521         /*!
522          * \brief Event descriptor version
523          * \note This _must_ be changed if this event descriptor is changed.
524          */
525         #define AST_SECURITY_EVENT_INVAL_TRANSPORT_VERSION 1
526         /*!
527          * \brief Common security event descriptor elements
528          * \note Account ID required
529          */
530         struct ast_security_event_common common;
531         /*!
532          * \brief Attempted transport
533          * \note required
534          */
535         const char *transport;
536 };
537
538 #if defined(__cplusplus) || defined(c_plusplus)
539 }
540 #endif
541
542 #endif /* __AST_SECURITY_EVENTS_DEFS_H__ */