Annotation of embedaddon/sudo/doc/sudo_plugin.cat, revision 1.1.1.4
1.1.1.3 misho 1: SUDO_PLUGIN(4) Programmer's Manual SUDO_PLUGIN(4)
1.1 misho 2:
3: NNAAMMEE
1.1.1.3 misho 4: ssuuddoo__pplluuggiinn - Sudo Plugin API
1.1 misho 5:
6: DDEESSCCRRIIPPTTIIOONN
1.1.1.3 misho 7: Starting with version 1.8, ssuuddoo supports a plugin API for policy and
1.1.1.4 ! misho 8: session logging. By default, the ssuuddooeerrss policy plugin and an associated
1.1.1.3 misho 9: I/O logging plugin are used. Via the plugin API, ssuuddoo can be configured
10: to use alternate policy and/or I/O logging plugins provided by third
1.1.1.4 ! misho 11: parties. The plugins to be used are specified in the sudo.conf(4) file.
1.1.1.3 misho 12:
13: The API is versioned with a major and minor number. The minor version
14: number is incremented when additions are made. The major number is
15: incremented when incompatible changes are made. A plugin should be check
16: the version passed to it and make sure that the major version matches.
17:
18: The plugin API is defined by the sudo_plugin.h header file.
19:
20: PPoolliiccyy pplluuggiinn AAPPII
21: A policy plugin must declare and populate a policy_plugin struct in the
22: global scope. This structure contains pointers to the functions that
23: implement the ssuuddoo policy checks. The name of the symbol should be
1.1.1.4 ! misho 24: specified in sudo.conf(4) along with a path to the plugin so that ssuuddoo
1.1.1.3 misho 25: can load it.
26:
27: struct policy_plugin {
28: #define SUDO_POLICY_PLUGIN 1
29: unsigned int type; /* always SUDO_POLICY_PLUGIN */
30: unsigned int version; /* always SUDO_API_VERSION */
31: int (*open)(unsigned int version, sudo_conv_t conversation,
32: sudo_printf_t plugin_printf, char * const settings[],
33: char * const user_info[], char * const user_env[],
34: char * const plugin_options[]);
35: void (*close)(int exit_status, int error);
36: int (*show_version)(int verbose);
37: int (*check_policy)(int argc, char * const argv[],
38: char *env_add[], char **command_info[],
39: char **argv_out[], char **user_env_out[]);
40: int (*list)(int argc, char * const argv[], int verbose,
41: const char *list_user);
42: int (*validate)(void);
43: void (*invalidate)(int remove);
44: int (*init_session)(struct passwd *pwd, char **user_env[]);
45: void (*register_hooks)(int version,
46: int (*register_hook)(struct sudo_hook *hook));
47: void (*deregister_hooks)(int version,
48: int (*deregister_hook)(struct sudo_hook *hook));
49: };
1.1 misho 50:
1.1.1.3 misho 51: The policy_plugin struct has the following fields:
1.1 misho 52:
1.1.1.3 misho 53: type The type field should always be set to SUDO_POLICY_PLUGIN.
1.1 misho 54:
1.1.1.3 misho 55: version
1.1 misho 56: The version field should be set to SUDO_API_VERSION.
57:
58: This allows ssuuddoo to determine the API version the plugin was built
59: against.
60:
1.1.1.3 misho 61: open
62: int (*open)(unsigned int version, sudo_conv_t conversation,
63: sudo_printf_t plugin_printf, char * const settings[],
64: char * const user_info[], char * const user_env[],
65: char * const plugin_options[]);
1.1 misho 66:
67: Returns 1 on success, 0 on failure, -1 if a general error occurred,
68: or -2 if there was a usage error. In the latter case, ssuuddoo will
69: print a usage message before it exits. If an error occurs, the
1.1.1.3 misho 70: plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff()
1.1 misho 71: function with SUDO_CONF_ERROR_MSG to present additional error
72: information to the user.
73:
74: The function arguments are as follows:
75:
76: version
1.1.1.3 misho 77: The version passed in by ssuuddoo allows the plugin to determine
78: the major and minor version number of the plugin API
79: supported by ssuuddoo.
1.1 misho 80:
81: conversation
1.1.1.3 misho 82: A pointer to the ccoonnvveerrssaattiioonn() function that can be used by
83: the plugin to interact with the user (see below). Returns 0
84: on success and -1 on failure.
1.1 misho 85:
86: plugin_printf
1.1.1.3 misho 87: A pointer to a pprriinnttff()-style function that may be used to
88: display informational or error messages (see below). Returns
89: the number of characters printed on success and -1 on
90: failure.
1.1 misho 91:
92: settings
1.1.1.3 misho 93: A vector of user-supplied ssuuddoo settings in the form of
94: ``name=value'' strings. The vector is terminated by a NULL
95: pointer. These settings correspond to flags the user
96: specified when running ssuuddoo. As such, they will only be
97: present when the corresponding flag has been specified on the
98: command line.
99:
100: When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt
101: equal sign (`=') since the _n_a_m_e field will never include one
102: itself but the _v_a_l_u_e might.
103:
1.1.1.4 ! misho 104: bsdauth_type=string
! 105: Authentication type, if specified by the --aa flag, to
! 106: use on systems where BSD authentication is supported.
! 107:
! 108: closefrom=number
! 109: If specified, the user has requested via the --CC flag
! 110: that ssuuddoo close all files descriptors with a value of
! 111: _n_u_m_b_e_r or higher. The plugin may optionally pass this,
! 112: or another value, back in the _c_o_m_m_a_n_d___i_n_f_o list.
! 113:
1.1.1.3 misho 114: debug_flags=string
115: A comma-separated list of debug flags that correspond
1.1.1.4 ! misho 116: to ssuuddoo's Debug entry in sudo.conf(4), if there is one.
! 117: The flags are passed to the plugin as they appear in
! 118: sudo.conf(4). The syntax used by ssuuddoo and the ssuuddooeerrss
! 119: plugin is _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y but the plugin is free to
! 120: use a different format so long as it does not include a
! 121: comma (`,'). There is not currently a way to specify a
! 122: set of debug flags specific to the plugin--the flags
! 123: are shared by ssuuddoo and the plugin.
1.1.1.3 misho 124:
125: debug_level=number
126: This setting has been deprecated in favor of
127: _d_e_b_u_g___f_l_a_g_s.
128:
1.1.1.4 ! misho 129: ignore_ticket=bool
! 130: Set to true if the user specified the --kk flag along
! 131: with a command, indicating that the user wishes to
! 132: ignore any cached authentication credentials.
! 133: _i_m_p_l_i_e_d___s_h_e_l_l to true. This allows ssuuddoo with no
! 134: arguments to be used similarly to su(1). If the plugin
! 135: does not to support this usage, it may return a value
! 136: of -2 from the cchheecckk__ppoolliiccyy() function, which will
! 137: cause ssuuddoo to print a usage message and exit.
1.1.1.3 misho 138:
1.1.1.4 ! misho 139: implied_shell=bool
! 140: If the user does not specify a program on the command
! 141: line, ssuuddoo will pass the plugin the path to the user's
! 142: shell and set
1.1.1.3 misho 143:
1.1.1.4 ! misho 144: login_class=string
! 145: BSD login class to use when setting resource limits and
! 146: nice value, if specified by the --cc flag.
1.1.1.3 misho 147:
1.1.1.4 ! misho 148: login_shell=bool
! 149: Set to true if the user specified the --ii flag,
! 150: indicating that the user wishes to run a login shell.
! 151:
! 152: max_groups=int
! 153: The maximum number of groups a user may belong to.
! 154: This will only be present if there is a corresponding
! 155: setting in sudo.conf(4).
! 156:
! 157: network_addrs=list
! 158: A space-separated list of IP network addresses and
! 159: netmasks in the form ``addr/netmask'', e.g.
! 160: ``192.168.1.2/255.255.255.0''. The address and netmask
! 161: pairs may be either IPv4 or IPv6, depending on what the
! 162: operating system supports. If the address contains a
! 163: colon (`:'), it is an IPv6 address, else it is IPv4.
! 164:
! 165: noninteractive=bool
! 166: Set to true if the user specified the --nn flag,
! 167: indicating that ssuuddoo should operate in non-interactive
! 168: mode. The plugin may reject a command run in non-
! 169: interactive mode if user interaction is required.
! 170:
! 171: plugin_dir=string
! 172: The default plugin directory used by the ssuuddoo front
! 173: end. This is the default directory set at compile time
! 174: and may not correspond to the directory the running
! 175: plugin was loaded from. It may be used by a plugin to
! 176: locate support files.
1.1.1.3 misho 177:
178: preserve_environment=bool
179: Set to true if the user specified the --EE flag,
180: indicating that the user wishes to preserve the
181: environment.
182:
183: preserve_groups=bool
184: Set to true if the user specified the --PP flag,
185: indicating that the user wishes to preserve the group
186: vector instead of setting it based on the runas user.
187:
1.1.1.4 ! misho 188: progname=string
! 189: The command name that sudo was run as, typically
! 190: ``sudo'' or ``sudoedit''.
1.1.1.3 misho 191:
1.1.1.4 ! misho 192: prompt=string
! 193: The prompt to use when requesting a password, if
! 194: specified via the --pp flag.
1.1.1.3 misho 195:
1.1.1.4 ! misho 196: run_shell=bool
! 197: Set to true if the user specified the --ss flag,
! 198: indicating that the user wishes to run a shell.
! 199:
! 200: runas_group=string
! 201: The group name or gid to to run the command as, if
! 202: specified via the --gg flag.
! 203:
! 204: runas_user=string
! 205: The user name or uid to to run the command as, if
! 206: specified via the --uu flag.
1.1.1.3 misho 207:
208: selinux_role=string
209: SELinux role to use when executing the command, if
210: specified by the --rr flag.
211:
212: selinux_type=string
213: SELinux type to use when executing the command, if
214: specified by the --tt flag.
215:
1.1.1.4 ! misho 216: set_home=bool
! 217: Set to true if the user specified the --HH flag. If
! 218: true, set the HOME environment variable to the target
! 219: user's home directory.
1.1.1.3 misho 220:
221: sudoedit=bool
222: Set to true when the --ee flag is is specified or if
223: invoked as ssuuddooeeddiitt. The plugin shall substitute an
224: editor into _a_r_g_v in the cchheecckk__ppoolliiccyy() function or
225: return -2 with a usage error if the plugin does not
226: support _s_u_d_o_e_d_i_t. For more information, see the
227: _c_h_e_c_k___p_o_l_i_c_y section.
228:
229: Additional settings may be added in the future so the plugin
230: should silently ignore settings that it does not recognize.
1.1 misho 231:
232: user_info
1.1.1.3 misho 233: A vector of information about the user running the command in
234: the form of ``name=value'' strings. The vector is terminated
235: by a NULL pointer.
236:
237: When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt
238: equal sign (`=') since the _n_a_m_e field will never include one
239: itself but the _v_a_l_u_e might.
240:
1.1.1.4 ! misho 241: cols=int
! 242: The number of columns the user's terminal supports. If
! 243: there is no terminal device available, a default value
! 244: of 80 is used.
1.1.1.3 misho 245:
1.1.1.4 ! misho 246: cwd=string
! 247: The user's current working directory.
1.1.1.3 misho 248:
1.1.1.4 ! misho 249: egid=gid_t
! 250: The effective group ID of the user invoking ssuuddoo.
1.1.1.3 misho 251:
252: euid=uid_t
253: The effective user ID of the user invoking ssuuddoo.
254:
255: gid=gid_t
256: The real group ID of the user invoking ssuuddoo.
257:
258: groups=list
259: The user's supplementary group list formatted as a
260: string of comma-separated group IDs.
261:
262: host=string
263: The local machine's hostname as returned by the
264: gethostname(2) system call.
265:
266: lines=int
267: The number of lines the user's terminal supports. If
268: there is no terminal device available, a default value
269: of 24 is used.
270:
1.1.1.4 ! misho 271: pgid=int
! 272: The ID of the process group that the running ssuuddoo
! 273: process is a member of. Only available starting with
! 274: API version 1.2
! 275:
! 276: pid=int
! 277: The process ID of the running ssuuddoo process. Only
! 278: available starting with API version 1.2
! 279:
! 280: plugin_options
! 281: Any (non-comment) strings immediately after the plugin
! 282: path are passed as arguments to the plugin. These
! 283: arguments are split on a white space boundary and are
! 284: passed to the plugin in the form of a NULL-terminated
! 285: array of strings. If no arguments were specified,
! 286: _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL pointer.
! 287:
! 288: NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available
! 289: starting with API version 1.2. A plugin mmuusstt check the
! 290: API version specified by the ssuuddoo front end before
! 291: using _p_l_u_g_i_n___o_p_t_i_o_n_s. Failure to do so may result in a
! 292: crash.
! 293:
! 294: ppid=int
! 295: The parent process ID of the running ssuuddoo process.
! 296: Only available starting with API version 1.2
! 297:
! 298: sid=int
! 299: The session ID of the running ssuuddoo process or 0 if ssuuddoo
! 300: is not part of a POSIX job control session. Only
! 301: available starting with API version 1.2
! 302:
! 303: tcpgid=int
! 304: The ID of the foreground process group associated with
! 305: the terminal device associated with the ssuuddoo process or
! 306: -1 if there is no terminal present. Only available
! 307: starting with API version 1.2
! 308:
! 309: tty=string
! 310: The path to the user's terminal device. If the user
! 311: has no terminal device associated with the session, the
! 312: value will be empty, as in ``tty=''.
! 313:
! 314: uid=uid_t
! 315: The real user ID of the user invoking ssuuddoo.
! 316:
! 317: user=string
! 318: The name of the user invoking ssuuddoo.
1.1 misho 319:
320: user_env
1.1.1.3 misho 321: The user's environment in the form of a NULL-terminated
322: vector of ``name=value'' strings.
1.1 misho 323:
1.1.1.3 misho 324: When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt
325: equal sign (`=') since the _n_a_m_e field will never include one
326: itself but the _v_a_l_u_e might.
1.1 misho 327:
1.1.1.3 misho 328: close
329: void (*close)(int exit_status, int error);
1.1 misho 330:
1.1.1.3 misho 331: The cclloossee() function is called when the command being run by ssuuddoo
1.1 misho 332: finishes.
333:
334: The function arguments are as follows:
335:
336: exit_status
1.1.1.3 misho 337: The command's exit status, as returned by the wait(2) system
338: call. The value of exit_status is undefined if error is non-
339: zero.
1.1 misho 340:
341: error
1.1.1.3 misho 342: If the command could not be executed, this is set to the
343: value of errno set by the execve(2) system call. The plugin
344: is responsible for displaying error information via the
345: ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function. If the command
346: was successfully executed, the value of error is 0.
347:
1.1.1.4 ! misho 348: If no cclloossee() function is defined, no I/O logging plugins are
! 349: loaded, and neither the _t_i_m_e_o_u_t not _u_s_e___p_t_y options are set in the
! 350: command_info list, the ssuuddoo front end may execute the command
! 351: directly instead of running it as a child process.
! 352:
1.1.1.3 misho 353: show_version
354: int (*show_version)(int verbose);
355:
356: The sshhooww__vveerrssiioonn() function is called by ssuuddoo when the user
357: specifies the --VV option. The plugin may display its version
358: information to the user via the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff()
359: function using SUDO_CONV_INFO_MSG. If the user requests detailed
360: version information, the verbose flag will be set.
361:
362: check_policy
363: int (*check_policy)(int argc, char * const argv[]
364: char *env_add[], char **command_info[],
365: char **argv_out[], char **user_env_out[]);
1.1 misho 366:
1.1.1.3 misho 367: The cchheecckk__ppoolliiccyy() function is called by ssuuddoo to determine whether
1.1 misho 368: the user is allowed to run the specified commands.
369:
370: If the _s_u_d_o_e_d_i_t option was enabled in the _s_e_t_t_i_n_g_s array passed to
1.1.1.3 misho 371: the ooppeenn() function, the user has requested _s_u_d_o_e_d_i_t mode.
372: _s_u_d_o_e_d_i_t is a mechanism for editing one or more files where an
373: editor is run with the user's credentials instead of with elevated
374: privileges. ssuuddoo achieves this by creating user-writable temporary
375: copies of the files to be edited and then overwriting the originals
376: with the temporary copies after editing is complete. If the plugin
377: supports _s_u_d_o_e_d_i_t, it should choose the editor to be used,
378: potentially from a variable in the user's environment, such as
379: EDITOR, and include it in _a_r_g_v___o_u_t (note that environment variables
380: may include command line flags). The files to be edited should be
381: copied from _a_r_g_v into _a_r_g_v___o_u_t, separated from the editor and its
382: arguments by a ``--'' element. The ``--'' will be removed by ssuuddoo
383: before the editor is executed. The plugin should also set
384: _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.
385:
386: The cchheecckk__ppoolliiccyy() function returns 1 if the command is allowed, 0
387: if not allowed, -1 for a general error, or -2 for a usage error or
388: if _s_u_d_o_e_d_i_t was specified but is unsupported by the plugin. In the
1.1 misho 389: latter case, ssuuddoo will print a usage message before it exits. If
1.1.1.3 misho 390: an error occurs, the plugin may optionally call the ccoonnvveerrssaattiioonn()
391: or pplluuggiinn__pprriinnttff() function with SUDO_CONF_ERROR_MSG to present
1.1 misho 392: additional error information to the user.
393:
394: The function arguments are as follows:
395:
1.1.1.3 misho 396: argc The number of elements in _a_r_g_v, not counting the final NULL
397: pointer.
398:
399: argv The argument vector describing the command the user wishes to
400: run, in the same form as what would be passed to the
401: execve(2) system call. The vector is terminated by a NULL
402: pointer.
1.1 misho 403:
404: env_add
1.1.1.3 misho 405: Additional environment variables specified by the user on the
406: command line in the form of a NULL-terminated vector of
407: ``name=value'' strings. The plugin may reject the command if
408: one or more variables are not allowed to be set, or it may
409: silently ignore such variables.
410:
411: When parsing _e_n_v___a_d_d, the plugin should split on the ffiirrsstt
412: equal sign (`=') since the _n_a_m_e field will never include one
413: itself but the _v_a_l_u_e might.
1.1 misho 414:
415: command_info
1.1.1.3 misho 416: Information about the command being run in the form of
417: ``name=value'' strings. These values are used by ssuuddoo to set
418: the execution environment when running a command. The plugin
419: is responsible for creating and populating the vector, which
420: must be terminated with a NULL pointer. The following values
421: are recognized by ssuuddoo:
422:
1.1.1.4 ! misho 423: chroot=string
! 424: The root directory to use when running the command.
1.1.1.3 misho 425:
1.1.1.4 ! misho 426: closefrom=number
! 427: If specified, ssuuddoo will close all files descriptors
! 428: with a value of _n_u_m_b_e_r or higher.
1.1.1.3 misho 429:
1.1.1.4 ! misho 430: command=string
! 431: Fully qualified path to the command to be executed.
1.1.1.3 misho 432:
433: cwd=string
434: The current working directory to change to when
435: executing the command.
436:
1.1.1.4 ! misho 437: exec_background=bool
! 438: By default, ssuuddoo runs a command as the foreground
! 439: process as long as ssuuddoo itself is running in the
! 440: foreground. When _e_x_e_c___b_a_c_k_g_r_o_u_n_d is enabled and the
! 441: command is being run in a pty (due to I/O logging or
! 442: the _u_s_e___p_t_y setting), the command will be run as a
! 443: background process. Attempts to read from the
! 444: controlling terminal (or to change terminal settings)
! 445: will result in the command being suspended with the
! 446: SIGTTIN signal (or SIGTTOU in the case of terminal
! 447: settings). If this happens when ssuuddoo is a foreground
! 448: process, the command will be granted the controlling
! 449: terminal and resumed in the foreground with no user
! 450: intervention required. The advantage of initially
! 451: running the command in the background is that ssuuddoo need
! 452: not read from the terminal unless the command
! 453: explicitly requests it. Otherwise, any terminal input
! 454: must be passed to the command, whether it has required
! 455: it or not (the kernel buffers terminals so it is not
! 456: possible to tell whether the command really wants the
! 457: input). This is different from historic _s_u_d_o behavior
! 458: or when the command is not being run in a pty.
! 459:
! 460: For this to work seamlessly, the operating system must
! 461: support the automatic restarting of system calls.
! 462: Unfortunately, not all operating systems do this by
! 463: default, and even those that do may have bugs. For
! 464: example, Mac OS X fails to restart the ttccggeettaattttrr() and
! 465: ttccsseettaattttrr() system calls (this is a bug in Mac OS X).
! 466: Furthermore, because this behavior depends on the
! 467: command stopping with the SIGTTIN or SIGTTOU signals,
! 468: programs that catch these signals and suspend
! 469: themselves with a different signal (usually SIGTOP)
! 470: will not be automatically foregrounded. Some versions
! 471: of the linux su(1) command behave this way. Because of
! 472: this, a plugin should not set _e_x_e_c___b_a_c_k_g_r_o_u_n_d unless it
! 473: is explicitly enabled by the administrator and there
! 474: should be a way to enabled or disable it on a per-
! 475: command basis.
1.1.1.3 misho 476:
1.1.1.4 ! misho 477: This setting has no effect unless I/O logging is
! 478: enabled or _u_s_e___p_t_y is enabled.
1.1.1.3 misho 479:
480: iolog_compress=bool
481: Set to true if the I/O logging plugins, if any, should
482: compress the log data. This is a hint to the I/O
483: logging plugin which may choose to ignore it.
484:
485: iolog_path=string
486: Fully qualified path to the file or directory in which
487: I/O log is to be stored. This is a hint to the I/O
488: logging plugin which may choose to ignore it. If no
489: I/O logging plugin is loaded, this setting has no
490: effect.
491:
492: iolog_stdin=bool
493: Set to true if the I/O logging plugins, if any, should
494: log the standard input if it is not connected to a
495: terminal device. This is a hint to the I/O logging
496: plugin which may choose to ignore it.
497:
498: iolog_stdout=bool
499: Set to true if the I/O logging plugins, if any, should
500: log the standard output if it is not connected to a
501: terminal device. This is a hint to the I/O logging
502: plugin which may choose to ignore it.
503:
504: iolog_stderr=bool
505: Set to true if the I/O logging plugins, if any, should
506: log the standard error if it is not connected to a
507: terminal device. This is a hint to the I/O logging
508: plugin which may choose to ignore it.
509:
510: iolog_ttyin=bool
511: Set to true if the I/O logging plugins, if any, should
512: log all terminal input. This only includes input typed
513: by the user and not from a pipe or redirected from a
514: file. This is a hint to the I/O logging plugin which
515: may choose to ignore it.
516:
517: iolog_ttyout=bool
518: Set to true if the I/O logging plugins, if any, should
519: log all terminal output. This only includes output to
520: the screen, not output to a pipe or file. This is a
521: hint to the I/O logging plugin which may choose to
522: ignore it.
523:
1.1.1.4 ! misho 524: login_class=string
! 525: BSD login class to use when setting resource limits and
! 526: nice value (optional). This option is only set on
! 527: systems that support login classes.
! 528:
! 529: nice=int
! 530: Nice value (priority) to use when executing the
! 531: command. The nice value, if specified, overrides the
! 532: priority associated with the _l_o_g_i_n___c_l_a_s_s on BSD
! 533: systems.
! 534:
! 535: noexec=bool
! 536: If set, prevent the command from executing other
! 537: programs.
! 538:
! 539: preserve_groups=bool
! 540: If set, ssuuddoo will preserve the user's group vector
! 541: instead of initializing the group vector based on
! 542: runas_user.
! 543:
! 544: runas_egid=gid
! 545: Effective group ID to run the command as. If not
! 546: specified, the value of _r_u_n_a_s___g_i_d is used.
! 547:
! 548: runas_euid=uid
! 549: Effective user ID to run the command as. If not
! 550: specified, the value of _r_u_n_a_s___u_i_d is used.
! 551:
! 552: runas_gid=gid
! 553: Group ID to run the command as.
! 554:
! 555: runas_groups=list
! 556: The supplementary group vector to use for the command
! 557: in the form of a comma-separated list of group IDs. If
! 558: _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, this option is ignored.
! 559:
! 560: runas_uid=uid
! 561: User ID to run the command as.
! 562:
! 563: selinux_role=string
! 564: SELinux role to use when executing the command.
! 565:
! 566: selinux_type=string
! 567: SELinux type to use when executing the command.
1.1.1.3 misho 568:
569: set_utmp=bool
570: Create a utmp (or utmpx) entry when a pseudo-tty is
571: allocated. By default, the new entry will be a copy of
572: the user's existing utmp entry (if any), with the tty,
573: time, type and pid fields updated.
574:
1.1.1.4 ! misho 575: sudoedit=bool
! 576: Set to true when in _s_u_d_o_e_d_i_t mode. The plugin may
! 577: enable _s_u_d_o_e_d_i_t mode even if ssuuddoo was not invoked as
! 578: ssuuddooeeddiitt. This allows the plugin to perform command
! 579: substitution and transparently enable _s_u_d_o_e_d_i_t when the
! 580: user attempts to run an editor.
! 581:
! 582: timeout=int
! 583: Command timeout. If non-zero then when the timeout
! 584: expires the command will be killed.
! 585:
! 586: umask=octal
! 587: The file creation mask to use when executing the
! 588: command.
! 589:
! 590: use_pty=bool
! 591: Allocate a pseudo-tty to run the command in, regardless
! 592: of whether or not I/O logging is in use. By default,
! 593: ssuuddoo will only run the command in a pty when an I/O log
! 594: plugin is loaded.
! 595:
1.1.1.3 misho 596: utmp_user=string
597: User name to use when constructing a new utmp (or
598: utmpx) entry when _s_e_t___u_t_m_p is enabled. This option can
599: be used to set the user field in the utmp entry to the
600: user the command runs as rather than the invoking user.
601: If not set, ssuuddoo will base the new entry on the
602: invoking user's existing entry.
1.1 misho 603:
1.1.1.3 misho 604: Unsupported values will be ignored.
1.1 misho 605:
606: argv_out
1.1.1.3 misho 607: The NULL-terminated argument vector to pass to the execve(2)
608: system call when executing the command. The plugin is
609: responsible for allocating and populating the vector.
1.1 misho 610:
611: user_env_out
1.1.1.3 misho 612: The NULL-terminated environment vector to use when executing
613: the command. The plugin is responsible for allocating and
614: populating the vector.
615:
616: list
617: int (*list)(int verbose, const char *list_user,
618: int argc, char * const argv[]);
1.1 misho 619:
620: List available privileges for the invoking user. Returns 1 on
621: success, 0 on failure and -1 on error. On error, the plugin may
1.1.1.3 misho 622: optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function with
1.1 misho 623: SUDO_CONF_ERROR_MSG to present additional error information to the
624: user.
625:
1.1.1.3 misho 626: Privileges should be output via the ccoonnvveerrssaattiioonn() or
627: pplluuggiinn__pprriinnttff() function using SUDO_CONV_INFO_MSG,
1.1 misho 628:
629: verbose
1.1.1.3 misho 630: Flag indicating whether to list in verbose mode or not.
1.1 misho 631:
632: list_user
1.1.1.3 misho 633: The name of a different user to list privileges for if the
634: policy allows it. If NULL, the plugin should list the
635: privileges of the invoking user.
636:
637: argc The number of elements in _a_r_g_v, not counting the final NULL
638: pointer.
639:
640: argv If non-NULL, an argument vector describing a command the user
641: wishes to check against the policy in the same form as what
642: would be passed to the execve(2) system call. If the command
643: is permitted by the policy, the fully-qualified path to the
644: command should be displayed along with any command line
645: arguments.
1.1 misho 646:
1.1.1.3 misho 647: validate
648: int (*validate)(void);
1.1 misho 649:
1.1.1.3 misho 650: The vvaalliiddaattee() function is called when ssuuddoo is run with the --vv
1.1.1.4 ! misho 651: flag. For policy plugins such as ssuuddooeerrss that cache authentication
1.1 misho 652: credentials, this function will validate and cache the credentials.
653:
1.1.1.3 misho 654: The vvaalliiddaattee() function should be NULL if the plugin does not
655: support credential caching.
1.1 misho 656:
657: Returns 1 on success, 0 on failure and -1 on error. On error, the
1.1.1.3 misho 658: plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff()
1.1 misho 659: function with SUDO_CONF_ERROR_MSG to present additional error
660: information to the user.
661:
1.1.1.3 misho 662: invalidate
663: void (*invalidate)(int remove);
1.1 misho 664:
1.1.1.3 misho 665: The iinnvvaalliiddaattee() function is called when ssuuddoo is called with the --kk
1.1.1.4 ! misho 666: or --KK flag. For policy plugins such as ssuuddooeerrss that cache
1.1 misho 667: authentication credentials, this function will invalidate the
668: credentials. If the _r_e_m_o_v_e flag is set, the plugin may remove the
669: credentials instead of simply invalidating them.
670:
1.1.1.3 misho 671: The iinnvvaalliiddaattee() function should be NULL if the plugin does not
1.1 misho 672: support credential caching.
673:
1.1.1.3 misho 674: init_session
675: int (*init_session)(struct passwd *pwd, char **user_envp[);
1.1 misho 676:
1.1.1.3 misho 677: The iinniitt__sseessssiioonn() function is called before ssuuddoo sets up the
1.1.1.2 misho 678: execution environment for the command. It is run in the parent
679: ssuuddoo process and before any uid or gid changes. This can be used
680: to perform session setup that is not supported by _c_o_m_m_a_n_d___i_n_f_o,
1.1.1.3 misho 681: such as opening the PAM session. The cclloossee() function can be used
682: to tear down the session that was opened by init_session.
1.1 misho 683:
684: The _p_w_d argument points to a passwd struct for the user the command
685: will be run as if the uid the command will run as was found in the
686: password database, otherwise it will be NULL.
687:
1.1.1.2 misho 688: The _u_s_e_r___e_n_v argument points to the environment the command will
1.1.1.3 misho 689: run in, in the form of a NULL-terminated vector of ``name=value''
1.1.1.2 misho 690: strings. This is the same string passed back to the front end via
1.1.1.3 misho 691: the Policy Plugin's _u_s_e_r___e_n_v___o_u_t parameter. If the iinniitt__sseessssiioonn()
1.1.1.2 misho 692: function needs to modify the user environment, it should update the
693: pointer stored in _u_s_e_r___e_n_v. The expected use case is to merge the
694: contents of the PAM environment (if any) with the contents of
695: _u_s_e_r___e_n_v. NOTE: the _u_s_e_r___e_n_v parameter is only available starting
696: with API version 1.2. A plugin mmuusstt check the API version
697: specified by the ssuuddoo front end before using _u_s_e_r___e_n_v. Failure to
698: do so may result in a crash.
699:
1.1 misho 700: Returns 1 on success, 0 on failure and -1 on error. On error, the
1.1.1.3 misho 701: plugin may optionally call the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff()
1.1 misho 702: function with SUDO_CONF_ERROR_MSG to present additional error
703: information to the user.
704:
1.1.1.3 misho 705: register_hooks
706: void (*register_hooks)(int version,
707: int (*register_hook)(struct sudo_hook *hook));
1.1.1.2 misho 708:
1.1.1.3 misho 709: The rreeggiisstteerr__hhooookkss() function is called by the sudo front end to
1.1.1.2 misho 710: register any hooks the plugin needs. If the plugin does not
711: support hooks, register_hooks should be set to the NULL pointer.
712:
713: The _v_e_r_s_i_o_n argument describes the version of the hooks API
714: supported by the ssuuddoo front end.
715:
1.1.1.3 misho 716: The rreeggiisstteerr__hhooookk() function should be used to register any
717: supported hooks the plugin needs. It returns 0 on success, 1 if
718: the hook type is not supported and -1 if the major version in
719: struct hook does not match the front end's major hook API version.
1.1.1.2 misho 720:
1.1.1.3 misho 721: See the _H_o_o_k _f_u_n_c_t_i_o_n _A_P_I section below for more information about
722: hooks.
1.1.1.2 misho 723:
1.1.1.3 misho 724: NOTE: the rreeggiisstteerr__hhooookkss() function is only available starting with
1.1.1.2 misho 725: API version 1.2. If the ssuuddoo front end doesn't support API version
726: 1.2 or higher, register_hooks will not be called.
727:
1.1.1.3 misho 728: deregister_hooks
729: void (*deregister_hooks)(int version,
730: int (*deregister_hook)(struct sudo_hook *hook));
1.1.1.2 misho 731:
1.1.1.3 misho 732: The ddeerreeggiisstteerr__hhooookkss() function is called by the sudo front end to
1.1.1.2 misho 733: deregister any hooks the plugin has registered. If the plugin does
734: not support hooks, deregister_hooks should be set to the NULL
735: pointer.
736:
737: The _v_e_r_s_i_o_n argument describes the version of the hooks API
738: supported by the ssuuddoo front end.
739:
1.1.1.3 misho 740: The ddeerreeggiisstteerr__hhooookk() function should be used to deregister any
741: hooks that were put in place by the rreeggiisstteerr__hhooookk() function. If
742: the plugin tries to deregister a hook that the front end does not
1.1.1.2 misho 743: support, deregister_hook will return an error.
744:
1.1.1.3 misho 745: See the _H_o_o_k _f_u_n_c_t_i_o_n _A_P_I section below for more information about
746: hooks.
1.1 misho 747:
1.1.1.3 misho 748: NOTE: the ddeerreeggiisstteerr__hhooookkss() function is only available starting
749: with API version 1.2. If the ssuuddoo front end doesn't support API
750: version 1.2 or higher, deregister_hooks will not be called.
751:
752: _P_o_l_i_c_y _P_l_u_g_i_n _V_e_r_s_i_o_n _M_a_c_r_o_s
753:
754: /* Plugin API version major/minor. */
755: #define SUDO_API_VERSION_MAJOR 1
756: #define SUDO_API_VERSION_MINOR 2
757: #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
758: #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
759: SUDO_API_VERSION_MINOR)
760:
761: /* Getters and setters for API version */
762: #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
763: #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
764: #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
765: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
766: } while(0)
767: #define SUDO_VERSION_SET_MINOR(vp, n) do { \
768: *(vp) = (*(vp) & 0xffff0000) | (n); \
769: } while(0)
770:
771: II//OO pplluuggiinn AAPPII
772: struct io_plugin {
773: #define SUDO_IO_PLUGIN 2
774: unsigned int type; /* always SUDO_IO_PLUGIN */
775: unsigned int version; /* always SUDO_API_VERSION */
1.1.1.4 ! misho 776: int (*open)(unsigned int version, sudo_conv_t conversation,
1.1.1.3 misho 777: sudo_printf_t plugin_printf, char * const settings[],
1.1.1.4 ! misho 778: char * const user_info[], char * const command_info[],
! 779: int argc, char * const argv[], char * const user_env[],
! 780: char * const plugin_options[]);
1.1.1.3 misho 781: void (*close)(int exit_status, int error); /* wait status or error */
782: int (*show_version)(int verbose);
783: int (*log_ttyin)(const char *buf, unsigned int len);
784: int (*log_ttyout)(const char *buf, unsigned int len);
785: int (*log_stdin)(const char *buf, unsigned int len);
786: int (*log_stdout)(const char *buf, unsigned int len);
787: int (*log_stderr)(const char *buf, unsigned int len);
788: void (*register_hooks)(int version,
789: int (*register_hook)(struct sudo_hook *hook));
790: void (*deregister_hooks)(int version,
791: int (*deregister_hook)(struct sudo_hook *hook));
792: };
793:
794: When an I/O plugin is loaded, ssuuddoo runs the command in a pseudo-tty.
795: This makes it possible to log the input and output from the user's
796: session. If any of the standard input, standard output or standard error
797: do not correspond to a tty, ssuuddoo will open a pipe to capture the I/O for
798: logging before passing it on.
799:
800: The log_ttyin function receives the raw user input from the terminal
801: device (note that this will include input even when echo is disabled,
802: such as when a password is read). The log_ttyout function receives
803: output from the pseudo-tty that is suitable for replaying the user's
804: session at a later time. The lloogg__ssttddiinn(), lloogg__ssttddoouutt() and lloogg__ssttddeerrrr()
805: functions are only called if the standard input, standard output or
806: standard error respectively correspond to something other than a tty.
807:
808: Any of the logging functions may be set to the NULL pointer if no logging
809: is to be performed. If the open function returns 0, no I/O will be sent
810: to the plugin.
1.1 misho 811:
1.1.1.3 misho 812: The io_plugin struct has the following fields:
1.1 misho 813:
1.1.1.3 misho 814: type The type field should always be set to SUDO_IO_PLUGIN.
1.1 misho 815:
1.1.1.3 misho 816: version
1.1 misho 817: The version field should be set to SUDO_API_VERSION.
818:
819: This allows ssuuddoo to determine the API version the plugin was built
820: against.
821:
1.1.1.3 misho 822: open
1.1.1.4 ! misho 823: int (*open)(unsigned int version, sudo_conv_t conversation,
1.1.1.3 misho 824: sudo_printf_t plugin_printf, char * const settings[],
825: char * const user_info[], int argc, char * const argv[],
826: char * const user_env[], char * const plugin_options[]);
827:
828: The ooppeenn() function is run before the lloogg__iinnppuutt(), lloogg__oouuttppuutt() or
829: sshhooww__vveerrssiioonn() functions are called. It is only called if the
830: version is being requested or the cchheecckk__ppoolliiccyy() function has
1.1 misho 831: returned successfully. It returns 1 on success, 0 on failure, -1
832: if a general error occurred, or -2 if there was a usage error. In
833: the latter case, ssuuddoo will print a usage message before it exits.
1.1.1.3 misho 834: If an error occurs, the plugin may optionally call the
835: ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function with SUDO_CONF_ERROR_MSG
836: to present additional error information to the user.
1.1 misho 837:
838: The function arguments are as follows:
839:
840: version
1.1.1.3 misho 841: The version passed in by ssuuddoo allows the plugin to determine
842: the major and minor version number of the plugin API
843: supported by ssuuddoo.
1.1 misho 844:
845: conversation
1.1.1.3 misho 846: A pointer to the ccoonnvveerrssaattiioonn() function that may be used by
847: the sshhooww__vveerrssiioonn() function to display version information
848: (see sshhooww__vveerrssiioonn() below). The ccoonnvveerrssaattiioonn() function may
849: also be used to display additional error message to the user.
850: The ccoonnvveerrssaattiioonn() function returns 0 on success and -1 on
851: failure.
1.1 misho 852:
853: plugin_printf
1.1.1.3 misho 854: A pointer to a pprriinnttff()-style function that may be used by
855: the sshhooww__vveerrssiioonn() function to display version information
856: (see show_version below). The pplluuggiinn__pprriinnttff() function may
857: also be used to display additional error message to the user.
858: The pplluuggiinn__pprriinnttff() function returns number of characters
859: printed on success and -1 on failure.
1.1 misho 860:
861: settings
1.1.1.3 misho 862: A vector of user-supplied ssuuddoo settings in the form of
863: ``name=value'' strings. The vector is terminated by a NULL
864: pointer. These settings correspond to flags the user
865: specified when running ssuuddoo. As such, they will only be
866: present when the corresponding flag has been specified on the
867: command line.
868:
869: When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt
870: equal sign (`=') since the _n_a_m_e field will never include one
871: itself but the _v_a_l_u_e might.
1.1 misho 872:
1.1.1.3 misho 873: See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a list of all possible
874: settings.
1.1 misho 875:
876: user_info
1.1.1.3 misho 877: A vector of information about the user running the command in
878: the form of ``name=value'' strings. The vector is terminated
879: by a NULL pointer.
880:
881: When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt
882: equal sign (`=') since the _n_a_m_e field will never include one
883: itself but the _v_a_l_u_e might.
884:
885: See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a list of all possible
886: strings.
887:
888: argc The number of elements in _a_r_g_v, not counting the final NULL
889: pointer.
890:
891: argv If non-NULL, an argument vector describing a command the user
892: wishes to run in the same form as what would be passed to the
893: execve(2) system call.
1.1 misho 894:
895: user_env
1.1.1.3 misho 896: The user's environment in the form of a NULL-terminated
897: vector of ``name=value'' strings.
1.1 misho 898:
1.1.1.3 misho 899: When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt
900: equal sign (`=') since the _n_a_m_e field will never include one
901: itself but the _v_a_l_u_e might.
1.1 misho 902:
1.1.1.2 misho 903: plugin_options
1.1.1.3 misho 904: Any (non-comment) strings immediately after the plugin path
905: are treated as arguments to the plugin. These arguments are
906: split on a white space boundary and are passed to the plugin
907: in the form of a NULL-terminated array of strings. If no
908: arguments were specified, _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL
909: pointer.
910:
911: NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available starting
912: with API version 1.2. A plugin mmuusstt check the API version
913: specified by the ssuuddoo front end before using _p_l_u_g_i_n___o_p_t_i_o_n_s.
914: Failure to do so may result in a crash.
1.1.1.2 misho 915:
1.1.1.3 misho 916: close
917: void (*close)(int exit_status, int error);
1.1 misho 918:
1.1.1.3 misho 919: The cclloossee() function is called when the command being run by ssuuddoo
1.1 misho 920: finishes.
921:
922: The function arguments are as follows:
923:
924: exit_status
1.1.1.3 misho 925: The command's exit status, as returned by the wait(2) system
926: call. The value of exit_status is undefined if error is non-
927: zero.
1.1 misho 928:
929: error
1.1.1.3 misho 930: If the command could not be executed, this is set to the
931: value of errno set by the execve(2) system call. If the
932: command was successfully executed, the value of error is 0.
933:
934: show_version
935: int (*show_version)(int verbose);
936:
937: The sshhooww__vveerrssiioonn() function is called by ssuuddoo when the user
938: specifies the --VV option. The plugin may display its version
939: information to the user via the ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff()
940: function using SUDO_CONV_INFO_MSG. If the user requests detailed
941: version information, the verbose flag will be set.
942:
943: log_ttyin
944: int (*log_ttyin)(const char *buf, unsigned int len);
945:
946: The lloogg__ttttyyiinn() function is called whenever data can be read from
947: the user but before it is passed to the running command. This
948: allows the plugin to reject data if it chooses to (for instance if
949: the input contains banned content). Returns 1 if the data should
950: be passed to the command, 0 if the data is rejected (which will
1.1 misho 951: terminate the command) or -1 if an error occurred.
952:
953: The function arguments are as follows:
954:
1.1.1.3 misho 955: buf The buffer containing user input.
1.1 misho 956:
1.1.1.3 misho 957: len The length of _b_u_f in bytes.
1.1 misho 958:
1.1.1.3 misho 959: log_ttyout
960: int (*log_ttyout)(const char *buf, unsigned int len);
1.1 misho 961:
1.1.1.3 misho 962: The lloogg__ttttyyoouutt() function is called whenever data can be read from
1.1 misho 963: the command but before it is written to the user's terminal. This
964: allows the plugin to reject data if it chooses to (for instance if
965: the output contains banned content). Returns 1 if the data should
966: be passed to the user, 0 if the data is rejected (which will
967: terminate the command) or -1 if an error occurred.
968:
969: The function arguments are as follows:
970:
1.1.1.3 misho 971: buf The buffer containing command output.
1.1 misho 972:
1.1.1.3 misho 973: len The length of _b_u_f in bytes.
1.1 misho 974:
1.1.1.3 misho 975: log_stdin
976: int (*log_stdin)(const char *buf, unsigned int len);
1.1 misho 977:
1.1.1.3 misho 978: The lloogg__ssttddiinn() function is only used if the standard input does
979: not correspond to a tty device. It is called whenever data can be
980: read from the standard input but before it is passed to the running
1.1 misho 981: command. This allows the plugin to reject data if it chooses to
982: (for instance if the input contains banned content). Returns 1 if
983: the data should be passed to the command, 0 if the data is rejected
984: (which will terminate the command) or -1 if an error occurred.
985:
986: The function arguments are as follows:
987:
1.1.1.3 misho 988: buf The buffer containing user input.
1.1 misho 989:
1.1.1.3 misho 990: len The length of _b_u_f in bytes.
1.1 misho 991:
1.1.1.3 misho 992: log_stdout
993: int (*log_stdout)(const char *buf, unsigned int len);
1.1 misho 994:
1.1.1.3 misho 995: The lloogg__ssttddoouutt() function is only used if the standard output does
1.1 misho 996: not correspond to a tty device. It is called whenever data can be
997: read from the command but before it is written to the standard
998: output. This allows the plugin to reject data if it chooses to
999: (for instance if the output contains banned content). Returns 1 if
1000: the data should be passed to the user, 0 if the data is rejected
1001: (which will terminate the command) or -1 if an error occurred.
1002:
1003: The function arguments are as follows:
1004:
1.1.1.3 misho 1005: buf The buffer containing command output.
1.1 misho 1006:
1.1.1.3 misho 1007: len The length of _b_u_f in bytes.
1.1 misho 1008:
1.1.1.3 misho 1009: log_stderr
1010: int (*log_stderr)(const char *buf, unsigned int len);
1.1 misho 1011:
1.1.1.3 misho 1012: The lloogg__ssttddeerrrr() function is only used if the standard error does
1013: not correspond to a tty device. It is called whenever data can be
1014: read from the command but before it is written to the standard
1015: error. This allows the plugin to reject data if it chooses to (for
1.1 misho 1016: instance if the output contains banned content). Returns 1 if the
1017: data should be passed to the user, 0 if the data is rejected (which
1018: will terminate the command) or -1 if an error occurred.
1019:
1020: The function arguments are as follows:
1021:
1.1.1.3 misho 1022: buf The buffer containing command output.
1.1 misho 1023:
1.1.1.3 misho 1024: len The length of _b_u_f in bytes.
1.1 misho 1025:
1.1.1.3 misho 1026: register_hooks
1027: See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a description of
1.1.1.2 misho 1028: register_hooks.
1029:
1.1.1.3 misho 1030: deregister_hooks
1031: See the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I section for a description of
1.1.1.2 misho 1032: deregister_hooks.
1033:
1.1.1.3 misho 1034: _I_/_O _P_l_u_g_i_n _V_e_r_s_i_o_n _M_a_c_r_o_s
1.1 misho 1035:
1.1.1.3 misho 1036: Same as for the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I.
1.1 misho 1037:
1.1.1.4 ! misho 1038: SSiiggnnaall hhaannddlleerrss
! 1039: The ssuuddoo front end installs default signal handlers to trap common
! 1040: signals while the plugin functions are run. The following signals are
! 1041: trapped by default before the command is executed:
! 1042:
! 1043: oo SIGALRM
! 1044: oo SIGHUP
! 1045: oo SIGINT
! 1046: oo SIGQUIT
! 1047: oo SIGTERM
! 1048: oo SIGTSTP
! 1049: oo SIGUSR1
! 1050: oo SIGUSR2
! 1051:
! 1052: If a fatal signal is received before the command is executed, ssuuddoo will
! 1053: call the plugin's cclloossee() function with an exit status of 128 plus the
! 1054: value of the signal that was received. This allows for consistent
! 1055: logging of commands killed by a signal for plugins that log such
! 1056: information in their cclloossee() function.
! 1057:
! 1058: A plugin may temporarily install its own signal handlers but must restore
! 1059: the original handler before the plugin function returns.
! 1060:
1.1.1.3 misho 1061: HHooookk ffuunnccttiioonn AAPPII
1062: Beginning with plugin API version 1.2, it is possible to install hooks
1063: for certain functions called by the ssuuddoo front end.
1.1.1.2 misho 1064:
1.1.1.3 misho 1065: Currently, the only supported hooks relate to the handling of environment
1066: variables. Hooks can be used to intercept attempts to get, set, or
1067: remove environment variables so that these changes can be reflected in
1068: the version of the environment that is used to execute a command. A
1069: future version of the API will support hooking internal ssuuddoo front end
1070: functions as well.
1.1.1.2 misho 1071:
1.1.1.3 misho 1072: _H_o_o_k _s_t_r_u_c_t_u_r_e
1.1.1.2 misho 1073:
1.1.1.3 misho 1074: Hooks in ssuuddoo are described by the following structure:
1.1.1.2 misho 1075:
1.1.1.3 misho 1076: typedef int (*sudo_hook_fn_t)();
1.1.1.2 misho 1077:
1.1.1.3 misho 1078: struct sudo_hook {
1079: int hook_version;
1080: int hook_type;
1081: sudo_hook_fn_t hook_fn;
1082: void *closure;
1083: };
1.1.1.2 misho 1084:
1.1.1.3 misho 1085: The sudo_hook structure has the following fields:
1.1.1.2 misho 1086:
1.1.1.3 misho 1087: hook_version
1.1.1.2 misho 1088: The hook_version field should be set to SUDO_HOOK_VERSION.
1089:
1.1.1.3 misho 1090: hook_type
1.1.1.2 misho 1091: The hook_type field may be one of the following supported hook
1092: types:
1093:
1094: SUDO_HOOK_SETENV
1.1.1.3 misho 1095: The C library setenv(3) function. Any registered hooks will
1096: run before the C library implementation. The hook_fn field
1097: should be a function that matches the following typedef:
1.1.1.2 misho 1098:
1.1.1.3 misho 1099: typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1100: const char *value, int overwrite, void *closure);
1.1.1.2 misho 1101:
1.1.1.3 misho 1102: If the registered hook does not match the typedef the results
1103: are unspecified.
1.1.1.2 misho 1104:
1105: SUDO_HOOK_UNSETENV
1.1.1.3 misho 1106: The C library unsetenv(3) function. Any registered hooks
1107: will run before the C library implementation. The hook_fn
1108: field should be a function that matches the following
1109: typedef:
1.1.1.2 misho 1110:
1.1.1.3 misho 1111: typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1112: void *closure);
1.1.1.2 misho 1113:
1114: SUDO_HOOK_GETENV
1.1.1.3 misho 1115: The C library getenv(3) function. Any registered hooks will
1116: run before the C library implementation. The hook_fn field
1117: should be a function that matches the following typedef:
1.1.1.2 misho 1118:
1.1.1.3 misho 1119: typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1120: char **value, void *closure);
1.1.1.2 misho 1121:
1.1.1.3 misho 1122: If the registered hook does not match the typedef the results
1123: are unspecified.
1.1.1.2 misho 1124:
1125: SUDO_HOOK_PUTENV
1.1.1.3 misho 1126: The C library putenv(3) function. Any registered hooks will
1127: run before the C library implementation. The hook_fn field
1128: should be a function that matches the following typedef:
1.1.1.2 misho 1129:
1.1.1.3 misho 1130: typedef int (*sudo_hook_fn_putenv_t)(char *string,
1131: void *closure);
1.1.1.2 misho 1132:
1.1.1.3 misho 1133: If the registered hook does not match the typedef the results
1134: are unspecified.
1.1.1.2 misho 1135:
1.1.1.3 misho 1136: hook_fn
1137: sudo_hook_fn_t hook_fn;
1.1.1.2 misho 1138:
1139: The hook_fn field should be set to the plugin's hook
1140: implementation. The actual function arguments will vary depending
1141: on the hook_type (see hook_type above). In all cases, the closure
1142: field of struct sudo_hook is passed as the last function parameter.
1143: This can be used to pass arbitrary data to the plugin's hook
1144: implementation.
1145:
1146: The function return value may be one of the following:
1147:
1148: SUDO_HOOK_RET_ERROR
1.1.1.3 misho 1149: The hook function encountered an error.
1.1.1.2 misho 1150:
1151: SUDO_HOOK_RET_NEXT
1.1.1.3 misho 1152: The hook completed without error, go on to the next hook
1153: (including the native implementation if applicable). For
1154: example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1155: the specified variable was not found in the private copy of
1156: the environment.
1.1.1.2 misho 1157:
1158: SUDO_HOOK_RET_STOP
1.1.1.3 misho 1159: The hook completed without error, stop processing hooks for
1160: this invocation. This can be used to replace the native
1161: implementation. For example, a setenv hook that operates on
1162: a private copy of the environment but leaves environ
1163: unchanged.
1164:
1165: Note that it is very easy to create an infinite loop when hooking C
1166: library functions. For example, a getenv(3) hook that calls the
1167: snprintf(3) function may create a loop if the snprintf(3) implementation
1168: calls getenv(3) to check the locale. To prevent this, you may wish to
1169: use a static variable in the hook function to guard against nested calls.
1170: For example:
1171:
1172: static int in_progress = 0; /* avoid recursion */
1173: if (in_progress)
1174: return SUDO_HOOK_RET_NEXT;
1175: in_progress = 1;
1176: ...
1177: in_progress = 0;
1178: return SUDO_HOOK_RET_STOP;
1179:
1180: _H_o_o_k _A_P_I _V_e_r_s_i_o_n _M_a_c_r_o_s
1181:
1182: /* Hook API version major/minor */
1183: #define SUDO_HOOK_VERSION_MAJOR 1
1184: #define SUDO_HOOK_VERSION_MINOR 0
1185: #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1186: #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1187: SUDO_HOOK_VERSION_MINOR)
1188:
1189: /* Getters and setters for hook API version */
1190: #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1191: #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1192: #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \
1193: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1194: } while(0)
1195: #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \
1196: *(vp) = (*(vp) & 0xffff0000) | (n); \
1197: } while(0)
1.1.1.2 misho 1198:
1.1 misho 1199: CCoonnvveerrssaattiioonn AAPPII
1.1.1.3 misho 1200: If the plugin needs to interact with the user, it may do so via the
1201: ccoonnvveerrssaattiioonn() function. A plugin should not attempt to read directly
1202: from the standard input or the user's tty (neither of which are
1203: guaranteed to exist). The caller must include a trailing newline in msg
1204: if one is to be printed.
1205:
1206: A pprriinnttff()-style function is also available that can be used to display
1207: informational or error messages to the user, which is usually more
1208: convenient for simple messages where no use input is required.
1209:
1210: struct sudo_conv_message {
1211: #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1212: #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1213: #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1214: #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1215: #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1216: #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1217: #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1218: int msg_type;
1219: int timeout;
1220: const char *msg;
1221: };
1222:
1223: struct sudo_conv_reply {
1224: char *reply;
1225: };
1226:
1227: typedef int (*sudo_conv_t)(int num_msgs,
1228: const struct sudo_conv_message msgs[],
1229: struct sudo_conv_reply replies[]);
1230:
1231: typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1232:
1233: Pointers to the ccoonnvveerrssaattiioonn() and pprriinnttff()-style functions are passed in
1234: to the plugin's ooppeenn() function when the plugin is initialized.
1235:
1236: To use the ccoonnvveerrssaattiioonn() function, the plugin must pass an array of
1237: sudo_conv_message and sudo_conv_reply structures. There must be a struct
1238: sudo_conv_message and struct sudo_conv_reply for each message in the
1239: conversation. The plugin is responsible for freeing the reply buffer
1240: filled in to the struct sudo_conv_reply, if any.
1241:
1242: The pprriinnttff()-style function uses the same underlying mechanism as the
1243: ccoonnvveerrssaattiioonn() function but only supports SUDO_CONV_INFO_MSG,
1244: SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _m_s_g___t_y_p_e parameter.
1245: It can be more convenient than using the ccoonnvveerrssaattiioonn() function if no
1246: user reply is needed and supports standard pprriinnttff() escape sequences.
1247:
1248: Unlike, SUDO_CONV_INFO_MSG and Dv SUDO_CONV_ERROR_MSG , messages sent
1249: with the SUDO_CONV_DEBUG_MSG _m_s_g___t_y_p_e are not directly user-visible.
1250: Instead, they are logged to the file specified in the Debug statement (if
1.1.1.4 ! misho 1251: any) in the sudo.conf(4). file. This allows a plugin to log debugging
! 1252: information and is intended to be used in conjunction with the
! 1253: _d_e_b_u_g___f_l_a_g_s setting.
1.1.1.3 misho 1254:
1255: See the sample plugin for an example of the ccoonnvveerrssaattiioonn() function
1256: usage.
1257:
1258: SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII
1.1.1.4 ! misho 1259: The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix
! 1260: group lookups. This can be used to query a group source other than the
! 1261: standard Unix group database. Two sample group plugins are bundled with
! 1262: ssuuddoo, _g_r_o_u_p___f_i_l_e and _s_y_s_t_e_m___g_r_o_u_p, are detailed in sudoers(4). Third
! 1263: party group plugins include a QAS AD plugin available from Quest
! 1264: Software.
1.1.1.3 misho 1265:
1266: A group plugin must declare and populate a sudoers_group_plugin struct in
1267: the global scope. This structure contains pointers to the functions that
1268: implement plugin initialization, cleanup and group lookup.
1269:
1270: struct sudoers_group_plugin {
1271: unsigned int version;
1272: int (*init)(int version, sudo_printf_t sudo_printf,
1273: char *const argv[]);
1274: void (*cleanup)(void);
1275: int (*query)(const char *user, const char *group,
1276: const struct passwd *pwd);
1277: };
1.1 misho 1278:
1.1.1.3 misho 1279: The sudoers_group_plugin struct has the following fields:
1.1 misho 1280:
1.1.1.3 misho 1281: version
1.1 misho 1282: The version field should be set to GROUP_API_VERSION.
1283:
1.1.1.4 ! misho 1284: This allows ssuuddooeerrss to determine the API version the group plugin
1.1 misho 1285: was built against.
1286:
1.1.1.3 misho 1287: init
1288: int (*init)(int version, sudo_printf_t plugin_printf,
1289: char *const argv[]);
1.1 misho 1290:
1.1.1.3 misho 1291: The iinniitt() function is called after _s_u_d_o_e_r_s has been parsed but
1.1 misho 1292: before any policy checks. It returns 1 on success, 0 on failure
1293: (or if the plugin is not configured), and -1 if a error occurred.
1.1.1.3 misho 1294: If an error occurs, the plugin may call the pplluuggiinn__pprriinnttff()
1295: function with SUDO_CONF_ERROR_MSG to present additional error
1296: information to the user.
1.1 misho 1297:
1298: The function arguments are as follows:
1299:
1300: version
1.1.1.4 ! misho 1301: The version passed in by ssuuddooeerrss allows the plugin to
1.1.1.3 misho 1302: determine the major and minor version number of the group
1.1.1.4 ! misho 1303: plugin API supported by ssuuddooeerrss.
1.1 misho 1304:
1305: plugin_printf
1.1.1.3 misho 1306: A pointer to a pprriinnttff()-style function that may be used to
1307: display informational or error message to the user. Returns
1308: the number of characters printed on success and -1 on
1309: failure.
1310:
1311: argv A NULL-terminated array of arguments generated from the
1312: _g_r_o_u_p___p_l_u_g_i_n option in _s_u_d_o_e_r_s. If no arguments were given,
1313: _a_r_g_v will be NULL.
1314:
1315: cleanup
1316: void (*cleanup)();
1317:
1.1.1.4 ! misho 1318: The cclleeaannuupp() function is called when ssuuddooeerrss has finished its
1.1.1.3 misho 1319: group checks. The plugin should free any memory it has allocated
1320: and close open file handles.
1321:
1322: query
1323: int (*query)(const char *user, const char *group,
1324: const struct passwd *pwd);
1.1 misho 1325:
1.1.1.3 misho 1326: The qquueerryy() function is used to ask the group plugin whether _u_s_e_r
1327: is a member of _g_r_o_u_p.
1.1 misho 1328:
1329: The function arguments are as follows:
1330:
1.1.1.3 misho 1331: user The name of the user being looked up in the external group
1332: database.
1.1 misho 1333:
1334: group
1.1.1.3 misho 1335: The name of the group being queried.
1.1 misho 1336:
1.1.1.3 misho 1337: pwd The password database entry for _u_s_e_r, if any. If _u_s_e_r is not
1338: present in the password database, _p_w_d will be NULL.
1.1 misho 1339:
1.1.1.3 misho 1340: _G_r_o_u_p _A_P_I _V_e_r_s_i_o_n _M_a_c_r_o_s
1.1 misho 1341:
1.1.1.3 misho 1342: /* Sudoers group plugin version major/minor */
1343: #define GROUP_API_VERSION_MAJOR 1
1344: #define GROUP_API_VERSION_MINOR 0
1345: #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1346: GROUP_API_VERSION_MINOR)
1347:
1348: /* Getters and setters for group version */
1349: #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1350: #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1351: #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1352: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1353: } while(0)
1354: #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1355: *(vp) = (*(vp) & 0xffff0000) | (n); \
1356: } while(0)
1.1 misho 1357:
1.1.1.2 misho 1358: PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG
1.1.1.3 misho 1359: The following revisions have been made to the Sudo Plugin API.
1.1.1.2 misho 1360:
1.1.1.3 misho 1361: Version 1.0
1.1.1.2 misho 1362: Initial API version.
1363:
1.1.1.4 ! misho 1364: Version 1.1 (sudo 1.8.0)
1.1.1.3 misho 1365: The I/O logging plugin's ooppeenn() function was modified to take the
1.1.1.2 misho 1366: command_info list as an argument.
1367:
1.1.1.4 ! misho 1368: Version 1.2 (sudo 1.8.5)
1.1.1.3 misho 1369: The Policy and I/O logging plugins' ooppeenn() functions are now passed
1.1.1.4 ! misho 1370: a list of plugin parameters if any are specified in sudo.conf(4).
1.1.1.2 misho 1371:
1372: A simple hooks API has been introduced to allow plugins to hook in
1373: to the system's environment handling functions.
1374:
1375: The init_session Policy plugin function is now passed a pointer to
1376: the user environment which can be updated as needed. This can be
1377: used to merge in environment variables stored in the PAM handle
1378: before a command is run.
1379:
1.1.1.4 ! misho 1380: Version 1.3 (sudo 1.8.7)
! 1381: Support for the _e_x_e_c___b_a_c_k_g_r_o_u_n_d entry has been added to the
! 1382: command_info list.
! 1383:
! 1384: The _m_a_x___g_r_o_u_p_s and _p_l_u_g_i_n___d_i_r entries were added to the settings
! 1385: list.
! 1386:
! 1387: The vveerrssiioonn() and cclloossee() functions are now optional. Previously,
! 1388: a missing vveerrssiioonn() or cclloossee() function would result in a crash.
! 1389: If no policy plugin cclloossee() function is defined, a default cclloossee()
! 1390: function will be provided by the ssuuddoo front end that displays a
! 1391: warning if the command could not be executed.
! 1392:
! 1393: The ssuuddoo front end now installs default signal handlers to trap
! 1394: common signals while the plugin functions are run.
! 1395:
1.1 misho 1396: SSEEEE AALLSSOO
1.1.1.4 ! misho 1397: sudo.conf(4), sudoers(4), sudo(1m)
1.1 misho 1398:
1399: BBUUGGSS
1.1.1.3 misho 1400: If you feel you have found a bug in ssuuddoo, please submit a bug report at
1401: http://www.sudo.ws/sudo/bugs/
1.1 misho 1402:
1403: SSUUPPPPOORRTT
1.1.1.3 misho 1404: Limited free support is available via the sudo-users mailing list, see
1405: http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the
1406: archives.
1.1 misho 1407:
1408: DDIISSCCLLAAIIMMEERR
1.1.1.3 misho 1409: ssuuddoo is provided ``AS IS'' and any express or implied warranties,
1410: including, but not limited to, the implied warranties of merchantability
1411: and fitness for a particular purpose are disclaimed. See the LICENSE
1412: file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for
1413: complete details.
1.1 misho 1414:
1.1.1.4 ! misho 1415: Sudo 1.8.7 March 5, 2013 Sudo 1.8.7
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo_plugin.cat CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc