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

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

static void	__init_thread_inhibit_escalations_tl (void)
	A thread local indicating whether the current thread can run 'dangerous' dialplan functions. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

Variables
static struct ast_cli_entry	acf_cli []

static struct acf_root	acf_root = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

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

static struct ast_threadstorage	thread_inhibit_escalations_tl = { .once = PTHREAD_ONCE_INIT , .key_init = __init_thread_inhibit_escalations_tl , .custom_init = NULL , }

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 373 of file pbx_functions.c.

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

 {
    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(2, "Registered custom function '" COLORIZE_FMT "'\n", COLORIZE(COLOR_BRCYAN, 0, acf->name));
 
    return 0;
 }

◆ __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 418 of file pbx_functions.c.

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

 {
    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;
 }

◆ __init_thread_inhibit_escalations_tl()

static void __init_thread_inhibit_escalations_tl ( void )

static

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

Definition at line 46 of file pbx_functions.c.

62 {

◆ acf_retrieve_docs()

static int acf_retrieve_docs ( struct ast_custom_function * acf )

static

Definition at line 328 of file pbx_functions.c.

Referenced by __ast_custom_function_register().

 {
 #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;
    }
 
    /* 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 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;
 }

◆ ast_custom_function_find()

struct ast_custom_function* ast_custom_function_find ( const char * name )

Definition at line 262 of file pbx_functions.c.

References ast_custom_function_find_nolock(), AST_RWLIST_RDLOCK, and AST_RWLIST_UNLOCK.

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

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

◆ ast_custom_function_find_nolock()

static struct ast_custom_function* ast_custom_function_find_nolock ( const char * name )

static

Definition at line 240 of file pbx_functions.c.

References AST_RWLIST_TRAVERSE, ast_custom_function::name, and NULL.

Referenced by __ast_custom_function_register(), and ast_custom_function_find().

 {
    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;
 }

◆ ast_custom_function_unregister()

int ast_custom_function_unregister ( struct ast_custom_function * acf )

Unregister a custom function.

Definition at line 273 of file pbx_functions.c.

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

Referenced by load_module(), manager_shutdown(), message_shutdown(), reload(), unload_features_config(), unload_module(), unload_parking_bridge_features(), and unload_pbx().

 {
    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(2, "Unregistered custom function %s\n", cur->name);
    }
    AST_RWLIST_UNLOCK(&acf_root);
 
    return cur ? 0 : -1;
 }

◆ 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 599 of file pbx_functions.c.

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, copy(), func_args(), is_read_allowed(), 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_getvariable(), lua_get_variable_value(), and pbx_substitute_variables_helper_full().

 {
    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;
 }

◆ 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 642 of file pbx_functions.c.

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_strdupa, 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, and VAR_BUF_SIZE.

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

 {
    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);
       }
       if (acfptr->mod && u) {
          __ast_module_user_remove(acfptr->mod, u);
       }
 
       return res;
    }
 
    return -1;
 }

◆ 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 692 of file pbx_functions.c.

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

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

 {
    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;
 }

◆ 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 479 of file pbx_functions.c.

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

Referenced by ast_add_extension2_lockopt(), and handle_tcptls_connection().

 {
    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;
 }

◆ 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 494 of file pbx_functions.c.

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

Referenced by ast_add_extension2_lockopt().

 {
    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;
 }

◆ complete_functions()

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

static

Definition at line 105 of file pbx_functions.c.

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

Referenced by handle_show_function().

 {
    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;
 }

◆ 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 448 of file pbx_functions.c.

References args, ast_log, and LOG_WARNING.

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

 {
    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;
 }

◆ 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 infotitle[64 + AST_MAX_APP + 22], syntitle[40], destitle[40], argtitle[40], seealsotitle[40];
    char info[64 + AST_MAX_APP], *synopsis = NULL, *description = NULL, *seealso = NULL;
    char stxtitle[40], *syntax = NULL, *arguments = NULL;
    int syntax_size, description_size, synopsis_size, arguments_size, seealso_size;
 
    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;
    }
 
    syntax_size = strlen(S_OR(acf->syntax, "Not Available")) + AST_TERM_MAX_ESCAPE_CHARS;
    syntax = ast_malloc(syntax_size);
    if (!syntax) {
       ast_cli(a->fd, "Memory allocation failure!\n");
 
       return CLI_FAILURE;
    }
 
    snprintf(info, sizeof(info), "\n  -= Info about function '%s' =- \n\n", acf->name);
    term_color(infotitle, info, COLOR_MAGENTA, 0, sizeof(infotitle));
    term_color(syntitle, "[Synopsis]\n", COLOR_MAGENTA, 0, 40);
    term_color(destitle, "[Description]\n", COLOR_MAGENTA, 0, 40);
    term_color(stxtitle, "[Syntax]\n", COLOR_MAGENTA, 0, 40);
    term_color(argtitle, "[Arguments]\n", COLOR_MAGENTA, 0, 40);
    term_color(seealsotitle, "[See Also]\n", COLOR_MAGENTA, 0, 40);
    term_color(syntax, S_OR(acf->syntax, "Not available"), COLOR_CYAN, 0, syntax_size);
 #ifdef AST_XML_DOCS
    if (acf->docsrc == AST_XML_DOC) {
       arguments = ast_xmldoc_printable(S_OR(acf->arguments, "Not available"), 1);
       synopsis = ast_xmldoc_printable(S_OR(acf->synopsis, "Not available"), 1);
       description = ast_xmldoc_printable(S_OR(acf->desc, "Not available"), 1);
       seealso = ast_xmldoc_printable(S_OR(acf->seealso, "Not available"), 1);
    } else
 #endif
    {
       synopsis_size = strlen(S_OR(acf->synopsis, "Not Available")) + AST_TERM_MAX_ESCAPE_CHARS;
       synopsis = ast_malloc(synopsis_size);
 
       description_size = strlen(S_OR(acf->desc, "Not Available")) + AST_TERM_MAX_ESCAPE_CHARS;
       description = ast_malloc(description_size);
 
       arguments_size = strlen(S_OR(acf->arguments, "Not Available")) + AST_TERM_MAX_ESCAPE_CHARS;
       arguments = ast_malloc(arguments_size);
 
       seealso_size = strlen(S_OR(acf->seealso, "Not Available")) + AST_TERM_MAX_ESCAPE_CHARS;
       seealso = ast_malloc(seealso_size);
 
       /* check allocated memory. */
       if (!synopsis || !description || !arguments || !seealso) {
          ast_free(synopsis);
          ast_free(description);
          ast_free(arguments);
          ast_free(seealso);
          ast_free(syntax);
 
          return CLI_FAILURE;
       }
 
       term_color(arguments, S_OR(acf->arguments, "Not available"), COLOR_CYAN, 0, arguments_size);
       term_color(synopsis, S_OR(acf->synopsis, "Not available"), COLOR_CYAN, 0, synopsis_size);
       term_color(description, S_OR(acf->desc, "Not available"), COLOR_CYAN, 0, description_size);
       term_color(seealso, S_OR(acf->seealso, "Not available"), COLOR_CYAN, 0, seealso_size);
    }
 
    ast_cli(a->fd, "%s%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n\n%s%s\n",
          infotitle, syntitle, synopsis, destitle, description,
          stxtitle, syntax, argtitle, arguments, seealsotitle, seealso);
 
    ast_free(arguments);
    ast_free(synopsis);
    ast_free(description);
    ast_free(seealso);
    ast_free(syntax);
 
    return CLI_SUCCESS;
 }

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

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

 {
    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;
 }

◆ 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 541 of file pbx_functions.c.

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

Referenced by ast_func_read(), and ast_func_read2().

 {
    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;
 }

◆ 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 574 of file pbx_functions.c.

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

Referenced by ast_func_write().

 {
    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;
 }

◆ load_pbx_functions_cli()

int load_pbx_functions_cli ( void )

Provided by pbx_functions.c

Definition at line 732 of file pbx_functions.c.

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

Referenced by asterisk_daemon().

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

◆ 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 466 of file pbx_functions.c.

References ast_log, live_dangerously, LOG_NOTICE, and LOG_WARNING.

Referenced by load_asterisk_conf().

 {
    if (new_live_dangerously && !live_dangerously) {
       ast_log(LOG_WARNING, "Privilege escalation protection disabled!\n"
          "See https://wiki.asterisk.org/wiki/x/1gKfAQ for more details.\n");
    }
 
    if (!new_live_dangerously && live_dangerously) {
       ast_log(LOG_NOTICE, "Privilege escalation protection enabled.\n");
    }
    live_dangerously = new_live_dangerously;
 }

◆ 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 303 of file pbx_functions.c.

References ast_custom_function::read_escalates.

Referenced by is_read_allowed().

 {
    return acf->read_escalates;
 }

◆ 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 518 of file pbx_functions.c.

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

Referenced by is_read_allowed(), and is_write_allowed().

 {
    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;
 }

◆ unload_pbx_functions_cli()

static void unload_pbx_functions_cli ( void )

static

Definition at line 727 of file pbx_functions.c.

References ARRAY_LEN, and ast_cli_unregister_multiple().

Referenced by load_pbx_functions_cli().

 {
    ast_cli_unregister_multiple(acf_cli, ARRAY_LEN(acf_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 315 of file pbx_functions.c.

References ast_custom_function::write_escalates.

Referenced by is_write_allowed().

 {
    return acf->write_escalates;
 }

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 722 of file pbx_functions.c.

◆ acf_root

struct acf_root acf_root = { .first = NULL, .last = NULL, .lock = { PTHREAD_RWLOCK_INITIALIZER , NULL, {1, 0} } , }

static

◆ live_dangerously

int live_dangerously

static

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

Definition at line 46 of file pbx_functions.c.

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

◆ thread_inhibit_escalations_tl

struct ast_threadstorage thread_inhibit_escalations_tl = { .once = PTHREAD_ONCE_INIT , .key_init = __init_thread_inhibit_escalations_tl , .custom_init = NULL , }

static

Definition at line 46 of file pbx_functions.c.

Referenced by ast_thread_inhibit_escalations(), ast_thread_inhibit_escalations_swap(), and thread_inhibits_escalations().

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ __ast_custom_function_register()

◆ __ast_custom_function_register_escalating()

◆ __init_thread_inhibit_escalations_tl()

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

◆ 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

◆ thread_inhibit_escalations_tl