Thu Oct 11 06:33:55 2012

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) 2012, 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    /*!
00115     * \brief Challenge was sent out, informational
00116     */
00117    AST_SECURITY_EVENT_CHAL_SENT,
00118    /*!
00119     * \brief An attempt to contact a peer on an invalid transport.
00120     */
00121    AST_SECURITY_EVENT_INVAL_TRANSPORT,
00122    /*!
00123     * \brief This _must_ stay at the end.
00124     */
00125    AST_SECURITY_EVENT_NUM_TYPES
00126 };
00127 
00128 /*!
00129  * \brief the severity of a security event
00130  *
00131  * This is defined as a bit field to make it easy for consumers of the API to
00132  * subscribe to any combination of the defined severity levels.
00133  *
00134  * XXX \todo Do we need any more levels here?
00135  */
00136 enum ast_security_event_severity {
00137    /*! \brief Informational event, not something that has gone wrong */
00138    AST_SECURITY_EVENT_SEVERITY_INFO  = (1 << 0),
00139    /*! \brief Something has gone wrong */
00140    AST_SECURITY_EVENT_SEVERITY_ERROR = (1 << 1),
00141 };
00142 
00143 /*!
00144  * \brief Transport types
00145  */
00146 enum ast_security_event_transport_type {
00147    AST_SECURITY_EVENT_TRANSPORT_UDP,
00148    AST_SECURITY_EVENT_TRANSPORT_TCP,
00149    AST_SECURITY_EVENT_TRANSPORT_TLS,
00150 };
00151 
00152 #define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)
00153 
00154 struct ast_security_event_ip_addr {
00155    const struct ast_sockaddr *addr;
00156    enum ast_security_event_transport_type transport;
00157 };
00158 
00159 /*!
00160  * \brief Common structure elements
00161  *
00162  * This is the structure header for all event descriptor structures defined
00163  * below.  The contents of this structure are very important and must not
00164  * change.  Even though these structures are exposed via a public API, we have
00165  * a version field that can be used to ensure ABI safety.  If the event
00166  * descriptors need to be changed or updated in the future, we can safely do
00167  * so and can detect ABI changes at runtime.
00168  */
00169 struct ast_security_event_common {
00170    /*! \brief The security event sub-type */
00171    enum ast_security_event_type event_type;
00172    /*! \brief security event version */
00173    uint32_t version;
00174    /*!
00175     * \brief Service that generated the event
00176     * \note Always required
00177     *
00178     * Examples: "SIP", "AMI"
00179     */
00180    const char *service;
00181    /*!
00182     * \brief Module, Normally the AST_MODULE define
00183     * \note Always optional
00184     */
00185    const char *module;
00186    /*!
00187     * \brief Account ID, specific to the service type
00188     * \note optional/required, depending on event type
00189     */
00190    const char *account_id;
00191    /*!
00192     * \brief Session ID, specific to the service type
00193     * \note Always required
00194     */
00195    const char *session_id;
00196    /*!
00197     * \brief Session timeval, when the session started
00198     * \note Always optional
00199     */
00200    const struct timeval *session_tv;
00201    /*!
00202     * \brief Local address the request came in on
00203     * \note Always required
00204     */
00205    struct ast_security_event_ip_addr local_addr;
00206    /*!
00207     * \brief Remote address the request came from
00208     * \note Always required
00209     */
00210    struct ast_security_event_ip_addr remote_addr;
00211 };
00212 
00213 /*!
00214  * \brief Checking against an IP access control list failed
00215  */
00216 struct ast_security_event_failed_acl {
00217    /*!
00218     * \brief Event descriptor version
00219     * \note This _must_ be changed if this event descriptor is changed.
00220     */
00221    #define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1
00222    /*!
00223     * \brief Common security event descriptor elements
00224     * \note Account ID required
00225     */
00226    struct ast_security_event_common common;
00227    /*!
00228     * \brief ACL name, identifies which ACL was hit
00229     * \note optional
00230     */
00231    const char *acl_name;
00232 };
00233 
00234 /*!
00235  * \brief Invalid account ID specified (invalid username, for example)
00236  */
00237 struct ast_security_event_inval_acct_id {
00238    /*!
00239     * \brief Event descriptor version
00240     * \note This _must_ be changed if this event descriptor is changed.
00241     */
00242    #define AST_SECURITY_EVENT_INVAL_ACCT_ID_VERSION 1
00243    /*!
00244     * \brief Common security event descriptor elements
00245     * \note Account ID required
00246     */
00247    struct ast_security_event_common common;
00248 };
00249 
00250 /*!
00251  * \brief Request denied because of a session limit
00252  */
00253 struct ast_security_event_session_limit {
00254    /*!
00255     * \brief Event descriptor version
00256     * \note This _must_ be changed if this event descriptor is changed.
00257     */
00258    #define AST_SECURITY_EVENT_SESSION_LIMIT_VERSION 1
00259    /*!
00260     * \brief Common security event descriptor elements
00261     * \note Account ID required
00262     */
00263    struct ast_security_event_common common;
00264 };
00265 
00266 /*!
00267  * \brief Request denied because of a memory limit
00268  */
00269 struct ast_security_event_mem_limit {
00270    /*!
00271     * \brief Event descriptor version
00272     * \note This _must_ be changed if this event descriptor is changed.
00273     */
00274    #define AST_SECURITY_EVENT_MEM_LIMIT_VERSION 1
00275    /*!
00276     * \brief Common security event descriptor elements
00277     * \note Account ID required
00278     */
00279    struct ast_security_event_common common;
00280 };
00281 
00282 /*!
00283  * \brief Request denied because of a load average limit
00284  */
00285 struct ast_security_event_load_avg {
00286    /*!
00287     * \brief Event descriptor version
00288     * \note This _must_ be changed if this event descriptor is changed.
00289     */
00290    #define AST_SECURITY_EVENT_LOAD_AVG_VERSION 1
00291    /*!
00292     * \brief Common security event descriptor elements
00293     * \note Account ID required
00294     */
00295    struct ast_security_event_common common;
00296 };
00297 
00298 /*!
00299  * \brief Request denied because we don't support it
00300  */
00301 struct ast_security_event_req_no_support {
00302    /*!
00303     * \brief Event descriptor version
00304     * \note This _must_ be changed if this event descriptor is changed.
00305     */
00306    #define AST_SECURITY_EVENT_REQ_NO_SUPPORT_VERSION 1
00307    /*!
00308     * \brief Common security event descriptor elements
00309     * \note Account ID required
00310     */
00311    struct ast_security_event_common common;
00312    /*!
00313     * \brief Request type that was made
00314     * \note required
00315     */
00316    const char *request_type;
00317 };
00318 
00319 /*!
00320  * \brief Request denied because it's not allowed
00321  */
00322 struct ast_security_event_req_not_allowed {
00323    /*!
00324     * \brief Event descriptor version
00325     * \note This _must_ be changed if this event descriptor is changed.
00326     */
00327    #define AST_SECURITY_EVENT_REQ_NOT_ALLOWED_VERSION 1
00328    /*!
00329     * \brief Common security event descriptor elements
00330     * \note Account ID required
00331     */
00332    struct ast_security_event_common common;
00333    /*!
00334     * \brief Request type that was made
00335     * \note required
00336     */
00337    const char *request_type;
00338    /*!
00339     * \brief Request type that was made
00340     * \note optional
00341     */
00342    const char *request_params;
00343 };
00344 
00345 /*!
00346  * \brief Auth method used not allowed
00347  */
00348 struct ast_security_event_auth_method_not_allowed {
00349    /*!
00350     * \brief Event descriptor version
00351     * \note This _must_ be changed if this event descriptor is changed.
00352     */
00353    #define AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED_VERSION 1
00354    /*!
00355     * \brief Common security event descriptor elements
00356     * \note Account ID required
00357     */
00358    struct ast_security_event_common common;
00359    /*!
00360     * \brief Auth method attempted
00361     * \note required
00362     */
00363    const char *auth_method;
00364 };
00365 
00366 /*!
00367  * \brief Invalid formatting of request
00368  */
00369 struct ast_security_event_req_bad_format {
00370    /*!
00371     * \brief Event descriptor version
00372     * \note This _must_ be changed if this event descriptor is changed.
00373     */
00374    #define AST_SECURITY_EVENT_REQ_BAD_FORMAT_VERSION 1
00375    /*!
00376     * \brief Common security event descriptor elements
00377     * \note Account ID optional
00378     */
00379    struct ast_security_event_common common;
00380    /*!
00381     * \brief Request type that was made
00382     * \note required
00383     */
00384    const char *request_type;
00385    /*!
00386     * \brief Request type that was made
00387     * \note optional
00388     */
00389    const char *request_params;
00390 };
00391 
00392 /*!
00393  * \brief Successful authentication
00394  */
00395 struct ast_security_event_successful_auth {
00396    /*!
00397     * \brief Event descriptor version
00398     * \note This _must_ be changed if this event descriptor is changed.
00399     */
00400    #define AST_SECURITY_EVENT_SUCCESSFUL_AUTH_VERSION 1
00401    /*!
00402     * \brief Common security event descriptor elements
00403     * \note Account ID required
00404     */
00405    struct ast_security_event_common common;
00406    /*!
00407     * \brief Using password - if a password was used or not
00408     * \note required, 0 = no, 1 = yes
00409     */
00410    uint32_t *using_password;
00411 };
00412 
00413 /*!
00414  * \brief Unexpected source address for a session in progress
00415  */
00416 struct ast_security_event_unexpected_addr {
00417    /*!
00418     * \brief Event descriptor version
00419     * \note This _must_ be changed if this event descriptor is changed.
00420     */
00421    #define AST_SECURITY_EVENT_UNEXPECTED_ADDR_VERSION 2
00422    /*!
00423     * \brief Common security event descriptor elements
00424     * \note Account ID required
00425     */
00426    struct ast_security_event_common common;
00427    /*!
00428     * \brief Expected remote address
00429     * \note required
00430     */
00431    struct ast_security_event_ip_addr expected_addr;
00432 };
00433 
00434 /*!
00435  * \brief An attempt at challenge/response auth failed
00436  */
00437 struct ast_security_event_chal_resp_failed {
00438    /*!
00439     * \brief Event descriptor version
00440     * \note This _must_ be changed if this event descriptor is changed.
00441     */
00442    #define AST_SECURITY_EVENT_CHAL_RESP_FAILED_VERSION 1
00443    /*!
00444     * \brief Common security event descriptor elements
00445     * \note Account ID required
00446     */
00447    struct ast_security_event_common common;
00448    /*!
00449     * \brief Challenge provided
00450     * \note required
00451     */
00452    const char *challenge;
00453    /*!
00454     * \brief Response received
00455     * \note required
00456     */
00457    const char *response;
00458    /*!
00459     * \brief Response expected to be received
00460     * \note required
00461     */
00462    const char *expected_response;
00463 };
00464 
00465 /*!
00466  * \brief An attempt at basic password auth failed
00467  */
00468 struct ast_security_event_inval_password {
00469    /*!
00470     * \brief Event descriptor version
00471     * \note This _must_ be changed if this event descriptor is changed.
00472     */
00473    #define AST_SECURITY_EVENT_INVAL_PASSWORD_VERSION 2
00474    /*!
00475     * \brief Common security event descriptor elements
00476     * \note Account ID required
00477     */
00478    struct ast_security_event_common common;
00479    /*!
00480     * \brief Challenge provided
00481     * \note required
00482     */
00483    const char *challenge;
00484    /*!
00485     * \brief Challenge received
00486     * \note required
00487     */
00488    const char *received_challenge;
00489    /*!
00490     * \brief Hash received
00491     * \note required
00492     */
00493    const char *received_hash;
00494 };
00495 
00496 /*!
00497  * \brief A challenge was sent out
00498  */
00499 struct ast_security_event_chal_sent {
00500    /*!
00501     * \brief Event descriptor version
00502     * \note This _must_ be changed if this event descriptor is changed.
00503     */
00504    #define AST_SECURITY_EVENT_CHAL_SENT_VERSION 1
00505    /*!
00506     * \brief Common security event descriptor elements
00507     * \note Account ID required
00508     */
00509    struct ast_security_event_common common;
00510    /*!
00511     * \brief Challenge sent
00512     * \note required
00513     */
00514    const char *challenge;
00515 };
00516 
00517 /*!
00518  * \brief Attempt to contact peer on invalid transport
00519  */
00520 struct ast_security_event_inval_transport {
00521         /*!
00522          * \brief Event descriptor version
00523          * \note This _must_ be changed if this event descriptor is changed.
00524          */
00525         #define AST_SECURITY_EVENT_INVAL_TRANSPORT_VERSION 1
00526         /*!
00527          * \brief Common security event descriptor elements
00528          * \note Account ID required
00529          */
00530    struct ast_security_event_common common;
00531    /*!
00532     * \brief Attempted transport
00533     * \note required
00534     */
00535    const char *transport;
00536 };
00537 
00538 #if defined(__cplusplus) || defined(c_plusplus)
00539 }
00540 #endif
00541 
00542 #endif /* __AST_SECURITY_EVENTS_DEFS_H__ */

Generated on Thu Oct 11 06:33:55 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6