00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 2009, Digium, Inc. 00005 * 00006 * Russell Bryant <russell@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 /*! 00020 * \file 00021 * 00022 * \brief Security Event Reporting Data Structures 00023 * 00024 * \author Russell Bryant <russell@digium.com> 00025 */ 00026 00027 #ifndef __AST_SECURITY_EVENTS_DEFS_H__ 00028 #define __AST_SECURITY_EVENTS_DEFS_H__ 00029 00030 #include "asterisk/network.h" 00031 00032 #if defined(__cplusplus) || defined(c_plusplus) 00033 extern "C" { 00034 #endif 00035 00036 /*! 00037 * \brief Security event types 00038 * 00039 * AST_EVENT_SECURITY is the event type of an ast_event generated as a security 00040 * event. The event will have an information element of type 00041 * AST_EVENT_IE_SECURITY_EVENT which identifies the security event sub-type. 00042 * This enum defines the possible values for this sub-type. 00043 */ 00044 enum ast_security_event_type { 00045 /*! 00046 * \brief Failed ACL 00047 * 00048 * This security event should be generated when an incoming request 00049 * was made, but was denied due to configured IP address access control 00050 * lists. 00051 */ 00052 AST_SECURITY_EVENT_FAILED_ACL, 00053 /*! 00054 * \brief Invalid Account ID 00055 * 00056 * This event is used when an invalid account identifier is supplied 00057 * during authentication. For example, if an invalid username is given, 00058 * this event should be used. 00059 */ 00060 AST_SECURITY_EVENT_INVAL_ACCT_ID, 00061 /*! 00062 * \brief Session limit reached 00063 * 00064 * A request has been denied because a configured session limit has been 00065 * reached, such as a call limit. 00066 */ 00067 AST_SECURITY_EVENT_SESSION_LIMIT, 00068 /*! 00069 * \brief Memory limit reached 00070 * 00071 * A request has been denied because a configured memory limit has been 00072 * reached. 00073 */ 00074 AST_SECURITY_EVENT_MEM_LIMIT, 00075 /*! 00076 * \brief Load Average limit reached 00077 * 00078 * A request has been denied because a configured load average limit has been 00079 * reached. 00080 */ 00081 AST_SECURITY_EVENT_LOAD_AVG, 00082 /*! 00083 * \brief A request was made that we understand, but do not support 00084 */ 00085 AST_SECURITY_EVENT_REQ_NO_SUPPORT, 00086 /*! 00087 * \brief A request was made that is not allowed 00088 */ 00089 AST_SECURITY_EVENT_REQ_NOT_ALLOWED, 00090 /*! 00091 * \brief The attempted authentication method is not allowed 00092 */ 00093 AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED, 00094 /*! 00095 * \brief Request received with bad formatting 00096 */ 00097 AST_SECURITY_EVENT_REQ_BAD_FORMAT, 00098 /*! 00099 * \brief FYI FWIW, Successful authentication has occurred 00100 */ 00101 AST_SECURITY_EVENT_SUCCESSFUL_AUTH, 00102 /*! 00103 * \brief An unexpected source address was seen for a session in progress 00104 */ 00105 AST_SECURITY_EVENT_UNEXPECTED_ADDR, 00106 /*! 00107 * \brief An attempt at challenge/response authentication failed 00108 */ 00109 AST_SECURITY_EVENT_CHAL_RESP_FAILED, 00110 /*! 00111 * \brief An attempt at basic password authentication failed 00112 */ 00113 AST_SECURITY_EVENT_INVAL_PASSWORD, 00114 /* \brief This _must_ stay at the end. */ 00115 AST_SECURITY_EVENT_NUM_TYPES 00116 }; 00117 00118 /*! 00119 * \brief the severity of a security event 00120 * 00121 * This is defined as a bit field to make it easy for consumers of the API to 00122 * subscribe to any combination of the defined severity levels. 00123 * 00124 * XXX \todo Do we need any more levels here? 00125 */ 00126 enum ast_security_event_severity { 00127 /*! \brief Informational event, not something that has gone wrong */ 00128 AST_SECURITY_EVENT_SEVERITY_INFO = (1 << 0), 00129 /*! \brief Something has gone wrong */ 00130 AST_SECURITY_EVENT_SEVERITY_ERROR = (1 << 1), 00131 }; 00132 00133 /*! 00134 * \brief Transport types 00135 */ 00136 enum ast_security_event_transport_type { 00137 AST_SECURITY_EVENT_TRANSPORT_UDP, 00138 AST_SECURITY_EVENT_TRANSPORT_TCP, 00139 AST_SECURITY_EVENT_TRANSPORT_TLS, 00140 }; 00141 00142 #define AST_SEC_EVT(e) ((struct ast_security_event_common *) e) 00143 00144 struct ast_security_event_ipv4_addr { 00145 const struct sockaddr_in *sin; 00146 enum ast_security_event_transport_type transport; 00147 }; 00148 00149 /*! 00150 * \brief Common structure elements 00151 * 00152 * This is the structure header for all event descriptor structures defined 00153 * below. The contents of this structure are very important and must not 00154 * change. Even though these structures are exposed via a public API, we have 00155 * a version field that can be used to ensure ABI safety. If the event 00156 * descriptors need to be changed or updated in the future, we can safely do 00157 * so and can detect ABI changes at runtime. 00158 */ 00159 struct ast_security_event_common { 00160 /*! \brief The security event sub-type */ 00161 enum ast_security_event_type event_type; 00162 /*! \brief security event version */ 00163 uint32_t version; 00164 /*! 00165 * \brief Service that generated the event 00166 * \note Always required 00167 * 00168 * Examples: "SIP", "AMI" 00169 */ 00170 const char *service; 00171 /*! 00172 * \brief Module, Normally the AST_MODULE define 00173 * \note Always optional 00174 */ 00175 const char *module; 00176 /*! 00177 * \brief Account ID, specific to the service type 00178 * \note optional/required, depending on event type 00179 */ 00180 const char *account_id; 00181 /*! 00182 * \brief Session ID, specific to the service type 00183 * \note Always required 00184 */ 00185 const char *session_id; 00186 /*! 00187 * \brief Session timeval, when the session started 00188 * \note Always optional 00189 */ 00190 const struct timeval *session_tv; 00191 /*! 00192 * \brief Local address the request came in on 00193 * \note Always required 00194 */ 00195 struct ast_security_event_ipv4_addr local_addr; 00196 /*! 00197 * \brief Remote address the request came from 00198 * \note Always required 00199 */ 00200 struct ast_security_event_ipv4_addr remote_addr; 00201 }; 00202 00203 /*! 00204 * \brief Checking against an IP access control list failed 00205 */ 00206 struct ast_security_event_failed_acl { 00207 /*! 00208 * \brief Event descriptor version 00209 * \note This _must_ be changed if this event descriptor is changed. 00210 */ 00211 #define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1 00212 /*! 00213 * \brief Common security event descriptor elements 00214 * \note Account ID required 00215 */ 00216 struct ast_security_event_common common; 00217 /*! 00218 * \brief ACL name, identifies which ACL was hit 00219 * \note optional 00220 */ 00221 const char *acl_name; 00222 }; 00223 00224 /*! 00225 * \brief Invalid account ID specified (invalid username, for example) 00226 */ 00227 struct ast_security_event_inval_acct_id { 00228 /*! 00229 * \brief Event descriptor version 00230 * \note This _must_ be changed if this event descriptor is changed. 00231 */ 00232 #define AST_SECURITY_EVENT_INVAL_ACCT_ID_VERSION 1 00233 /*! 00234 * \brief Common security event descriptor elements 00235 * \note Account ID required 00236 */ 00237 struct ast_security_event_common common; 00238 }; 00239 00240 /*! 00241 * \brief Request denied because of a session limit 00242 */ 00243 struct ast_security_event_session_limit { 00244 /*! 00245 * \brief Event descriptor version 00246 * \note This _must_ be changed if this event descriptor is changed. 00247 */ 00248 #define AST_SECURITY_EVENT_SESSION_LIMIT_VERSION 1 00249 /*! 00250 * \brief Common security event descriptor elements 00251 * \note Account ID required 00252 */ 00253 struct ast_security_event_common common; 00254 }; 00255 00256 /*! 00257 * \brief Request denied because of a memory limit 00258 */ 00259 struct ast_security_event_mem_limit { 00260 /*! 00261 * \brief Event descriptor version 00262 * \note This _must_ be changed if this event descriptor is changed. 00263 */ 00264 #define AST_SECURITY_EVENT_MEM_LIMIT_VERSION 1 00265 /*! 00266 * \brief Common security event descriptor elements 00267 * \note Account ID required 00268 */ 00269 struct ast_security_event_common common; 00270 }; 00271 00272 /*! 00273 * \brief Request denied because of a load average limit 00274 */ 00275 struct ast_security_event_load_avg { 00276 /*! 00277 * \brief Event descriptor version 00278 * \note This _must_ be changed if this event descriptor is changed. 00279 */ 00280 #define AST_SECURITY_EVENT_LOAD_AVG_VERSION 1 00281 /*! 00282 * \brief Common security event descriptor elements 00283 * \note Account ID required 00284 */ 00285 struct ast_security_event_common common; 00286 }; 00287 00288 /*! 00289 * \brief Request denied because we don't support it 00290 */ 00291 struct ast_security_event_req_no_support { 00292 /*! 00293 * \brief Event descriptor version 00294 * \note This _must_ be changed if this event descriptor is changed. 00295 */ 00296 #define AST_SECURITY_EVENT_REQ_NO_SUPPORT_VERSION 1 00297 /*! 00298 * \brief Common security event descriptor elements 00299 * \note Account ID required 00300 */ 00301 struct ast_security_event_common common; 00302 /*! 00303 * \brief Request type that was made 00304 * \note required 00305 */ 00306 const char *request_type; 00307 }; 00308 00309 /*! 00310 * \brief Request denied because it's not allowed 00311 */ 00312 struct ast_security_event_req_not_allowed { 00313 /*! 00314 * \brief Event descriptor version 00315 * \note This _must_ be changed if this event descriptor is changed. 00316 */ 00317 #define AST_SECURITY_EVENT_REQ_NOT_ALLOWED_VERSION 1 00318 /*! 00319 * \brief Common security event descriptor elements 00320 * \note Account ID required 00321 */ 00322 struct ast_security_event_common common; 00323 /*! 00324 * \brief Request type that was made 00325 * \note required 00326 */ 00327 const char *request_type; 00328 /*! 00329 * \brief Request type that was made 00330 * \note optional 00331 */ 00332 const char *request_params; 00333 }; 00334 00335 /*! 00336 * \brief Auth method used not allowed 00337 */ 00338 struct ast_security_event_auth_method_not_allowed { 00339 /*! 00340 * \brief Event descriptor version 00341 * \note This _must_ be changed if this event descriptor is changed. 00342 */ 00343 #define AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED_VERSION 1 00344 /*! 00345 * \brief Common security event descriptor elements 00346 * \note Account ID required 00347 */ 00348 struct ast_security_event_common common; 00349 /*! 00350 * \brief Auth method attempted 00351 * \note required 00352 */ 00353 const char *auth_method; 00354 }; 00355 00356 /*! 00357 * \brief Invalid formatting of request 00358 */ 00359 struct ast_security_event_req_bad_format { 00360 /*! 00361 * \brief Event descriptor version 00362 * \note This _must_ be changed if this event descriptor is changed. 00363 */ 00364 #define AST_SECURITY_EVENT_REQ_BAD_FORMAT_VERSION 1 00365 /*! 00366 * \brief Common security event descriptor elements 00367 * \note Account ID optional 00368 */ 00369 struct ast_security_event_common common; 00370 /*! 00371 * \brief Request type that was made 00372 * \note required 00373 */ 00374 const char *request_type; 00375 /*! 00376 * \brief Request type that was made 00377 * \note optional 00378 */ 00379 const char *request_params; 00380 }; 00381 00382 /*! 00383 * \brief Successful authentication 00384 */ 00385 struct ast_security_event_successful_auth { 00386 /*! 00387 * \brief Event descriptor version 00388 * \note This _must_ be changed if this event descriptor is changed. 00389 */ 00390 #define AST_SECURITY_EVENT_SUCCESSFUL_AUTH_VERSION 1 00391 /*! 00392 * \brief Common security event descriptor elements 00393 * \note Account ID required 00394 */ 00395 struct ast_security_event_common common; 00396 }; 00397 00398 /*! 00399 * \brief Unexpected source address for a session in progress 00400 */ 00401 struct ast_security_event_unexpected_addr { 00402 /*! 00403 * \brief Event descriptor version 00404 * \note This _must_ be changed if this event descriptor is changed. 00405 */ 00406 #define AST_SECURITY_EVENT_UNEXPECTED_ADDR_VERSION 1 00407 /*! 00408 * \brief Common security event descriptor elements 00409 * \note Account ID required 00410 */ 00411 struct ast_security_event_common common; 00412 /*! 00413 * \brief Expected remote address 00414 * \note required 00415 */ 00416 struct ast_security_event_ipv4_addr expected_addr; 00417 }; 00418 00419 /*! 00420 * \brief An attempt at challenge/response auth failed 00421 */ 00422 struct ast_security_event_chal_resp_failed { 00423 /*! 00424 * \brief Event descriptor version 00425 * \note This _must_ be changed if this event descriptor is changed. 00426 */ 00427 #define AST_SECURITY_EVENT_CHAL_RESP_FAILED_VERSION 1 00428 /*! 00429 * \brief Common security event descriptor elements 00430 * \note Account ID required 00431 */ 00432 struct ast_security_event_common common; 00433 /*! 00434 * \brief Challenge provided 00435 * \note required 00436 */ 00437 const char *challenge; 00438 /*! 00439 * \brief Response received 00440 * \note required 00441 */ 00442 const char *response; 00443 /*! 00444 * \brief Response expected to be received 00445 * \note required 00446 */ 00447 const char *expected_response; 00448 }; 00449 00450 /*! 00451 * \brief An attempt at basic password auth failed 00452 */ 00453 struct ast_security_event_inval_password { 00454 /*! 00455 * \brief Event descriptor version 00456 * \note This _must_ be changed if this event descriptor is changed. 00457 */ 00458 #define AST_SECURITY_EVENT_INVAL_PASSWORD_VERSION 1 00459 /*! 00460 * \brief Common security event descriptor elements 00461 * \note Account ID required 00462 */ 00463 struct ast_security_event_common common; 00464 }; 00465 00466 #if defined(__cplusplus) || defined(c_plusplus) 00467 } 00468 #endif 00469 00470 #endif /* __AST_SECURITY_EVENTS_DEFS_H__ */