Wed Jan 27 20:02:15 2016

Asterisk developer's documentation


security_events_defs.h

Go to the documentation of this file.
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__ */

Generated on 27 Jan 2016 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1