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

1 files changed, 470 insertions, 0 deletions

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__ */