Annotation of embedaddon/sudo/doc/sudo_plugin.cat, revision 1.1.1.1
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
35: are ignored. Lines that don't begin with Plugin or Path are silently
36: ignored.
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:
48: # Plugin plugin_name plugin_path
49: # Path askpass /path/to/askpass
50: #
51: # The plugin_path is relative to /usr/local/libexec unless
52: # fully qualified.
53: # The plugin_name corresponds to a global symbol in the plugin
54: # that contains the plugin interface structure.
55: #
56: Plugin sudoers_policy sudoers.so
57: Plugin sudoers_io sudoers.so
58:
59: PPoolliiccyy PPlluuggiinn AAPPII
60: A policy plugin must declare and populate a policy_plugin struct in the
61: global scope. This structure contains pointers to the functions that
62: implement the ssuuddoo policy checks. The name of the symbol should be
63: specified in _/_e_t_c_/_s_u_d_o_._c_o_n_f along with a path to the plugin so that
64: ssuuddoo can load it.
65:
66: struct policy_plugin {
67: #define SUDO_POLICY_PLUGIN 1
68: unsigned int type; /* always SUDO_POLICY_PLUGIN */
69: unsigned int version; /* always SUDO_API_VERSION */
70: int (*open)(unsigned int version, sudo_conv_t conversation,
71: sudo_printf_t plugin_printf, char * const settings[],
72: char * const user_info[], char * const user_env[]);
73: void (*close)(int exit_status, int error);
74: int (*show_version)(int verbose);
75: int (*check_policy)(int argc, char * const argv[],
76: char *env_add[], char **command_info[],
77: char **argv_out[], char **user_env_out[]);
78: int (*list)(int argc, char * const argv[], int verbose,
79: const char *list_user);
80: int (*validate)(void);
81: void (*invalidate)(int remove);
82: int (*init_session)(struct passwd *pwd);
83: };
84:
85: The policy_plugin struct has the following fields:
86:
87: type
88: The type field should always be set to SUDO_POLICY_PLUGIN.
89:
90: version
91: The version field should be set to SUDO_API_VERSION.
92:
93: This allows ssuuddoo to determine the API version the plugin was built
94: against.
95:
96: open
97: int (*open)(unsigned int version, sudo_conv_t conversation,
98: sudo_printf_t plugin_printf, char * const settings[],
99: char * const user_info[], char * const user_env[]);
100:
101: Returns 1 on success, 0 on failure, -1 if a general error occurred,
102: or -2 if there was a usage error. In the latter case, ssuuddoo will
103: print a usage message before it exits. If an error occurs, the
104: plugin may optionally call the conversation or plugin_printf
105: function with SUDO_CONF_ERROR_MSG to present additional error
106: information to the user.
107:
108: The function arguments are as follows:
109:
110: version
111: The version passed in by ssuuddoo allows the plugin to determine
112: the major and minor version number of the plugin API supported
113: by ssuuddoo.
114:
115: conversation
116: A pointer to the conversation function that can be used by the
117: plugin to interact with the user (see below). Returns 0 on
118: success and -1 on failure.
119:
120: plugin_printf
121: A pointer to a printf-style function that may be used to
122: display informational or error messages (see below). Returns
123: the number of characters printed on success and -1 on failure.
124:
125: settings
126: A vector of user-supplied ssuuddoo settings in the form of
127: "name=value" strings. The vector is terminated by a NULL
128: pointer. These settings correspond to flags the user specified
129: when running ssuuddoo. As such, they will only be present when the
130: corresponding flag has been specified on the command line.
131:
132: When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt
133: equal sign ('=') since the _n_a_m_e field will never include one
134: itself but the _v_a_l_u_e might.
135:
136: debug_level=number
137: A numeric debug level, from 1-9, if specified via the -D
138: flag.
139:
140: runas_user=string
141: The user name or uid to to run the command as, if specified
142: via the -u flag.
143:
144: runas_group=string
145: The group name or gid to to run the command as, if
146: specified via the -g flag.
147:
148: prompt=string
149: The prompt to use when requesting a password, if specified
150: via the -p flag.
151:
152: set_home=bool
153: Set to true if the user specified the -H flag. If true,
154: set the HOME environment variable to the target user's home
155: directory.
156:
157: preserve_environment=bool
158: Set to true if the user specified the -E flag, indicating
159: that the user wishes to preserve the environment.
160:
161: run_shell=bool
162: Set to true if the user specified the -s flag, indicating
163: that the user wishes to run a shell.
164:
165: login_shell=bool
166: Set to true if the user specified the -i flag, indicating
167: that the user wishes to run a login shell.
168:
169: implied_shell=bool
170: If the user does not specify a program on the command line,
171: ssuuddoo will pass the plugin the path to the user's shell and
172: set _i_m_p_l_i_e_d___s_h_e_l_l to true. This allows ssuuddoo with no
173: arguments to be used similarly to _s_u(1). If the plugin
174: does not to support this usage, it may return a value of -2
175: from the check_policy function, which will cause ssuuddoo to
176: print a usage message and exit.
177:
178: preserve_groups=bool
179: Set to true if the user specified the -P flag, indicating
180: that the user wishes to preserve the group vector instead
181: of setting it based on the runas user.
182:
183: ignore_ticket=bool
184: Set to true if the user specified the -k flag along with a
185: command, indicating that the user wishes to ignore any
186: cached authentication credentials.
187:
188: noninteractive=bool
189: Set to true if the user specified the -n flag, indicating
190: that ssuuddoo should operate in non-interactive mode. The
191: plugin may reject a command run in non-interactive mode if
192: user interaction is required.
193:
194: login_class=string
195: BSD login class to use when setting resource limits and
196: nice value, if specified by the -c flag.
197:
198: selinux_role=string
199: SELinux role to use when executing the command, if
200: specified by the -r flag.
201:
202: selinux_type=string
203: SELinux type to use when executing the command, if
204: specified by the -t flag.
205:
206: bsdauth_type=string
207: Authentication type, if specified by the -a flag, to use on
208: systems where BSD authentication is supported.
209:
210: network_addrs=list
211: A space-separated list of IP network addresses and netmasks
212: in the form "addr/netmask", e.g.
213: "192.168.1.2/255.255.255.0". The address and netmask pairs
214: may be either IPv4 or IPv6, depending on what the operating
215: system supports. If the address contains a colon (':'), it
216: is an IPv6 address, else it is IPv4.
217:
218: progname=string
219: The command name that sudo was run as, typically "sudo" or
220: "sudoedit".
221:
222: sudoedit=bool
223: Set to true when the -e flag is is specified or if invoked
224: as ssuuddooeeddiitt. The plugin shall substitute an editor into
225: _a_r_g_v in the _c_h_e_c_k___p_o_l_i_c_y function or return -2 with a usage
226: error if the plugin does not support _s_u_d_o_e_d_i_t. For more
227: information, see the _c_h_e_c_k___p_o_l_i_c_y section.
228:
229: closefrom=number
230: If specified, the user has requested via the -C flag that
231: ssuuddoo close all files descriptors with a value of _n_u_m_b_e_r or
232: higher. The plugin may optionally pass this, or another
233: value, back in the _c_o_m_m_a_n_d___i_n_f_o list.
234:
235: Additional settings may be added in the future so the plugin
236: should silently ignore settings that it does not recognize.
237:
238: user_info
239: A vector of information about the user running the command in
240: the form of "name=value" strings. The vector is terminated by
241: a NULL pointer.
242:
243: When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt
244: equal sign ('=') since the _n_a_m_e field will never include one
245: itself but the _v_a_l_u_e might.
246:
247: user=string
248: The name of the user invoking ssuuddoo.
249:
250: uid=uid_t
251: The real user ID of the user invoking ssuuddoo.
252:
253: gid=gid_t
254: The real group ID of the user invoking ssuuddoo.
255:
256: groups=list
257: The user's supplementary group list formatted as a string
258: of comma-separated group IDs.
259:
260: cwd=string
261: The user's current working directory.
262:
263: tty=string
264: The path to the user's terminal device. If the user has no
265: terminal device associated with the session, the value will
266: be empty, as in tty=.
267:
268: host=string
269: The local machine's hostname as returned by the
270: gethostname() system call.
271:
272: lines=int
273: The number of lines the user's terminal supports. If there
274: is no terminal device available, a default value of 24 is
275: used.
276:
277: cols=int
278: The number of columns the user's terminal supports. If
279: there is no terminal device available, a default value of
280: 80 is used.
281:
282: user_env
283: The user's environment in the form of a NULL-terminated vector
284: of "name=value" strings.
285:
286: When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt
287: equal sign ('=') since the _n_a_m_e field will never include one
288: itself but the _v_a_l_u_e might.
289:
290: close
291: void (*close)(int exit_status, int error);
292:
293: The close function is called when the command being run by ssuuddoo
294: finishes.
295:
296: The function arguments are as follows:
297:
298: exit_status
299: The command's exit status, as returned by the _w_a_i_t(2) system
300: call. The value of exit_status is undefined if error is non-
301: zero.
302:
303: error
304: If the command could not be executed, this is set to the value
305: of errno set by the _e_x_e_c_v_e(2) system call. The plugin is
306: responsible for displaying error information via the
307: conversation or plugin_printf function. If the command was
308: successfully executed, the value of error is 0.
309:
310: show_version
311: int (*show_version)(int verbose);
312:
313: The show_version function is called by ssuuddoo when the user specifies
314: the -V option. The plugin may display its version information to
315: the user via the conversation or plugin_printf function using
316: SUDO_CONV_INFO_MSG. If the user requests detailed version
317: information, the verbose flag will be set.
318:
319: check_policy
320: int (*check_policy)(int argc, char * const argv[]
321: char *env_add[], char **command_info[],
322: char **argv_out[], char **user_env_out[]);
323:
324: The _c_h_e_c_k___p_o_l_i_c_y function is called by ssuuddoo to determine whether
325: the user is allowed to run the specified commands.
326:
327: 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
328: 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
329: is a mechanism for editing one or more files where an editor is run
330: with the user's credentials instead of with elevated privileges.
331: ssuuddoo achieves this by creating user-writable temporary copies of
332: the files to be edited and then overwriting the originals with the
333: temporary copies after editing is complete. If the plugin supports
334: ssuuddooeeddiitt, it should choose the editor to be used, potentially from
335: a variable in the user's environment, such as EDITOR, and include
336: it in _a_r_g_v___o_u_t (note that environment variables may include command
337: line flags). The files to be edited should be copied from _a_r_g_v
338: into _a_r_g_v___o_u_t, separated from the editor and its arguments by a
339: "--" element. The "--" will be removed by ssuuddoo before the editor
340: is executed. The plugin should also set _s_u_d_o_e_d_i_t_=_t_r_u_e in the
341: _c_o_m_m_a_n_d___i_n_f_o list.
342:
343: The _c_h_e_c_k___p_o_l_i_c_y function returns 1 if the command is allowed, 0 if
344: not allowed, -1 for a general error, or -2 for a usage error or if
345: ssuuddooeeddiitt was specified but is unsupported by the plugin. In the
346: latter case, ssuuddoo will print a usage message before it exits. If
347: an error occurs, the plugin may optionally call the conversation or
348: plugin_printf function with SUDO_CONF_ERROR_MSG to present
349: additional error information to the user.
350:
351: The function arguments are as follows:
352:
353: argc
354: The number of elements in _a_r_g_v, not counting the final NULL
355: pointer.
356:
357: argv
358: The argument vector describing the command the user wishes to
359: run, in the same form as what would be passed to the _e_x_e_c_v_e_(_)
360: system call. The vector is terminated by a NULL pointer.
361:
362: env_add
363: Additional environment variables specified by the user on the
364: command line in the form of a NULL-terminated vector of
365: "name=value" strings. The plugin may reject the command if one
366: or more variables are not allowed to be set, or it may silently
367: ignore such variables.
368:
369: When parsing _e_n_v___a_d_d, the plugin should split on the ffiirrsstt
370: equal sign ('=') since the _n_a_m_e field will never include one
371: itself but the _v_a_l_u_e might.
372:
373: command_info
374: Information about the command being run in the form of
375: "name=value" strings. These values are used by ssuuddoo to set the
376: execution environment when running a command. The plugin is
377: responsible for creating and populating the vector, which must
378: be terminated with a NULL pointer. The following values are
379: recognized by ssuuddoo:
380:
381: command=string
382: Fully qualified path to the command to be executed.
383:
384: runas_uid=uid
385: User ID to run the command as.
386:
387: runas_euid=uid
388: Effective user ID to run the command as. If not specified,
389: the value of _r_u_n_a_s___u_i_d is used.
390:
391: runas_gid=gid
392: Group ID to run the command as.
393:
394: runas_egid=gid
395: Effective group ID to run the command as. If not
396: specified, the value of _r_u_n_a_s___g_i_d is used.
397:
398: runas_groups=list
399: The supplementary group vector to use for the command in
400: the form of a comma-separated list of group IDs. If
401: _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, this option is ignored.
402:
403: login_class=string
404: BSD login class to use when setting resource limits and
405: nice value (optional). This option is only set on systems
406: that support login classes.
407:
408: preserve_groups=bool
409: If set, ssuuddoo will preserve the user's group vector instead
410: of initializing the group vector based on runas_user.
411:
412: cwd=string
413: The current working directory to change to when executing
414: the command.
415:
416: noexec=bool
417: If set, prevent the command from executing other programs.
418:
419: chroot=string
420: The root directory to use when running the command.
421:
422: nice=int
423: Nice value (priority) to use when executing the command.
424: The nice value, if specified, overrides the priority
425: associated with the _l_o_g_i_n___c_l_a_s_s on BSD systems.
426:
427: umask=octal
428: The file creation mask to use when executing the command.
429:
430: selinux_role=string
431: SELinux role to use when executing the command.
432:
433: selinux_type=string
434: SELinux type to use when executing the command.
435:
436: timeout=int
437: Command timeout. If non-zero then when the timeout expires
438: the command will be killed.
439:
440: sudoedit=bool
441: Set to true when in _s_u_d_o_e_d_i_t mode. The plugin may enable
442: _s_u_d_o_e_d_i_t mode even if ssuuddoo was not invoked as ssuuddooeeddiitt.
443: This allows the plugin to perform command substitution and
444: transparently enable _s_u_d_o_e_d_i_t when the user attempts to run
445: an editor.
446:
447: closefrom=number
448: If specified, ssuuddoo will close all files descriptors with a
449: value of _n_u_m_b_e_r or higher.
450:
451: iolog_compress=bool
452: Set to true if the I/O logging plugins, if any, should
453: compress the log data. This is a hint to the I/O logging
454: plugin which may choose to ignore it.
455:
456: iolog_path=string
457: Fully qualified path to the file or directory in which I/O
458: log is to be stored. This is a hint to the I/O logging
459: plugin which may choose to ignore it. If no I/O logging
460: plugin is loaded, this setting has no effect.
461:
462: iolog_stdin=bool
463: Set to true if the I/O logging plugins, if any, should log
464: the standard input if it is not connected to a terminal
465: device. This is a hint to the I/O logging plugin which may
466: choose to ignore it.
467:
468: iolog_stdout=bool
469: Set to true if the I/O logging plugins, if any, should log
470: the standard output if it is not connected to a terminal
471: device. This is a hint to the I/O logging plugin which may
472: choose to ignore it.
473:
474: iolog_stderr=bool
475: Set to true if the I/O logging plugins, if any, should log
476: the standard error if it is not connected to a terminal
477: device. This is a hint to the I/O logging plugin which may
478: choose to ignore it.
479:
480: iolog_ttyin=bool
481: Set to true if the I/O logging plugins, if any, should log
482: all terminal input. This only includes input typed by the
483: user and not from a pipe or redirected from a file. This
484: is a hint to the I/O logging plugin which may choose to
485: ignore it.
486:
487: iolog_ttyout=bool
488: Set to true if the I/O logging plugins, if any, should log
489: all terminal output. This only includes output to the
490: screen, not output to a pipe or file. This is a hint to
491: the I/O logging plugin which may choose to ignore it.
492:
493: use_pty=bool
494: Allocate a pseudo-tty to run the command in, regardless of
495: whether or not I/O logging is in use. By default, ssuuddoo
496: will only run the command in a pty when an I/O log plugin
497: is loaded.
498:
499: set_utmp=bool
500: Create a utmp (or utmpx) entry when a pseudo-tty is
501: allocated. By default, the new entry will be a copy of the
502: user's existing utmp entry (if any), with the tty, time,
503: type and pid fields updated.
504:
505: utmp_user=string
506: User name to use when constructing a new utmp (or utmpx)
507: entry when _s_e_t___u_t_m_p is enabled. This option can be used to
508: set the user field in the utmp entry to the user the
509: command runs as rather than the invoking user. If not set,
510: ssuuddoo will base the new entry on the invoking user's
511: existing entry.
512:
513: Unsupported values will be ignored.
514:
515: argv_out
516: The NULL-terminated argument vector to pass to the _e_x_e_c_v_e_(_)
517: system call when executing the command. The plugin is
518: responsible for allocating and populating the vector.
519:
520: user_env_out
521: The NULL-terminated environment vector to use when executing
522: the command. The plugin is responsible for allocating and
523: populating the vector.
524:
525: list
526: int (*list)(int verbose, const char *list_user,
527: int argc, char * const argv[]);
528:
529: List available privileges for the invoking user. Returns 1 on
530: success, 0 on failure and -1 on error. On error, the plugin may
531: optionally call the conversation or plugin_printf function with
532: SUDO_CONF_ERROR_MSG to present additional error information to the
533: user.
534:
535: Privileges should be output via the conversation or plugin_printf
536: function using SUDO_CONV_INFO_MSG.
537:
538: verbose
539: Flag indicating whether to list in verbose mode or not.
540:
541: list_user
542: The name of a different user to list privileges for if the
543: policy allows it. If NULL, the plugin should list the
544: privileges of the invoking user.
545:
546: argc
547: The number of elements in _a_r_g_v, not counting the final NULL
548: pointer.
549:
550: argv
551: If non-NULL, an argument vector describing a command the user
552: wishes to check against the policy in the same form as what
553: would be passed to the _e_x_e_c_v_e_(_) system call. If the command is
554: permitted by the policy, the fully-qualified path to the
555: command should be displayed along with any command line
556: arguments.
557:
558: validate
559: int (*validate)(void);
560:
561: The validate function is called when ssuuddoo is run with the -v flag.
562: For policy plugins such as _s_u_d_o_e_r_s that cache authentication
563: credentials, this function will validate and cache the credentials.
564:
565: The validate function should be NULL if the plugin does not support
566: credential caching.
567:
568: Returns 1 on success, 0 on failure and -1 on error. On error, the
569: plugin may optionally call the conversation or plugin_printf
570: function with SUDO_CONF_ERROR_MSG to present additional error
571: information to the user.
572:
573: invalidate
574: void (*invalidate)(int remove);
575:
576: The invalidate function is called when ssuuddoo is called with the -k
577: or -K flag. For policy plugins such as _s_u_d_o_e_r_s that cache
578: authentication credentials, this function will invalidate the
579: credentials. If the _r_e_m_o_v_e flag is set, the plugin may remove the
580: credentials instead of simply invalidating them.
581:
582: The invalidate function should be NULL if the plugin does not
583: support credential caching.
584:
585: init_session
586: int (*init_session)(struct passwd *pwd);
587:
588: The init_session function is called when ssuuddoo sets up the execution
589: environment for the command, immediately before the contents of the
590: _c_o_m_m_a_n_d___i_n_f_o list are applied (before the uid changes). This can
591: be used to do session setup that is not supported by _c_o_m_m_a_n_d___i_n_f_o,
592: such as opening the PAM session.
593:
594: The _p_w_d argument points to a passwd struct for the user the command
595: will be run as if the uid the command will run as was found in the
596: password database, otherwise it will be NULL.
597:
598: Returns 1 on success, 0 on failure and -1 on error. On error, the
599: plugin may optionally call the conversation or plugin_printf
600: function with SUDO_CONF_ERROR_MSG to present additional error
601: information to the user.
602:
603: _V_e_r_s_i_o_n _m_a_c_r_o_s
604:
605: #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
606: #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
607: #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
608: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
609: } while(0)
610: #define SUDO_VERSION_SET_MINOR(vp, n) do { \
611: *(vp) = (*(vp) & 0xffff0000) | (n); \
612: } while(0)
613:
614: #define SUDO_API_VERSION_MAJOR 1
615: #define SUDO_API_VERSION_MINOR 0
616: #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
617: SUDO_API_VERSION_MINOR)
618:
619: II//OO PPlluuggiinn AAPPII
620: struct io_plugin {
621: #define SUDO_IO_PLUGIN 2
622: unsigned int type; /* always SUDO_IO_PLUGIN */
623: unsigned int version; /* always SUDO_API_VERSION */
624: int (*open)(unsigned int version, sudo_conv_t conversation
625: sudo_printf_t plugin_printf, char * const settings[],
626: char * const user_info[], int argc, char * const argv[],
627: char * const user_env[]);
628: void (*close)(int exit_status, int error); /* wait status or error */
629: int (*show_version)(int verbose);
630: int (*log_ttyin)(const char *buf, unsigned int len);
631: int (*log_ttyout)(const char *buf, unsigned int len);
632: int (*log_stdin)(const char *buf, unsigned int len);
633: int (*log_stdout)(const char *buf, unsigned int len);
634: int (*log_stderr)(const char *buf, unsigned int len);
635: };
636:
637: When an I/O plugin is loaded, ssuuddoo runs the command in a pseudo-tty.
638: This makes it possible to log the input and output from the user's
639: session. If any of the standard input, standard output or standard
640: error do not correspond to a tty, ssuuddoo will open a pipe to capture the
641: I/O for logging before passing it on.
642:
643: The log_ttyin function receives the raw user input from the terminal
644: device (note that this will include input even when echo is disabled,
645: such as when a password is read). The log_ttyout function receives
646: output from the pseudo-tty that is suitable for replaying the user's
647: session at a later time. The log_stdin, log_stdout and log_stderr
648: functions are only called if the standard input, standard output or
649: standard error respectively correspond to something other than a tty.
650:
651: Any of the logging functions may be set to the NULL pointer if no
652: logging is to be performed. If the open function returns 0, no I/O
653: will be sent to the plugin.
654:
655: The io_plugin struct has the following fields:
656:
657: type
658: The type field should always be set to SUDO_IO_PLUGIN
659:
660: version
661: The version field should be set to SUDO_API_VERSION.
662:
663: This allows ssuuddoo to determine the API version the plugin was built
664: against.
665:
666: open
667: int (*open)(unsigned int version, sudo_conv_t conversation
668: sudo_printf_t plugin_printf, char * const settings[],
669: char * const user_info[], int argc, char * const argv[],
670: char * const user_env[]);
671:
672: 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
673: _s_h_o_w___v_e_r_s_i_o_n functions are called. It is only called if the
674: version is being requested or the _c_h_e_c_k___p_o_l_i_c_y function has
675: returned successfully. It returns 1 on success, 0 on failure, -1
676: if a general error occurred, or -2 if there was a usage error. In
677: the latter case, ssuuddoo will print a usage message before it exits.
678: If an error occurs, the plugin may optionally call the conversation
679: or plugin_printf function with SUDO_CONF_ERROR_MSG to present
680: additional error information to the user.
681:
682: The function arguments are as follows:
683:
684: version
685: The version passed in by ssuuddoo allows the plugin to determine
686: the major and minor version number of the plugin API supported
687: by ssuuddoo.
688:
689: conversation
690: A pointer to the conversation function that may be used by the
691: _s_h_o_w___v_e_r_s_i_o_n function to display version information (see
692: show_version below). The conversation function may also be
693: used to display additional error message to the user. The
694: conversation function returns 0 on success and -1 on failure.
695:
696: plugin_printf
697: A pointer to a printf-style function that may be used by the
698: _s_h_o_w___v_e_r_s_i_o_n function to display version information (see
699: show_version below). The plugin_printf function may also be
700: used to display additional error message to the user. The
701: plugin_printf function returns number of characters printed on
702: success and -1 on failure.
703:
704: settings
705: A vector of user-supplied ssuuddoo settings in the form of
706: "name=value" strings. The vector is terminated by a NULL
707: pointer. These settings correspond to flags the user specified
708: when running ssuuddoo. As such, they will only be present when the
709: corresponding flag has been specified on the command line.
710:
711: When parsing _s_e_t_t_i_n_g_s, the plugin should split on the ffiirrsstt
712: equal sign ('=') since the _n_a_m_e field will never include one
713: itself but the _v_a_l_u_e might.
714:
715: See the "Policy Plugin API" section for a list of all possible
716: settings.
717:
718: user_info
719: A vector of information about the user running the command in
720: the form of "name=value" strings. The vector is terminated by
721: a NULL pointer.
722:
723: When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt
724: equal sign ('=') since the _n_a_m_e field will never include one
725: itself but the _v_a_l_u_e might.
726:
727: See the "Policy Plugin API" section for a list of all possible
728: strings.
729:
730: argc
731: The number of elements in _a_r_g_v, not counting the final NULL
732: pointer.
733:
734: argv
735: If non-NULL, an argument vector describing a command the user
736: wishes to run in the same form as what would be passed to the
737: _e_x_e_c_v_e_(_) system call.
738:
739: user_env
740: The user's environment in the form of a NULL-terminated vector
741: of "name=value" strings.
742:
743: When parsing _u_s_e_r___e_n_v, the plugin should split on the ffiirrsstt
744: equal sign ('=') since the _n_a_m_e field will never include one
745: itself but the _v_a_l_u_e might.
746:
747: close
748: void (*close)(int exit_status, int error);
749:
750: The close function is called when the command being run by ssuuddoo
751: finishes.
752:
753: The function arguments are as follows:
754:
755: exit_status
756: The command's exit status, as returned by the _w_a_i_t(2) system
757: call. The value of exit_status is undefined if error is non-
758: zero.
759:
760: error
761: If the command could not be executed, this is set to the value
762: of errno set by the _e_x_e_c_v_e(2) system call. If the command was
763: successfully executed, the value of error is 0.
764:
765: show_version
766: int (*show_version)(int verbose);
767:
768: The show_version function is called by ssuuddoo when the user specifies
769: the -V option. The plugin may display its version information to
770: the user via the conversation or plugin_printf function using
771: SUDO_CONV_INFO_MSG. If the user requests detailed version
772: information, the verbose flag will be set.
773:
774: log_ttyin
775: int (*log_ttyin)(const char *buf, unsigned int len);
776:
777: The _l_o_g___t_t_y_i_n function is called whenever data can be read from the
778: user but before it is passed to the running command. This allows
779: the plugin to reject data if it chooses to (for instance if the
780: input contains banned content). Returns 1 if the data should be
781: passed to the command, 0 if the data is rejected (which will
782: terminate the command) or -1 if an error occurred.
783:
784: The function arguments are as follows:
785:
786: buf The buffer containing user input.
787:
788: len The length of _b_u_f in bytes.
789:
790: log_ttyout
791: int (*log_ttyout)(const char *buf, unsigned int len);
792:
793: The _l_o_g___t_t_y_o_u_t function is called whenever data can be read from
794: the command but before it is written to the user's terminal. This
795: allows the plugin to reject data if it chooses to (for instance if
796: the output contains banned content). Returns 1 if the data should
797: be passed to the user, 0 if the data is rejected (which will
798: terminate the command) or -1 if an error occurred.
799:
800: The function arguments are as follows:
801:
802: buf The buffer containing command output.
803:
804: len The length of _b_u_f in bytes.
805:
806: log_stdin
807: int (*log_stdin)(const char *buf, unsigned int len);
808:
809: The _l_o_g___s_t_d_i_n function is only used if the standard input does not
810: correspond to a tty device. It is called whenever data can be read
811: from the standard input but before it is passed to the running
812: command. This allows the plugin to reject data if it chooses to
813: (for instance if the input contains banned content). Returns 1 if
814: the data should be passed to the command, 0 if the data is rejected
815: (which will terminate the command) or -1 if an error occurred.
816:
817: The function arguments are as follows:
818:
819: buf The buffer containing user input.
820:
821: len The length of _b_u_f in bytes.
822:
823: log_stdout
824: int (*log_stdout)(const char *buf, unsigned int len);
825:
826: The _l_o_g___s_t_d_o_u_t function is only used if the standard output does
827: not correspond to a tty device. It is called whenever data can be
828: read from the command but before it is written to the standard
829: output. This allows the plugin to reject data if it chooses to
830: (for instance if the output contains banned content). Returns 1 if
831: the data should be passed to the user, 0 if the data is rejected
832: (which will terminate the command) or -1 if an error occurred.
833:
834: The function arguments are as follows:
835:
836: buf The buffer containing command output.
837:
838: len The length of _b_u_f in bytes.
839:
840: log_stderr
841: int (*log_stderr)(const char *buf, unsigned int len);
842:
843: The _l_o_g___s_t_d_e_r_r function is only used if the standard error does not
844: correspond to a tty device. It is called whenever data can be read
845: from the command but before it is written to the standard error.
846: This allows the plugin to reject data if it chooses to (for
847: instance if the output contains banned content). Returns 1 if the
848: data should be passed to the user, 0 if the data is rejected (which
849: will terminate the command) or -1 if an error occurred.
850:
851: The function arguments are as follows:
852:
853: buf The buffer containing command output.
854:
855: len The length of _b_u_f in bytes.
856:
857: _V_e_r_s_i_o_n _m_a_c_r_o_s
858:
859: Same as for the "Policy Plugin API".
860:
861: CCoonnvveerrssaattiioonn AAPPII
862: If the plugin needs to interact with the user, it may do so via the
863: conversation function. A plugin should not attempt to read directly
864: from the standard input or the user's tty (neither of which are
865: guaranteed to exist). The caller must include a trailing newline in
866: msg if one is to be printed.
867:
868: A printf-style function is also available that can be used to display
869: informational or error messages to the user, which is usually more
870: convenient for simple messages where no use input is required.
871:
872: struct sudo_conv_message {
873: #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
874: #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
875: #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
876: #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
877: #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
878: #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
879: int msg_type;
880: int timeout;
881: const char *msg;
882: };
883:
884: struct sudo_conv_reply {
885: char *reply;
886: };
887:
888: typedef int (*sudo_conv_t)(int num_msgs,
889: const struct sudo_conv_message msgs[],
890: struct sudo_conv_reply replies[]);
891:
892: typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
893:
894: Pointers to the conversation and printf-style functions are passed in
895: to the plugin's open function when the plugin is initialized.
896:
897: To use the conversation function, the plugin must pass an array of
898: sudo_conv_message and sudo_conv_reply structures. There must be a
899: struct sudo_conv_message and struct sudo_conv_reply for each message in
900: the conversation. The plugin is responsible for freeing the reply
901: buffer filled in to the struct sudo_conv_reply, if any.
902:
903: The printf-style function uses the same underlying mechanism as the
904: conversation function but only supports SUDO_CONV_INFO_MSG and
905: SUDO_CONV_ERROR_MSG for the _m_s_g___t_y_p_e parameter. It can be more
906: convenient than using the conversation function if no user reply is
907: needed and supports standard _p_r_i_n_t_f_(_) escape sequences.
908:
909: See the sample plugin for an example of the conversation function
910: usage.
911:
912: SSuuddooeerrss GGrroouupp PPlluuggiinn AAPPII
913: The _s_u_d_o_e_r_s module supports a plugin interface to allow non-Unix group
914: lookups. This can be used to query a group source other than the
915: standard Unix group database. A sample group plugin is bundled with
916: ssuuddoo that implements file-based lookups. Third party group plugins
917: include a QAS AD plugin available from Quest Software.
918:
919: A group plugin must declare and populate a sudoers_group_plugin struct
920: in the global scope. This structure contains pointers to the functions
921: that implement plugin initialization, cleanup and group lookup.
922:
923: struct sudoers_group_plugin {
924: unsigned int version;
925: int (*init)(int version, sudo_printf_t sudo_printf,
926: char *const argv[]);
927: void (*cleanup)(void);
928: int (*query)(const char *user, const char *group,
929: const struct passwd *pwd);
930: };
931:
932: The sudoers_group_plugin struct has the following fields:
933:
934: version
935: The version field should be set to GROUP_API_VERSION.
936:
937: This allows _s_u_d_o_e_r_s to determine the API version the group plugin
938: was built against.
939:
940: init
941: int (*init)(int version, sudo_printf_t plugin_printf,
942: char *const argv[]);
943:
944: The _i_n_i_t function is called after _s_u_d_o_e_r_s has been parsed but
945: before any policy checks. It returns 1 on success, 0 on failure
946: (or if the plugin is not configured), and -1 if a error occurred.
947: If an error occurs, the plugin may call the plugin_printf function
948: with SUDO_CONF_ERROR_MSG to present additional error information to
949: the user.
950:
951: The function arguments are as follows:
952:
953: version
954: The version passed in by _s_u_d_o_e_r_s allows the plugin to determine
955: the major and minor version number of the group plugin API
956: supported by _s_u_d_o_e_r_s.
957:
958: plugin_printf
959: A pointer to a printf-style function that may be used to
960: display informational or error message to the user. Returns
961: the number of characters printed on success and -1 on failure.
962:
963: argv
964: A NULL-terminated array of arguments generated from the
965: _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,
966: _a_r_g_v will be NULL.
967:
968: cleanup
969: void (*cleanup)();
970:
971: The _c_l_e_a_n_u_p function is called when _s_u_d_o_e_r_s has finished its group
972: checks. The plugin should free any memory it has allocated and
973: close open file handles.
974:
975: query
976: int (*query)(const char *user, const char *group,
977: const struct passwd *pwd);
978:
979: The _q_u_e_r_y function is used to ask the group plugin whether _u_s_e_r is
980: a member of _g_r_o_u_p.
981:
982: The function arguments are as follows:
983:
984: user
985: The name of the user being looked up in the external group
986: database.
987:
988: group
989: The name of the group being queried.
990:
991: pwd The password database entry for _u_s_e_r, if any. If _u_s_e_r is not
992: present in the password database, _p_w_d will be NULL.
993:
994: _V_e_r_s_i_o_n _M_a_c_r_o_s
995:
996: /* Sudoers group plugin version major/minor */
997: #define GROUP_API_VERSION_MAJOR 1
998: #define GROUP_API_VERSION_MINOR 0
999: #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1000: GROUP_API_VERSION_MINOR)
1001:
1002: /* Getters and setters for group version */
1003: #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1004: #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1005: #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1006: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1007: } while(0)
1008: #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1009: *(vp) = (*(vp) & 0xffff0000) | (n); \
1010: } while(0)
1011:
1012: SSEEEE AALLSSOO
1013: _s_u_d_o_e_r_s(4), _s_u_d_o(1m)
1014:
1015: BBUUGGSS
1016: If you feel you have found a bug in ssuuddoo, please submit a bug report at
1017: http://www.sudo.ws/sudo/bugs/
1018:
1019: SSUUPPPPOORRTT
1020: Limited free support is available via the sudo-workers mailing list,
1021: see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1022: search the archives.
1023:
1024: DDIISSCCLLAAIIMMEERR
1025: ssuuddoo is provided ``AS IS'' and any express or implied warranties,
1026: including, but not limited to, the implied warranties of
1027: merchantability and fitness for a particular purpose are disclaimed.
1028: See the LICENSE file distributed with ssuuddoo or
1029: http://www.sudo.ws/sudo/license.html for complete details.
1030:
1031:
1032:
1033: 1.8.3 September 16, 2011 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