Fri Jan 20 06:37:00 2012

Asterisk developer's documentation

security_events.c File Reference

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 531 of file security_events.c.

00531                  {
00532    NOT_REQUIRED,
00533    REQUIRED
00534 };

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 536 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_ATTEMPTED_TRANSPORT, 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_RECEIVED_CHALLENGE, AST_EVENT_IE_RECEIVED_HASH, 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_EVENT_IE_USING_PASSWORD, 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().

00538 {
00539    int res = 0;
00540 
00541    switch (ie_type->ie_type) {
00542    case AST_EVENT_IE_SERVICE:
00543    case AST_EVENT_IE_ACCOUNT_ID:
00544    case AST_EVENT_IE_SESSION_ID:
00545    case AST_EVENT_IE_MODULE:
00546    case AST_EVENT_IE_ACL_NAME:
00547    case AST_EVENT_IE_REQUEST_TYPE:
00548    case AST_EVENT_IE_REQUEST_PARAMS:
00549    case AST_EVENT_IE_AUTH_METHOD:
00550    case AST_EVENT_IE_CHALLENGE:
00551    case AST_EVENT_IE_RESPONSE:
00552    case AST_EVENT_IE_EXPECTED_RESPONSE:
00553    case AST_EVENT_IE_RECEIVED_CHALLENGE:
00554    case AST_EVENT_IE_RECEIVED_HASH:
00555    case AST_EVENT_IE_ATTEMPTED_TRANSPORT:
00556    {
00557       const char *str;
00558 
00559       str = *((const char **)(((const char *) sec) + ie_type->offset));
00560 
00561       if (req && !str) {
00562          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00563                "type '%d' not present\n", ie_type->ie_type,
00564                sec->event_type);
00565          res = -1;
00566       }
00567 
00568       if (str) {
00569          res = ast_event_append_ie_str(event, ie_type->ie_type, str);
00570       }
00571 
00572       break;
00573    }
00574    case AST_EVENT_IE_EVENT_VERSION:
00575    case AST_EVENT_IE_USING_PASSWORD:
00576    {
00577       uint32_t val;
00578       val = *((const uint32_t *)(((const char *) sec) + ie_type->offset));
00579       res = ast_event_append_ie_uint(event, ie_type->ie_type, val);
00580       break;
00581    }
00582    case AST_EVENT_IE_LOCAL_ADDR:
00583    case AST_EVENT_IE_REMOTE_ADDR:
00584    case AST_EVENT_IE_EXPECTED_ADDR:
00585    {
00586       const struct ast_security_event_ipv4_addr *addr;
00587 
00588       addr = (const struct ast_security_event_ipv4_addr *)(((const char *) sec) + ie_type->offset);
00589 
00590       if (req && !addr->sin) {
00591          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00592                "type '%d' not present\n", ie_type->ie_type,
00593                sec->event_type);
00594          res = -1;
00595       }
00596 
00597       if (addr->sin) {
00598          res = add_ipv4_ie(event, ie_type->ie_type, addr);
00599       }
00600       break;
00601    }
00602    case AST_EVENT_IE_SESSION_TV:
00603    {
00604       const struct timeval *tval;
00605 
00606       tval = *((const struct timeval **)(((const char *) sec) + ie_type->offset));
00607 
00608       if (req && !tval) {
00609          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00610                "type '%d' not present\n", ie_type->ie_type,
00611                sec->event_type);
00612          res = -1;
00613       }
00614 
00615       if (tval) {
00616          add_timeval_ie(event, ie_type->ie_type, tval);
00617       }
00618 
00619       break;
00620    }
00621    case AST_EVENT_IE_EVENT_TV:
00622    case AST_EVENT_IE_SEVERITY:
00623       /* Added automatically, nothing to do here. */
00624       break;
00625    default:
00626       ast_log(LOG_WARNING, "Unhandled IE type '%d', this security event "
00627             "will be missing data.\n", ie_type->ie_type);
00628       break;
00629    }
00630 
00631    return res;
00632 }

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 505 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().

00507 {
00508    struct ast_str *str = ast_str_alloca(64);
00509 
00510    ast_str_set(&str, 0, "IPV4/");
00511 
00512    switch (addr->transport) {
00513    case AST_SECURITY_EVENT_TRANSPORT_UDP:
00514       ast_str_append(&str, 0, "UDP/");
00515       break;
00516    case AST_SECURITY_EVENT_TRANSPORT_TCP:
00517       ast_str_append(&str, 0, "TCP/");
00518       break;
00519    case AST_SECURITY_EVENT_TRANSPORT_TLS:
00520       ast_str_append(&str, 0, "TLS/");
00521       break;
00522    }
00523 
00524    ast_str_append(&str, 0, "%s/%hu",
00525          ast_inet_ntoa(addr->sin->sin_addr),
00526          ntohs(addr->sin->sin_port));
00527 
00528    return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
00529 }

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

Definition at line 495 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().

00497 {
00498    struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);
00499 
00500    encode_timestamp(&str, tv);
00501 
00502    return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
00503 }

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

Definition at line 469 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().

00470 {
00471    struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);
00472    struct timeval tv = ast_tvnow();
00473    const char *severity_str;
00474 
00475    if (check_event_type(sec->event_type)) {
00476       return NULL;
00477    }
00478 
00479    encode_timestamp(&str, &tv);
00480 
00481    severity_str = S_OR(
00482       ast_security_event_severity_get_name(sec_events[sec->event_type].severity),
00483       "Unknown"
00484    );
00485 
00486    return ast_event_new(AST_EVENT_SECURITY,
00487       AST_EVENT_IE_SECURITY_EVENT, AST_EVENT_IE_PLTYPE_UINT, sec->event_type,
00488       AST_EVENT_IE_EVENT_VERSION, AST_EVENT_IE_PLTYPE_UINT, sec->version,
00489       AST_EVENT_IE_EVENT_TV, AST_EVENT_IE_PLTYPE_STR, str->str,
00490       AST_EVENT_IE_SERVICE, AST_EVENT_IE_PLTYPE_STR, sec->service,
00491       AST_EVENT_IE_SEVERITY, AST_EVENT_IE_PLTYPE_STR, severity_str,
00492       AST_EVENT_IE_END);
00493 }

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 433 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by security_event_cb().

00434 {
00435    if (check_event_type(event_type)) {
00436       return NULL;
00437    }
00438 
00439    return sec_events[event_type].name;
00440 }

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 452 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

00454 {
00455    if (check_event_type(event_type)) {
00456       return NULL;
00457    }
00458 
00459    return sec_events[event_type].optional_ies;
00460 }

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 442 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

00444 {
00445    if (check_event_type(event_type)) {
00446       return NULL;
00447    }
00448 
00449    return sec_events[event_type].required_ies;
00450 }

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 675 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().

00676 {
00677    int res;
00678 
00679    if (sec->event_type < 0 || sec->event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
00680       ast_log(LOG_ERROR, "Invalid security event type\n");
00681       return -1;
00682    }
00683 
00684    if (!sec_events[sec->event_type].name) {
00685       ast_log(LOG_WARNING, "Security event type %u not handled\n",
00686             sec->event_type);
00687       return -1;
00688    }
00689 
00690    if (sec->version != sec_events[sec->event_type].version) {
00691       ast_log(LOG_WARNING, "Security event %u version mismatch\n",
00692             sec->event_type);
00693       return -1;
00694    }
00695 
00696    res = handle_security_event(sec);
00697 
00698    return res;
00699 }

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 409 of file security_events.c.

References ARRAY_LEN, and severities.

Referenced by alloc_event().

00411 {
00412    unsigned int i;
00413 
00414    for (i = 0; i < ARRAY_LEN(severities); i++) {
00415       if (severities[i].severity == severity) {
00416          return severities[i].str;
00417       }
00418    }
00419 
00420    return NULL;
00421 }

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

Definition at line 423 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().

00424 {
00425    if (event_type < 0 || event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
00426       ast_log(LOG_ERROR, "Invalid security event type %u\n", event_type);
00427       return -1;
00428    }
00429 
00430    return 0;
00431 }

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

Definition at line 462 of file security_events.c.

References ast_str_set().

Referenced by add_timeval_ie(), and alloc_event().

00463 {
00464    ast_str_set(str, 0, "%u-%u",
00465          (unsigned int) tv->tv_sec,
00466          (unsigned int) tv->tv_usec);
00467 }

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

Definition at line 634 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().

00635 {
00636    struct ast_event *event;
00637    const struct ast_security_event_ie_type *ies;
00638    unsigned int i;
00639 
00640    if (!(event = alloc_event(sec))) {
00641       return -1;
00642    }
00643 
00644    for (ies = ast_security_event_get_required_ies(sec->event_type), i = 0;
00645          ies[i].ie_type != AST_EVENT_IE_END;
00646          i++) {
00647       if (add_ie(&event, sec, ies + i, REQUIRED)) {
00648          goto return_error;
00649       }
00650    }
00651 
00652    for (ies = ast_security_event_get_optional_ies(sec->event_type), i = 0;
00653          ies[i].ie_type != AST_EVENT_IE_END;
00654          i++) {
00655       if (add_ie(&event, sec, ies + i, NOT_REQUIRED)) {
00656          goto return_error;
00657       }
00658    }
00659 
00660 
00661    if (ast_event_queue(event)) {
00662       goto return_error;
00663    }
00664 
00665    return 0;
00666 
00667 return_error:
00668    if (event) {
00669       ast_event_destroy(event);
00670    }
00671 
00672    return -1;
00673 }

Variable Documentation

const char* name

Definition at line 39 of file security_events.c.

struct ast_security_event_ie_type optional_ies[MAX_SECURITY_IES]

Definition at line 44 of file security_events.c.

struct ast_security_event_ie_type required_ies[MAX_SECURITY_IES]

Definition at line 43 of file security_events.c.

struct { ... } sec_events[AST_SECURITY_EVENT_NUM_TYPES] [static]

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

struct { ... } severities[] [static]

Referenced by ast_security_event_severity_get_name().

enum ast_security_event_severity severity

Definition at line 41 of file security_events.c.

const char* str

Definition at line 403 of file security_events.c.

const size_t TIMESTAMP_STR_LEN = 32 [static]

Definition at line 36 of file security_events.c.

uint32_t version

Definition at line 40 of file security_events.c.

Referenced by add_sdp(), aji_dinfo_handler(), ast_adsi_begin_download(), ast_readconfig(), ast_remotecontrol(), ast_rtp_read(), ast_var_Version(), check_access(), config_module(), dump_versioned_codec(), iax_parse_ies(), manager_modulecheck(), and update_registry().

Generated on Fri Jan 20 06:37:01 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6