Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


security_events_defs.h
Go to the documentation of this file.
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  */
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  */
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  */
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  */
68  /*!
69  * \brief Memory limit reached
70  *
71  * A request has been denied because a configured memory limit has been
72  * reached.
73  */
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  */
82  /*!
83  * \brief A request was made that we understand, but do not support
84  */
86  /*!
87  * \brief A request was made that is not allowed
88  */
90  /*!
91  * \brief The attempted authentication method is not allowed
92  */
94  /*!
95  * \brief Request received with bad formatting
96  */
98  /*!
99  * \brief FYI FWIW, Successful authentication has occurred
100  */
102  /*!
103  * \brief An unexpected source address was seen for a session in progress
104  */
106  /*!
107  * \brief An attempt at challenge/response authentication failed
108  */
110  /*!
111  * \brief An attempt at basic password authentication failed
112  */
114  /* \brief This _must_ stay at the end. */
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  */
127  /*! \brief Informational event, not something that has gone wrong */
129  /*! \brief Something has gone wrong */
131 };
132 
133 /*!
134  * \brief Transport types
135  */
140 };
141 
142 #define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)
143 
145  const struct sockaddr_in *sin;
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  */
160  /*! \brief The security event sub-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  */
196  /*!
197  * \brief Remote address the request came from
198  * \note Always required
199  */
201 };
202 
203 /*!
204  * \brief Checking against an IP access control list failed
205  */
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  */
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  */
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  */
238 };
239 
240 /*!
241  * \brief Request denied because of a session limit
242  */
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  */
254 };
255 
256 /*!
257  * \brief Request denied because of a memory limit
258  */
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  */
270 };
271 
272 /*!
273  * \brief Request denied because of a load average limit
274  */
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  */
286 };
287 
288 /*!
289  * \brief Request denied because we don't support it
290  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
396 };
397 
398 /*!
399  * \brief Unexpected source address for a session in progress
400  */
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  */
412  /*!
413  * \brief Expected remote address
414  * \note required
415  */
417 };
418 
419 /*!
420  * \brief An attempt at challenge/response auth failed
421  */
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  */
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  */
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  */
464 };
465 
466 #if defined(__cplusplus) || defined(c_plusplus)
467 }
468 #endif
469 
470 #endif /* __AST_SECURITY_EVENTS_DEFS_H__ */
ast_security_event_severity
the severity of a security event
An attempt at basic password authentication failed.
struct ast_security_event_common common
Common security event descriptor elements.
enum ast_security_event_type event_type
The security event sub-type.
ast_security_event_type
Security event types.
const char * auth_method
Auth method attempted.
FYI FWIW, Successful authentication has occurred.
struct ast_security_event_ipv4_addr remote_addr
Remote address the request came from.
const char * expected_response
Response expected to be received.
An attempt at challenge/response auth failed.
const char * service
Service that generated the event.
const char * account_id
Account ID, specific to the service type.
const char * module
Module, Normally the AST_MODULE define.
ast_security_event_transport_type
Transport types.
Request denied because we don&#39;t support it.
Checking against an IP access control list failed.
const char * challenge
Challenge provided.
struct ast_security_event_common common
Common security event descriptor elements.
const char * request_type
Request type that was made.
The attempted authentication method is not allowed.
const char * response
Response received.
Unexpected source address for a session in progress.
Common structure elements.
struct ast_security_event_common common
Common security event descriptor elements.
A request was made that is not allowed.
struct ast_security_event_common common
Common security event descriptor elements.
An unexpected source address was seen for a session in progress.
struct ast_security_event_common common
Common security event descriptor elements.
uint32_t version
security event version
struct ast_security_event_ipv4_addr local_addr
Local address the request came in on.
Informational event, not something that has gone wrong.
enum ast_security_event_transport_type transport
An attempt at basic password auth failed.
const char * request_type
Request type that was made.
Request received with bad formatting.
Request denied because of a session limit.
const char * session_id
Session ID, specific to the service type.
const char * request_params
Request type that was made.
struct ast_security_event_common common
Common security event descriptor elements.
struct ast_security_event_common common
Common security event descriptor elements.
Wrapper for network related headers, masking differences between various operating systems...
struct ast_security_event_common common
Common security event descriptor elements.
Request denied because of a memory limit.
struct ast_security_event_common common
Common security event descriptor elements.
struct timeval * session_tv
Session timeval, when the session started.
Load Average limit reached.
Request denied because of a load average limit.
An attempt at challenge/response authentication failed.
const char * acl_name
ACL name, identifies which ACL was hit.
struct ast_security_event_common common
Common security event descriptor elements.
struct ast_security_event_common common
Common security event descriptor elements.
Invalid account ID specified (invalid username, for example)
struct ast_security_event_common common
Common security event descriptor elements.
struct ast_security_event_common common
Common security event descriptor elements.
Invalid formatting of request.
const char * request_params
Request type that was made.
struct ast_security_event_ipv4_addr expected_addr
Expected remote address.
Request denied because it&#39;s not allowed.
const char * request_type
Request type that was made.
A request was made that we understand, but do not support.