[asterisk-commits] russell: branch group/security_events r193500 - /team/group/security_events/i...

SVN commits to the Asterisk project asterisk-commits at lists.digium.com
Sun May 10 09:11:06 CDT 2009


Author: russell
Date: Sun May 10 09:10:53 2009
New Revision: 193500

URL: http://svn.asterisk.org/svn-view/asterisk?view=rev&rev=193500
Log:
add some docs, put data structures in their own header

Added:
    team/group/security_events/include/asterisk/security_events_defs.h   (with props)
Modified:
    team/group/security_events/include/asterisk/security_events.h

Modified: team/group/security_events/include/asterisk/security_events.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/security_events/include/asterisk/security_events.h?view=diff&rev=193500&r1=193499&r2=193500
==============================================================================
--- team/group/security_events/include/asterisk/security_events.h (original)
+++ team/group/security_events/include/asterisk/security_events.h Sun May 10 09:10:53 2009
@@ -19,7 +19,7 @@
 /*!
  * \file
  *
- * \brief Security Event Reporting Helpers
+ * \brief Security Event Reporting API
  * 
  * \author Russell Bryant <russell at digium.com>
  */
@@ -28,62 +28,64 @@
 #define __AST_SECURITY_EVENTS_H__
 
 #include "asterisk/event.h"
-#include "asterisk/network.h"
+
+/* Data structure definitions */
+#include "asterisk/security_events_defs.h"
 
 #if defined(__cplusplus) || defined(c_plusplus)
 extern "C" {
 #endif
 
-enum ast_security_event_type {
-	AST_SECURITY_EVENT_FAILED_ACL,
-	/* \brief This _must_ stay at the end. */
-	AST_SECURITY_EVENT_NUM_TYPES
-};
-
-enum ast_security_event_transport_type {
-	AST_SECURITY_EVENT_TRANSPORT_UDP,
-	AST_SECURITY_EVENT_TRANSPORT_TCP,
-	AST_SECURITY_EVENT_TRANSPORT_TLS,
-};
+/*!
+ * \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);
 
 /*!
- * \brief Common structure elements
+ * \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
  */
-struct ast_security_event_common {
-	enum ast_security_event_type event_type;
-	uint32_t version;
-	const char *service;
-};
-
-struct ast_security_event_failed_acl {
-#define AST_SECURITY_EVENT_FAILED_ACL_VERSION 1
-	struct ast_security_event_common common;
-	/*! \brief optional */
-	const char *module;
-	/*! \brief required */
-	const char *account_id;
-	/*! \brief required */
-	const char *session_id;
-	/*! \brief optional */
-	const char *acl_name;
-	/*! \brief optional */
-	const struct timeval *session_tv;
-	/*! \brief required */
-	const struct sockaddr_in *sin_local;
-	/*! \brief required */
-	const struct sockaddr_in *sin_remote;
-	/*! \brief required */
-	enum ast_security_event_transport_type transport;
-};
-
-int ast_security_event_report(const struct ast_security_event_common *sec);
-
 const enum ast_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 enum ast_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);
 
 #if defined(__cplusplus) || defined(c_plusplus)

Added: team/group/security_events/include/asterisk/security_events_defs.h
URL: http://svn.asterisk.org/svn-view/asterisk/team/group/security_events/include/asterisk/security_events_defs.h?view=auto&rev=193500
==============================================================================
--- team/group/security_events/include/asterisk/security_events_defs.h (added)
+++ team/group/security_events/include/asterisk/security_events_defs.h Sun May 10 09:10:53 2009
@@ -1,0 +1,146 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2009, Digium, Inc.
+ *
+ * Russell Bryant <russell at 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 at 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 This _must_ stay at the end. */
+	AST_SECURITY_EVENT_NUM_TYPES
+};
+
+/*!
+ * \brief Transport types
+ */
+enum ast_security_event_transport_type {
+	AST_SECURITY_EVENT_TRANSPORT_UDP,
+	AST_SECURITY_EVENT_TRANSPORT_TCP,
+	AST_SECURITY_EVENT_TRANSPORT_TLS,
+};
+
+/*!
+ * \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
+	 *
+	 * Examples: "SIP"
+	 */
+	const char *service;
+};
+
+/*!
+ * \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 */
+	struct ast_security_event_common common;
+	/*! 
+	 * \brief Module, Normally the AST_MODULE define
+	 * \note optional 
+	 */
+	const char *module;
+	/*!
+	 * \brief Account ID, specific to the service type
+	 * \note required
+	 */
+	const char *account_id;
+	/*!
+	 * \brief Session ID, specific to the service type
+	 * \note required
+	 */
+	const char *session_id;
+	/*!
+	 * \brief ACL name, identifies which ACL was hit
+	 * \note optional
+	 */
+	const char *acl_name;
+	/*!
+	 * \brief Session timeval, when the session started
+	 * \note optional
+	 */
+	const struct timeval *session_tv;
+	/*!
+	 * \brief Local address the request came in on
+	 * \note required
+	 */
+	const struct sockaddr_in *sin_local;
+	/*!
+	 * \brief Remote address the request came from
+	 * \note required
+	 */
+	const struct sockaddr_in *sin_remote;
+	/*! 
+	 * \brief Transport type in use
+	 * \note required
+	 */
+	enum ast_security_event_transport_type transport;
+};
+
+#if defined(__cplusplus) || defined(c_plusplus)
+}
+#endif
+
+#endif /* __AST_SECURITY_EVENTS_DEFS_H__ */

Propchange: team/group/security_events/include/asterisk/security_events_defs.h
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: team/group/security_events/include/asterisk/security_events_defs.h
------------------------------------------------------------------------------
    svn:keywords = Author Date Id Revision

Propchange: team/group/security_events/include/asterisk/security_events_defs.h
------------------------------------------------------------------------------
    svn:mime-type = text/plain




More information about the asterisk-commits mailing list