Annotation of embedaddon/sudo/doc/sudo_plugin.pod, revision 1.1.1.1
1.1 misho 1: Copyright (c) 2009-2011 Todd C. Miller <Todd.Miller@courtesan.com>
2:
3: Permission to use, copy, modify, and distribute this software for any
4: purpose with or without fee is hereby granted, provided that the above
5: copyright notice and this permission notice appear in all copies.
6:
7: THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8: WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9: MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10: ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11: WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12: ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13: OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14: ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
15:
16: =pod
17:
18: =head1 NAME
19:
20: sudo_plugin - Sudo Plugin API
21:
22: =head1 DESCRIPTION
23:
24: Starting with version 1.8, B<sudo> supports a plugin API
25: for policy and session logging. By default, the I<sudoers> policy
26: plugin and an associated I/O logging plugin are used. Via the plugin
27: API, B<sudo> can be configured to use alternate policy and/or I/O
28: logging plugins provided by third parties. The plugins to be used
29: are specified via the F<@sysconfdir@/sudo.conf> file.
30:
31: The API is versioned with a major and minor number. The minor
32: version number is incremented when additions are made. The major
33: number is incremented when incompatible changes are made. A plugin
34: should be check the version passed to it and make sure that the
35: major version matches.
36:
37: The plugin API is defined by the C<sudo_plugin.h> header file.
38:
39: =head2 The sudo.conf File
40:
41: The F<@sysconfdir@/sudo.conf> file contains plugin configuration directives.
42: Currently, the only supported keyword is the C<Plugin> directive,
43: which causes a plugin plugin to be loaded.
44:
45: A C<Plugin> line consists of the C<Plugin> keyword, followed by the
46: I<symbol_name> and the I<path> to the shared object containing the
47: plugin. The I<symbol_name> is the name of the C<struct policy_plugin>
48: or C<struct io_plugin> in the plugin shared object. The I<path>
49: may be fully qualified or relative. If not fully qualified it is
50: relative to the F<@prefix@/libexec> directory. Any additional
51: parameters after the I<path> are ignored. Lines that don't begin
52: with C<Plugin> or C<Path> are silently ignored.
53:
54: The same shared object may contain multiple plugins, each with a
55: different symbol name. The shared object file must be owned by uid
56: 0 and only writable by its owner. Because of ambiguities that arise
57: from composite policies, only a single policy plugin may be specified.
58: This limitation does not apply to I/O plugins.
59:
60: #
61: # Default @sysconfdir@/sudo.conf file
62: #
63: # Format:
64: # Plugin plugin_name plugin_path
65: # Path askpass /path/to/askpass
66: #
67: # The plugin_path is relative to @prefix@/libexec unless
68: # fully qualified.
69: # The plugin_name corresponds to a global symbol in the plugin
70: # that contains the plugin interface structure.
71: #
72: Plugin sudoers_policy sudoers.so
73: Plugin sudoers_io sudoers.so
74:
75: =head2 Policy Plugin API
76:
77: A policy plugin must declare and populate a C<policy_plugin> struct
78: in the global scope. This structure contains pointers to the functions
79: that implement the B<sudo> policy checks. The name of the symbol should
80: be specified in F<@sysconfdir@/sudo.conf> along with a path to the plugin
81: so that B<sudo> can load it.
82:
83: struct policy_plugin {
84: #define SUDO_POLICY_PLUGIN 1
85: unsigned int type; /* always SUDO_POLICY_PLUGIN */
86: unsigned int version; /* always SUDO_API_VERSION */
87: int (*open)(unsigned int version, sudo_conv_t conversation,
88: sudo_printf_t plugin_printf, char * const settings[],
89: char * const user_info[], char * const user_env[]);
90: void (*close)(int exit_status, int error);
91: int (*show_version)(int verbose);
92: int (*check_policy)(int argc, char * const argv[],
93: char *env_add[], char **command_info[],
94: char **argv_out[], char **user_env_out[]);
95: int (*list)(int argc, char * const argv[], int verbose,
96: const char *list_user);
97: int (*validate)(void);
98: void (*invalidate)(int remove);
99: int (*init_session)(struct passwd *pwd);
100: };
101:
102: The policy_plugin struct has the following fields:
103:
104: =over 4
105:
106: =item type
107:
108: The C<type> field should always be set to SUDO_POLICY_PLUGIN.
109:
110: =item version
111:
112: The C<version> field should be set to SUDO_API_VERSION.
113:
114: This allows B<sudo> to determine the API version the plugin was
115: built against.
116:
117: =item open
118:
119: int (*open)(unsigned int version, sudo_conv_t conversation,
120: sudo_printf_t plugin_printf, char * const settings[],
121: char * const user_info[], char * const user_env[]);
122:
123: Returns 1 on success, 0 on failure, -1 if a general error occurred,
124: or -2 if there was a usage error. In the latter case, B<sudo> will
125: print a usage message before it exits. If an error occurs, the
126: plugin may optionally call the conversation or plugin_printf function
127: with C<SUDO_CONF_ERROR_MSG> to present additional error information
128: to the user.
129:
130: The function arguments are as follows:
131:
132: =over 4
133:
134: =item version
135:
136: The version passed in by B<sudo> allows the plugin to determine the
137: major and minor version number of the plugin API supported by
138: B<sudo>.
139:
140: =item conversation
141:
142: A pointer to the conversation function that can be used by the
143: plugin to interact with the user (see below).
144: Returns 0 on success and -1 on failure.
145:
146: =item plugin_printf
147:
148: A pointer to a printf-style function that may be used to display
149: informational or error messages (see below).
150: Returns the number of characters printed on success and -1 on failure.
151:
152: =item settings
153:
154: A vector of user-supplied B<sudo> settings in the form of "name=value"
155: strings. The vector is terminated by a C<NULL> pointer. These
156: settings correspond to flags the user specified when running B<sudo>.
157: As such, they will only be present when the corresponding flag has
158: been specified on the command line.
159:
160: When parsing I<settings>, the plugin should split on the B<first>
161: equal sign ('=') since the I<name> field will never include one
162: itself but the I<value> might.
163:
164: =over 4
165:
166: =item debug_level=number
167:
168: A numeric debug level, from 1-9, if specified via the C<-D> flag.
169:
170: =item runas_user=string
171:
172: The user name or uid to to run the command as, if specified via the
173: C<-u> flag.
174:
175: =item runas_group=string
176:
177: The group name or gid to to run the command as, if specified via
178: the C<-g> flag.
179:
180: =item prompt=string
181:
182: The prompt to use when requesting a password, if specified via
183: the C<-p> flag.
184:
185: =item set_home=bool
186:
187: Set to true if the user specified the C<-H> flag. If true, set the
188: C<HOME> environment variable to the target user's home directory.
189:
190: =item preserve_environment=bool
191:
192: Set to true if the user specified the C<-E> flag, indicating that
193: the user wishes to preserve the environment.
194:
195: =item run_shell=bool
196:
197: Set to true if the user specified the C<-s> flag, indicating that
198: the user wishes to run a shell.
199:
200: =item login_shell=bool
201:
202: Set to true if the user specified the C<-i> flag, indicating that
203: the user wishes to run a login shell.
204:
205: =item implied_shell=bool
206:
207: If the user does not specify a program on the command line, B<sudo>
208: will pass the plugin the path to the user's shell and set
209: I<implied_shell> to true. This allows B<sudo> with no arguments
210: to be used similarly to L<su(1)>. If the plugin does not to support
211: this usage, it may return a value of -2 from the C<check_policy>
212: function, which will cause B<sudo> to print a usage message and
213: exit.
214:
215: =item preserve_groups=bool
216:
217: Set to true if the user specified the C<-P> flag, indicating that
218: the user wishes to preserve the group vector instead of setting it
219: based on the runas user.
220:
221: =item ignore_ticket=bool
222:
223: Set to true if the user specified the C<-k> flag along with a
224: command, indicating that the user wishes to ignore any cached
225: authentication credentials.
226:
227: =item noninteractive=bool
228:
229: Set to true if the user specified the C<-n> flag, indicating that
230: B<sudo> should operate in non-interactive mode. The plugin may
231: reject a command run in non-interactive mode if user interaction
232: is required.
233:
234: =item login_class=string
235:
236: BSD login class to use when setting resource limits and nice value,
237: if specified by the C<-c> flag.
238:
239: =item selinux_role=string
240:
241: SELinux role to use when executing the command, if specified by
242: the C<-r> flag.
243:
244: =item selinux_type=string
245:
246: SELinux type to use when executing the command, if specified by
247: the C<-t> flag.
248:
249: =item bsdauth_type=string
250:
251: Authentication type, if specified by the C<-a> flag, to use on
252: systems where BSD authentication is supported.
253:
254: =item network_addrs=list
255:
256: A space-separated list of IP network addresses and netmasks in the
257: form "addr/netmask", e.g. "192.168.1.2/255.255.255.0". The address
258: and netmask pairs may be either IPv4 or IPv6, depending on what the
259: operating system supports. If the address contains a colon (':'),
260: it is an IPv6 address, else it is IPv4.
261:
262: =item progname=string
263:
264: The command name that sudo was run as, typically "sudo" or "sudoedit".
265:
266: =item sudoedit=bool
267:
268: Set to true when the C<-e> flag is is specified or if invoked as
269: B<sudoedit>. The plugin shall substitute an editor into I<argv>
270: in the I<check_policy> function or return C<-2> with a usage error
271: if the plugin does not support I<sudoedit>. For more information,
272: see the I<check_policy> section.
273:
274: =item closefrom=number
275:
276: If specified, the user has requested via the C<-C> flag that B<sudo>
277: close all files descriptors with a value of I<number> or higher.
278: The plugin may optionally pass this, or another value, back in the
279: I<command_info> list.
280:
281: =back
282:
283: Additional settings may be added in the future so the plugin should
284: silently ignore settings that it does not recognize.
285:
286: =item user_info
287:
288: A vector of information about the user running the command in the form of
289: "name=value" strings. The vector is terminated by a C<NULL> pointer.
290:
291: When parsing I<user_info>, the plugin should split on the B<first>
292: equal sign ('=') since the I<name> field will never include one
293: itself but the I<value> might.
294:
295: =over 4
296:
297: =item user=string
298:
299: The name of the user invoking B<sudo>.
300:
301: =item uid=uid_t
302:
303: The real user ID of the user invoking B<sudo>.
304:
305: =item gid=gid_t
306:
307: The real group ID of the user invoking B<sudo>.
308:
309: =item groups=list
310:
311: The user's supplementary group list formatted as a string of
312: comma-separated group IDs.
313:
314: =item cwd=string
315:
316: The user's current working directory.
317:
318: =item tty=string
319:
320: The path to the user's terminal device. If the user has no terminal
321: device associated with the session, the value will be empty, as in
322: C<tty=>.
323:
324: =item host=string
325:
326: The local machine's hostname as returned by the C<gethostname()>
327: system call.
328:
329: =item lines=int
330:
331: The number of lines the user's terminal supports. If there is
332: no terminal device available, a default value of 24 is used.
333:
334: =item cols=int
335:
336: The number of columns the user's terminal supports. If there is
337: no terminal device available, a default value of 80 is used.
338:
339: =back
340:
341: =item user_env
342:
343: The user's environment in the form of a C<NULL>-terminated vector of
344: "name=value" strings.
345:
346: When parsing I<user_env>, the plugin should split on the B<first>
347: equal sign ('=') since the I<name> field will never include one
348: itself but the I<value> might.
349:
350: =back
351:
352: =item close
353:
354: void (*close)(int exit_status, int error);
355:
356: The C<close> function is called when the command being run by B<sudo>
357: finishes.
358:
359: The function arguments are as follows:
360:
361: =over 4
362:
363: =item exit_status
364:
365: The command's exit status, as returned by the wait(2) system call.
366: The value of C<exit_status> is undefined if C<error> is non-zero.
367:
368: =item error
369:
370: If the command could not be executed, this is set to the value of
371: C<errno> set by the execve(2) system call. The plugin is responsible
372: for displaying error information via the conversation or plugin_printf
373: function. If the command was successfully executed, the value of
374: C<error> is 0.
375:
376: =back
377:
378: =item show_version
379:
380: int (*show_version)(int verbose);
381:
382: The C<show_version> function is called by B<sudo> when the user specifies
383: the C<-V> option. The plugin may display its version information
384: to the user via the conversation or plugin_printf function using
385: C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
386: information, the verbose flag will be set.
387:
388: =item check_policy
389:
390: int (*check_policy)(int argc, char * const argv[]
391: char *env_add[], char **command_info[],
392: char **argv_out[], char **user_env_out[]);
393:
394: The I<check_policy> function is called by B<sudo> to determine
395: whether the user is allowed to run the specified commands.
396:
397: If the I<sudoedit> option was enabled in the I<settings> array
398: passed to the I<open> function, the user has requested I<sudoedit>
399: mode. I<sudoedit> is a mechanism for editing one or more files
400: where an editor is run with the user's credentials instead of with
401: elevated privileges. B<sudo> achieves this by creating user-writable
402: temporary copies of the files to be edited and then overwriting the
403: originals with the temporary copies after editing is complete. If
404: the plugin supports B<sudoedit>, it should choose the editor to be
405: used, potentially from a variable in the user's environment, such
406: as C<EDITOR>, and include it in I<argv_out> (note that environment
407: variables may include command line flags). The files to be edited
408: should be copied from I<argv> into I<argv_out>, separated from the
409: editor and its arguments by a C<"--"> element. The C<"--"> will
410: be removed by B<sudo> before the editor is executed. The plugin
411: should also set I<sudoedit=true> in the I<command_info> list.
412:
413: The I<check_policy> function returns 1 if the command is allowed,
414: 0 if not allowed, -1 for a general error, or -2 for a usage error
415: or if B<sudoedit> was specified but is unsupported by the plugin.
416: In the latter case, B<sudo> will print a usage message before it
417: exits. If an error occurs, the plugin may optionally call the
418: conversation or plugin_printf function with C<SUDO_CONF_ERROR_MSG>
419: to present additional error information to the user.
420:
421: The function arguments are as follows:
422:
423: =over 4
424:
425: =item argc
426:
427: The number of elements in I<argv>, not counting the final C<NULL>
428: pointer.
429:
430: =item argv
431:
432: The argument vector describing the command the user wishes to run,
433: in the same form as what would be passed to the execve() system
434: call. The vector is terminated by a C<NULL> pointer.
435:
436: =item env_add
437:
438: Additional environment variables specified by the user on the command
439: line in the form of a C<NULL>-terminated vector of "name=value"
440: strings. The plugin may reject the command if one or more variables
441: are not allowed to be set, or it may silently ignore such variables.
442:
443: When parsing I<env_add>, the plugin should split on the B<first>
444: equal sign ('=') since the I<name> field will never include one
445: itself but the I<value> might.
446:
447: =item command_info
448:
449: Information about the command being run in the form of "name=value"
450: strings. These values are used by B<sudo> to set the execution
451: environment when running a command. The plugin is responsible for
452: creating and populating the vector, which must be terminated with
453: a C<NULL> pointer. The following values are recognized by B<sudo>:
454:
455: =over 4
456:
457: =item command=string
458:
459: Fully qualified path to the command to be executed.
460:
461: =item runas_uid=uid
462:
463: User ID to run the command as.
464:
465: =item runas_euid=uid
466:
467: Effective user ID to run the command as.
468: If not specified, the value of I<runas_uid> is used.
469:
470: =item runas_gid=gid
471:
472: Group ID to run the command as.
473:
474: =item runas_egid=gid
475:
476: Effective group ID to run the command as.
477: If not specified, the value of I<runas_gid> is used.
478:
479: =item runas_groups=list
480:
481: The supplementary group vector to use for the command in the form
482: of a comma-separated list of group IDs. If I<preserve_groups>
483: is set, this option is ignored.
484:
485: =item login_class=string
486:
487: BSD login class to use when setting resource limits and nice value
488: (optional). This option is only set on systems that support login
489: classes.
490:
491: =item preserve_groups=bool
492:
493: If set, B<sudo> will preserve the user's group vector instead of
494: initializing the group vector based on C<runas_user>.
495:
496: =item cwd=string
497:
498: The current working directory to change to when executing the command.
499:
500: =item noexec=bool
501:
502: If set, prevent the command from executing other programs.
503:
504: =item chroot=string
505:
506: The root directory to use when running the command.
507:
508: =item nice=int
509:
510: Nice value (priority) to use when executing the command. The nice
511: value, if specified, overrides the priority associated with the
512: I<login_class> on BSD systems.
513:
514: =item umask=octal
515:
516: The file creation mask to use when executing the command.
517:
518: =item selinux_role=string
519:
520: SELinux role to use when executing the command.
521:
522: =item selinux_type=string
523:
524: SELinux type to use when executing the command.
525:
526: =item timeout=int
527:
528: Command timeout. If non-zero then when the timeout expires the
529: command will be killed.
530:
531: =item sudoedit=bool
532:
533: Set to true when in I<sudoedit> mode. The plugin may enable
534: I<sudoedit> mode even if B<sudo> was not invoked as B<sudoedit>.
535: This allows the plugin to perform command substitution and transparently
536: enable I<sudoedit> when the user attempts to run an editor.
537:
538: =item closefrom=number
539:
540: If specified, B<sudo> will close all files descriptors with a value
541: of I<number> or higher.
542:
543: =item iolog_compress=bool
544:
545: Set to true if the I/O logging plugins, if any, should compress the
546: log data. This is a hint to the I/O logging plugin which may choose
547: to ignore it.
548:
549: =item iolog_path=string
550:
551: Fully qualified path to the file or directory in which I/O log is
552: to be stored. This is a hint to the I/O logging plugin which may
553: choose to ignore it. If no I/O logging plugin is loaded, this
554: setting has no effect.
555:
556: =item iolog_stdin=bool
557:
558: Set to true if the I/O logging plugins, if any, should log the
559: standard input if it is not connected to a terminal device. This
560: is a hint to the I/O logging plugin which may choose to ignore it.
561:
562: =item iolog_stdout=bool
563:
564: Set to true if the I/O logging plugins, if any, should log the
565: standard output if it is not connected to a terminal device. This
566: is a hint to the I/O logging plugin which may choose to ignore it.
567:
568: =item iolog_stderr=bool
569:
570: Set to true if the I/O logging plugins, if any, should log the
571: standard error if it is not connected to a terminal device. This
572: is a hint to the I/O logging plugin which may choose to ignore it.
573:
574: =item iolog_ttyin=bool
575:
576: Set to true if the I/O logging plugins, if any, should log all
577: terminal input. This only includes input typed by the user and not
578: from a pipe or redirected from a file. This is a hint to the I/O
579: logging plugin which may choose to ignore it.
580:
581: =item iolog_ttyout=bool
582:
583: Set to true if the I/O logging plugins, if any, should log all
584: terminal output. This only includes output to the screen, not
585: output to a pipe or file. This is a hint to the I/O logging plugin
586: which may choose to ignore it.
587:
588: =item use_pty=bool
589:
590: Allocate a pseudo-tty to run the command in, regardless of whether
591: or not I/O logging is in use. By default, B<sudo> will only run
592: the command in a pty when an I/O log plugin is loaded.
593:
594: =item set_utmp=bool
595:
596: Create a utmp (or utmpx) entry when a pseudo-tty is allocated. By
597: default, the new entry will be a copy of the user's existing utmp
598: entry (if any), with the tty, time, type and pid fields updated.
599:
600: =item utmp_user=string
601:
602: User name to use when constructing a new utmp (or utmpx) entry when
603: I<set_utmp> is enabled. This option can be used to set the user
604: field in the utmp entry to the user the command runs as rather than
605: the invoking user. If not set, B<sudo> will base the new entry on
606: the invoking user's existing entry.
607:
608: =back
609:
610: Unsupported values will be ignored.
611:
612: =item argv_out
613:
614: The C<NULL>-terminated argument vector to pass to the execve()
615: system call when executing the command. The plugin is responsible
616: for allocating and populating the vector.
617:
618: =item user_env_out
619:
620: The C<NULL>-terminated environment vector to use when executing the
621: command. The plugin is responsible for allocating and populating
622: the vector.
623:
624: =back
625:
626: =item list
627:
628: int (*list)(int verbose, const char *list_user,
629: int argc, char * const argv[]);
630:
631: List available privileges for the invoking user. Returns 1 on
632: success, 0 on failure and -1 on error. On error, the plugin may
633: optionally call the conversation or plugin_printf function with
634: C<SUDO_CONF_ERROR_MSG> to present additional error information to
635: the user.
636:
637: Privileges should be output via the conversation or plugin_printf
638: function using C<SUDO_CONV_INFO_MSG>.
639:
640: =over 4
641:
642: =item verbose
643:
644: Flag indicating whether to list in verbose mode or not.
645:
646: =item list_user
647:
648: The name of a different user to list privileges for if the policy
649: allows it. If C<NULL>, the plugin should list the privileges of
650: the invoking user.
651:
652: =item argc
653:
654: The number of elements in I<argv>, not counting the final C<NULL>
655: pointer.
656:
657: =item argv
658:
659: If non-C<NULL>, an argument vector describing a command the user
660: wishes to check against the policy in the same form as what would
661: be passed to the execve() system call. If the command is permitted
662: by the policy, the fully-qualified path to the command should be
663: displayed along with any command line arguments.
664:
665: =back
666:
667: =item validate
668:
669: int (*validate)(void);
670:
671: The C<validate> function is called when B<sudo> is run with the
672: C<-v> flag. For policy plugins such as I<sudoers> that cache
673: authentication credentials, this function will validate and cache
674: the credentials.
675:
676: The C<validate> function should be C<NULL> if the plugin does not
677: support credential caching.
678:
679: Returns 1 on success, 0 on failure and -1 on error.
680: On error, the plugin may optionally call the conversation or plugin_printf
681: function with C<SUDO_CONF_ERROR_MSG> to present additional
682: error information to the user.
683:
684: =item invalidate
685:
686: void (*invalidate)(int remove);
687:
688: The C<invalidate> function is called when B<sudo> is called with
689: the C<-k> or C<-K> flag. For policy plugins such as I<sudoers> that
690: cache authentication credentials, this function will invalidate the
691: credentials. If the I<remove> flag is set, the plugin may remove
692: the credentials instead of simply invalidating them.
693:
694: The C<invalidate> function should be C<NULL> if the plugin does not
695: support credential caching.
696:
697: =item init_session
698:
699: int (*init_session)(struct passwd *pwd);
700:
701: The C<init_session> function is called when B<sudo> sets up the
702: execution environment for the command, immediately before the
703: contents of the I<command_info> list are applied (before the uid
704: changes). This can be used to do session setup that is not supported
705: by I<command_info>, such as opening the PAM session.
706:
707: The I<pwd> argument points to a passwd struct for the user the
708: command will be run as if the uid the command will run as was found
709: in the password database, otherwise it will be NULL.
710:
711: Returns 1 on success, 0 on failure and -1 on error.
712: On error, the plugin may optionally call the conversation or plugin_printf
713: function with C<SUDO_CONF_ERROR_MSG> to present additional
714: error information to the user.
715:
716: =back
717:
718: =head3 Version macros
719:
720: #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
721: #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
722: #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
723: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
724: } while(0)
725: #define SUDO_VERSION_SET_MINOR(vp, n) do { \
726: *(vp) = (*(vp) & 0xffff0000) | (n); \
727: } while(0)
728:
729: #define SUDO_API_VERSION_MAJOR 1
730: #define SUDO_API_VERSION_MINOR 0
731: #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
732: SUDO_API_VERSION_MINOR)
733:
734: =head2 I/O Plugin API
735:
736: struct io_plugin {
737: #define SUDO_IO_PLUGIN 2
738: unsigned int type; /* always SUDO_IO_PLUGIN */
739: unsigned int version; /* always SUDO_API_VERSION */
740: int (*open)(unsigned int version, sudo_conv_t conversation
741: sudo_printf_t plugin_printf, char * const settings[],
742: char * const user_info[], int argc, char * const argv[],
743: char * const user_env[]);
744: void (*close)(int exit_status, int error); /* wait status or error */
745: int (*show_version)(int verbose);
746: int (*log_ttyin)(const char *buf, unsigned int len);
747: int (*log_ttyout)(const char *buf, unsigned int len);
748: int (*log_stdin)(const char *buf, unsigned int len);
749: int (*log_stdout)(const char *buf, unsigned int len);
750: int (*log_stderr)(const char *buf, unsigned int len);
751: };
752:
753: When an I/O plugin is loaded, B<sudo> runs the command in a pseudo-tty.
754: This makes it possible to log the input and output from the user's
755: session. If any of the standard input, standard output or standard
756: error do not correspond to a tty, B<sudo> will open a pipe to capture
757: the I/O for logging before passing it on.
758:
759: The log_ttyin function receives the raw user input from the terminal
760: device (note that this will include input even when echo is disabled,
761: such as when a password is read). The log_ttyout function receives
762: output from the pseudo-tty that is suitable for replaying the user's
763: session at a later time. The log_stdin, log_stdout and log_stderr
764: functions are only called if the standard input, standard output
765: or standard error respectively correspond to something other than
766: a tty.
767:
768: Any of the logging functions may be set to the NULL
769: pointer if no logging is to be performed. If the open function
770: returns C<0>, no I/O will be sent to the plugin.
771:
772: The io_plugin struct has the following fields:
773:
774: =over 4
775:
776: =item type
777:
778: The C<type> field should always be set to SUDO_IO_PLUGIN
779:
780: =item version
781:
782: The C<version> field should be set to SUDO_API_VERSION.
783:
784: This allows B<sudo> to determine the API version the plugin was
785: built against.
786:
787: =item open
788:
789: int (*open)(unsigned int version, sudo_conv_t conversation
790: sudo_printf_t plugin_printf, char * const settings[],
791: char * const user_info[], int argc, char * const argv[],
792: char * const user_env[]);
793:
794: The I<open> function is run before the I<log_input>, I<log_output>
795: or I<show_version> functions are called. It is only called if the
796: version is being requested or the I<check_policy> function has
797: returned successfully. It returns 1 on success, 0 on failure, -1
798: if a general error occurred, or -2 if there was a usage error. In
799: the latter case, B<sudo> will print a usage message before it exits.
800: If an error occurs, the plugin may optionally call the conversation
801: or plugin_printf function with C<SUDO_CONF_ERROR_MSG> to present
802: additional error information to the user.
803:
804: The function arguments are as follows:
805:
806: =over 4
807:
808: =item version
809:
810: The version passed in by B<sudo> allows the plugin to determine the
811: major and minor version number of the plugin API supported by
812: B<sudo>.
813:
814: =item conversation
815:
816: A pointer to the conversation function that may be used by the
817: I<show_version> function to display version information (see
818: show_version below). The conversation function may also be used
819: to display additional error message to the user.
820: The conversation function returns 0 on success and -1 on failure.
821:
822: =item plugin_printf
823:
824: A pointer to a printf-style function that may be used by the
825: I<show_version> function to display version information (see
826: show_version below). The plugin_printf function may also be used
827: to display additional error message to the user.
828: The plugin_printf function returns number of characters printed on
829: success and -1 on failure.
830:
831: =item settings
832:
833: A vector of user-supplied B<sudo> settings in the form of "name=value"
834: strings. The vector is terminated by a C<NULL> pointer. These
835: settings correspond to flags the user specified when running B<sudo>.
836: As such, they will only be present when the corresponding flag has
837: been specified on the command line.
838:
839: When parsing I<settings>, the plugin should split on the B<first>
840: equal sign ('=') since the I<name> field will never include one
841: itself but the I<value> might.
842:
843: See the L<Policy Plugin API> section for a list of all possible settings.
844:
845: =item user_info
846:
847: A vector of information about the user running the command in the form of
848: "name=value" strings. The vector is terminated by a C<NULL> pointer.
849:
850: When parsing I<user_info>, the plugin should split on the B<first>
851: equal sign ('=') since the I<name> field will never include one
852: itself but the I<value> might.
853:
854: See the L<Policy Plugin API> section for a list of all possible strings.
855:
856: =item argc
857:
858: The number of elements in I<argv>, not counting the final C<NULL>
859: pointer.
860:
861: =item argv
862:
863: If non-C<NULL>, an argument vector describing a command the user
864: wishes to run in the same form as what would be passed to the
865: execve() system call.
866:
867: =item user_env
868:
869: The user's environment in the form of a C<NULL>-terminated vector of
870: "name=value" strings.
871:
872: When parsing I<user_env>, the plugin should split on the B<first>
873: equal sign ('=') since the I<name> field will never include one
874: itself but the I<value> might.
875:
876: =back
877:
878: =item close
879:
880: void (*close)(int exit_status, int error);
881:
882: The C<close> function is called when the command being run by B<sudo>
883: finishes.
884:
885: The function arguments are as follows:
886:
887: =over 4
888:
889: =item exit_status
890:
891: The command's exit status, as returned by the wait(2) system call.
892: The value of C<exit_status> is undefined if C<error> is non-zero.
893:
894: =item error
895:
896: If the command could not be executed, this is set to the value of
897: C<errno> set by the execve(2) system call. If the command was
898: successfully executed, the value of C<error> is 0.
899:
900: =back
901:
902: =item show_version
903:
904: int (*show_version)(int verbose);
905:
906: The C<show_version> function is called by B<sudo> when the user specifies
907: the C<-V> option. The plugin may display its version information
908: to the user via the conversation or plugin_printf function using
909: C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
910: information, the verbose flag will be set.
911:
912: =item log_ttyin
913:
914: int (*log_ttyin)(const char *buf, unsigned int len);
915:
916: The I<log_ttyin> function is called whenever data can be read from
917: the user but before it is passed to the running command. This
918: allows the plugin to reject data if it chooses to (for instance
919: if the input contains banned content). Returns C<1> if the data
920: should be passed to the command, C<0> if the data is rejected
921: (which will terminate the command) or C<-1> if an error occurred.
922:
923: The function arguments are as follows:
924:
925: =over 4
926:
927: =item buf
928:
929: The buffer containing user input.
930:
931: =item len
932:
933: The length of I<buf> in bytes.
934:
935: =back
936:
937: =item log_ttyout
938:
939: int (*log_ttyout)(const char *buf, unsigned int len);
940:
941: The I<log_ttyout> function is called whenever data can be read from
942: the command but before it is written to the user's terminal. This
943: allows the plugin to reject data if it chooses to (for instance
944: if the output contains banned content). Returns C<1> if the data
945: should be passed to the user, C<0> if the data is rejected
946: (which will terminate the command) or C<-1> if an error occurred.
947:
948: The function arguments are as follows:
949:
950: =over 4
951:
952: =item buf
953:
954: The buffer containing command output.
955:
956: =item len
957:
958: The length of I<buf> in bytes.
959:
960: =back
961:
962: =item log_stdin
963:
964: int (*log_stdin)(const char *buf, unsigned int len);
965:
966: The I<log_stdin> function is only used if the standard input does
967: not correspond to a tty device. It is called whenever data can be
968: read from the standard input but before it is passed to the running
969: command. This allows the plugin to reject data if it chooses to
970: (for instance if the input contains banned content). Returns C<1>
971: if the data should be passed to the command, C<0> if the data is
972: rejected (which will terminate the command) or C<-1> if an error
973: occurred.
974:
975: The function arguments are as follows:
976:
977: =over 4
978:
979: =item buf
980:
981: The buffer containing user input.
982:
983: =item len
984:
985: The length of I<buf> in bytes.
986:
987: =back
988:
989: =item log_stdout
990:
991: int (*log_stdout)(const char *buf, unsigned int len);
992:
993: The I<log_stdout> function is only used if the standard output does
994: not correspond to a tty device. It is called whenever data can be
995: read from the command but before it is written to the standard
996: output. This allows the plugin to reject data if it chooses to
997: (for instance if the output contains banned content). Returns C<1>
998: if the data should be passed to the user, C<0> if the data is
999: rejected (which will terminate the command) or C<-1> if an error
1000: occurred.
1001:
1002: The function arguments are as follows:
1003:
1004: =over 4
1005:
1006: =item buf
1007:
1008: The buffer containing command output.
1009:
1010: =item len
1011:
1012: The length of I<buf> in bytes.
1013:
1014: =back
1015:
1016: =item log_stderr
1017:
1018: int (*log_stderr)(const char *buf, unsigned int len);
1019:
1020: The I<log_stderr> function is only used if the standard error does
1021: not correspond to a tty device. It is called whenever data can be
1022: read from the command but before it is written to the standard
1023: error. This allows the plugin to reject data if it chooses to
1024: (for instance if the output contains banned content). Returns C<1>
1025: if the data should be passed to the user, C<0> if the data is
1026: rejected (which will terminate the command) or C<-1> if an error
1027: occurred.
1028:
1029: The function arguments are as follows:
1030:
1031: =over 4
1032:
1033: =item buf
1034:
1035: The buffer containing command output.
1036:
1037: =item len
1038:
1039: The length of I<buf> in bytes.
1040:
1041: =back
1042:
1043: =back
1044:
1045: =head3 Version macros
1046:
1047: Same as for the L<Policy Plugin API>.
1048:
1049: =head2 Conversation API
1050:
1051: If the plugin needs to interact with the user, it may do so via the
1052: conversation function. A plugin should not attempt to read directly
1053: from the standard input or the user's tty (neither of which are
1054: guaranteed to exist). The caller must include a trailing newline
1055: in C<msg> if one is to be printed.
1056:
1057: A printf-style function is also available that can be used to display
1058: informational or error messages to the user, which is usually more
1059: convenient for simple messages where no use input is required.
1060:
1061: struct sudo_conv_message {
1062: #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1063: #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1064: #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1065: #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1066: #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1067: #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1068: int msg_type;
1069: int timeout;
1070: const char *msg;
1071: };
1072:
1073: struct sudo_conv_reply {
1074: char *reply;
1075: };
1076:
1077: typedef int (*sudo_conv_t)(int num_msgs,
1078: const struct sudo_conv_message msgs[],
1079: struct sudo_conv_reply replies[]);
1080:
1081: typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1082:
1083: Pointers to the conversation and printf-style functions are passed
1084: in to the plugin's C<open> function when the plugin is initialized.
1085:
1086: To use the conversation function, the plugin must pass an array of
1087: C<sudo_conv_message> and C<sudo_conv_reply> structures. There must
1088: be a C<struct sudo_conv_message> and C<struct sudo_conv_reply> for
1089: each message in the conversation. The plugin is responsible for
1090: freeing the reply buffer filled in to the C<struct sudo_conv_reply>,
1091: if any.
1092:
1093: The printf-style function uses the same underlying mechanism as the
1094: conversation function but only supports C<SUDO_CONV_INFO_MSG> and
1095: C<SUDO_CONV_ERROR_MSG> for the I<msg_type> parameter. It can be
1096: more convenient than using the conversation function if no user
1097: reply is needed and supports standard printf() escape sequences.
1098:
1099: See the sample plugin for an example of the conversation function usage.
1100:
1101: =head2 Sudoers Group Plugin API
1102:
1103: The I<sudoers> module supports a plugin interface to allow non-Unix
1104: group lookups. This can be used to query a group source other than
1105: the standard Unix group database. A sample group plugin is bundled
1106: with B<sudo> that implements file-based lookups. Third party group
1107: plugins include a QAS AD plugin available from Quest Software.
1108:
1109: A group plugin must declare and populate a C<sudoers_group_plugin>
1110: struct in the global scope. This structure contains pointers to
1111: the functions that implement plugin initialization, cleanup and
1112: group lookup.
1113:
1114: struct sudoers_group_plugin {
1115: unsigned int version;
1116: int (*init)(int version, sudo_printf_t sudo_printf,
1117: char *const argv[]);
1118: void (*cleanup)(void);
1119: int (*query)(const char *user, const char *group,
1120: const struct passwd *pwd);
1121: };
1122:
1123: The C<sudoers_group_plugin> struct has the following fields:
1124:
1125: =over 4
1126:
1127: =item version
1128:
1129: The C<version> field should be set to GROUP_API_VERSION.
1130:
1131: This allows I<sudoers> to determine the API version the group plugin
1132: was built against.
1133:
1134: =item init
1135:
1136: int (*init)(int version, sudo_printf_t plugin_printf,
1137: char *const argv[]);
1138:
1139: The I<init> function is called after I<sudoers> has been parsed but
1140: before any policy checks. It returns 1 on success, 0 on failure
1141: (or if the plugin is not configured), and -1 if a error occurred.
1142: If an error occurs, the plugin may call the plugin_printf function
1143: with C<SUDO_CONF_ERROR_MSG> to present additional error information
1144: to the user.
1145:
1146: The function arguments are as follows:
1147:
1148: =over 4
1149:
1150: =item version
1151:
1152: The version passed in by I<sudoers> allows the plugin to determine the
1153: major and minor version number of the group plugin API supported by
1154: I<sudoers>.
1155:
1156: =item plugin_printf
1157:
1158: A pointer to a printf-style function that may be used to display
1159: informational or error message to the user.
1160: Returns the number of characters printed on success and -1 on failure.
1161:
1162: =item argv
1163:
1164: A NULL-terminated array of arguments generated from the I<group_plugin>
1165: option in I<sudoers>. If no arguments were given, I<argv> will be
1166: NULL.
1167:
1168: =back
1169:
1170: =item cleanup
1171:
1172: void (*cleanup)();
1173:
1174: The I<cleanup> function is called when I<sudoers> has finished its
1175: group checks. The plugin should free any memory it has allocated
1176: and close open file handles.
1177:
1178: =item query
1179:
1180: int (*query)(const char *user, const char *group,
1181: const struct passwd *pwd);
1182:
1183: The I<query> function is used to ask the group plugin whether I<user>
1184: is a member of I<group>.
1185:
1186: The function arguments are as follows:
1187:
1188: =over 4
1189:
1190: =item user
1191:
1192: The name of the user being looked up in the external group database.
1193:
1194: =item group
1195:
1196: The name of the group being queried.
1197:
1198: =item pwd
1199:
1200: The password database entry for I<user>, if any. If I<user> is not
1201: present in the password database, I<pwd> will be C<NULL>.
1202:
1203: =back
1204:
1205: =back
1206:
1207: =head3 Version Macros
1208:
1209: /* Sudoers group plugin version major/minor */
1210: #define GROUP_API_VERSION_MAJOR 1
1211: #define GROUP_API_VERSION_MINOR 0
1212: #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1213: GROUP_API_VERSION_MINOR)
1214:
1215: /* Getters and setters for group version */
1216: #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1217: #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1218: #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1219: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1220: } while(0)
1221: #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1222: *(vp) = (*(vp) & 0xffff0000) | (n); \
1223: } while(0)
1224:
1225: =head1 SEE ALSO
1226:
1227: L<sudoers(5)>, L<sudo(8)>
1228:
1229: =head1 BUGS
1230:
1231: If you feel you have found a bug in B<sudo>, please submit a bug report
1232: at http://www.sudo.ws/sudo/bugs/
1233:
1234: =head1 SUPPORT
1235:
1236: Limited free support is available via the sudo-workers mailing list,
1237: see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1238: search the archives.
1239:
1240: =head1 DISCLAIMER
1241:
1242: B<sudo> is provided ``AS IS'' and any express or implied warranties,
1243: including, but not limited to, the implied warranties of merchantability
1244: and fitness for a particular purpose are disclaimed. See the LICENSE
1245: file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
1246: for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo_plugin.pod 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