From: Todd C. Miller Date: Sat, 24 Nov 2018 15:39:09 +0000 (-0700) Subject: Sudo plugin manual updates and clarification from Guillem Jover: X-Git-Tag: SUDO_1_8_27^2~27 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=23006c72c7ecf3d186f52d269f7ab927fe36013d;p=sudo Sudo plugin manual updates and clarification from Guillem Jover: - Add missing return information for show_version(). - Fix prototypes for several function pointers. - Update SUDO_API_VERSION_MINOR. - Add missing references to log_suspend() and change_winsize(). - Add missing "array.". - Clarify that argc can be zero on sudo -V. - Clarify size requirements for conversation array arguments. - Clarify timeout zero value for struct sudo_conv_message. - Clarify initial and final state of reply in struct sudo_conv_reply. --- diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index ac5549226..eda4cebec 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -391,8 +391,12 @@ DDEESSCCRRIIPPTTIIOONN function using SUDO_CONV_INFO_MSG. If the user requests detailed version information, the verbose flag will be set. + Returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error, although the return value is + currently ignored. + check_policy - int (*check_policy)(int argc, char * const argv[] + int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[]); @@ -692,8 +696,8 @@ DDEESSCCRRIIPPTTIIOONN populating the vector. list - int (*list)(int verbose, const char *list_user, - int argc, char * const argv[]); + int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); List available privileges for the invoking user. Returns 1 on success, 0 on failure and -1 on error. On error, the plugin may @@ -831,7 +835,7 @@ DDEESSCCRRIIPPTTIIOONN /* Plugin API version major/minor. */ #define SUDO_API_VERSION_MAJOR 1 - #define SUDO_API_VERSION_MINOR 2 + #define SUDO_API_VERSION_MINOR 13 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y) #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\ SUDO_API_VERSION_MINOR) @@ -914,19 +918,21 @@ DDEESSCCRRIIPPTTIIOONN open int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t plugin_printf, char * const settings[], - char * const user_info[], int argc, char * const argv[], - char * const user_env[], char * const plugin_options[]); + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); The ooppeenn() function is run before the lloogg__ttttyyiinn(), lloogg__ttttyyoouutt(), - lloogg__ssttddiinn(), lloogg__ssttddoouutt(), lloogg__ssttddeerrrr(), or sshhooww__vveerrssiioonn() - functions are called. It is only called if the version is being - requested or if the policy plugin's cchheecckk__ppoolliiccyy() 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 - the latter case, ssuuddoo will print a usage message before it exits. - If an error occurs, the plugin may optionally call the - ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function with SUDO_CONF_ERROR_MSG - to present additional error information to the user. + lloogg__ssttddiinn(), lloogg__ssttddoouutt(), lloogg__ssttddeerrrr(), lloogg__ssuussppeenndd(), + cchhaannggee__wwiinnssiizzee(), or sshhooww__vveerrssiioonn() functions are called. It is + only called if the version is being requested or if the policy + plugin's cchheecckk__ppoolliiccyy() 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 the latter case, ssuuddoo will + print a usage message before it exits. If an error occurs, the + plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. The function arguments are as follows: @@ -979,7 +985,7 @@ DDEESSCCRRIIPPTTIIOONN strings. argc The number of elements in _a_r_g_v, not counting the final NULL - pointer. + pointer. It can be zero, when ssuuddoo is called with --VV. argv If non-NULL, an argument vector describing a command the user wishes to run in the same form as what would be passed to the @@ -1033,6 +1039,10 @@ DDEESSCCRRIIPPTTIIOONN function using SUDO_CONV_INFO_MSG. If the user requests detailed version information, the verbose flag will be set. + Returns 1 on success, 0 on failure, -1 if a general error occurred, + or -2 if there was a usage error, although the return value is + currently ignored. + log_ttyin int (*log_ttyin)(const char *buf, unsigned int len); @@ -1383,9 +1393,11 @@ DDEESSCCRRIIPPTTIIOONN To use the ccoonnvveerrssaattiioonn() function, the plugin must pass an array of sudo_conv_message and sudo_conv_reply structures. There must be a struct sudo_conv_message and struct sudo_conv_reply for each message in the - conversation. The struct sudo_conv_callback pointer, if not NULL, should - contain function pointers to be called when the ssuuddoo process is suspended - and/or resumed during conversation input. The _o_n___s_u_s_p_e_n_d and _o_n___r_e_s_u_m_e + conversation, that is, both arrays must have the same number of elements. + Each struct sudo_conv_reply must have its _r_e_p_l_y member initialized to + NULL. The struct sudo_conv_callback pointer, if not NULL, should contain + function pointers to be called when the ssuuddoo process is suspended and/or + resumed during conversation input. The _o_n___s_u_s_p_e_n_d and _o_n___r_e_s_u_m_e functions are called with the signal that caused ssuuddoo to be suspended and the _c_l_o_s_u_r_e pointer from the struct sudo_conv_callback. These functions should return 0 on success and -1 on error. On error, the conversation @@ -1399,11 +1411,12 @@ DDEESSCCRRIIPPTTIIOONN SUDO_CONV_PROMPT_ECHO_OFF Prompt the user for input with echo disabled; this is generally - used for passwords. The reply will be stored in the _r_e_p_l_i_e_s array. + used for passwords. The reply will be stored in the _r_e_p_l_i_e_s array, + and it will never be NULL. SUDO_CONV_PROMPT_ECHO_ON Prompt the user for input with echo enabled. The reply will be - stored in the _r_e_p_l_i_e_s array. + stored in the _r_e_p_l_i_e_s array, and it will never be NULL. SUDO_CONV_ERROR_MSG Display an error message. The message is written to the standard @@ -1417,9 +1430,10 @@ DDEESSCCRRIIPPTTIIOONN SUDO_CONV_PROMPT_MASK Prompt the user for input but echo an asterisk character for each - character read. The reply will be stored in the _r_e_p_l_i_e_s This can - be used to provide visual feedback to the user while reading - sensitive information that should not be displayed. + character read. The reply will be stored in the _r_e_p_l_i_e_s array, and + it will never be NULL. This can be used to provide visual feedback + to the user while reading sensitive information that should not be + displayed. In addition to the above values, the following flag bits may also be set: @@ -1438,6 +1452,9 @@ DDEESSCCRRIIPPTTIIOONN used for output. SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used. + The _t_i_m_e_o_u_t in seconds until the prompt will wait for no more input. A + zero value implies an infinite timeout. + The plugin is responsible for freeing the reply buffer located in each struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents the maximum length of the reply buffer (not including the trailing NUL @@ -1663,4 +1680,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or https://www.sudo.ws/license.html for complete details. -Sudo 1.8.26 October 7, 2018 Sudo 1.8.26 +Sudo 1.8.26 October 24, 2018 Sudo 1.8.26 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index f184164bd..c336033b5 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.TH "SUDO_PLUGIN" "5" "October 7, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.TH "SUDO_PLUGIN" "5" "October 24, 2018" "Sudo @PACKAGE_VERSION@" "File Formats Manual" .nh .if n .ad l .SH "NAME" @@ -669,12 +669,16 @@ or function using \fRSUDO_CONV_INFO_MSG\fR. If the user requests detailed version information, the verbose flag will be set. +.sp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. .RE .TP 6n check_policy .nf .RS 6n -int (*check_policy)(int argc, char * const argv[] +int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[]); .RE @@ -1117,8 +1121,8 @@ The plugin is responsible for allocating and populating the vector. list .nf .RS 6n -int (*list)(int verbose, const char *list_user, - int argc, char * const argv[]); +int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); .RE .fi .RS 6n @@ -1434,7 +1438,7 @@ will not be called. .RS 0n /* Plugin API version major/minor. */ #define SUDO_API_VERSION_MAJOR 1 -#define SUDO_API_VERSION_MINOR 2 +#define SUDO_API_VERSION_MINOR 13 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y) #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e SUDO_API_VERSION_MINOR) @@ -1547,8 +1551,9 @@ open .RS 6n int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t plugin_printf, char * const settings[], - char * const user_info[], int argc, char * const argv[], - char * const user_env[], char * const plugin_options[]); + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); .RE .fi .RS 6n @@ -1561,6 +1566,8 @@ function is run before the \fBlog_stdin\fR(), \fBlog_stdout\fR(), \fBlog_stderr\fR(), +\fBlog_suspend\fR(), +\fBchange_winsize\fR(), or \fBshow_version\fR() functions are called. @@ -1682,6 +1689,10 @@ The number of elements in not counting the final \fRNULL\fR pointer. +It can be zero, when +\fBsudo\fR +is called with +\fB\-V\fR. .TP 6n argv If @@ -1806,6 +1817,10 @@ or function using \fRSUDO_CONV_INFO_MSG\fR. If the user requests detailed version information, the verbose flag will be set. +.sp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. .RE .TP 6n log_ttyin @@ -2440,7 +2455,14 @@ There must be a and \fRstruct sudo_conv_reply\fR for -each message in the conversation. +each message in the conversation, that is, both arrays must have the same +number of elements. +Each +\fRstruct sudo_conv_reply\fR +must have its +\fIreply\fR +member initialized to +\fRNULL\fR. The \fRstruct sudo_conv_callback\fR pointer, if not @@ -2475,13 +2497,15 @@ Prompt the user for input with echo disabled; this is generally used for passwords. The reply will be stored in the \fIreplies\fR -array. +array, and it will never be +\fRNULL\fR. .TP 6n SUDO_CONV_PROMPT_ECHO_ON Prompt the user for input with echo enabled. The reply will be stored in the \fIreplies\fR -array. +array, and it will never be +\fRNULL\fR. .TP 6n SUDO_CONV_ERROR_MSG Display an error message. @@ -2500,6 +2524,8 @@ Prompt the user for input but echo an asterisk character for each character read. The reply will be stored in the \fIreplies\fR +array, and it will never be +\fRNULL\fR. This can be used to provide visual feedback to the user while reading sensitive information that should not be displayed. .PP @@ -2531,6 +2557,11 @@ or \fRSUDO_CONV_INFO_MSG\fR was used. .PP +The +\fItimeout\fR +in seconds until the prompt will wait for no more input. +A zero value implies an infinite timeout. +.PP The plugin is responsible for freeing the reply buffer located in each \fRstruct sudo_conv_reply\fR, if it is not diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in index 18ed9e4ef..a293ee3b7 100644 --- a/doc/sudo_plugin.mdoc.in +++ b/doc/sudo_plugin.mdoc.in @@ -13,7 +13,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd October 7, 2018 +.Dd October 24, 2018 .Dt SUDO_PLUGIN @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -588,9 +588,13 @@ or function using .Dv SUDO_CONV_INFO_MSG . If the user requests detailed version information, the verbose flag will be set. +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. .It check_policy .Bd -literal -compact -int (*check_policy)(int argc, char * const argv[] +int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[]); .Ed @@ -982,8 +986,8 @@ The plugin is responsible for allocating and populating the vector. .El .It list .Bd -literal -compact -int (*list)(int verbose, const char *list_user, - int argc, char * const argv[]); +int (*list)(int argc, char * const argv[], + int verbose, const char *list_user); .Ed .Pp List available privileges for the invoking user. @@ -1265,7 +1269,7 @@ will not be called. .Bd -literal /* Plugin API version major/minor. */ #define SUDO_API_VERSION_MAJOR 1 -#define SUDO_API_VERSION_MINOR 2 +#define SUDO_API_VERSION_MINOR 13 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y) #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e SUDO_API_VERSION_MINOR) @@ -1372,8 +1376,9 @@ built against. .Bd -literal -compact int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t plugin_printf, char * const settings[], - char * const user_info[], int argc, char * const argv[], - char * const user_env[], char * const plugin_options[]); + char * const user_info[], char * const command_info[], + int argc, char * const argv[], char * const user_env[], + char * const plugin_options[]); .Ed .Pp The @@ -1384,6 +1389,8 @@ function is run before the .Fn log_stdin , .Fn log_stdout , .Fn log_stderr , +.Fn log_suspend , +.Fn change_winsize , or .Fn show_version functions are called. @@ -1500,6 +1507,10 @@ The number of elements in not counting the final .Dv NULL pointer. +It can be zero, when +.Nm sudo +is called with +.Fl V . .It argv If .No non- Ns Dv NULL , @@ -1604,6 +1615,10 @@ or function using .Dv SUDO_CONV_INFO_MSG . If the user requests detailed version information, the verbose flag will be set. +.Pp +Returns 1 on success, 0 on failure, \-1 if a general error occurred, +or \-2 if there was a usage error, although the return value is currently +ignored. .It log_ttyin .Bd -literal -compact int (*log_ttyin)(const char *buf, unsigned int len); @@ -2125,7 +2140,14 @@ There must be a and .Li struct sudo_conv_reply for -each message in the conversation. +each message in the conversation, that is, both arrays must have the same +number of elements. +Each +.Li struct sudo_conv_reply +must have its +.Em reply +member initialized to +.Dv NULL . The .Li struct sudo_conv_callback pointer, if not @@ -2160,12 +2182,14 @@ Prompt the user for input with echo disabled; this is generally used for passwords. The reply will be stored in the .Em replies -array. +array, and it will never be +.Dv NULL . .It SUDO_CONV_PROMPT_ECHO_ON Prompt the user for input with echo enabled. The reply will be stored in the .Em replies -array. +array, and it will never be +.Dv NULL . .It SUDO_CONV_ERROR_MSG Display an error message. The message is written to the standard error unless the @@ -2181,6 +2205,8 @@ Prompt the user for input but echo an asterisk character for each character read. The reply will be stored in the .Em replies +array, and it will never be +.Dv NULL . This can be used to provide visual feedback to the user while reading sensitive information that should not be displayed. .El @@ -2213,6 +2239,11 @@ or was used. .El .Pp +The +.Em timeout +in seconds until the prompt will wait for no more input. +A zero value implies an infinite timeout. +.Pp The plugin is responsible for freeing the reply buffer located in each .Li struct sudo_conv_reply , if it is not