Security Event Reporting API. More...

#include "asterisk/event.h"
#include "asterisk/security_events_defs.h"

Include dependency graph for security_events.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ast_security_event_ie_type

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

const 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. More...

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

struct stasis_message_type *	ast_security_event_type (void)
	A stasis_message_type for security events. More...

int	ast_security_stasis_init (void)
	initializes stasis topic/event types for ast_security_topic and ast_security_event_type More...

struct stasis_topic *	ast_security_topic (void)
	A stasis_topic which publishes messages for security related issues. More...

Detailed Description

Security Event Reporting API.

Author: Russell Bryant russe.nosp@m.ll@d.nosp@m.igium.nosp@m..com

Definition in file security_events.h.

Function Documentation

◆ ast_security_event_get_name()

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 895 of file main/security_events.c.

{
    if (check_event_type(event_type)) {
        return NULL;
    }
 
    return sec_events[event_type].name;
}

References check_event_type(), NULL, and sec_events.

Referenced by add_json_object(), ast_security_event_report(), gen_events(), security_event_stasis_cb(), and security_event_to_ami_blob().

◆ ast_security_event_get_optional_ies()

const 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 914 of file main/security_events.c.

{
    if (check_event_type(event_type)) {
        return NULL;
    }
 
    return sec_events[event_type].optional_ies;
}

References check_event_type(), NULL, and sec_events.

Referenced by handle_security_event(), security_event_stasis_cb(), and security_event_to_ami_blob().

◆ ast_security_event_get_required_ies()

const 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 904 of file main/security_events.c.

{
    if (check_event_type(event_type)) {
        return NULL;
    }
 
    return sec_events[event_type].required_ies;
}

References check_event_type(), NULL, and sec_events.

Referenced by handle_security_event(), security_event_stasis_cb(), and security_event_to_ami_blob().

◆ ast_security_event_report()

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 1171 of file main/security_events.c.

{
    if ((unsigned int)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;
    }
 
    if (handle_security_event(sec)) {
        ast_log(LOG_ERROR, "Failed to issue security event of type %s.\n",
                ast_security_event_get_name(sec->event_type));
    }
 
    return 0;
}

References ast_log, ast_security_event_get_name(), 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 ast_sip_report_auth_challenge_sent(), ast_sip_report_auth_failed_challenge_response(), ast_sip_report_auth_success(), ast_sip_report_failed_acl(), ast_sip_report_invalid_endpoint(), ast_sip_report_mem_limit(), ast_sip_report_req_no_support(), evt_gen_auth_method_not_allowed(), evt_gen_chal_resp_failed(), evt_gen_chal_sent(), evt_gen_failed_acl(), evt_gen_inval_acct_id(), evt_gen_inval_password(), evt_gen_inval_transport(), evt_gen_load_avg(), evt_gen_mem_limit(), evt_gen_req_bad_format(), evt_gen_req_no_support(), evt_gen_req_not_allowed(), evt_gen_session_limit(), evt_gen_successful_auth(), evt_gen_unexpected_addr(), 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().

◆ ast_security_event_severity_get_name()

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 871 of file main/security_events.c.

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

References ARRAY_LEN, NULL, severities, and severity.

Referenced by alloc_security_event_json_object().

◆ ast_security_event_type()

struct stasis_message_type * ast_security_event_type ( void )

A stasis_message_type for security events.

Since: 12

Return values

NULL on error

Returns: stasis_message_type for security events

Note: Messages of this type should always be issued on and expected from the ast_security_topic stasis_topic

◆ ast_security_stasis_init()

int ast_security_stasis_init ( void )

initializes stasis topic/event types for ast_security_topic and ast_security_event_type

Since: 12

Return values

0	on success
-1	on failure

Definition at line 483 of file main/security_events.c.

{
    ast_register_cleanup(security_stasis_cleanup);
 
    security_topic = stasis_topic_create("security:all");
    if (!security_topic) {
        return -1;
    }
 
    if (STASIS_MESSAGE_TYPE_INIT(ast_security_event_type)) {
        return -1;
    }
 
 
    return 0;
}