[svn-commits] russell: branch group/security_events r193500 - /team/group/security_events/i...
SVN commits to the Digium repositories
svn-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 svn-commits
mailing list