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