From 4feaf3c264b534e656ddb16e6a6327812e75b271 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Thu, 12 Aug 2010 10:29:43 -0400 Subject: [PATCH] Document sudo_conv_t function and sudo_printf_t return values. --- doc/sudo_plugin.cat | 156 ++++++++++++++++++++--------------------- doc/sudo_plugin.man.in | 8 ++- doc/sudo_plugin.pod | 6 ++ 3 files changed, 91 insertions(+), 79 deletions(-) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 5013da3b6..eaf55716b 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -61,7 +61,7 @@ DDEESSCCRRIIPPTTIIOONN -1.8.0b1 July 7, 2010 1 +1.8.0b1 August 12, 2010 1 @@ -127,7 +127,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b1 July 7, 2010 2 +1.8.0b1 August 12, 2010 2 @@ -140,11 +140,13 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) conversation A pointer to the conversation function that can be used by the - plugin to interact with the user (see below). + plugin to interact with the user (see below). Returns 0 on + success and -1 on failure. plugin_printf A pointer to a printf-style function that may be used to - display informational or error messages (see below). + display informational or error messages (see below). Returns + the number of characters printed on success and -1 on failure. settings A vector of user-supplied ssuuddoo settings in the form of @@ -188,12 +190,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) implied_shell=bool If the user does not specify a program on the command line, - ssuuddoo will pass the plugin the path to the user's shell and - set _i_m_p_l_i_e_d___s_h_e_l_l to true. This allows ssuuddoo with no -1.8.0b1 July 7, 2010 3 +1.8.0b1 August 12, 2010 3 @@ -202,6 +202,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + ssuuddoo will pass the plugin the path to the user's shell and + set _i_m_p_l_i_e_d___s_h_e_l_l to true. This allows ssuuddoo with no arguments to be used similarly to _s_u(1). If the plugin does not to support this usage, it may return a value of -2 from the check_policy function, which will cause ssuuddoo to @@ -254,12 +256,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) If specified, the user has requested via the -C flag that ssuuddoo close all files descriptors with a value of _n_u_m_b_e_r or higher. The plugin may optionally pass this, or another - value, back in the _c_o_m_m_a_n_d___i_n_f_o list. - -1.8.0b1 July 7, 2010 4 +1.8.0b1 August 12, 2010 4 @@ -268,6 +268,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + value, back in the _c_o_m_m_a_n_d___i_n_f_o list. + Additional settings may be added in the future so the plugin should silently ignore settings that it does not recognize. @@ -320,12 +322,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) of "name=value" strings. When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt - equal sign ('=') since the _n_a_m_e field will never include one - itself but the _v_a_l_u_e might. -1.8.0b1 July 7, 2010 5 +1.8.0b1 August 12, 2010 5 @@ -334,6 +334,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + equal sign ('=') since the _n_a_m_e field will never include one + itself but the _v_a_l_u_e might. + close void (*close)(int exit_status, int error); @@ -385,13 +388,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) into _a_r_g_v___o_u_t, separated from the editor and its arguments by a "--" element. The "--" will be removed by ssuuddoo before the editor is executed. The plugin should also set _s_u_d_o_e_d_i_t_=_t_r_u_e in the - _c_o_m_m_a_n_d___i_n_f_o list. - - The _c_h_e_c_k___p_o_l_i_c_y function returns 1 if the command is allowed, 0 if -1.8.0b1 July 7, 2010 6 +1.8.0b1 August 12, 2010 6 @@ -400,6 +400,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + _c_o_m_m_a_n_d___i_n_f_o list. + + The _c_h_e_c_k___p_o_l_i_c_y function returns 1 if the command is allowed, 0 if not allowed, -1 for a general error, or -2 for a usage error or if ssuuddooeeddiitt was specified but is unsupported by the plugin. In the latter case, ssuuddoo will print a usage message before it exits. If @@ -450,14 +453,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) runas_gid=gid Group ID to run the command as. - runas_egid=gid - Effective group ID to run the command as. If not - specified, the value of _r_u_n_a_s___g_i_d is used. -1.8.0b1 July 7, 2010 7 +1.8.0b1 August 12, 2010 7 @@ -466,6 +466,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + runas_egid=gid + Effective group ID to run the command as. If not + specified, the value of _r_u_n_a_s___g_i_d is used. + runas_groups=list The supplementary group vector to use for the command in the form of a comma-separated list of group IDs. If @@ -515,15 +519,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) transparently enable _s_u_d_o_e_d_i_t when the user attempts to run an editor. - closefrom=number - If specified, ssuuddoo will close all files descriptors with a - value of _n_u_m_b_e_r or higher. - Unsupported values will be ignored. -1.8.0b1 July 7, 2010 8 +1.8.0b1 August 12, 2010 8 @@ -532,6 +532,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + closefrom=number + If specified, ssuuddoo will close all files descriptors with a + value of _n_u_m_b_e_r or higher. + + Unsupported values will be ignored. + argv_out The NULL-terminated argument vector to pass to the _e_x_e_c_v_e_(_) system call when executing the command. The plugin is @@ -580,24 +586,24 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The validate function is called when ssuuddoo is run with the -v flag. For policy plugins such as _s_u_d_o_e_r_s that cache authentication - credentials, this function will validate and cache the credentials. - The validate function should be NULL if the plugin does not support - credential caching. - Returns 1 on success, 0 on failure and -1 on error. On error, the +1.8.0b1 August 12, 2010 9 -1.8.0b1 July 7, 2010 9 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + credentials, this function will validate and cache the credentials. + The validate function should be NULL if the plugin does not support + credential caching. + Returns 1 on success, 0 on failure and -1 on error. On error, the plugin may optionally call the conversation or plugin_printf function with SUDO_CONF_ERROR_MSG to present additional error information to the user. @@ -646,16 +652,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) #define SUDO_API_VERSION_MAJOR 1 #define SUDO_API_VERSION_MINOR 0 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \ - SUDO_API_VERSION_MINOR) - - II//OO PPlluuggiinn AAPPII - - - -1.8.0b1 July 7, 2010 10 +1.8.0b1 August 12, 2010 10 @@ -664,6 +664,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + SUDO_API_VERSION_MINOR) + + II//OO PPlluuggiinn AAPPII struct io_plugin { #define SUDO_IO_PLUGIN 2 unsigned int type; /* always SUDO_IO_PLUGIN */ @@ -716,12 +719,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) char * const user_info[], int argc, char * const argv[], char * const user_env[]); - The _o_p_e_n function is run before the _l_o_g___i_n_p_u_t, _l_o_g___o_u_t_p_u_t or - _s_h_o_w___v_e_r_s_i_o_n functions are called. It is only called if the - -1.8.0b1 July 7, 2010 11 +1.8.0b1 August 12, 2010 11 @@ -730,6 +730,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + The _o_p_e_n function is run before the _l_o_g___i_n_p_u_t, _l_o_g___o_u_t_p_u_t or + _s_h_o_w___v_e_r_s_i_o_n functions are called. It is only called if the version is being requested or the _c_h_e_c_k___p_o_l_i_c_y function has returned successfully. It returns 1 on success, 0 on failure, -1 if a general error occurred, or -2 if there was a usage error. In @@ -749,13 +751,16 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) A pointer to the conversation function that may be used by the _s_h_o_w___v_e_r_s_i_o_n function to display version information (see show_version below). The conversation function may also be - used to display additional error message to the user. + used to display additional error message to the user. The + conversation function returns 0 on success and -1 on failure. plugin_printf A pointer to a printf-style function that may be used by the _s_h_o_w___v_e_r_s_i_o_n function to display version information (see show_version below). The plugin_printf function may also be - used to display additional error message to the user. + used to display additional error message to the user. The + plugin_printf function returns number of characters printed on + success and -1 on failure. settings A vector of user-supplied ssuuddoo settings in the form of @@ -780,14 +785,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) equal sign ('=') since the _n_a_m_e field will never include one itself but the _v_a_l_u_e might. - See the "Policy Plugin API" section for a list of all possible - strings. - - - -1.8.0b1 July 7, 2010 12 +1.8.0b1 August 12, 2010 12 @@ -796,6 +796,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + See the "Policy Plugin API" section for a list of all possible + strings. + argc The number of elements in _a_r_g_v, not counting the final NULL pointer. @@ -847,13 +850,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) user but before it is passed to the running command. This allows the plugin to reject data if it chooses to (for instance if the input contains banned content). Returns 1 if the data should be - passed to the command, 0 if the data is rejected (which will - terminate the command) or -1 if an error occurred. - -1.8.0b1 July 7, 2010 13 +1.8.0b1 August 12, 2010 13 @@ -862,6 +862,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + passed to the command, 0 if the data is rejected (which will + terminate the command) or -1 if an error occurred. + The function arguments are as follows: buf The buffer containing user input. @@ -914,12 +917,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The function arguments are as follows: - buf The buffer containing command output. - - -1.8.0b1 July 7, 2010 14 +1.8.0b1 August 12, 2010 14 @@ -928,6 +928,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + buf The buffer containing command output. + len The length of _b_u_f in bytes. log_stderr @@ -980,12 +982,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) typedef int (*sudo_conv_t)(int num_msgs, const struct sudo_conv_message msgs[], - struct sudo_conv_reply replies[]); - -1.8.0b1 July 7, 2010 15 +1.8.0b1 August 12, 2010 15 @@ -994,6 +994,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + struct sudo_conv_reply replies[]); + typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); Pointers to the conversation and printf-style functions are passed in @@ -1046,12 +1048,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) int (*init)(int version, sudo_printf_t plugin_printf, char *const argv[]); - The _i_n_i_t function is called after _s_u_d_o_e_r_s has been parsed but - before any policy checks. It returns 1 on success, 0 on failure -1.8.0b1 July 7, 2010 16 +1.8.0b1 August 12, 2010 16 @@ -1060,6 +1060,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + The _i_n_i_t function is called after _s_u_d_o_e_r_s has been parsed but + before any policy checks. It returns 1 on success, 0 on failure (or if the plugin is not configured), and -1 if a error occurred. If an error occurs, the plugin may call the plugin_printf function with SUDO_CONF_ERROR_MSG to present additional error information to @@ -1074,7 +1076,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) plugin_printf A pointer to a printf-style function that may be used to - display informational or error message to the user. + display informational or error message to the user. Returns + the number of characters printed on success and -1 on failure. argv A NULL-terminated array of arguments generated from the @@ -1109,15 +1112,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) _V_e_r_s_i_o_n _M_a_c_r_o_s - /* Sudoers group plugin version major/minor */ - #define GROUP_API_VERSION_MAJOR 1 - #define GROUP_API_VERSION_MINOR 0 - #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \ - GROUP_API_VERSION_MINOR) -1.8.0b1 July 7, 2010 17 + + +1.8.0b1 August 12, 2010 17 @@ -1126,6 +1126,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + /* Sudoers group plugin version major/minor */ + #define GROUP_API_VERSION_MAJOR 1 + #define GROUP_API_VERSION_MINOR 0 + #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \ + GROUP_API_VERSION_MINOR) /* Getters and setters for group version */ #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16) @@ -1178,11 +1183,6 @@ DDIISSCCLLAAIIMMEERR - - - - - -1.8.0b1 July 7, 2010 18 +1.8.0b1 August 12, 2010 18 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index ee368d714..27d7af763 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -139,7 +139,7 @@ .\" ======================================================================== .\" .IX Title "SUDO_PLUGIN @mansectsu@" -.TH SUDO_PLUGIN @mansectsu@ "July 7, 2010" "1.8.0b1" "MAINTENANCE COMMANDS" +.TH SUDO_PLUGIN @mansectsu@ "August 12, 2010" "1.8.0b1" "MAINTENANCE COMMANDS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -264,10 +264,12 @@ major and minor version number of the plugin \s-1API\s0 supported by .IX Item "conversation" A pointer to the conversation function that can be used by the plugin to interact with the user (see below). +Returns 0 on success and \-1 on failure. .IP "plugin_printf" 4 .IX Item "plugin_printf" A pointer to a printf-style function that may be used to display informational or error messages (see below). +Returns the number of characters printed on success and \-1 on failure. .IP "settings" 4 .IX Item "settings" A vector of user-supplied \fBsudo\fR settings in the form of \*(L"name=value\*(R" @@ -803,12 +805,15 @@ A pointer to the conversation function that may be used by the \&\fIshow_version\fR function to display version information (see show_version below). The conversation function may also be used to display additional error message to the user. +The conversation function returns 0 on success and \-1 on failure. .IP "plugin_printf" 4 .IX Item "plugin_printf" A pointer to a printf-style function that may be used by the \&\fIshow_version\fR function to display version information (see show_version below). The plugin_printf function may also be used to display additional error message to the user. +The plugin_printf function returns number of characters printed on +success and \-1 on failure. .IP "settings" 4 .IX Item "settings" A vector of user-supplied \fBsudo\fR settings in the form of \*(L"name=value\*(R" @@ -1126,6 +1131,7 @@ major and minor version number of the group plugin \s-1API\s0 supported by .IX Item "plugin_printf" A pointer to a printf-style function that may be used to display informational or error message to the user. +Returns the number of characters printed on success and \-1 on failure. .IP "argv" 4 .IX Item "argv" A NULL-terminated array of arguments generated from the \fIgroup_plugin\fR diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod index e7874fda0..4097c2876 100644 --- a/doc/sudo_plugin.pod +++ b/doc/sudo_plugin.pod @@ -141,11 +141,13 @@ B. A pointer to the conversation function that can be used by the plugin to interact with the user (see below). +Returns 0 on success and -1 on failure. =item plugin_printf A pointer to a printf-style function that may be used to display informational or error messages (see below). +Returns the number of characters printed on success and -1 on failure. =item settings @@ -737,6 +739,7 @@ A pointer to the conversation function that may be used by the I function to display version information (see show_version below). The conversation function may also be used to display additional error message to the user. +The conversation function returns 0 on success and -1 on failure. =item plugin_printf @@ -744,6 +747,8 @@ A pointer to a printf-style function that may be used by the I function to display version information (see show_version below). The plugin_printf function may also be used to display additional error message to the user. +The plugin_printf function returns number of characters printed on +success and -1 on failure. =item settings @@ -1074,6 +1079,7 @@ I. A pointer to a printf-style function that may be used to display informational or error message to the user. +Returns the number of characters printed on success and -1 on failure. =item argv -- 2.40.0