Add an API for reporting security events, and a security event logging module.

This commit introduces the security events API.  This API is to be used by
Asterisk components to report events that have security implications.
A simple example is when a connection is made but fails authentication.  These
events can be used by external tools manipulate firewall rules or something
similar after detecting unusual activity based on security events.

Inside of Asterisk, the events go through the ast_event API.  This means that
they have a binary encoding, and it is easy to write code to subscribe to these
events and do something with them.

One module is provided that is a subscriber to these events - res_security_log.
This module turns security events into a parseable text format and sends them
to the "security" logger level.  Using logger.conf, these log entries may be
sent to a file, or to syslog.

One service, AMI, has been fully updated for reporting security events.
AMI was chosen as it was a fairly straight forward service to convert.
The next target will be chan_sip.  That will be more complicated and will
be done as its own project as the next phase of security events work.

For more information on the security events framework, see the documentation
generated from doc/tex/.  "make asterisk.pdf"

Review: https://reviewboard.asterisk.org/r/273/


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@206021 65c4cc65-6c06-0410-ace0-fbb531ad65f3

3 files changed, 643 insertions, 38 deletions

diff --git a/include/asterisk/event_defs.h b/include/asterisk/event_defs.h
index 99edb6f55..3779dac73 100644
--- a/include/asterisk/event_defs.h
+++ b/include/asterisk/event_defs.h
@@ -49,58 +49,60 @@ enum ast_event_type {
 	 *  directly, in general.  Use AST_EVENT_DEVICE_STATE instead. */
 	AST_EVENT_DEVICE_STATE_CHANGE = 0x06,
 	/*! Channel Event Logging events */
-	AST_EVENT_CEL = 0x07,
+	AST_EVENT_CEL                 = 0x07,
+	/*! A report of a security related event (see security_events.h) */
+	AST_EVENT_SECURITY            = 0x08,
 	/*! Number of event types.  This should be the last event type + 1 */
-	AST_EVENT_TOTAL        = 0x08,
+	AST_EVENT_TOTAL               = 0x09,
 };
 
 /*! \brief Event Information Element types */
 enum ast_event_ie_type {
 	/*! Used to terminate the arguments to event functions */
-	AST_EVENT_IE_END       = -1,
+	AST_EVENT_IE_END                 = -1,
 
 	/*! 
 	 * \brief Number of new messages
 	 * Used by: AST_EVENT_MWI 
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_NEWMSGS   = 0x01,
+	AST_EVENT_IE_NEWMSGS             = 0x0001,
 	/*! 
 	 * \brief Number of
 	 * Used by: AST_EVENT_MWI 
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_OLDMSGS   = 0x02,
+	AST_EVENT_IE_OLDMSGS             = 0x0002,
 	/*! 
 	 * \brief Mailbox name \verbatim (mailbox[@context]) \endverbatim
 	 * Used by: AST_EVENT_MWI 
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_MAILBOX   = 0x03,
+	AST_EVENT_IE_MAILBOX             = 0x0003,
 	/*! 
 	 * \brief Unique ID
 	 * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_UNIQUEID  = 0x04,
+	AST_EVENT_IE_UNIQUEID            = 0x0004,
 	/*! 
 	 * \brief Event type 
 	 * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_EVENTTYPE = 0x05,
+	AST_EVENT_IE_EVENTTYPE           = 0x0005,
 	/*!
 	 * \brief Hint that someone cares that an IE exists
 	 * Used by: AST_EVENT_SUB
 	 * Payload type: UINT (ast_event_ie_type)
 	 */
-	AST_EVENT_IE_EXISTS    = 0x6,
+	AST_EVENT_IE_EXISTS              = 0x0006,
 	/*!
 	 * \brief Device Name
 	 * Used by AST_EVENT_DEVICE_STATE_CHANGE
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_DEVICE    = 0x07,
+	AST_EVENT_IE_DEVICE              = 0x0007,
 	/*!
 	 * \brief Generic State IE
 	 * Used by AST_EVENT_DEVICE_STATE_CHANGE
@@ -108,162 +110,181 @@ enum ast_event_ie_type {
 	 * The actual state values depend on the event which
 	 * this IE is a part of.
 	 */
-	 AST_EVENT_IE_STATE    = 0x08,
+	 AST_EVENT_IE_STATE              = 0x0008,
 	 /*!
 	  * \brief Context IE
 	  * Used by AST_EVENT_MWI
 	  * Payload type: str
 	  */
-	 AST_EVENT_IE_CONTEXT  = 0x09,
+	 AST_EVENT_IE_CONTEXT            = 0x0009,
 	/*! 
 	 * \brief Channel Event Type
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_CEL_EVENT_TYPE = 0x0a,
+	AST_EVENT_IE_CEL_EVENT_TYPE      = 0x000a,
 	/*! 
 	 * \brief Channel Event Time (seconds)
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_CEL_EVENT_TIME = 0x0b,
+	AST_EVENT_IE_CEL_EVENT_TIME      = 0x000b,
 	/*! 
 	 * \brief Channel Event Time (micro-seconds)
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_CEL_EVENT_TIME_USEC = 0x0c,
+	AST_EVENT_IE_CEL_EVENT_TIME_USEC = 0x000c,
 	/*! 
 	 * \brief Channel Event User Event Name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_USEREVENT_NAME = 0x0d,
+	AST_EVENT_IE_CEL_USEREVENT_NAME  = 0x000d,
 	/*! 
 	 * \brief Channel Event CID name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CIDNAME = 0x0e,
+	AST_EVENT_IE_CEL_CIDNAME         = 0x000e,
 	/*! 
 	 * \brief Channel Event CID num
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CIDNUM = 0x0f,
+	AST_EVENT_IE_CEL_CIDNUM          = 0x000f,
 	/*! 
 	 * \brief Channel Event extension name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_EXTEN = 0x10,
+	AST_EVENT_IE_CEL_EXTEN           = 0x0010,
 	/*! 
 	 * \brief Channel Event context name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CONTEXT = 0x11,
+	AST_EVENT_IE_CEL_CONTEXT         = 0x0011,
 	/*! 
 	 * \brief Channel Event channel name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CHANNAME = 0x12,
+	AST_EVENT_IE_CEL_CHANNAME        = 0x0012,
 	/*! 
 	 * \brief Channel Event app name
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_APPNAME = 0x13,
+	AST_EVENT_IE_CEL_APPNAME         = 0x0013,
 	/*! 
 	 * \brief Channel Event app args/data
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_APPDATA = 0x14,
+	AST_EVENT_IE_CEL_APPDATA         = 0x0014,
 	/*! 
 	 * \brief Channel Event AMA flags
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: UINT
 	 */
-	AST_EVENT_IE_CEL_AMAFLAGS = 0x15,
+	AST_EVENT_IE_CEL_AMAFLAGS        = 0x0015,
 	/*! 
 	 * \brief Channel Event AccountCode
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_ACCTCODE = 0x16,
+	AST_EVENT_IE_CEL_ACCTCODE        = 0x0016,
 	/*! 
 	 * \brief Channel Event UniqueID
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_UNIQUEID = 0x17,
+	AST_EVENT_IE_CEL_UNIQUEID        = 0x0017,
 	/*! 
 	 * \brief Channel Event Userfield
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_USERFIELD = 0x18,
+	AST_EVENT_IE_CEL_USERFIELD       = 0x0018,
 	/*! 
 	 * \brief Channel Event CID ANI field
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CIDANI = 0x19,
+	AST_EVENT_IE_CEL_CIDANI          = 0x0019,
 	/*! 
 	 * \brief Channel Event CID RDNIS field
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CIDRDNIS = 0x1a,
+	AST_EVENT_IE_CEL_CIDRDNIS        = 0x001a,
 	/*! 
 	 * \brief Channel Event CID dnid
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_CIDDNID = 0x1b,
+	AST_EVENT_IE_CEL_CIDDNID         = 0x001b,
 	/*! 
 	 * \brief Channel Event Peer -- for Things involving multiple channels, like BRIDGE
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_PEER = 0x1c,
+	AST_EVENT_IE_CEL_PEER            = 0x001c,
 	/*! 
 	 * \brief Channel Event LinkedID
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_LINKEDID = 0x1d,
+	AST_EVENT_IE_CEL_LINKEDID        = 0x001d,
 	/*! 
 	 * \brief Channel Event peeraccount
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_PEERACCT = 0x1e,
+	AST_EVENT_IE_CEL_PEERACCT        = 0x001e,
 	/*! 
 	 * \brief Channel Event extra data
 	 * Used by: AST_EVENT_CEL
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_CEL_EXTRA = 0x1f,
+	AST_EVENT_IE_CEL_EXTRA           = 0x001f,
 	/*!
 	 * \brief Description
 	 * Used by: AST_EVENT_SUB, AST_EVENT_UNSUB
 	 * Payload type: STR
 	 */
-	AST_EVENT_IE_DESCRIPTION = 0x20,
+	AST_EVENT_IE_DESCRIPTION         = 0x0020,
 	/*!
 	 * \brief Entity ID
 	 * Used by All events
 	 * Payload type: RAW
 	 * This IE indicates which server the event originated from
 	 */
-	AST_EVENT_IE_EID      = 0x21,
+	AST_EVENT_IE_EID                 = 0x0021,
+	AST_EVENT_IE_SECURITY_EVENT      = 0x0022,
+	AST_EVENT_IE_EVENT_VERSION       = 0x0023,
+	AST_EVENT_IE_SERVICE             = 0x0024,
+	AST_EVENT_IE_MODULE              = 0x0025,
+	AST_EVENT_IE_ACCOUNT_ID          = 0x0026,
+	AST_EVENT_IE_SESSION_ID          = 0x0027,
+	AST_EVENT_IE_SESSION_TV          = 0x0028,
+	AST_EVENT_IE_ACL_NAME            = 0x0029,
+	AST_EVENT_IE_LOCAL_ADDR          = 0x002a,
+	AST_EVENT_IE_REMOTE_ADDR         = 0x002b,
+	AST_EVENT_IE_EVENT_TV            = 0x002c,
+	AST_EVENT_IE_REQUEST_TYPE        = 0x002d,
+	AST_EVENT_IE_REQUEST_PARAMS      = 0x002e,
+	AST_EVENT_IE_AUTH_METHOD         = 0x002f,
+	AST_EVENT_IE_SEVERITY            = 0x0030,
+	AST_EVENT_IE_EXPECTED_ADDR       = 0x0031,
+	AST_EVENT_IE_CHALLENGE           = 0x0032,
+	AST_EVENT_IE_RESPONSE            = 0x0033,
+	AST_EVENT_IE_EXPECTED_RESPONSE   = 0x0034,
+	/*! \brief Must be the last IE value +1 */
+	AST_EVENT_IE_TOTAL               = 0x0035,
 };
 
-#define AST_EVENT_IE_MAX AST_EVENT_IE_EID
-
 /*!
  * \brief Payload types for event information elements
  */
diff --git a/include/asterisk/security_events.h b/include/asterisk/security_events.h
new file mode 100644
index 000000000..c15d04f0e
--- /dev/null
+++ b/include/asterisk/security_events.h
@@ -0,0 +1,114 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell@digium.com>
+ *
+ * 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 API
+ *
+ * \author Russell Bryant <russell@digium.com>
+ */
+
+#ifndef __AST_SECURITY_EVENTS_H__
+#define __AST_SECURITY_EVENTS_H__
+
+#include "asterisk/event.h"
+
+/* Data structure definitions */
+#include "asterisk/security_events_defs.h"
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/*!
+ * \brief Report a security event
+ *
+ * \param[in] sec security event data.  Callers of this function should never
+ *            declare an instance of ast_security_event_common directly.  The
+ *            argument should be an instance of a specific security event
+ *            descriptor which has ast_security_event_common at the very
+ *            beginning.
+ *
+ * \retval 0 success
+ * \retval non-zero failure
+ */
+int ast_security_event_report(const struct ast_security_event_common *sec);
+
+struct ast_security_event_ie_type {
+	enum ast_event_ie_type ie_type;
+	/*! \brief For internal usage */
+	size_t offset;
+};
+
+/*!
+ * \brief Get the list of required IEs for a given security event sub-type
+ *
+ * \param[in] event_type security event sub-type
+ *
+ * \retval NULL invalid event_type
+ * \retval non-NULL An array terminated with the value AST_EVENT_IE_END
+ *
+ * \since 1.6.3
+ */
+const struct ast_security_event_ie_type *ast_security_event_get_required_ies(
+		const enum ast_security_event_type event_type);
+
+/*!
+ * \brief Get the list of optional IEs for a given security event sub-type
+ *
+ * \param[in] event_type security event sub-type
+ *
+ * \retval NULL invalid event_type
+ * \retval non-NULL An array terminated with the value AST_EVENT_IE_END
+ *
+ * \since 1.6.3
+ */
+const struct ast_security_event_ie_type *ast_security_event_get_optional_ies(
+		const enum ast_security_event_type event_type);
+
+/*!
+ * \brief Get the name of a security event sub-type
+ *
+ * \param[in] event_type security event sub-type
+ *
+ * \retval NULL if event_type is invalid
+ * \retval non-NULL the name of the security event type
+ *
+ * \since 1.6.3
+ */
+const char *ast_security_event_get_name(const enum ast_security_event_type event_type);
+
+/*!
+ * \brief Get the name of a security event severity
+ *
+ * \param[in] severity security event severity
+ *
+ * \retval NULL if severity is invalid
+ * \retval non-NULL the name of the security event severity
+ *
+ * \since 1.6.3
+ */
+const char *ast_security_event_severity_get_name(
+		const enum ast_security_event_severity severity);
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* __AST_SECURITY_EVENTS_H__ */
diff --git a/include/asterisk/security_events_defs.h b/include/asterisk/security_events_defs.h
new file mode 100644
index 000000000..e39cf312d
--- /dev/null
+++ b/include/asterisk/security_events_defs.h
@@ -0,0 +1,470 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell@digium.com>
+ *
+ * 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 <russell@digium.com>
+ */
+
+#ifndef __AST_SECURITY_EVENTS_DEFS_H__
+#define __AST_SECURITY_EVENTS_DEFS_H__
+
+#include "asterisk/network.h"
+
+#if defined(__cplusplus) || defined(c_plusplus)
+extern "C" {
+#endif
+
+/*!
+ * \brief Security event types
+ *
+ * AST_EVENT_SECURITY is the event type of an ast_event generated as a security
+ * event.  The event will have an information element of type
+ * AST_EVENT_IE_SECURITY_EVENT which identifies the security event sub-type.
+ * This enum defines the possible values for this sub-type.
+ */
+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 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),
+};
+
+/*!
+ * \brief Transport types
+ */
+enum ast_security_event_transport_type {
+	AST_SECURITY_EVENT_TRANSPORT_UDP,
+	AST_SECURITY_EVENT_TRANSPORT_TCP,
+	AST_SECURITY_EVENT_TRANSPORT_TLS,
+};
+
+#define AST_SEC_EVT(e) ((struct ast_security_event_common *) e)
+
+struct ast_security_event_ipv4_addr {
+	const struct sockaddr_in *sin;
+	enum ast_security_event_transport_type 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_ipv4_addr local_addr;
+	/*!
+	 * \brief Remote address the request came from
+	 * \note Always required
+	 */
+	struct ast_security_event_ipv4_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 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 1
+	/*!
+	 * \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_ipv4_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 1
+	/*!
+	 * \brief Common security event descriptor elements
+	 * \note Account ID required
+	 */
+	struct ast_security_event_common common;
+};
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* __AST_SECURITY_EVENTS_DEFS_H__ */