security_events_defs.h

Go to the documentation of this file.

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 2012, Digium, Inc.
 *
 * Russell Bryant <[email protected]>
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*!
 * \file
 *
 * \brief Security Event Reporting Data Structures
 *
 * \author Russell Bryant <[email protected]>
 */

#ifndef __AST_SECURITY_EVENTS_DEFS_H__
#define __AST_SECURITY_EVENTS_DEFS_H__

#include "asterisk/network.h"
#include "asterisk/netsock2.h"

#if defined(__cplusplus) || defined(c_plusplus)
extern "C" {
#endif

/*!
 * \brief Security event types
 */
enum ast_security_event_type {
 /*!
 * \brief Failed ACL
 *
 * This security event should be generated when an incoming request
 * was made, but was denied due to configured IP address access control
 * lists.
 */
 AST_SECURITY_EVENT_FAILED_ACL,
 /*!
 * \brief Invalid Account ID
 *
 * This event is used when an invalid account identifier is supplied
 * during authentication. For example, if an invalid username is given,
 * this event should be used.
 */
 AST_SECURITY_EVENT_INVAL_ACCT_ID,
 /*!
 * \brief Session limit reached
 *
 * A request has been denied because a configured session limit has been
 * reached, such as a call limit.
 */
 AST_SECURITY_EVENT_SESSION_LIMIT,
 /*!
 * \brief Memory limit reached
 *
 * A request has been denied because a configured memory limit has been
 * reached.
 */
 AST_SECURITY_EVENT_MEM_LIMIT,
 /*!
 * \brief Load Average limit reached
 *
 * A request has been denied because a configured load average limit has been
 * reached.
 */
 AST_SECURITY_EVENT_LOAD_AVG,
 /*!
 * \brief A request was made that we understand, but do not support
 */
 AST_SECURITY_EVENT_REQ_NO_SUPPORT,
 /*!
 * \brief A request was made that is not allowed
 */
 AST_SECURITY_EVENT_REQ_NOT_ALLOWED,
 /*!
 * \brief The attempted authentication method is not allowed
 */
 AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED,
 /*!
 * \brief Request received with bad formatting
 */
 AST_SECURITY_EVENT_REQ_BAD_FORMAT,
 /*!
 * \brief FYI FWIW, Successful authentication has occurred
 */
 AST_SECURITY_EVENT_SUCCESSFUL_AUTH,
 /*!
 * \brief An unexpected source address was seen for a session in progress
 */
 AST_SECURITY_EVENT_UNEXPECTED_ADDR,
 /*!
 * \brief An attempt at challenge/response authentication failed
 */
 AST_SECURITY_EVENT_CHAL_RESP_FAILED,
 /*!
 * \brief An attempt at basic password authentication failed
 */
 AST_SECURITY_EVENT_INVAL_PASSWORD,
 /*!
 * \brief Challenge was sent out, informational
 */
 AST_SECURITY_EVENT_CHAL_SENT,
 /*!
 * \brief An attempt to contact a peer on an invalid transport.
 */
 AST_SECURITY_EVENT_INVAL_TRANSPORT,
 /*!
 * \brief This _must_ stay at the end.
 */
 AST_SECURITY_EVENT_NUM_TYPES
};

/*!
 * \brief the severity of a security event
 *
 * This is defined as a bit field to make it easy for consumers of the API to
 * subscribe to any combination of the defined severity levels.
 *
 * XXX \todo Do we need any more levels here?
 */
enum ast_security_event_severity {
 /*! \brief Informational event, not something that has gone wrong */
 AST_SECURITY_EVENT_SEVERITY_INFO = (1 << 0),
 /*! \brief Something has gone wrong */
 AST_SECURITY_EVENT_SEVERITY_ERROR = (1 << 1),
};

#define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)

struct ast_security_event_ip_addr {
 const struct ast_sockaddr *addr;
 enum ast_transport transport;
};

/*!
 * \brief Common structure elements
 *
 * This is the structure header for all event descriptor structures defined
 * below. The contents of this structure are very important and must not
 * change. Even though these structures are exposed via a public API, we have
 * a version field that can be used to ensure ABI safety. If the event
 * descriptors need to be changed or updated in the future, we can safely do
 * so and can detect ABI changes at runtime.
 */
struct ast_security_event_common {
 /*! \brief The security event sub-type */
 enum ast_security_event_type event_type;
 /*! \brief security event version */
 uint32_t version;
 /*!
 * \brief Service that generated the event
 * \note Always required
 *
 * Examples: "SIP", "AMI"
 */
 const char *service;
 /*!
 * \brief Module, Normally the AST_MODULE define
 * \note Always optional
 */
 const char *module;
 /*!
 * \brief Account ID, specific to the service type
 * \note optional/required, depending on event type
 */
 const char *account_id;
 /*!
 * \brief Session ID, specific to the service type
 * \note Always required
 */
 const char *session_id;
 /*!
 * \brief Session timeval, when the session started
 * \note Always optional
 */
 const struct timeval *session_tv;
 /*!
 * \brief Local address the request came in on
 * \note Always required
 */
 struct ast_security_event_ip_addr local_addr;
 /*!
 * \brief Remote address the request came from
 * \note Always required
 */
 struct ast_security_event_ip_addr remote_addr;
};

/*!
 * \brief Checking against an IP access control list failed
 */
struct ast_security_event_failed_acl {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief ACL name, identifies which ACL was hit
 * \note optional
 */
 const char *acl_name;
};

/*!
 * \brief Invalid account ID specified (invalid username, for example)
 */
struct ast_security_event_inval_acct_id {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_INVAL_ACCT_ID_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
};

/*!
 * \brief Request denied because of a session limit
 */
struct ast_security_event_session_limit {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_SESSION_LIMIT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
};

/*!
 * \brief Request denied because of a memory limit
 */
struct ast_security_event_mem_limit {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_MEM_LIMIT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
};

/*!
 * \brief Request denied because of a load average limit
 */
struct ast_security_event_load_avg {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_LOAD_AVG_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
};

/*!
 * \brief Request denied because we don't support it
 */
struct ast_security_event_req_no_support {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_REQ_NO_SUPPORT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Request type that was made
 * \note required
 */
 const char *request_type;
};

/*!
 * \brief Request denied because it's not allowed
 */
struct ast_security_event_req_not_allowed {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_REQ_NOT_ALLOWED_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Request type that was made
 * \note required
 */
 const char *request_type;
 /*!
 * \brief Request type that was made
 * \note optional
 */
 const char *request_params;
};

/*!
 * \brief Auth method used not allowed
 */
struct ast_security_event_auth_method_not_allowed {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_AUTH_METHOD_NOT_ALLOWED_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Auth method attempted
 * \note required
 */
 const char *auth_method;
};

/*!
 * \brief Invalid formatting of request
 */
struct ast_security_event_req_bad_format {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_REQ_BAD_FORMAT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID optional
 */
 struct ast_security_event_common common;
 /*!
 * \brief Request type that was made
 * \note required
 */
 const char *request_type;
 /*!
 * \brief Request type that was made
 * \note optional
 */
 const char *request_params;
};

/*!
 * \brief Successful authentication
 */
struct ast_security_event_successful_auth {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_SUCCESSFUL_AUTH_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Using password - if a password was used or not
 * \note required, 0 = no, 1 = yes
 */
 uint32_t using_password;
};

/*!
 * \brief Unexpected source address for a session in progress
 */
struct ast_security_event_unexpected_addr {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_UNEXPECTED_ADDR_VERSION 2
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Expected remote address
 * \note required
 */
 struct ast_security_event_ip_addr expected_addr;
};

/*!
 * \brief An attempt at challenge/response auth failed
 */
struct ast_security_event_chal_resp_failed {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_CHAL_RESP_FAILED_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Challenge provided
 * \note required
 */
 const char *challenge;
 /*!
 * \brief Response received
 * \note required
 */
 const char *response;
 /*!
 * \brief Response expected to be received
 * \note required
 */
 const char *expected_response;
};

/*!
 * \brief An attempt at basic password auth failed
 */
struct ast_security_event_inval_password {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_INVAL_PASSWORD_VERSION 2
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Challenge provided
 * \note required
 */
 const char *challenge;
 /*!
 * \brief Challenge received
 * \note required
 */
 const char *received_challenge;
 /*!
 * \brief Hash received
 * \note required
 */
 const char *received_hash;
};

/*!
 * \brief A challenge was sent out
 */
struct ast_security_event_chal_sent {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_CHAL_SENT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Challenge sent
 * \note required
 */
 const char *challenge;
};

/*!
 * \brief Attempt to contact peer on invalid transport
 */
struct ast_security_event_inval_transport {
 /*!
 * \brief Event descriptor version
 * \note This _must_ be changed if this event descriptor is changed.
 */
 #define AST_SECURITY_EVENT_INVAL_TRANSPORT_VERSION 1
 /*!
 * \brief Common security event descriptor elements
 * \note Account ID required
 */
 struct ast_security_event_common common;
 /*!
 * \brief Attempted transport
 * \note required
 */
 const char *transport;
};

#if defined(__cplusplus) || defined(c_plusplus)
}
#endif

#endif /* __AST_SECURITY_EVENTS_DEFS_H__ */