Wed Jan 8 2020 09:50:20

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.

Macros

#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_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. More...
 
struct 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. More...
 
struct 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. More...
 
int ast_security_event_report (const struct ast_security_event_common *sec)
 Report a security event. More...
 
const char * ast_security_event_severity_get_name (const enum ast_security_event_severity severity)
 Get the name of a security event severity. More...
 
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 russe.nosp@m.ll@d.nosp@m.igium.nosp@m..com

Definition in file security_events.c.

Macro Definition Documentation

#define MAX_SECURITY_IES   12

Definition at line 46 of file security_events.c.

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

Enumeration Type Documentation

Enumerator
NOT_REQUIRED 
REQUIRED 
NOT_REQUIRED 
REQUIRED 

Definition at line 485 of file security_events.c.

485  {
486  NOT_REQUIRED,
487  REQUIRED
488 };

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 490 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_common::event_type, 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().

492 {
493  int res = 0;
494 
495  switch (ie_type->ie_type) {
499  case AST_EVENT_IE_MODULE:
507  {
508  const char *str;
509 
510  str = *((const char **)(((const char *) sec) + ie_type->offset));
511 
512  if (req && !str) {
513  ast_log(LOG_WARNING, "Required IE '%d' for security event "
514  "type '%u' not present\n", ie_type->ie_type,
515  sec->event_type);
516  res = -1;
517  }
518 
519  if (str) {
520  res = ast_event_append_ie_str(event, ie_type->ie_type, str);
521  }
522 
523  break;
524  }
526  {
527  uint32_t val;
528  val = *((const uint32_t *)(((const char *) sec) + ie_type->offset));
529  res = ast_event_append_ie_uint(event, ie_type->ie_type, val);
530  break;
531  }
535  {
536  const struct ast_security_event_ipv4_addr *addr;
537 
538  addr = (const struct ast_security_event_ipv4_addr *)(((const char *) sec) + ie_type->offset);
539 
540  if (req && !addr->sin) {
541  ast_log(LOG_WARNING, "Required IE '%d' for security event "
542  "type '%u' not present\n", ie_type->ie_type,
543  sec->event_type);
544  res = -1;
545  }
546 
547  if (addr->sin) {
548  res = add_ipv4_ie(event, ie_type->ie_type, addr);
549  }
550  break;
551  }
553  {
554  const struct timeval *tval;
555 
556  tval = *((const struct timeval **)(((const char *) sec) + ie_type->offset));
557 
558  if (req && !tval) {
559  ast_log(LOG_WARNING, "Required IE '%d' for security event "
560  "type '%u' not present\n", ie_type->ie_type,
561  sec->event_type);
562  res = -1;
563  }
564 
565  if (tval) {
566  add_timeval_ie(event, ie_type->ie_type, tval);
567  }
568 
569  break;
570  }
573  /* Added automatically, nothing to do here. */
574  break;
575  default:
576  ast_log(LOG_WARNING, "Unhandled IE type '%d', this security event "
577  "will be missing data.\n", ie_type->ie_type);
578  break;
579  }
580 
581  return res;
582 }
enum ast_security_event_type event_type
The security event sub-type.
Definition: ast_expr2.c:325
#define LOG_WARNING
Definition: logger.h:144
size_t offset
For internal usage.
const char * str
Definition: app_jack.c:144
static int add_ipv4_ie(struct ast_event **event, enum ast_event_ie_type ie_type, const struct ast_security_event_ipv4_addr *addr)
enum ast_event_ie_type ie_type
static int add_timeval_ie(struct ast_event **event, enum ast_event_ie_type ie_type, const struct timeval *tv)
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
int ast_event_append_ie_uint(struct ast_event **event, enum ast_event_ie_type ie_type, uint32_t data)
Append an information element that has an integer payload.
Definition: event.c:1160
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 459 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().

461 {
462  struct ast_str *str = ast_str_alloca(64);
463 
464  ast_str_set(&str, 0, "IPV4/");
465 
466  switch (addr->transport) {
468  ast_str_append(&str, 0, "UDP/");
469  break;
471  ast_str_append(&str, 0, "TCP/");
472  break;
474  ast_str_append(&str, 0, "TLS/");
475  break;
476  }
477 
478  ast_str_append(&str, 0, "%s/%hu",
479  ast_inet_ntoa(addr->sin->sin_addr),
480  ntohs(addr->sin->sin_port));
481 
482  return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
483 }
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
int ast_str_append(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Append to a thread local dynamic string.
Definition: strings.h:900
#define ast_str_alloca(init_len)
Definition: strings.h:608
const char * str
Definition: app_jack.c:144
enum ast_security_event_transport_type transport
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:874
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
const char * ast_inet_ntoa(struct in_addr ia)
thread-safe replacement for inet_ntoa().
Definition: utils.c:564
static int add_timeval_ie ( struct ast_event **  event,
enum ast_event_ie_type  ie_type,
const struct timeval *  tv 
)
static

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

451 {
453 
454  encode_timestamp(&str, tv);
455 
456  return ast_event_append_ie_str(event, ie_type, ast_str_buffer(str));
457 }
static void encode_timestamp(struct ast_str **str, const struct timeval *tv)
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
#define ast_str_alloca(init_len)
Definition: strings.h:608
const char * str
Definition: app_jack.c:144
static const size_t TIMESTAMP_STR_LEN
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
int ast_event_append_ie_str(struct ast_event **event, enum ast_event_ie_type ie_type, const char *str)
Append an information element that has a string payload.
Definition: event.c:1139
struct timeval tv
static struct ast_event* alloc_event ( const struct ast_security_event_common sec)
static

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

424 {
426  struct timeval tv = ast_tvnow();
427  const char *severity_str;
428 
429  if (check_event_type(sec->event_type)) {
430  return NULL;
431  }
432 
433  encode_timestamp(&str, &tv);
434 
435  severity_str = S_OR(
437  "Unknown"
438  );
439 
447 }
enum ast_security_event_type event_type
The security event sub-type.
static void encode_timestamp(struct ast_str **str, const struct timeval *tv)
const char * service
Service that generated the event.
char * ast_str_buffer(const struct ast_str *buf)
Returns the string buffer within the ast_str buf.
Definition: strings.h:497
const char * ast_security_event_severity_get_name(const enum ast_security_event_severity severity)
Get the name of a security event severity.
struct timeval ast_tvnow(void)
Returns current timeval. Meant to replace calls to gettimeofday().
Definition: time.h:142
#define ast_str_alloca(init_len)
Definition: strings.h:608
const char * str
Definition: app_jack.c:144
uint32_t version
security event version
static struct @298 sec_events[AST_SECURITY_EVENT_NUM_TYPES]
static const size_t TIMESTAMP_STR_LEN
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
struct ast_event * ast_event_new(enum ast_event_type event_type,...)
Create a new event.
Definition: event.c:1202
#define S_OR(a, b)
returns the equivalent of logic or for strings: first one if not empty, otherwise second one...
Definition: strings.h:77
struct timeval tv
static int check_event_type(const enum ast_security_event_type event_type)
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_typesecurity event sub-type
Return values
NULLif event_type is invalid
non-NULLthe name of the security event type
Since
1.8

Definition at line 387 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by security_event_cb().

388 {
389  if (check_event_type(event_type)) {
390  return NULL;
391  }
392 
393  return sec_events[event_type].name;
394 }
static struct @298 sec_events[AST_SECURITY_EVENT_NUM_TYPES]
static int check_event_type(const enum ast_security_event_type event_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.

Parameters
[in]event_typesecurity event sub-type
Return values
NULLinvalid event_type
non-NULLAn array terminated with the value AST_EVENT_IE_END
Since
1.8

Definition at line 406 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

408 {
409  if (check_event_type(event_type)) {
410  return NULL;
411  }
412 
413  return sec_events[event_type].optional_ies;
414 }
static struct @298 sec_events[AST_SECURITY_EVENT_NUM_TYPES]
static int check_event_type(const enum ast_security_event_type event_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.

Parameters
[in]event_typesecurity event sub-type
Return values
NULLinvalid event_type
non-NULLAn array terminated with the value AST_EVENT_IE_END
Since
1.8

Definition at line 396 of file security_events.c.

References check_event_type(), and sec_events.

Referenced by handle_security_event(), and security_event_cb().

398 {
399  if (check_event_type(event_type)) {
400  return NULL;
401  }
402 
403  return sec_events[event_type].required_ies;
404 }
static struct @298 sec_events[AST_SECURITY_EVENT_NUM_TYPES]
static int check_event_type(const enum ast_security_event_type event_type)
int ast_security_event_report ( const struct ast_security_event_common sec)

Report a security event.

Parameters
[in]secsecurity 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
0success
non-zerofailure

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

626 {
627  int res;
628 
629  if (sec->event_type < 0 || sec->event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
630  ast_log(LOG_ERROR, "Invalid security event type\n");
631  return -1;
632  }
633 
634  if (!sec_events[sec->event_type].name) {
635  ast_log(LOG_WARNING, "Security event type %u not handled\n",
636  sec->event_type);
637  return -1;
638  }
639 
640  if (sec->version != sec_events[sec->event_type].version) {
641  ast_log(LOG_WARNING, "Security event %u version mismatch\n",
642  sec->event_type);
643  return -1;
644  }
645 
646  res = handle_security_event(sec);
647 
648  return res;
649 }
enum ast_security_event_type event_type
The security event sub-type.
#define LOG_WARNING
Definition: logger.h:144
uint32_t version
security event version
static struct @298 sec_events[AST_SECURITY_EVENT_NUM_TYPES]
#define LOG_ERROR
Definition: logger.h:155
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static int handle_security_event(const struct ast_security_event_common *sec)
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]severitysecurity event severity
Return values
NULLif severity is invalid
non-NULLthe name of the security event severity
Since
1.8

Definition at line 363 of file security_events.c.

References ARRAY_LEN, and severities.

Referenced by alloc_event().

365 {
366  unsigned int i;
367 
368  for (i = 0; i < ARRAY_LEN(severities); i++) {
369  if (severities[i].severity == severity) {
370  return severities[i].str;
371  }
372  }
373 
374  return NULL;
375 }
#define ARRAY_LEN(a)
Definition: isdn_lib.c:42
static struct @299 severities[]
enum ast_security_event_severity severity
static int check_event_type ( const enum ast_security_event_type  event_type)
static

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

378 {
379  if (event_type < 0 || event_type >= AST_SECURITY_EVENT_NUM_TYPES) {
380  ast_log(LOG_ERROR, "Invalid security event type %u\n", event_type);
381  return -1;
382  }
383 
384  return 0;
385 }
#define LOG_ERROR
Definition: logger.h:155
void ast_log(int level, const char *file, int line, const char *function, const char *fmt,...)
Used for sending a log message This is the standard logger function. Probably the only way you will i...
Definition: logger.c:1207
static void encode_timestamp ( struct ast_str **  str,
const struct timeval *  tv 
)
static

Definition at line 416 of file security_events.c.

References ast_str_set().

Referenced by add_timeval_ie(), and alloc_event().

417 {
418  ast_str_set(str, 0, "%u-%u",
419  (unsigned int) tv->tv_sec,
420  (unsigned int) tv->tv_usec);
421 }
int ast_str_set(struct ast_str **buf, ssize_t max_len, const char *fmt,...)
Set a dynamic string using variable arguments.
Definition: strings.h:874
struct timeval tv
static int handle_security_event ( const struct ast_security_event_common sec)
static

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

585 {
586  struct ast_event *event;
587  const struct ast_security_event_ie_type *ies;
588  unsigned int i;
589 
590  if (!(event = alloc_event(sec))) {
591  return -1;
592  }
593 
594  for (ies = ast_security_event_get_required_ies(sec->event_type), i = 0;
595  ies[i].ie_type != AST_EVENT_IE_END;
596  i++) {
597  if (add_ie(&event, sec, ies + i, REQUIRED)) {
598  goto return_error;
599  }
600  }
601 
602  for (ies = ast_security_event_get_optional_ies(sec->event_type), i = 0;
603  ies[i].ie_type != AST_EVENT_IE_END;
604  i++) {
605  if (add_ie(&event, sec, ies + i, NOT_REQUIRED)) {
606  goto return_error;
607  }
608  }
609 
610 
611  if (ast_event_queue(event)) {
612  goto return_error;
613  }
614 
615  return 0;
616 
617 return_error:
618  if (event) {
619  ast_event_destroy(event);
620  }
621 
622  return -1;
623 }
An event.
Definition: event.c:85
enum ast_security_event_type event_type
The 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.
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)
int ast_event_queue(struct ast_event *event)
Queue an event.
Definition: event.c:1517
enum ast_event_ie_type ie_type
static struct ast_event * alloc_event(const struct ast_security_event_common *sec)
void ast_event_destroy(struct ast_event *event)
Destroy an event.
Definition: event.c:1314

Variable Documentation

const char* name

Definition at line 43 of file security_events.c.

Definition at line 48 of file security_events.c.

Definition at line 47 of file security_events.c.

struct { ... } severities[]
Initial value:
= {
{ AST_SECURITY_EVENT_SEVERITY_INFO, "Informational" },
}
Informational event, not something that has gone wrong.

Referenced by ast_security_event_severity_get_name().

Definition at line 45 of file security_events.c.

const char* str

Definition at line 357 of file security_events.c.

const size_t TIMESTAMP_STR_LEN = 32
static

Definition at line 40 of file security_events.c.