Security Event Reporting Helpers. More...

#include "asterisk.h"
#include "asterisk/utils.h"
#include "asterisk/strings.h"
#include "asterisk/network.h"
#include "asterisk/security_events.h"

Include dependency graph for security_events.c:

Go to the source code of this file.

Defines
#define	MAX_SECURITY_IES 12
#define	SEC_EVT_FIELD(e, field) (offsetof(struct ast_security_event_##e, field))
Enumerations
enum	ie_required { NOT_REQUIRED, REQUIRED, NOT_REQUIRED, REQUIRED }
Functions
static int	add_ie (struct ast_event *event, const struct ast_security_event_common sec, const struct ast_security_event_ie_type *ie_type, enum ie_required req)
static int	add_ipv4_ie (struct ast_event *event, enum ast_event_ie_type ie_type, const struct ast_security_event_ipv4_addr addr)
static int	add_timeval_ie (struct ast_event *event, enum ast_event_ie_type ie_type, const struct timeval tv)
static struct ast_event *	alloc_event (const struct ast_security_event_common *sec)
const char *	ast_security_event_get_name (const enum ast_security_event_type event_type)
	Get the name of a security event sub-type.
struct ast_security_event_ie_type *	ast_security_event_get_optional_ies (const enum ast_security_event_type event_type)
	Get the list of optional IEs for a given security event sub-type.
struct ast_security_event_ie_type *	ast_security_event_get_required_ies (const enum ast_security_event_type event_type)
	Get the list of required IEs for a given security event sub-type.
int	ast_security_event_report (const struct ast_security_event_common *sec)
	Report a security event.
const char *	ast_security_event_severity_get_name (const enum ast_security_event_severity severity)
	Get the name of a security event severity.
static int	check_event_type (const enum ast_security_event_type event_type)
static void	encode_timestamp (struct ast_str *str, const struct timeval tv)
static int	handle_security_event (const struct ast_security_event_common *sec)
Variables
struct {
const char * name
struct ast_security_event_ie_type optional_ies [MAX_SECURITY_IES]
struct ast_security_event_ie_type required_ies [MAX_SECURITY_IES]
enum ast_security_event_severity severity
uint32_t version
}	sec_events [AST_SECURITY_EVENT_NUM_TYPES]
struct {
enum ast_security_event_severity severity
const char * str
}	severities []
static const size_t	TIMESTAMP_STR_LEN = 32

Detailed Description

Security Event Reporting Helpers.

Author:: Russell Bryant <russell@digium.com>

Definition in file security_events.c.

Define Documentation

#define MAX_SECURITY_IES 12

Definition at line 42 of file security_events.c.

#define SEC_EVT_FIELD	(	e,
		field
	)	(offsetof(struct ast_security_event_##e, field))

Enumeration Type Documentation

enum ie_required

Enumerator:

NOT_REQUIRED
REQUIRED
NOT_REQUIRED
REQUIRED

Definition at line 481 of file security_events.c.

                 {
   NOT_REQUIRED,
   REQUIRED
};

Function Documentation

static int add_ie	(	struct ast_event **	event,
		const struct ast_security_event_common *	sec,
		const struct ast_security_event_ie_type *	ie_type,
		enum ie_required	req
	)		`[static]`

Definition at line 486 of file security_events.c.

References add_ipv4_ie(), add_timeval_ie(), ast_event_append_ie_str(), ast_event_append_ie_uint(), AST_EVENT_IE_ACCOUNT_ID, AST_EVENT_IE_ACL_NAME, AST_EVENT_IE_AUTH_METHOD, AST_EVENT_IE_CHALLENGE, AST_EVENT_IE_EVENT_TV, AST_EVENT_IE_EVENT_VERSION, AST_EVENT_IE_EXPECTED_ADDR, AST_EVENT_IE_EXPECTED_RESPONSE, AST_EVENT_IE_LOCAL_ADDR, AST_EVENT_IE_MODULE, AST_EVENT_IE_REMOTE_ADDR, AST_EVENT_IE_REQUEST_PARAMS, AST_EVENT_IE_REQUEST_TYPE, AST_EVENT_IE_RESPONSE, AST_EVENT_IE_SERVICE, AST_EVENT_IE_SESSION_ID, AST_EVENT_IE_SESSION_TV, AST_EVENT_IE_SEVERITY, ast_log(), ast_security_event_ie_type::ie_type, LOG_WARNING, ast_security_event_ie_type::offset, ast_security_event_ipv4_addr::sin, and str.

Referenced by handle_security_event().

{
   int res = 0;

   switch (ie_type->ie_type) {
   case AST_EVENT_IE_SERVICE:
   case AST_EVENT_IE_ACCOUNT_ID:
   case AST_EVENT_IE_SESSION_ID:
   case AST_EVENT_IE_MODULE:
   case AST_EVENT_IE_ACL_NAME:
   case AST_EVENT_IE_REQUEST_TYPE:
   case AST_EVENT_IE_REQUEST_PARAMS:
   case AST_EVENT_IE_AUTH_METHOD:
   case AST_EVENT_IE_CHALLENGE:
   case AST_EVENT_IE_RESPONSE:
   case AST_EVENT_IE_EXPECTED_RESPONSE:
   {
      const char *str;

      str = *((const char **)(((const char *) sec) + ie_type->offset));

      if (req && !str) {
         ast_log(LOG_WARNING, "Required IE '%d' for security event "
               "type '%d' not present\n", ie_type->ie_type,
               sec->event_type);
         res = -1;
      }

      if (str) {
         res = ast_event_append_ie_str(event, ie_type->ie_type, str);
      }

      break;
   }
   case AST_EVENT_IE_EVENT_VERSION:
   {
      uint32_t val;
      val = *((const uint32_t *)(((const char *) sec) + ie_type->offset));
      res = ast_event_append_ie_uint(event, ie_type->ie_type, val);
      break;
   }
   case AST_EVENT_IE_LOCAL_ADDR:
   case AST_EVENT_IE_REMOTE_ADDR:
   case AST_EVENT_IE_EXPECTED_ADDR:
   {
      const struct ast_security_event_ipv4_addr *addr;

      addr = (const struct ast_security_event_ipv4_addr *)(((const char *) sec) + ie_type->offset);

      if (req && !addr->sin) {
         ast_log(LOG_WARNING, "Required IE '%d' for security event "
               "type '%d' not present\n", ie_type->ie_type,
               sec->event_type);
         res = -1;
      }

      if (addr->sin) {
         res = add_ipv4_ie(event, ie_type->ie_type, addr);
      }
      break;
   }
   case AST_EVENT_IE_SESSION_TV:
   {
      const struct timeval *tval;

      tval = *((const struct timeval **)(((const char *) sec) + ie_type->offset));

      if (req && !tval) {
         ast_log(LOG_WARNING, "Required IE '%d' for security event "
               "type '%d' not present\n", ie_type->ie_type,
               sec->event_type);
         res = -1;
      }

      if (tval) {
         add_timeval_ie(event, ie_type->ie_type, tval);
      }

      break;
   }
   case AST_EVENT_IE_EVENT_TV:
   case AST_EVENT_IE_SEVERITY:
      /* Added automatically, nothing to do here. */
      break;
   default:
      ast_log(LOG_WARNING, "Unhandled IE type '%d', this security event "
            "will be missing data.\n", ie_type->ie_type);
      break;
   }

   return res;
}

static int add_ipv4_ie	(	struct ast_event **	event,
		enum ast_event_ie_type	ie_type,
		const struct ast_security_event_ipv4_addr *	addr
	)		`[static]`

Definition at line 455 of file security_events.c.

References ast_event_append_ie_str(), ast_inet_ntoa(), AST_SECURITY_EVENT_TRANSPORT_TCP, AST_SECURITY_EVENT_TRANSPORT_TLS, AST_SECURITY_EVENT_TRANSPORT_UDP, ast_str_alloca, ast_str_append(), ast_str_buffer(), ast_str_set(), ast_security_event_ipv4_addr::sin, str, and ast_security_event_ipv4_addr::transport.

Referenced by add_ie().

{
   struct ast_str *str = ast_str_alloca(64);

   ast_str_set(&str, 0, "IPV4/");

   switch (addr->transport) {
   case AST_SECURITY_EVENT_TRANSPORT_UDP:
      ast_str_append(&str, 0, "UDP/");
      break;
   case AST_SECURITY_EVENT_TRANSPORT_TCP:
      ast_str_append(&str, 0, "TCP/");
      break;
   case AST_SECURITY_EVENT_TRANSPORT_TLS:
      ast_str_append(&str, 0, "TLS/");
      break;
   }

   ast_str_append(&str, 0, "%s/%hu",
         ast_inet_ntoa(addr->sin->sin_addr),
         ntohs(addr->sin->sin_port));

   return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
}

static int add_timeval_ie	(	struct ast_event **	event,
		enum ast_event_ie_type	ie_type,
		const struct timeval *	tv
	)		`[static]`

Definition at line 445 of file security_events.c.

References ast_event_append_ie_str(), ast_str_alloca, ast_str_buffer(), encode_timestamp(), and str.

Referenced by add_ie().

{
   struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);

   encode_timestamp(&str, tv);

   return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
}

static struct ast_event* alloc_event ( const struct ast_security_event_common * sec ) [static, read]

Definition at line 419 of file security_events.c.

References AST_EVENT_IE_END, AST_EVENT_IE_EVENT_TV, AST_EVENT_IE_EVENT_VERSION, AST_EVENT_IE_PLTYPE_STR, AST_EVENT_IE_PLTYPE_UINT, AST_EVENT_IE_SECURITY_EVENT, AST_EVENT_IE_SERVICE, AST_EVENT_IE_SEVERITY, ast_event_new(), AST_EVENT_SECURITY, ast_security_event_severity_get_name(), ast_str_alloca, ast_tvnow(), check_event_type(), encode_timestamp(), ast_security_event_common::event_type, S_OR, sec_events, ast_security_event_common::service, str, and ast_security_event_common::version.

Referenced by handle_security_event().

{
   struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);
   struct timeval tv = ast_tvnow();
   const char *severity_str;

   if (check_event_type(sec->event_type)) {
      return NULL;
   }

   encode_timestamp(&str, &tv);

   severity_str = S_OR(
      ast_security_event_severity_get_name(sec_events[sec->event_type].severity),
      "Unknown"
   );

   return ast_event_new(AST_EVENT_SECURITY,
      AST_EVENT_IE_SECURITY_EVENT, AST_EVENT_IE_PLTYPE_UINT, sec->event_type,
      AST_EVENT_IE_EVENT_VERSION, AST_EVENT_IE_PLTYPE_UINT, sec->version,
      AST_EVENT_IE_EVENT_TV, AST_EVENT_IE_PLTYPE_STR, str->str,
      AST_EVENT_IE_SERVICE, AST_EVENT_IE_PLTYPE_STR, sec->service,
      AST_EVENT_IE_SEVERITY, AST_EVENT_IE_PLTYPE_STR, severity_str,
      AST_EVENT_IE_END);
}

const char* ast_security_event_get_name ( const enum ast_security_event_type event_type )

Get the name of a security event sub-type.

Parameters:

[in] event_type security event sub-type

Return values:

NULL	if event_type is invalid
non-NULL	the name of the security event type

Since:: 1.8

Definition at line 383 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by security_event_cb().

{
   if (check_event_type(event_type)) {
      return NULL;
   }

   return sec_events[event_type].name;
}

struct ast_security_event_ie_type* ast_security_event_get_optional_ies ( const enum ast_security_event_type event_type ) [read]

Get the list of optional IEs for a given security event sub-type.

Parameters:

[in] event_type security event sub-type

Return values:

NULL	invalid event_type
non-NULL	An array terminated with the value AST_EVENT_IE_END

Since:: 1.8

Definition at line 402 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

{
   if (check_event_type(event_type)) {
      return NULL;
   }

   return sec_events[event_type].optional_ies;
}

struct ast_security_event_ie_type* ast_security_event_get_required_ies ( const enum ast_security_event_type event_type ) [read]

Get the list of required IEs for a given security event sub-type.

Parameters:

[in] event_type security event sub-type

Return values:

NULL	invalid event_type
non-NULL	An array terminated with the value AST_EVENT_IE_END

Since:: 1.8

Definition at line 392 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

{
   if (check_event_type(event_type)) {
      return NULL;
   }

   return sec_events[event_type].required_ies;
}

int ast_security_event_report ( const struct ast_security_event_common * sec )

Report a security event.

Parameters:

[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.

Return values:

0	success
non-zero	failure

Definition at line 621 of file security_events.c.

References ast_log(), AST_SECURITY_EVENT_NUM_TYPES, ast_security_event_common::event_type, handle_security_event(), LOG_ERROR, LOG_WARNING, sec_events, and ast_security_event_common::version.

Referenced by report_auth_success(), report_failed_acl(), report_failed_challenge_response(), report_inval_password(), report_invalid_user(), report_req_bad_format(), report_req_not_allowed(), and report_session_limit().

{
   int res;

   if (sec->event_type < 0 || sec->event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
      ast_log(LOG_ERROR, "Invalid security event type\n");
      return -1;
   }

   if (!sec_events[sec->event_type].name) {
      ast_log(LOG_WARNING, "Security event type %u not handled\n",
            sec->event_type);
      return -1;
   }

   if (sec->version != sec_events[sec->event_type].version) {
      ast_log(LOG_WARNING, "Security event %u version mismatch\n",
            sec->event_type);
      return -1;
   }

   res = handle_security_event(sec);

   return res;
}

const char* ast_security_event_severity_get_name ( const enum ast_security_event_severity severity )

Get the name of a security event severity.

Parameters:

[in] severity security event severity

Return values:

NULL	if severity is invalid
non-NULL	the name of the security event severity

Since:: 1.8

Definition at line 359 of file security_events.c.

References ARRAY_LEN, and severities.

Referenced by alloc_event().

{
   unsigned int i;

   for (i = 0; i < ARRAY_LEN(severities); i++) {
      if (severities[i].severity == severity) {
         return severities[i].str;
      }
   }

   return NULL;
}

static int check_event_type ( const enum ast_security_event_type event_type ) [static]

Definition at line 373 of file security_events.c.

References ast_log(), AST_SECURITY_EVENT_NUM_TYPES, and LOG_ERROR.

Referenced by alloc_event(), ast_security_event_get_name(), ast_security_event_get_optional_ies(), and ast_security_event_get_required_ies().

{
   if (event_type < 0 || event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
      ast_log(LOG_ERROR, "Invalid security event type %u\n", event_type);
      return -1;
   }

   return 0;
}

static void encode_timestamp	(	struct ast_str **	str,
		const struct timeval *	tv
	)		`[static]`

Definition at line 412 of file security_events.c.

References ast_str_set().

Referenced by add_timeval_ie(), and alloc_event().

{
   ast_str_set(str, 0, "%u-%u",
         (unsigned int) tv->tv_sec,
         (unsigned int) tv->tv_usec);
}

static int handle_security_event ( const struct ast_security_event_common * sec ) [static]

Definition at line 580 of file security_events.c.

References add_ie(), alloc_event(), ast_event_destroy(), AST_EVENT_IE_END, ast_event_queue(), ast_security_event_get_optional_ies(), ast_security_event_get_required_ies(), ast_security_event_common::event_type, ast_security_event_ie_type::ie_type, NOT_REQUIRED, and REQUIRED.

Referenced by ast_security_event_report().

{
   struct ast_event *event;
   const struct ast_security_event_ie_type *ies;
   unsigned int i;

   if (!(event = alloc_event(sec))) {
      return -1;
   }

   for (ies = ast_security_event_get_required_ies(sec->event_type), i = 0;
         ies[i].ie_type != AST_EVENT_IE_END;
         i++) {
      if (add_ie(&event, sec, ies + i, REQUIRED)) {
         goto return_error;
      }
   }

   for (ies = ast_security_event_get_optional_ies(sec->event_type), i = 0;
         ies[i].ie_type != AST_EVENT_IE_END;
         i++) {
      if (add_ie(&event, sec, ies + i, NOT_REQUIRED)) {
         goto return_error;
      }
   }


   if (ast_event_queue(event)) {
      goto return_error;
   }

   return 0;

return_error:
   if (event) {
      ast_event_destroy(event);
   }

   return -1;
}