April 2024 | ||||||
Mo | Tu | We | Th | Fr | Sa | Su |
1 | 2 | 3 | 4 | 5 | 6 | 7 |
8 | 9 | 10 | 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | 20 | 21 |
22 | 23 | 24 | 25 | 26 | 27 | 28 |
29 | 30 | 1 | 2 | 3 | 4 | 5 |
6 | 7 | 8 | 9 | 10 | 11 | 12 |
The API is versioned with a major and minor number. The minor version number is incremented when additions are made. The major number is incremented when incompatible changes are made. A plugin should be check the version passed to it and make sure that the major version matches.
The plugin API is defined by the
sudo_plugin.h
header file.
A
Plugin
line consists of the
Plugin
keyword, followed by the
symbol_name and the path to the shared object containing the
plugin. The symbol_name is the name of the
struct policy_plugin
or
struct io_plugin
in the plugin shared object. The path
may be fully qualified or relative. If not fully qualified it is
relative to the /usr/libexec directory. Any additional
parameters after the path are ignored. Lines that don't begin
with
Plugin
or
Path
are silently ignored.
The same shared object may contain multiple plugins, each with a different symbol name. The shared object file must be owned by uid 0 and only writable by its owner. Because of ambiguities that arise from composite policies, only a single policy plugin may be specified. This limitation does not apply to I/O plugins.
# # Default /etc/sudo.conf file # # Format: # Plugin plugin_name plugin_path # Path askpass /path/to/askpass # # The plugin_path is relative to /usr/libexec unless # fully qualified. # The plugin_name corresponds to a global symbol in the plugin # that contains the plugin interface structure. # Plugin sudoers_policy sudoers.so Plugin sudoers_io sudoers.so
struct policy_plugin { #define SUDO_POLICY_PLUGIN 1 unsigned int type; /* always SUDO_POLICY_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t plugin_printf, char * const settings[], char * const user_info[], char * const user_env[]); void (*close)(int exit_status, int error); int (*show_version)(int verbose); int (*check_policy)(int argc, char * const argv[], char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[]); int (*list)(int argc, char * const argv[], int verbose, const char *list_user); int (*validate)(void); void (*invalidate)(int remove); int (*init_session)(struct passwd *pwd); };
The policy_plugin struct has the following fields:
This allows sudo to determine the API version the plugin was built against.
int (*open)(unsigned int version, sudo_conv_t conversation, sudo_printf_t plugin_printf, char * const settings[], char * const user_info[], char * const user_env[]);
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, sudo 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 as follows:
When parsing settings, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
Additional settings may be added in the future so the plugin should silently ignore settings that it does not recognize.
When parsing user_info, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
When parsing user_env, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
void (*close)(int exit_status, int error);
The
close
function is called when the command being run by sudo
finishes.
The function arguments are as follows:
int (*show_version)(int verbose);
The
show_version
function is called by sudo when the user specifies
the
-V
option. The plugin may display its version information
to the user via the conversation or plugin_printf function using
SUDO_CONV_INFO_MSG
. If the user requests detailed version
information, the verbose flag will be set.
int (*check_policy)(int argc, char * const argv[] char *env_add[], char **command_info[], char **argv_out[], char **user_env_out[]);
The check_policy function is called by sudo to determine whether the user is allowed to run the specified commands.
If the sudoedit option was enabled in the settings array
passed to the open function, the user has requested sudoedit
mode. sudoedit is a mechanism for editing one or more files
where an editor is run with the user's credentials instead of with
elevated privileges. sudo achieves 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. If
the plugin supports sudoedit, it should choose the editor to be
used, potentially from a variable in the user's environment, such
as
EDITOR
, and include it in argv_out (note that environment
variables may include command line flags). The files to be edited
should be copied from argv into argv_out, separated from the
editor and its arguments by a "--" element. The "--" will
be removed by sudo before the editor is executed. The plugin
should also set sudoedit=true in the command_info list.
The check_policy 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 sudoedit was specified but is unsupported by the plugin.
In the latter case, sudo 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 as follows:
When parsing env_add, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
Unsupported values will be ignored.
int (*list)(int verbose, const char *list_user, int argc, char * const argv[]);
List available privileges for the invoking user. 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.
Privileges should be output via the conversation or plugin_printf
function using
SUDO_CONV_INFO_MSG
.
int (*validate)(void);
The
validate
function is called when sudo is run with the
-v
flag. For policy plugins such as sudoers 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 plugin may optionally call the conversation or plugin_printf
function with
SUDO_CONF_ERROR_MSG
to present additional
error information to the user.
void (*invalidate)(int remove);
The
invalidate
function is called when sudo is called with
the
-k
or
-K
flag. For policy plugins such as sudoers that
cache authentication credentials, this function will invalidate the
credentials. If the remove flag is set, the plugin may remove
the credentials instead of simply invalidating them.
The
invalidate
function should be
NULL
if the plugin does not
support credential caching.
int (*init_session)(struct passwd *pwd);
The
init_session
function is called when sudo sets up the
execution environment for the command, immediately before the
contents of the command_info list are applied (before the uid
changes). This can be used to do session setup that is not supported
by command_info, such as opening the PAM session.
The pwd argument points to a passwd struct for the user the command will be run as if the uid the command will run as was found in the password database, otherwise it will be NULL.
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.
Version macros
#define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \ *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \ } while(0) #define SUDO_VERSION_SET_MINOR(vp, n) do { \ *(vp) = (*(vp) & 0xffff0000) | (n); \ } while(0) #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)
struct io_plugin { #define SUDO_IO_PLUGIN 2 unsigned int type; /* always SUDO_IO_PLUGIN */ unsigned int version; /* always SUDO_API_VERSION */ 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[]); void (*close)(int exit_status, int error); /* wait status or error */ int (*show_version)(int verbose); int (*log_ttyin)(const char *buf, unsigned int len); int (*log_ttyout)(const char *buf, unsigned int len); int (*log_stdin)(const char *buf, unsigned int len); int (*log_stdout)(const char *buf, unsigned int len); int (*log_stderr)(const char *buf, unsigned int len); };
When an I/O plugin is loaded, sudo runs the command in a pseudo-tty. This makes it possible to log the input and output from the user's session. If any of the standard input, standard output or standard error do not correspond to a tty, sudo will open a pipe to capture the I/O for logging before passing it on.
The log_ttyin function receives the raw user input from the terminal device (note that this will include input even when echo is disabled, such as when a password is read). The log_ttyout function receives output from the pseudo-tty that is suitable for replaying the user's session at a later time. The log_stdin, log_stdout and log_stderr functions are only called if the standard input, standard output or standard error respectively correspond to something other than a tty.
Any of the logging functions may be set to the NULL pointer if no logging is to be performed. If the open function returns 0, no I/O will be sent to the plugin.
The io_plugin struct has the following fields:
This allows sudo to determine the API version the plugin was built against.
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[]);
The open function is run before the log_input, log_output
or show_version functions are called. It is only called if the
version is being requested or the check_policy 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, sudo 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 as follows:
When parsing settings, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
See the ``Policy Plugin API'' section for a list of all possible settings.
When parsing user_info, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
See the ``Policy Plugin API'' section for a list of all possible strings.
When parsing user_env, the plugin should split on the first equal sign ('=') since the name field will never include one itself but the value might.
void (*close)(int exit_status, int error);
The
close
function is called when the command being run by sudo
finishes.
The function arguments are as follows:
int (*show_version)(int verbose);
The
show_version
function is called by sudo when the user specifies
the
-V
option. The plugin may display its version information
to the user via the conversation or plugin_printf function using
SUDO_CONV_INFO_MSG
. If the user requests detailed version
information, the verbose flag will be set.
int (*log_ttyin)(const char *buf, unsigned int len);
The log_ttyin function is called whenever data can be read from
the 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.
The function arguments are as follows:
int (*log_ttyout)(const char *buf, unsigned int len);
The log_ttyout function is called whenever data can be read from
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 be passed to the user, 0 if the data is rejected
(which will terminate the command) or
-1
if an error occurred.
The function arguments are as follows:
int (*log_stdin)(const char *buf, unsigned int len);
The log_stdin function is only used if the standard input does
not correspond to a tty device. It is called whenever data can be
read from the standard input 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.
The function arguments are as follows:
int (*log_stdout)(const char *buf, unsigned int len);
The log_stdout function is only used if the standard output does
not correspond to a tty device. It is called whenever data can be
read from the command but before it is written to the standard
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 (which will terminate the command) or
-1
if an error
occurred.
The function arguments are as follows:
int (*log_stderr)(const char *buf, unsigned int len);
The log_stderr function is only used if the standard error does
not correspond to a tty device. It is called whenever data can be
read from the command but before it is written to the standard
error. 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 (which will terminate the command) or
-1
if an error
occurred.
The function arguments are as follows:
Version macros
Same as for the ``Policy Plugin API''.
A printf-style function is also available that can be used to display informational or error messages to the user, which is usually more convenient for simple messages where no use input is required.
struct sudo_conv_message { #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */ #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */ #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */ #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */ #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */ #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */ int msg_type; int timeout; const char *msg; }; struct sudo_conv_reply { char *reply; }; typedef int (*sudo_conv_t)(int num_msgs, const struct sudo_conv_message msgs[], 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 to the plugin's
open
function when the plugin is initialized.
To use the conversation 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 plugin is responsible for
freeing the reply buffer filled in to the
struct sudo_conv_reply
,
if any.
The printf-style function uses the same underlying mechanism as the
conversation function but only supports
SUDO_CONV_INFO_MSG
and
SUDO_CONV_ERROR_MSG
for the msg_type parameter. It can be
more convenient than using the conversation function if no user
reply is needed and supports standard printf() escape sequences.
See the sample plugin for an example of the conversation function usage.
A group plugin must declare and populate a
sudoers_group_plugin
struct in the global scope. This structure contains pointers to
the functions that implement plugin initialization, cleanup and
group lookup.
struct sudoers_group_plugin { unsigned int version; int (*init)(int version, sudo_printf_t sudo_printf, char *const argv[]); void (*cleanup)(void); int (*query)(const char *user, const char *group, const struct passwd *pwd); };
The
sudoers_group_plugin
struct has the following fields:
This allows sudoers to determine the API version the group plugin was built against.
int (*init)(int version, sudo_printf_t plugin_printf, char *const argv[]);
The init function is called after sudoers 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 the user.
The function arguments are as follows:
void (*cleanup)();
The cleanup function is called when sudoers has finished its group checks. The plugin should free any memory it has allocated and close open file handles.
int (*query)(const char *user, const char *group, const struct passwd *pwd);
The query function is used to ask the group plugin whether user is a member of group.
The function arguments are as follows:
Version Macros
/* 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) #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff) #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \ *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \ } while(0) #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \ *(vp) = (*(vp) & 0xffff0000) | (n); \ } while(0)