Wed Apr 6 11:30:10 2011

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"

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 }

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_eventalloc_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.
ast_security_event_ie_typeast_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.
ast_security_event_ie_typeast_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
   ast_security_event_ie_type   optional_ies [MAX_SECURITY_IES]
   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 

Definition at line 481 of file security_events.c.

00481                  {
00482    NOT_REQUIRED,
00483    REQUIRED
00484 };


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

00488 {
00489    int res = 0;
00490 
00491    switch (ie_type->ie_type) {
00492    case AST_EVENT_IE_SERVICE:
00493    case AST_EVENT_IE_ACCOUNT_ID:
00494    case AST_EVENT_IE_SESSION_ID:
00495    case AST_EVENT_IE_MODULE:
00496    case AST_EVENT_IE_ACL_NAME:
00497    case AST_EVENT_IE_REQUEST_TYPE:
00498    case AST_EVENT_IE_REQUEST_PARAMS:
00499    case AST_EVENT_IE_AUTH_METHOD:
00500    case AST_EVENT_IE_CHALLENGE:
00501    case AST_EVENT_IE_RESPONSE:
00502    case AST_EVENT_IE_EXPECTED_RESPONSE:
00503    {
00504       const char *str;
00505 
00506       str = *((const char **)(((const char *) sec) + ie_type->offset));
00507 
00508       if (req && !str) {
00509          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00510                "type '%d' not present\n", ie_type->ie_type,
00511                sec->event_type);
00512          res = -1;
00513       }
00514 
00515       if (str) {
00516          res = ast_event_append_ie_str(event, ie_type->ie_type, str);
00517       }
00518 
00519       break;
00520    }
00521    case AST_EVENT_IE_EVENT_VERSION:
00522    {
00523       uint32_t val;
00524       val = *((const uint32_t *)(((const char *) sec) + ie_type->offset));
00525       res = ast_event_append_ie_uint(event, ie_type->ie_type, val);
00526       break;
00527    }
00528    case AST_EVENT_IE_LOCAL_ADDR:
00529    case AST_EVENT_IE_REMOTE_ADDR:
00530    case AST_EVENT_IE_EXPECTED_ADDR:
00531    {
00532       const struct ast_security_event_ipv4_addr *addr;
00533 
00534       addr = (const struct ast_security_event_ipv4_addr *)(((const char *) sec) + ie_type->offset);
00535 
00536       if (req && !addr->sin) {
00537          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00538                "type '%d' not present\n", ie_type->ie_type,
00539                sec->event_type);
00540          res = -1;
00541       }
00542 
00543       if (addr->sin) {
00544          res = add_ipv4_ie(event, ie_type->ie_type, addr);
00545       }
00546       break;
00547    }
00548    case AST_EVENT_IE_SESSION_TV:
00549    {
00550       const struct timeval *tval;
00551 
00552       tval = *((const struct timeval **)(((const char *) sec) + ie_type->offset));
00553 
00554       if (req && !tval) {
00555          ast_log(LOG_WARNING, "Required IE '%d' for security event "
00556                "type '%d' not present\n", ie_type->ie_type,
00557                sec->event_type);
00558          res = -1;
00559       }
00560 
00561       if (tval) {
00562          add_timeval_ie(event, ie_type->ie_type, tval);
00563       }
00564 
00565       break;
00566    }
00567    case AST_EVENT_IE_EVENT_TV:
00568    case AST_EVENT_IE_SEVERITY:
00569       /* Added automatically, nothing to do here. */
00570       break;
00571    default:
00572       ast_log(LOG_WARNING, "Unhandled IE type '%d', this security event "
00573             "will be missing data.\n", ie_type->ie_type);
00574       break;
00575    }
00576 
00577    return res;
00578 }

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

00457 {
00458    struct ast_str *str = ast_str_alloca(64);
00459 
00460    ast_str_set(&str, 0, "IPV4/");
00461 
00462    switch (addr->transport) {
00463    case AST_SECURITY_EVENT_TRANSPORT_UDP:
00464       ast_str_append(&str, 0, "UDP/");
00465       break;
00466    case AST_SECURITY_EVENT_TRANSPORT_TCP:
00467       ast_str_append(&str, 0, "TCP/");
00468       break;
00469    case AST_SECURITY_EVENT_TRANSPORT_TLS:
00470       ast_str_append(&str, 0, "TLS/");
00471       break;
00472    }
00473 
00474    ast_str_append(&str, 0, "%s/%hu",
00475          ast_inet_ntoa(addr->sin->sin_addr),
00476          ntohs(addr->sin->sin_port));
00477 
00478    return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
00479 }

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

00447 {
00448    struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);
00449 
00450    encode_timestamp(&str, tv);
00451 
00452    return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
00453 }

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

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, ast_security_event_common::service, str, and ast_security_event_common::version.

Referenced by handle_security_event().

00420 {
00421    struct ast_str *str = ast_str_alloca(TIMESTAMP_STR_LEN);
00422    struct timeval tv = ast_tvnow();
00423    const char *severity_str;
00424 
00425    if (check_event_type(sec->event_type)) {
00426       return NULL;
00427    }
00428 
00429    encode_timestamp(&str, &tv);
00430 
00431    severity_str = S_OR(
00432       ast_security_event_severity_get_name(sec_events[sec->event_type].severity),
00433       "Unknown"
00434    );
00435 
00436    return ast_event_new(AST_EVENT_SECURITY,
00437       AST_EVENT_IE_SECURITY_EVENT, AST_EVENT_IE_PLTYPE_UINT, sec->event_type,
00438       AST_EVENT_IE_EVENT_VERSION, AST_EVENT_IE_PLTYPE_UINT, sec->version,
00439       AST_EVENT_IE_EVENT_TV, AST_EVENT_IE_PLTYPE_STR, str->str,
00440       AST_EVENT_IE_SERVICE, AST_EVENT_IE_PLTYPE_STR, sec->service,
00441       AST_EVENT_IE_SEVERITY, AST_EVENT_IE_PLTYPE_STR, severity_str,
00442       AST_EVENT_IE_END);
00443 }

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

Referenced by security_event_cb().

00384 {
00385    if (check_event_type(event_type)) {
00386       return NULL;
00387    }
00388 
00389    return sec_events[event_type].name;
00390 }

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.

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

Referenced by handle_security_event(), and security_event_cb().

00404 {
00405    if (check_event_type(event_type)) {
00406       return NULL;
00407    }
00408 
00409    return sec_events[event_type].optional_ies;
00410 }

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.

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

Referenced by handle_security_event(), and security_event_cb().

00394 {
00395    if (check_event_type(event_type)) {
00396       return NULL;
00397    }
00398 
00399    return sec_events[event_type].required_ies;
00400 }

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

00622 {
00623    int res;
00624 
00625    if (sec->event_type < 0 || sec->event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
00626       ast_log(LOG_ERROR, "Invalid security event type\n");
00627       return -1;
00628    }
00629 
00630    if (!sec_events[sec->event_type].name) {
00631       ast_log(LOG_WARNING, "Security event type %u not handled\n",
00632             sec->event_type);
00633       return -1;
00634    }
00635 
00636    if (sec->version != sec_events[sec->event_type].version) {
00637       ast_log(LOG_WARNING, "Security event %u version mismatch\n",
00638             sec->event_type);
00639       return -1;
00640    }
00641 
00642    res = handle_security_event(sec);
00643 
00644    return res;
00645 }

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

00361 {
00362    unsigned int i;
00363 
00364    for (i = 0; i < ARRAY_LEN(severities); i++) {
00365       if (severities[i].severity == severity) {
00366          return severities[i].str;
00367       }
00368    }
00369 
00370    return NULL;
00371 }

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

00374 {
00375    if (event_type < 0 || event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
00376       ast_log(LOG_ERROR, "Invalid security event type %u\n", event_type);
00377       return -1;
00378    }
00379 
00380    return 0;
00381 }

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(), and str.

Referenced by add_timeval_ie(), and alloc_event().

00413 {
00414    ast_str_set(str, 0, "%u-%u",
00415          (unsigned int) tv->tv_sec,
00416          (unsigned int) tv->tv_usec);
00417 }

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, and NOT_REQUIRED.

Referenced by ast_security_event_report().

00581 {
00582    struct ast_event *event;
00583    const struct ast_security_event_ie_type *ies;
00584    unsigned int i;
00585 
00586    if (!(event = alloc_event(sec))) {
00587       return -1;
00588    }
00589 
00590    for (ies = ast_security_event_get_required_ies(sec->event_type), i = 0;
00591          ies[i].ie_type != AST_EVENT_IE_END;
00592          i++) {
00593       if (add_ie(&event, sec, ies + i, REQUIRED)) {
00594          goto return_error;
00595       }
00596    }
00597 
00598    for (ies = ast_security_event_get_optional_ies(sec->event_type), i = 0;
00599          ies[i].ie_type != AST_EVENT_IE_END;
00600          i++) {
00601       if (add_ie(&event, sec, ies + i, NOT_REQUIRED)) {
00602          goto return_error;
00603       }
00604    }
00605 
00606 
00607    if (ast_event_queue(event)) {
00608       goto return_error;
00609    }
00610 
00611    return 0;
00612 
00613 return_error:
00614    if (event) {
00615       ast_event_destroy(event);
00616    }
00617 
00618    return -1;
00619 }


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]

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

Referenced by ast_security_event_severity_get_name().

enum ast_security_event_severity severity

Definition at line 352 of file security_events.c.

enum ast_security_event_severity severity

Definition at line 41 of file security_events.c.

const char* str

Definition at line 353 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_remotecontrol(), ast_rtp_read(), ast_var_Version(), check_access(), config_module(), dump_versioned_codec(), iax_parse_ies(), ldap_reconnect(), manager_modulecheck(), parse_config(), and update_registry().


Generated on Wed Apr 6 11:30:10 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7