Custom function management routines. More...

#include "asterisk.h"
#include "asterisk/_private.h"
#include "asterisk/cli.h"
#include "asterisk/linkedlists.h"
#include "asterisk/module.h"
#include "asterisk/pbx.h"
#include "asterisk/term.h"
#include "asterisk/threadstorage.h"
#include "asterisk/xmldoc.h"
#include "pbx_private.h"

Include dependency graph for pbx_functions.c:

Go to the source code of this file.

Data Structures
struct	acf_root
	Registered functions container. More...

Functions
int	__ast_custom_function_register (struct ast_custom_function acf, struct ast_module mod)
	Register a custom function.

int	__ast_custom_function_register_escalating (struct ast_custom_function acf, enum ast_custom_function_escalation escalation, struct ast_module mod)
	Register a custom function which requires escalated privileges.

static int	acf_retrieve_docs (struct ast_custom_function *acf)

struct ast_custom_function *	ast_custom_function_find (const char *name)

static struct ast_custom_function *	ast_custom_function_find_nolock (const char *name)

int	ast_custom_function_unregister (struct ast_custom_function *acf)
	Unregister a custom function.

int	ast_func_read (struct ast_channel chan, const char function, char *workspace, size_t len)
	executes a read operation on a function

int	ast_func_read2 (struct ast_channel chan, const char function, struct ast_str **str, ssize_t maxlen)
	executes a read operation on a function

int	ast_func_write (struct ast_channel chan, const char function, const char *value)
	executes a write operation on a function

int	ast_thread_inhibit_escalations (void)
	Inhibit (in the current thread) the execution of dialplan functions which cause privilege escalations. If pbx_live_dangerously() has been called, this function has no effect.

int	ast_thread_inhibit_escalations_swap (int inhibit)
	Swap the current thread escalation inhibit setting.

	AST_THREADSTORAGE_CUSTOM_SCOPE (thread_inhibit_escalations_tl, NULL, ast_free_ptr, static)
	A thread local indicating whether the current thread can run 'dangerous' dialplan functions.

static char *	complete_functions (const char *word, int pos, int state)

static char *	func_args (char *function)
	return a pointer to the arguments of the function, and terminates the function name with '\0'

static char *	handle_show_function (struct ast_cli_entry e, int cmd, struct ast_cli_args a)

static char *	handle_show_functions (struct ast_cli_entry e, int cmd, struct ast_cli_args a)

static int	is_read_allowed (struct ast_custom_function *acfptr)
	Determines whether execution of a custom function's read function is allowed.

static int	is_write_allowed (struct ast_custom_function *acfptr)
	Determines whether execution of a custom function's write function is allowed.

int	load_pbx_functions_cli (void)

void	pbx_live_dangerously (int new_live_dangerously)
	Enable/disable the execution of 'dangerous' functions from external protocols (AMI, etc.).

static int	read_escalates (const struct ast_custom_function *acf)
	Returns true if given custom function escalates privileges on read.

static int	thread_inhibits_escalations (void)
	Indicates whether the current thread inhibits the execution of dangerous functions.

static void	unload_pbx_functions_cli (void)

static int	write_escalates (const struct ast_custom_function *acf)
	Returns true if given custom function escalates privileges on write.

Variables
static struct ast_cli_entry	acf_cli []

static struct acf_root	acf_root = AST_RWLIST_HEAD_INIT_VALUE

static int	live_dangerously
	Set to true (non-zero) to globally allow all dangerous dialplan functions to run.

Detailed Description

Custom function management routines.

Author: Corey Farrell git@c.nosp@m.fwar.nosp@m.e.com

Definition in file pbx_functions.c.

Function Documentation

◆ __ast_custom_function_register()

int __ast_custom_function_register	(	struct ast_custom_function *	acf,
		struct ast_module *	mod
	)

Register a custom function.

Definition at line 388 of file pbx_functions.c.

{
    struct ast_custom_function *cur;
 
    if (!acf) {
        return -1;
    }
 
    acf->mod = mod;
#ifdef AST_XML_DOCS
    acf->docsrc = AST_STATIC_DOC;
#endif
 
    if (acf_retrieve_docs(acf)) {
        return -1;
    }
 
    AST_RWLIST_WRLOCK(&acf_root);
 
    cur = ast_custom_function_find_nolock(acf->name);
    if (cur) {
        ast_log(LOG_ERROR, "Function %s already registered.\n", acf->name);
        AST_RWLIST_UNLOCK(&acf_root);
        return -1;
    }
 
    /* Store in alphabetical order */
    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&acf_root, cur, acflist) {
        if (strcmp(acf->name, cur->name) < 0) {
            AST_RWLIST_INSERT_BEFORE_CURRENT(acf, acflist);
            break;
        }
    }
    AST_RWLIST_TRAVERSE_SAFE_END;
    if (!cur) {
        AST_RWLIST_INSERT_TAIL(&acf_root, acf, acflist);
    }
 
    AST_RWLIST_UNLOCK(&acf_root);
 
    ast_verb(5, "Registered custom function '" COLORIZE_FMT "'\n", COLORIZE(COLOR_BRCYAN, 0, acf->name));
 
    return 0;
}

References acf_retrieve_docs(), ast_custom_function::acflist, ast_custom_function_find_nolock(), ast_log, AST_RWLIST_INSERT_BEFORE_CURRENT, AST_RWLIST_INSERT_TAIL, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, AST_STATIC_DOC, ast_verb, COLOR_BRCYAN, COLORIZE, COLORIZE_FMT, ast_custom_function::docsrc, LOG_ERROR, ast_custom_function::mod, and ast_custom_function::name.

Referenced by __ast_custom_function_register_escalating(), __init_manager(), ast_msg_init(), load_features_config(), and load_pbx().

◆ __ast_custom_function_register_escalating()

int __ast_custom_function_register_escalating	(	struct ast_custom_function *	acf,
		enum ast_custom_function_escalation	escalation,
		struct ast_module *	mod
	)

Register a custom function which requires escalated privileges.

Examples would be SHELL() (for which a read needs permission to execute arbitrary code) or FILE() (for which write needs permission to change files on the filesystem).

Definition at line 433 of file pbx_functions.c.

{
    int res;
 
    res = __ast_custom_function_register(acf, mod);
    if (res != 0) {
        return -1;
    }
 
    switch (escalation) {
    case AST_CFE_NONE:
        break;
    case AST_CFE_READ:
        acf->read_escalates = 1;
        break;
    case AST_CFE_WRITE:
        acf->write_escalates = 1;
        break;
    case AST_CFE_BOTH:
        acf->read_escalates = 1;
        acf->write_escalates = 1;
        break;
    }
 
    return 0;
}

References __ast_custom_function_register(), AST_CFE_BOTH, AST_CFE_NONE, AST_CFE_READ, AST_CFE_WRITE, ast_custom_function::mod, ast_custom_function::read_escalates, and ast_custom_function::write_escalates.

◆ acf_retrieve_docs()

static int acf_retrieve_docs ( struct ast_custom_function * acf )

static

Definition at line 323 of file pbx_functions.c.

{
#ifdef AST_XML_DOCS
    char *tmpxml;
 
    /* Let's try to find it in the Documentation XML */
    if (!ast_strlen_zero(acf->desc) || !ast_strlen_zero(acf->synopsis)) {
        return 0;
    }
 
    if (ast_string_field_init(acf, 128)) {
        return -1;
    }
 
    if (ast_string_field_init_extended(acf, since)) {
        ast_string_field_free_memory(acf);
        return -1;
    }
 
    if (ast_string_field_init_extended(acf, provided_by)) {
        ast_string_field_free_memory(acf);
        return -1;
    }
 
    /* load synopsis */
    tmpxml = ast_xmldoc_build_synopsis("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, synopsis, tmpxml);
    ast_free(tmpxml);
 
    /* load provided_by */
    tmpxml = ast_xmldoc_build_provided_by("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, provided_by, tmpxml);
    ast_free(tmpxml);
 
    /* load since */
    tmpxml = ast_xmldoc_build_since("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, since, tmpxml);
    ast_free(tmpxml);
 
    /* load description */
    tmpxml = ast_xmldoc_build_description("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, desc, tmpxml);
    ast_free(tmpxml);
 
    /* load syntax */
    tmpxml = ast_xmldoc_build_syntax("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, syntax, tmpxml);
    ast_free(tmpxml);
 
    /* load arguments */
    tmpxml = ast_xmldoc_build_arguments("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, arguments, tmpxml);
    ast_free(tmpxml);
 
    /* load seealso */
    tmpxml = ast_xmldoc_build_seealso("function", acf->name, ast_module_name(acf->mod));
    ast_string_field_set(acf, seealso, tmpxml);
    ast_free(tmpxml);
 
    acf->docsrc = AST_XML_DOC;
#endif
 
    return 0;
}

References ast_custom_function::arguments, ast_free, ast_module_name(), ast_string_field_free_memory, ast_string_field_init, ast_string_field_init_extended, ast_string_field_set, ast_strlen_zero(), AST_XML_DOC, ast_xmldoc_build_arguments(), ast_xmldoc_build_description(), ast_xmldoc_build_provided_by(), ast_xmldoc_build_seealso(), ast_xmldoc_build_since(), ast_xmldoc_build_synopsis(), ast_xmldoc_build_syntax(), desc, ast_custom_function::desc, ast_custom_function::docsrc, ast_custom_function::mod, ast_custom_function::name, ast_custom_function::seealso, synopsis, ast_custom_function::synopsis, and ast_custom_function::syntax.

Referenced by __ast_custom_function_register().

◆ ast_custom_function_find()

struct ast_custom_function * ast_custom_function_find ( const char * name )

Definition at line 257 of file pbx_functions.c.

{
    struct ast_custom_function *acf;
 
    AST_RWLIST_RDLOCK(&acf_root);
    acf = ast_custom_function_find_nolock(name);
    AST_RWLIST_UNLOCK(&acf_root);
 
    return acf;
}

References ast_custom_function_find_nolock(), AST_RWLIST_RDLOCK, AST_RWLIST_UNLOCK, and name.

Referenced by ast_func_read(), ast_func_read2(), ast_func_write(), and handle_show_function().

◆ ast_custom_function_find_nolock()

static struct ast_custom_function * ast_custom_function_find_nolock ( const char * name )

static

Definition at line 235 of file pbx_functions.c.

{
    struct ast_custom_function *cur;
    int cmp;
 
    AST_RWLIST_TRAVERSE(&acf_root, cur, acflist) {
        cmp = strcmp(name, cur->name);
        if (cmp > 0) {
            continue;
        }
        if (!cmp) {
            /* Found it. */
            break;
        }
        /* Not in container. */
        cur = NULL;
        break;
    }
 
    return cur;
}

References ast_custom_function::acflist, AST_RWLIST_TRAVERSE, name, ast_custom_function::name, and NULL.

Referenced by __ast_custom_function_register(), and ast_custom_function_find().

◆ ast_custom_function_unregister()

int ast_custom_function_unregister ( struct ast_custom_function * acf )

Unregister a custom function.

Definition at line 268 of file pbx_functions.c.

{
    struct ast_custom_function *cur;
 
    if (!acf) {
        return -1;
    }
 
    AST_RWLIST_WRLOCK(&acf_root);
    cur = AST_RWLIST_REMOVE(&acf_root, acf, acflist);
    if (cur) {
#ifdef AST_XML_DOCS
        if (cur->docsrc == AST_XML_DOC) {
            ast_string_field_free_memory(acf);
        }
#endif
        ast_verb(5, "Unregistered custom function %s\n", cur->name);
    }
    AST_RWLIST_UNLOCK(&acf_root);
 
    return cur ? 0 : -1;
}

References ast_custom_function::acflist, AST_RWLIST_REMOVE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_string_field_free_memory, ast_verb, AST_XML_DOC, ast_custom_function::docsrc, and ast_custom_function::name.

◆ ast_func_read()

int ast_func_read	(	struct ast_channel *	chan,
		const char *	function,
		char *	workspace,
		size_t	len
	)

executes a read operation on a function

Parameters

chan	Channel to execute on
function	Data containing the function call string (will be modified)
workspace	A pointer to safe memory to use for a return value
len	the number of bytes in workspace

This application executes a function in read mode on a given channel.

Return values

0	success
non-zero	failure

Definition at line 614 of file pbx_functions.c.

{
    char *copy = ast_strdupa(function);
    char *args = func_args(copy);
    struct ast_custom_function *acfptr = ast_custom_function_find(copy);
    int res;
    struct ast_module_user *u = NULL;
 
    if (acfptr == NULL) {
        ast_log(LOG_ERROR, "Function %s not registered\n", copy);
    } else if (!acfptr->read && !acfptr->read2) {
        ast_log(LOG_ERROR, "Function %s cannot be read\n", copy);
    } else if (!is_read_allowed(acfptr)) {
        ast_log(LOG_ERROR, "Dangerous function %s read blocked\n", copy);
    } else if (acfptr->read) {
        if (acfptr->mod) {
            u = __ast_module_user_add(acfptr->mod, chan);
        }
        res = acfptr->read(chan, copy, args, workspace, len);
        if (acfptr->mod && u) {
            __ast_module_user_remove(acfptr->mod, u);
        }
 
        return res;
    } else {
        struct ast_str *str = ast_str_create(16);
 
        if (acfptr->mod) {
            u = __ast_module_user_add(acfptr->mod, chan);
        }
        res = acfptr->read2(chan, copy, args, &str, 0);
        if (acfptr->mod && u) {
            __ast_module_user_remove(acfptr->mod, u);
        }
        ast_copy_string(workspace, ast_str_buffer(str), len > ast_str_size(str) ? ast_str_size(str) : len);
        ast_free(str);
 
        return res;
    }
 
    return -1;
}

References __ast_module_user_add(), __ast_module_user_remove(), args, ast_copy_string(), ast_custom_function_find(), ast_free, ast_log, ast_str_buffer(), ast_str_create, ast_str_size(), ast_strdupa, ast_module_user::chan, copy(), func_args(), is_read_allowed(), len(), LOG_ERROR, ast_custom_function::mod, NULL, ast_custom_function::read, ast_custom_function::read2, and str.

Referenced by action_getvar(), assign_uuid(), fetch_access_token(), fetch_google_access_token(), generate_status(), handle_eval_function(), handle_getvariable(), lua_get_variable_value(), and pbx_substitute_variables_helper_full_location().

◆ ast_func_read2()

int ast_func_read2	(	struct ast_channel *	chan,
		const char *	function,
		struct ast_str **	str,
		ssize_t	maxlen
	)

executes a read operation on a function

Parameters

chan	Channel to execute on
function	Data containing the function call string (will be modified)
str	A dynamic string buffer into which to place the result.
maxlen	<0 if the dynamic buffer should not grow; >0 if the dynamic buffer should be limited to that number of bytes; 0 if the dynamic buffer has no upper limit

This application executes a function in read mode on a given channel.

Return values

0	success
non-zero	failure

Definition at line 657 of file pbx_functions.c.

{
    char *copy = ast_strdupa(function);
    char *args = func_args(copy);
    struct ast_custom_function *acfptr = ast_custom_function_find(copy);
    int res;
    struct ast_module_user *u = NULL;
 
    if (acfptr == NULL) {
        ast_log(LOG_ERROR, "Function %s not registered\n", copy);
    } else if (!acfptr->read && !acfptr->read2) {
        ast_log(LOG_ERROR, "Function %s cannot be read\n", copy);
    } else if (!is_read_allowed(acfptr)) {
        ast_log(LOG_ERROR, "Dangerous function %s read blocked\n", copy);
    } else {
        if (acfptr->mod) {
            u = __ast_module_user_add(acfptr->mod, chan);
        }
        ast_str_reset(*str);
        if (acfptr->read2) {
            /* ast_str enabled */
            res = acfptr->read2(chan, copy, args, str, maxlen);
        } else {
            /* Legacy function pointer, allocate buffer for result */
            int maxsize = ast_str_size(*str);
 
            if (maxlen > -1) {
                if (maxlen == 0) {
                    if (acfptr->read_max) {
                        maxsize = acfptr->read_max;
                    } else {
                        maxsize = VAR_BUF_SIZE;
                    }
                } else {
                    maxsize = maxlen;
                }
                ast_str_make_space(str, maxsize);
            }
            res = acfptr->read(chan, copy, args, ast_str_buffer(*str), maxsize);
            ast_str_update(*str); /* Manually set the string length */
        }
        if (acfptr->mod && u) {
            __ast_module_user_remove(acfptr->mod, u);
        }
 
        return res;
    }
 
    return -1;
}

References __ast_module_user_add(), __ast_module_user_remove(), args, ast_custom_function_find(), ast_log, ast_str_buffer(), ast_str_make_space, ast_str_reset(), ast_str_size(), ast_str_update(), ast_strdupa, ast_module_user::chan, copy(), func_args(), is_read_allowed(), LOG_ERROR, maxsize, ast_custom_function::mod, NULL, ast_custom_function::read, ast_custom_function::read2, ast_custom_function::read_max, str, and VAR_BUF_SIZE.

Referenced by ast_ari_channels_get_channel_var(), ast_str_substitute_variables_full2(), AST_TEST_DEFINE(), AST_TEST_DEFINE(), and channel_get_external_vars().

◆ ast_func_write()

int ast_func_write	(	struct ast_channel *	chan,
		const char *	function,
		const char *	value
	)

executes a write operation on a function

Parameters

chan	Channel to execute on
function	Data containing the function call string (will be modified)
value	A value parameter to pass for writing

This application executes a function in write mode on a given channel.

Return values

0	success
non-zero	failure

Definition at line 708 of file pbx_functions.c.

{
    char *copy = ast_strdupa(function);
    char *args = func_args(copy);
    struct ast_custom_function *acfptr = ast_custom_function_find(copy);
 
    if (acfptr == NULL) {
        ast_log(LOG_ERROR, "Function %s not registered\n", copy);
    } else if (!acfptr->write) {
        ast_log(LOG_ERROR, "Function %s cannot be written to\n", copy);
    } else if (!is_write_allowed(acfptr)) {
        ast_log(LOG_ERROR, "Dangerous function %s write blocked\n", copy);
    } else {
        int res;
        struct ast_module_user *u = NULL;
 
        if (acfptr->mod) {
            u = __ast_module_user_add(acfptr->mod, chan);
        }
        res = acfptr->write(chan, copy, args, value);
        if (acfptr->mod && u) {
            __ast_module_user_remove(acfptr->mod, u);
        }
 
        return res;
    }
 
    return -1;
}

References __ast_module_user_add(), __ast_module_user_remove(), args, ast_custom_function_find(), ast_log, ast_strdupa, ast_module_user::chan, copy(), func_args(), is_write_allowed(), LOG_ERROR, ast_custom_function::mod, NULL, value, and ast_custom_function::write.

Referenced by ast_channel_hangupcause_hash_set(), AST_TEST_DEFINE(), chanavail_exec(), conf_run(), conf_run(), confbridge_exec(), disa_exec(), fetch_google_access_token(), pbx_builtin_pushvar_helper(), pbx_builtin_setvar_helper(), setup_profile_bridge(), setup_profile_caller(), and setup_profile_paged().

◆ ast_thread_inhibit_escalations()

int ast_thread_inhibit_escalations ( void )

Inhibit (in the current thread) the execution of dialplan functions which cause privilege escalations. If pbx_live_dangerously() has been called, this function has no effect.

Returns: 0 if successfuly marked current thread.; Non-zero if marking current thread failed.

Definition at line 494 of file pbx_functions.c.

{
    int *thread_inhibit_escalations;
 
    thread_inhibit_escalations = ast_threadstorage_get(
        &thread_inhibit_escalations_tl, sizeof(*thread_inhibit_escalations));
    if (thread_inhibit_escalations == NULL) {
        ast_log(LOG_ERROR, "Error inhibiting privilege escalations for current thread\n");
        return -1;
    }
 
    *thread_inhibit_escalations = 1;
    return 0;
}

References ast_log, ast_threadstorage_get(), LOG_ERROR, and NULL.

Referenced by ast_add_extension2_lockopt(), and handle_tcptls_connection().

◆ ast_thread_inhibit_escalations_swap()

int ast_thread_inhibit_escalations_swap ( int inhibit )

Swap the current thread escalation inhibit setting.

Since: 11.24.0

Parameters

inhibit New setting. Non-zero to inhibit.

Return values

1	if dangerous function execution was inhibited.
0	if dangerous function execution was allowed.
-1	on error.

Definition at line 509 of file pbx_functions.c.

{
    int *thread_inhibit_escalations;
    int orig;
 
    thread_inhibit_escalations = ast_threadstorage_get(
        &thread_inhibit_escalations_tl, sizeof(*thread_inhibit_escalations));
    if (thread_inhibit_escalations == NULL) {
        ast_log(LOG_ERROR, "Error swapping privilege escalations inhibit for current thread\n");
        return -1;
    }
 
    orig = *thread_inhibit_escalations;
    *thread_inhibit_escalations = !!inhibit;
    return orig;
}

References ast_log, ast_threadstorage_get(), LOG_ERROR, and NULL.

Referenced by ast_add_extension2_lockopt().

◆ AST_THREADSTORAGE_CUSTOM_SCOPE()

AST_THREADSTORAGE_CUSTOM_SCOPE	(	thread_inhibit_escalations_tl	,
		NULL	,
		ast_free_ptr	,
		static
	)

A thread local indicating whether the current thread can run 'dangerous' dialplan functions.

◆ complete_functions()

static char * complete_functions	(	const char *	word,
		int	pos,
		int	state
	)

static

Definition at line 105 of file pbx_functions.c.

{
    struct ast_custom_function *cur;
    char *ret = NULL;
    int which = 0;
    int wordlen;
    int cmp;
 
    if (pos != 3) {
        return NULL;
    }
 
    wordlen = strlen(word);
    AST_RWLIST_RDLOCK(&acf_root);
    AST_RWLIST_TRAVERSE(&acf_root, cur, acflist) {
        /*
         * Do a case-insensitive search for convenience in this
         * 'complete' function.
         *
         * We must search the entire container because the functions are
         * sorted and normally found case sensitively.
         */
        cmp = strncasecmp(word, cur->name, wordlen);
        if (!cmp) {
            /* Found match. */
            if (++which <= state) {
                /* Not enough matches. */
                continue;
            }
            ret = ast_strdup(cur->name);
            break;
        }
    }
    AST_RWLIST_UNLOCK(&acf_root);
 
    return ret;
}

References ast_custom_function::acflist, AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, ast_strdup, ast_custom_function::name, and NULL.

Referenced by handle_show_function().

◆ func_args()

static char * func_args ( char * function )

static

return a pointer to the arguments of the function, and terminates the function name with '\0'

Definition at line 463 of file pbx_functions.c.

{
    char *args = strchr(function, '(');
 
    if (!args) {
        ast_log(LOG_WARNING, "Function '%s' doesn't contain parentheses.  Assuming null argument.\n", function);
    } else {
        char *p;
        *args++ = '\0';
        if ((p = strrchr(args, ')'))) {
            *p = '\0';
        } else {
            ast_log(LOG_WARNING, "Can't find trailing parenthesis for function '%s(%s'?\n", function, args);
        }
    }
    return args;
}

References args, ast_log, and LOG_WARNING.

Referenced by ast_func_read(), ast_func_read2(), ast_func_write(), pjsip_acf_channel_read(), pjsip_acf_parse_uri_read(), and read_pjsip().

◆ handle_show_function()

static char * handle_show_function	(	struct ast_cli_entry *	e,
		int	cmd,
		struct ast_cli_args *	a
	)

static

Definition at line 143 of file pbx_functions.c.

{
    struct ast_custom_function *acf;
    /* Maximum number of characters added by terminal coloring is 22 */
    char *synopsis = NULL, *provided_by = NULL, *since = NULL, *description = NULL, *syntax = NULL, *arguments = NULL, *seealso = NULL;
    char *rtn = CLI_SUCCESS;
 
    switch (cmd) {
    case CLI_INIT:
        e->command = "core show function";
        e->usage =
            "Usage: core show function <function>\n"
            "       Describe a particular dialplan function.\n";
        return NULL;
    case CLI_GENERATE:
        return complete_functions(a->word, a->pos, a->n);
    }
 
    if (a->argc != 4) {
        return CLI_SHOWUSAGE;
    }
 
    if (!(acf = ast_custom_function_find(a->argv[3]))) {
        ast_cli(a->fd, "No function by that name registered.\n");
 
        return CLI_FAILURE;
    }
 
#ifdef AST_XML_DOCS
    if (acf->docsrc == AST_XML_DOC) {
        synopsis = ast_xmldoc_printable(S_OR(acf->synopsis, "Not available"), 1);
        provided_by = ast_xmldoc_printable(S_OR(acf->provided_by, "Not available"), 1);
        since = ast_xmldoc_printable(S_OR(acf->since, "Not available"), 1);
        description = ast_xmldoc_printable(S_OR(acf->desc, "Not available"), 1);
        syntax = ast_xmldoc_printable(S_OR(acf->syntax, "Not available"), 1);
        arguments = ast_xmldoc_printable(S_OR(acf->arguments, "Not available"), 1);
        seealso = ast_xmldoc_printable(S_OR(acf->seealso, "Not available"), 1);
    } else
#endif
    {
        synopsis = ast_strdup(S_OR(acf->synopsis, "Not Available"));
        provided_by = ast_strdup(S_OR(acf->provided_by, "Not available"));
        since = ast_strdup(S_OR(acf->since, "Not Available"));
        description = ast_strdup(S_OR(acf->desc, "Not Available"));
        syntax = ast_strdup(S_OR(acf->syntax, "Not Available"));
        arguments = ast_strdup(S_OR(acf->arguments, "Not Available"));
        seealso = ast_strdup(S_OR(acf->seealso, "Not Available"));
    }
        /* check allocated memory. */
    if (!synopsis || !provided_by || !since || !description || !syntax || !arguments || !seealso) {
        rtn = CLI_FAILURE;
        goto free_docs;
    }
 
    ast_cli(a->fd, "\n"
        "%s  -= Info about Function '%s' =- %s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n"
        COLORIZE_FMT "\n"
        "%s\n\n",
        ast_term_color(COLOR_MAGENTA, 0), acf->name, ast_term_reset(),
        COLORIZE(COLOR_MAGENTA, 0, "[Synopsis]"), synopsis,
        COLORIZE(COLOR_MAGENTA, 0, "[Provided By]"), provided_by,
        COLORIZE(COLOR_MAGENTA, 0, "[Since]"), since,
        COLORIZE(COLOR_MAGENTA, 0, "[Description]"), description,
        COLORIZE(COLOR_MAGENTA, 0, "[Syntax]"), syntax,
        COLORIZE(COLOR_MAGENTA, 0, "[Arguments]"), arguments,
        COLORIZE(COLOR_MAGENTA, 0, "[See Also]"), seealso
        );
 
free_docs:
    ast_free(synopsis);
    ast_free(provided_by);
    ast_free(since);
    ast_free(description);
    ast_free(syntax);
    ast_free(arguments);
    ast_free(seealso);
 
    return rtn;
}

References a, ast_custom_function::arguments, ast_cli(), ast_custom_function_find(), ast_free, ast_strdup, ast_term_color(), ast_term_reset(), AST_XML_DOC, ast_xmldoc_printable(), CLI_FAILURE, CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, COLOR_MAGENTA, COLORIZE, COLORIZE_FMT, ast_cli_entry::command, complete_functions(), ast_custom_function::desc, ast_custom_function::docsrc, ast_custom_function::name, NULL, S_OR, ast_custom_function::seealso, synopsis, ast_custom_function::synopsis, ast_custom_function::syntax, and ast_cli_entry::usage.

◆ handle_show_functions()

static char * handle_show_functions	(	struct ast_cli_entry *	e,
		int	cmd,
		struct ast_cli_args *	a
	)

static

Definition at line 61 of file pbx_functions.c.

{
    struct ast_custom_function *acf;
    int count_acf = 0;
    int like = 0;
 
    switch (cmd) {
    case CLI_INIT:
        e->command = "core show functions [like]";
        e->usage =
            "Usage: core show functions [like <text>]\n"
            "       List builtin functions, optionally only those matching a given string\n";
        return NULL;
    case CLI_GENERATE:
        return NULL;
    }
 
    if (a->argc == 5 && (!strcmp(a->argv[3], "like")) ) {
        like = 1;
    } else if (a->argc != 3) {
        return CLI_SHOWUSAGE;
    }
 
    ast_cli(a->fd, "%s Custom Functions:\n"
        "--------------------------------------------------------------------------------\n",
        like ? "Matching" : "Installed");
 
    AST_RWLIST_RDLOCK(&acf_root);
    AST_RWLIST_TRAVERSE(&acf_root, acf, acflist) {
        if (!like || strstr(acf->name, a->argv[4])) {
            count_acf++;
            ast_cli(a->fd, "%-20.20s  %-35.35s  %s\n",
                S_OR(acf->name, ""),
                S_OR(acf->syntax, ""),
                S_OR(acf->synopsis, ""));
        }
    }
    AST_RWLIST_UNLOCK(&acf_root);
 
    ast_cli(a->fd, "%d %scustom functions installed.\n", count_acf, like ? "matching " : "");
 
    return CLI_SUCCESS;
}

References a, ast_custom_function::acflist, ast_cli(), AST_RWLIST_RDLOCK, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, CLI_GENERATE, CLI_INIT, CLI_SHOWUSAGE, CLI_SUCCESS, ast_cli_entry::command, ast_custom_function::name, NULL, S_OR, ast_custom_function::synopsis, ast_custom_function::syntax, and ast_cli_entry::usage.

◆ is_read_allowed()

static int is_read_allowed ( struct ast_custom_function * acfptr )

static

Determines whether execution of a custom function's read function is allowed.

Parameters

acfptr Custom function to check

Returns: True (non-zero) if reading is allowed.; False (zero) if reading is not allowed.

Definition at line 556 of file pbx_functions.c.

{
    if (!acfptr) {
        return 1;
    }
 
    if (!read_escalates(acfptr)) {
        return 1;
    }
 
    if (!thread_inhibits_escalations()) {
        return 1;
    }
 
    if (live_dangerously) {
        /* Global setting overrides the thread's preference */
        ast_debug(2, "Reading %s from a dangerous context\n",
            acfptr->name);
        return 1;
    }
 
    /* We have no reason to allow this function to execute */
    return 0;
}

References ast_debug, live_dangerously, ast_custom_function::name, read_escalates(), and thread_inhibits_escalations().

Referenced by ast_func_read(), and ast_func_read2().

◆ is_write_allowed()

static int is_write_allowed ( struct ast_custom_function * acfptr )

static

Determines whether execution of a custom function's write function is allowed.

Parameters

acfptr Custom function to check

Returns: True (non-zero) if writing is allowed.; False (zero) if writing is not allowed.

Definition at line 589 of file pbx_functions.c.

{
    if (!acfptr) {
        return 1;
    }
 
    if (!write_escalates(acfptr)) {
        return 1;
    }
 
    if (!thread_inhibits_escalations()) {
        return 1;
    }
 
    if (live_dangerously) {
        /* Global setting overrides the thread's preference */
        ast_debug(2, "Writing %s from a dangerous context\n",
            acfptr->name);
        return 1;
    }
 
    /* We have no reason to allow this function to execute */
    return 0;
}

References ast_debug, live_dangerously, ast_custom_function::name, thread_inhibits_escalations(), and write_escalates().

Referenced by ast_func_write().

◆ load_pbx_functions_cli()

int load_pbx_functions_cli ( void )

Provided by pbx_functions.c

Definition at line 748 of file pbx_functions.c.

{
    ast_cli_register_multiple(acf_cli, ARRAY_LEN(acf_cli));
    ast_register_cleanup(unload_pbx_functions_cli);
 
    return 0;
}

References acf_cli, ARRAY_LEN, ast_cli_register_multiple, ast_register_cleanup(), and unload_pbx_functions_cli().

Referenced by asterisk_daemon().

◆ pbx_live_dangerously()

void pbx_live_dangerously ( int new_live_dangerously )

Enable/disable the execution of 'dangerous' functions from external protocols (AMI, etc.).

These dialplan functions (such as SHELL) provide an opportunity for privilege escalation. They are okay to invoke from the dialplan, but external protocols with permission controls should not normally invoke them.

This function can globally enable/disable the execution of dangerous functions from external protocols.

Parameters

new_live_dangerously If true, enable the execution of escalating functions from external protocols.

Definition at line 481 of file pbx_functions.c.

{
    if (new_live_dangerously && !live_dangerously) {
        ast_log(LOG_WARNING, "Privilege escalation protection disabled!\n"
            "See https://docs.asterisk.org/Configuration/Dialplan/Privilege-Escalations-with-Dialplan-Functions/ for more details.\n");
    }
 
    if (!new_live_dangerously && live_dangerously) {
        ast_log(LOG_NOTICE, "Privilege escalation protection enabled.\n");
    }
    live_dangerously = new_live_dangerously;
}

References ast_log, live_dangerously, LOG_NOTICE, and LOG_WARNING.

Referenced by load_asterisk_conf().

◆ read_escalates()

static int read_escalates ( const struct ast_custom_function * acf )

static

Returns true if given custom function escalates privileges on read.

Parameters

acf	Custom function to query.

Returns: True (non-zero) if reads escalate privileges.; False (zero) if reads just read.

Definition at line 298 of file pbx_functions.c.

{
    return acf->read_escalates;
}

References ast_custom_function::read_escalates.

Referenced by is_read_allowed().

◆ thread_inhibits_escalations()

static int thread_inhibits_escalations ( void )

static

Indicates whether the current thread inhibits the execution of dangerous functions.

Returns: True (non-zero) if dangerous function execution is inhibited.; False (zero) if dangerous function execution is allowed.

Definition at line 533 of file pbx_functions.c.

{
    int *thread_inhibit_escalations;
 
    thread_inhibit_escalations = ast_threadstorage_get(
        &thread_inhibit_escalations_tl, sizeof(*thread_inhibit_escalations));
    if (thread_inhibit_escalations == NULL) {
        ast_log(LOG_ERROR, "Error checking thread's ability to run dangerous functions\n");
        /* On error, assume that we are inhibiting */
        return 1;
    }
 
    return *thread_inhibit_escalations;
}

References ast_log, ast_threadstorage_get(), LOG_ERROR, and NULL.

Referenced by is_read_allowed(), and is_write_allowed().

◆ unload_pbx_functions_cli()

static void unload_pbx_functions_cli ( void )

static

Definition at line 743 of file pbx_functions.c.

{
    ast_cli_unregister_multiple(acf_cli, ARRAY_LEN(acf_cli));
}

References acf_cli, ARRAY_LEN, and ast_cli_unregister_multiple().

Referenced by load_pbx_functions_cli().

◆ write_escalates()

static int write_escalates ( const struct ast_custom_function * acf )

static

Returns true if given custom function escalates privileges on write.

Parameters

acf	Custom function to query.

Returns: True (non-zero) if writes escalate privileges.; False (zero) if writes just write.

Definition at line 310 of file pbx_functions.c.

{
    return acf->write_escalates;
}

References ast_custom_function::write_escalates.

Referenced by is_write_allowed().

Variable Documentation

◆ acf_cli

struct ast_cli_entry acf_cli[]

static

Initial value:

= {
    { .handler =  handle_show_functions , .summary =  "Shows registered dialplan functions" ,},
    { .handler =  handle_show_function , .summary =  "Describe a specific dialplan function" ,},
}

Definition at line 738 of file pbx_functions.c.

                                        {
    AST_CLI_DEFINE(handle_show_functions, "Shows registered dialplan functions"),
    AST_CLI_DEFINE(handle_show_function, "Describe a specific dialplan function"),
};

Referenced by load_pbx_functions_cli(), and unload_pbx_functions_cli().

◆ acf_root

struct acf_root acf_root = AST_RWLIST_HEAD_INIT_VALUE

static

◆ live_dangerously

int live_dangerously

static

Set to true (non-zero) to globally allow all dangerous dialplan functions to run.

Definition at line 52 of file pbx_functions.c.

Referenced by is_read_allowed(), is_write_allowed(), and pbx_live_dangerously().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ __ast_custom_function_register()

◆ __ast_custom_function_register_escalating()

◆ acf_retrieve_docs()

◆ ast_custom_function_find()

◆ ast_custom_function_find_nolock()

◆ ast_custom_function_unregister()

◆ ast_func_read()

◆ ast_func_read2()

◆ ast_func_write()

◆ ast_thread_inhibit_escalations()

◆ ast_thread_inhibit_escalations_swap()

◆ AST_THREADSTORAGE_CUSTOM_SCOPE()

◆ complete_functions()

◆ func_args()

◆ handle_show_function()

◆ handle_show_functions()

◆ is_read_allowed()

◆ is_write_allowed()

◆ load_pbx_functions_cli()

◆ pbx_live_dangerously()

◆ read_escalates()

◆ thread_inhibits_escalations()

◆ unload_pbx_functions_cli()

◆ write_escalates()

Variable Documentation

◆ acf_cli

◆ acf_root

◆ live_dangerously