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