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