From: Todd C. Miller Date: Thu, 13 May 2010 21:49:52 +0000 (-0400) Subject: Document sudoedit X-Git-Tag: SUDO_1_8_0~634 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c8a62b1ecb2a8f18aceda28187aae5d730762382;p=sudo Document sudoedit --- diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 6dd2f4eb2..08be5adb5 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -61,7 +61,7 @@ SSuuddoo PPlluuggiinn AAPPII -1.8.0a1 May 5, 2010 1 +1.8.0a1 May 13, 2010 1 @@ -86,6 +86,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) const char *list_user); int (*validate)(void); void (*invalidate)(int remove); + int (*check_sudoedit)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); }; The policy_plugin struct has the following fields: @@ -122,12 +125,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) A pointer to the conversation function that can be used by the plugin to interact with the user (see below). - plugin_printf - A pointer to a printf-style function that may be used to - -1.8.0a1 May 5, 2010 2 +1.8.0a1 May 13, 2010 2 @@ -136,6 +136,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) 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 messages (see below). settings @@ -187,13 +189,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) from the check_policy function, which will cause ssuuddoo to print a usage message and exit. - preserve_groups=bool - Set to true if the user specified the -P flag, indicating - that the user wishes to preserve the group vector instead -1.8.0a1 May 5, 2010 3 + +1.8.0a1 May 13, 2010 3 @@ -202,6 +202,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + preserve_groups=bool + Set to true if the user specified the -P flag, indicating + that the user wishes to preserve the group vector instead of setting it based on the runas user. ignore_ticket=bool @@ -253,13 +256,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) uid=uid_t The real user ID of the user invoking ssuuddoo. - gid=gid_t - The real group ID of the user invoking ssuuddoo. - -1.8.0a1 May 5, 2010 4 +1.8.0a1 May 13, 2010 4 @@ -268,6 +268,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + gid=gid_t + The real group ID of the user invoking ssuuddoo. + groups=list The user's supplementary group list formatted as a string of comma-separated group IDs. @@ -319,13 +322,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) If the command could not be executed, this is set to the value of errno set by the _e_x_e_c_v_e(2) system call. The plugin is responsible for displaying error information via the - conversation or plugin_printf function. If the command was - successfully executed, the value of error is 0. - -1.8.0a1 May 5, 2010 5 +1.8.0a1 May 13, 2010 5 @@ -334,6 +334,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + conversation or plugin_printf function. If the command was + successfully executed, the value of error is 0. + show_version int (*show_version)(int verbose); @@ -385,13 +388,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) execution environment when running a command. The plugin is responsible for creating and populating the vector, which must be terminated with a NULL pointer. The following values are - recognized by ssuuddoo: - - -1.8.0a1 May 5, 2010 6 +1.8.0a1 May 13, 2010 6 @@ -400,6 +400,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + recognized by ssuuddoo: + command=string Fully qualified path to the command to be executed. @@ -452,12 +454,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) selinux_role=string SELinux role to use when executing the command. - selinux_type=string - SELinux type to use when executing the command. -1.8.0a1 May 5, 2010 7 +1.8.0a1 May 13, 2010 7 @@ -466,6 +466,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + selinux_type=string + SELinux type to use when executing the command. + timeout=int Command timeout. If non-zero then when the timeout expires the command will be killed. @@ -518,12 +521,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) validate int (*validate)(void); - 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 - -1.8.0a1 May 5, 2010 8 +1.8.0a1 May 13, 2010 8 @@ -532,6 +532,8 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) 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 @@ -554,8 +556,48 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The invalidate function should be NULL if the plugin does not support credential caching. + check_sudoedit + int (*check_sudoedit)(int argc, char * const argv[] + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + + The _c_h_e_c_k___s_u_d_o_e_d_i_t function is called instead of _c_h_e_c_k___p_o_l_i_c_y when + ssuuddoo is invoked as ssuuddooeeddiitt or with the -e flag. ssuuddooeeddiitt is a + mechanism for editing one or more files where the user's editor is + run with the user's credentials instead of elevated privileges. + ssuuddoo does this by creating user-writable temporary copies of the + files to be edited and then overwriting the originals with the + temporary copies after editing is complete. + + The plugin should choose the editor to be used, potentially from a + variable in the user's environment, and include it in _a_r_g_v___o_u_t. + The files to be edited should be copied from _a_r_g_v 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. + + Returns 1 if the command is allowed, 0 if not allowed, -1 for a + general error, or -2 for 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 conversation or plugin_printf + function with SUDO_CONF_ERROR_MSG to present additional error + information to the user. + + The function arguments are the same as for _c_h_e_c_k___p_o_l_i_c_y. + _C_o_n_v_e_r_s_a_t_i_o_n _A_P_I + + + +1.8.0a1 May 13, 2010 9 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + If the plugin needs to interact with the user, it may do so via the conversation function. A plugin should not attempt to read directly from the standard input or the user's tty (neither of which are @@ -586,18 +628,6 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...); - - - -1.8.0a1 May 5, 2010 9 - - - - - -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - Pointers to the conversation and printf-style functions are passed in to the plugin's open function when the plugin is initialized. @@ -617,6 +647,23 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) usage. II//OO PPlluuggiinn AAPPII + + + + + + + + +1.8.0a1 May 13, 2010 10 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + struct io_plugin { #define SUDO_IO_PLUGIN 2 unsigned int type; /* always SUDO_IO_PLUGIN */ @@ -653,17 +700,6 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The io_plugin struct has the following fields: - - -1.8.0a1 May 5, 2010 10 - - - - - -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - type The type field should always be set to SUDO_IO_PLUGIN @@ -682,6 +718,18 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) _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 + + + +1.8.0a1 May 13, 2010 11 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + 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 conversation @@ -718,18 +766,6 @@ 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. - - - -1.8.0a1 May 5, 2010 11 - - - - - -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - See the "Policy Plugin API" section for a list of all possible settings. @@ -749,6 +785,17 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The user's environment in the form of a NULL-terminated vector of "name=value" strings. + + +1.8.0a1 May 13, 2010 12 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + 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. @@ -784,18 +831,6 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) int (*log_ttyin)(const char *buf, unsigned int len); The _l_o_g___t_t_y_i_n function is called whenever data can be read from the - - - -1.8.0a1 May 5, 2010 12 - - - - - -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 @@ -815,6 +850,18 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) the command but before it is written to the user's terminal. This allows the plugin to reject data if it chooses to (for instance if the output contains banned content). Returns 1 if the data should + + + +1.8.0a1 May 13, 2010 13 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + be passed to the user, 0 if the data is rejected (which will terminate the command) or -1 if an error occurred. @@ -850,18 +897,6 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) output. This allows the plugin to reject data if it chooses to (for instance if the output contains banned content). Returns 1 if the data should be passed to the user, 0 if the data is rejected - - - -1.8.0a1 May 5, 2010 13 - - - - - -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - (which will terminate the command) or -1 if an error occurred. The function arguments are as follows: @@ -881,6 +916,18 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) data should be passed to the user, 0 if the data is rejected (which will terminate the command) or -1 if an error occurred. + + + +1.8.0a1 May 13, 2010 14 + + + + + +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + + The function arguments are as follows: buf The buffer containing command output. @@ -919,6 +966,25 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0a1 May 5, 2010 14 + + + + + + + + + + + + + + + + + + + +1.8.0a1 May 13, 2010 15 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index 11e23a274..e94a4b29b 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@ "May 5, 2010" "1.8.0a1" "MAINTENANCE COMMANDS" +.TH SUDO_PLUGIN @mansectsu@ "May 13, 2010" "1.8.0a1" "MAINTENANCE COMMANDS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -219,6 +219,9 @@ so that \fBsudo\fR can load it. \& const char *list_user); \& int (*validate)(void); \& void (*invalidate)(int remove); +\& int (*check_sudoedit)(int argc, char * const argv[], +\& char *env_add[], char **command_info[], +\& char **argv_out[], char **user_env_out[]); \& }; .Ve .PP @@ -635,6 +638,36 @@ the credentials instead of simply invalidating them. .Sp The \f(CW\*(C`invalidate\*(C'\fR function should be \f(CW\*(C`NULL\*(C'\fR if the plugin does not support credential caching. +.IP "check_sudoedit" 4 +.IX Item "check_sudoedit" +.Vb 3 +\& int (*check_sudoedit)(int argc, char * const argv[] +\& char *env_add[], char **command_info[], +\& char **argv_out[], char **user_env_out[]); +.Ve +.Sp +The \fIcheck_sudoedit\fR function is called instead of \fIcheck_policy\fR +when \fBsudo\fR is invoked as \fBsudoedit\fR or with the \f(CW\*(C`\-e\*(C'\fR flag. +\&\fBsudoedit\fR is a mechanism for editing one or more files where the +user's editor is run with the user's credentials instead of elevated +privileges. \fBsudo\fR does this by creating user-writable temporary +copies of the files to be edited and then overwriting the originals +with the temporary copies after editing is complete. +.Sp +The plugin should choose the editor to be used, potentially from a +variable in the user's environment, and include it in \fIargv_out\fR. +The files to be edited should be copied from \fIargv\fR into \fIargv_out\fR, +separated from the editor and its arguments by a \f(CW"\-\-"\fR element. +The \f(CW"\-\-"\fR will be removed by \fBsudo\fR before the editor is executed. +.Sp +Returns 1 if the command is allowed, 0 if not allowed, \-1 for a +general error, or \-2 for a usage error. In the latter case, \fBsudo\fR +will print a usage message before it exits. If an error occurs, +the plugin may optionally call the conversation or plugin_printf +function with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional error +information to the user. +.Sp +The function arguments are the same as for \fIcheck_policy\fR. .PP \fIConversation \s-1API\s0\fR .IX Subsection "Conversation API" diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod index 3209df492..eca8c1f26 100644 --- a/doc/sudo_plugin.pod +++ b/doc/sudo_plugin.pod @@ -89,6 +89,9 @@ so that B can load it. const char *list_user); int (*validate)(void); void (*invalidate)(int remove); + int (*check_sudoedit)(int argc, char * const argv[], + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); }; The policy_plugin struct has the following fields: @@ -561,6 +564,35 @@ the credentials instead of simply invalidating them. The C function should be C if the plugin does not support credential caching. +=item check_sudoedit + + int (*check_sudoedit)(int argc, char * const argv[] + char *env_add[], char **command_info[], + char **argv_out[], char **user_env_out[]); + +The I function is called instead of I +when B is invoked as B or with the C<-e> flag. +B is a mechanism for editing one or more files where the +user's editor is run with the user's credentials instead of elevated +privileges. B does this by creating user-writable temporary +copies of the files to be edited and then overwriting the originals +with the temporary copies after editing is complete. + +The plugin should choose the editor to be used, potentially from a +variable in the user's environment, and include it in I. +The files to be edited should be copied from I into I, +separated from the editor and its arguments by a C<"--"> element. +The C<"--"> will be removed by B before the editor is executed. + +Returns 1 if the command is allowed, 0 if not allowed, -1 for a +general error, or -2 for a usage error. In the latter case, B +will print a usage message before it exits. If an error occurs, +the plugin may optionally call the conversation or plugin_printf +function with C to present additional error +information to the user. + +The function arguments are the same as for I. + =back =head3 Conversation API