Annotation of embedaddon/sudo/doc/sudo_plugin.mdoc.in, revision 1.1.1.1
1.1 misho 1: .\"
2: .\" Copyright (c) 2009-2012 Todd C. Miller <Todd.Miller@courtesan.com>
3: .\"
4: .\" Permission to use, copy, modify, and distribute this software for any
5: .\" purpose with or without fee is hereby granted, provided that the above
6: .\" copyright notice and this permission notice appear in all copies.
7: .\"
8: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
16: .\"
17: .Dd July 16, 2012
18: .Dt SUDO_PLUGIN @mansectform@
19: .Os Sudo @PACKAGE_VERSION@
20: .Sh NAME
21: .Nm sudo_plugin
22: .Nd Sudo Plugin API
23: .Sh DESCRIPTION
24: Starting with version 1.8,
25: .Nm sudo
26: supports a plugin API
27: for policy and session logging.
28: By default, the
29: .Em sudoers
30: policy plugin and an associated I/O logging plugin are used.
31: Via the plugin API,
32: .Nm sudo
33: can be configured to use alternate policy and/or I/O logging plugins
34: provided by third parties.
35: The plugins to be used are specified via the
36: .Pa @sysconfdir@/sudo.conf
37: file.
38: .Pp
39: The API is versioned with a major and minor number.
40: The minor version number is incremented when additions are made.
41: The major number is incremented when incompatible changes are made.
42: A plugin should be check the version passed to it and make sure that the
43: major version matches.
44: .Pp
45: The plugin API is defined by the
46: .Li sudo_plugin.h
47: header file.
48: .Ss The sudo.conf file
49: The
50: .Pa @sysconfdir@/sudo.conf
51: file contains plugin configuration directives.
52: The primary keyword is the
53: .Li Plugin
54: directive, which causes a plugin to be loaded.
55: .Pp
56: A
57: .Li Plugin
58: line consists of the
59: .Li Plugin
60: keyword, followed by the
61: .Em symbol_name
62: and the
63: .Em path
64: to the shared object containing the plugin.
65: The
66: .Em symbol_name
67: is the name of the
68: .Li struct policy_plugin
69: or
70: .Li struct io_plugin
71: in the plugin shared object.
72: The
73: .Em path
74: may be fully qualified or relative.
75: If not fully qualified it is relative to the
76: .Pa @prefix@/libexec
77: directory.
78: Any additional parameters after the
79: .Em path
80: are passed as options to the plugin's
81: .Fn open
82: function.
83: Lines that don't begin with
84: .Li Plugin ,
85: .Li Path ,
86: .Li Debug
87: or
88: .Li Set
89: are silently ignored.
90: .Pp
91: The same shared object may contain multiple plugins, each with a
92: different symbol name.
93: The shared object file must be owned by uid 0 and only writable by its owner.
94: Because of ambiguities that arise from composite policies, only a single
95: policy plugin may be specified.
96: This limitation does not apply to I/O plugins.
97: .Bd -literal
98: #
99: # Default @sysconfdir@/sudo.conf file
100: #
101: # Format:
102: # Plugin plugin_name plugin_path plugin_options ...
103: # Path askpass /path/to/askpass
104: # Path noexec /path/to/sudo_noexec.so
105: # Debug sudo /var/log/sudo_debug all@warn
106: # Set disable_coredump true
107: #
108: # The plugin_path is relative to @prefix@/libexec unless
109: # fully qualified.
110: # The plugin_name corresponds to a global symbol in the plugin
111: # that contains the plugin interface structure.
112: # The plugin_options are optional.
113: #
114: Plugin sudoers_policy sudoers.so
115: Plugin sudoers_io sudoers.so
116: .Ed
117: .Ss Policy plugin API
118: A policy plugin must declare and populate a
119: .Li policy_plugin
120: struct in the global scope.
121: This structure contains pointers to the functions that implement the
122: .Nm sudo
123: policy checks.
124: The name of the symbol should be specified in
125: .Pa @sysconfdir@/sudo.conf
126: along with a path to the plugin so that
127: .Nm sudo
128: can load it.
129: .Bd -literal
130: struct policy_plugin {
131: #define SUDO_POLICY_PLUGIN 1
132: unsigned int type; /* always SUDO_POLICY_PLUGIN */
133: unsigned int version; /* always SUDO_API_VERSION */
134: int (*open)(unsigned int version, sudo_conv_t conversation,
135: sudo_printf_t plugin_printf, char * const settings[],
136: char * const user_info[], char * const user_env[],
137: char * const plugin_options[]);
138: void (*close)(int exit_status, int error);
139: int (*show_version)(int verbose);
140: int (*check_policy)(int argc, char * const argv[],
141: char *env_add[], char **command_info[],
142: char **argv_out[], char **user_env_out[]);
143: int (*list)(int argc, char * const argv[], int verbose,
144: const char *list_user);
145: int (*validate)(void);
146: void (*invalidate)(int remove);
147: int (*init_session)(struct passwd *pwd, char **user_env[]);
148: void (*register_hooks)(int version,
149: int (*register_hook)(struct sudo_hook *hook));
150: void (*deregister_hooks)(int version,
151: int (*deregister_hook)(struct sudo_hook *hook));
152: };
153: .Ed
154: .Pp
155: The policy_plugin struct has the following fields:
156: .Bl -tag -width 4n
157: .It type
158: The
159: .Li type
160: field should always be set to SUDO_POLICY_PLUGIN.
161: .It version
162: The
163: .Li version
164: field should be set to
165: .Dv SUDO_API_VERSION .
166: .Pp
167: This allows
168: .Nm sudo
169: to determine the API version the plugin was
170: built against.
171: .It open
172: .Bd -literal -compact
173: int (*open)(unsigned int version, sudo_conv_t conversation,
174: sudo_printf_t plugin_printf, char * const settings[],
175: char * const user_info[], char * const user_env[],
176: char * const plugin_options[]);
177: .Ed
178: .Pp
179: Returns 1 on success, 0 on failure, \-1 if a general error occurred,
180: or \-2 if there was a usage error.
181: In the latter case,
182: .Nm sudo
183: will print a usage message before it exits.
184: If an error occurs, the plugin may optionally call the
185: .Fn conversation
186: or
187: .Fn plugin_printf
188: function with
189: .Dv SUDO_CONF_ERROR_MSG
190: to present additional error information to the user.
191: .Pp
192: The function arguments are as follows:
193: .Bl -tag -width 4n
194: .It version
195: The version passed in by
196: .Nm sudo
197: allows the plugin to determine the
198: major and minor version number of the plugin API supported by
199: .Nm sudo .
200: .It conversation
201: A pointer to the
202: .Fn conversation
203: function that can be used by the plugin to interact with the user (see below).
204: Returns 0 on success and \-1 on failure.
205: .It plugin_printf
206: A pointer to a
207: .Fn printf Ns No -style
208: function that may be used to display informational or error messages
209: (see below).
210: Returns the number of characters printed on success and \-1 on failure.
211: .It settings
212: A vector of user-supplied
213: .Nm sudo
214: settings in the form of
215: .Dq name=value
216: strings.
217: The vector is terminated by a
218: .Dv NULL
219: pointer.
220: These settings correspond to flags the user specified when running
221: .Nm sudo .
222: As such, they will only be present when the corresponding flag has
223: been specified on the command line.
224: .Pp
225: When parsing
226: .Em settings ,
227: the plugin should split on the
228: .Sy first
229: equal sign
230: .Pq Ql =
231: since the
232: .Em name
233: field will never include one
234: itself but the
235: .Em value
236: might.
237: .Bl -tag -width 4n
238: .It debug_flags=string
239: A comma-separated list of debug flags that correspond to
240: .Nm sudo Ns No 's
241: .Li Debug
242: entry in
243: .Pa @sysconfdir@/sudo.conf ,
244: if there is one.
245: The flags are passed to the plugin as they appear in
246: .Pa @sysconfdir@/sudo.conf .
247: The syntax used by
248: .Nm sudo
249: and the
250: .Em sudoers
251: plugin is
252: .Em subsystem Ns No @ Ns Em priority
253: but the plugin is free to use a different
254: format so long as it does not include a comma
255: .Pq Ql ,\& .
256: .Pp
257: For reference, the priorities supported by the
258: .Nm sudo
259: front end and
260: .Em sudoers
261: are:
262: .Em crit ,
263: .Em err ,
264: .Em warn ,
265: .Em notice ,
266: .Em diag ,
267: .Em info ,
268: .Em trace
269: and
270: .Em debug .
271: .Pp
272: The following subsystems are defined:
273: .Em main ,
274: .Em memory ,
275: .Em args ,
276: .Em exec ,
277: .Em pty ,
278: .Em utmp ,
279: .Em conv ,
280: .Em pcomm ,
281: .Em util ,
282: .Em list ,
283: .Em netif ,
284: .Em audit ,
285: .Em edit ,
286: .Em selinux ,
287: .Em ldap ,
288: .Em match ,
289: .Em parser ,
290: .Em alias ,
291: .Em defaults ,
292: .Em auth ,
293: .Em env ,
294: .Em logging ,
295: .Em nss ,
296: .Em rbtree ,
297: .Em perms ,
298: .Em plugin .
299: The subsystem
300: .Em all
301: includes every subsystem.
302: .Pp
303: There is not currently a way to specify a set of debug flags specific
304: to the plugin--the flags are shared by
305: .Nm sudo
306: and the plugin.
307: .It debug_level=number
308: This setting has been deprecated in favor of
309: .Em debug_flags .
310: .It runas_user=string
311: The user name or uid to to run the command as, if specified via the
312: .Fl u
313: flag.
314: .It runas_group=string
315: The group name or gid to to run the command as, if specified via
316: the
317: .Fl g
318: flag.
319: .It prompt=string
320: The prompt to use when requesting a password, if specified via
321: the
322: .Fl p
323: flag.
324: .It set_home=bool
325: Set to true if the user specified the
326: .Fl H
327: flag.
328: If true, set the
329: .Li HOME
330: environment variable to the target user's home directory.
331: .It preserve_environment=bool
332: Set to true if the user specified the
333: .Fl E
334: flag, indicating that
335: the user wishes to preserve the environment.
336: .It run_shell=bool
337: Set to true if the user specified the
338: .Fl s
339: flag, indicating that
340: the user wishes to run a shell.
341: .It login_shell=bool
342: Set to true if the user specified the
343: .Fl i
344: flag, indicating that
345: the user wishes to run a login shell.
346: .It implied_shell=bool
347: If the user does not specify a program on the command line,
348: .Nm sudo
349: will pass the plugin the path to the user's shell and set
350: .Em implied_shell
351: to true.
352: This allows
353: .Nm sudo
354: with no arguments
355: to be used similarly to
356: .Xr su 1 .
357: If the plugin does not to support this usage, it may return a value of \-2
358: from the
359: .Fn check_policy
360: function, which will cause
361: .Nm sudo
362: to print a usage message and
363: exit.
364: .It preserve_groups=bool
365: Set to true if the user specified the
366: .Fl P
367: flag, indicating that
368: the user wishes to preserve the group vector instead of setting it
369: based on the runas user.
370: .It ignore_ticket=bool
371: Set to true if the user specified the
372: .Fl k
373: flag along with a
374: command, indicating that the user wishes to ignore any cached
375: authentication credentials.
376: .It noninteractive=bool
377: Set to true if the user specified the
378: .Fl n
379: flag, indicating that
380: .Nm sudo
381: should operate in non-interactive mode.
382: The plugin may reject a command run in non-interactive mode if user
383: interaction is required.
384: .It login_class=string
385: BSD login class to use when setting resource limits and nice value,
386: if specified by the
387: .Fl c
388: flag.
389: .It selinux_role=string
390: SELinux role to use when executing the command, if specified by
391: the
392: .Fl r
393: flag.
394: .It selinux_type=string
395: SELinux type to use when executing the command, if specified by
396: the
397: .Fl t
398: flag.
399: .It bsdauth_type=string
400: Authentication type, if specified by the
401: .Fl a
402: flag, to use on
403: systems where BSD authentication is supported.
404: .It network_addrs=list
405: A space-separated list of IP network addresses and netmasks in the
406: form
407: .Dq addr/netmask ,
408: e.g.\&
409: .Dq 192.168.1.2/255.255.255.0 .
410: The address and netmask pairs may be either IPv4 or IPv6, depending on
411: what the operating system supports.
412: If the address contains a colon
413: .Pq Ql :\& ,
414: it is an IPv6 address, else it is IPv4.
415: .It progname=string
416: The command name that sudo was run as, typically
417: .Dq sudo
418: or
419: .Dq sudoedit .
420: .It sudoedit=bool
421: Set to true when the
422: .Fl e
423: flag is is specified or if invoked as
424: .Nm sudoedit .
425: The plugin shall substitute an editor into
426: .Em argv
427: in the
428: .Fn check_policy
429: function or return \-2 with a usage error
430: if the plugin does not support
431: .Em sudoedit .
432: For more information, see the
433: .Em check_policy
434: section.
435: .It closefrom=number
436: If specified, the user has requested via the
437: .Fl C
438: flag that
439: .Nm sudo
440: close all files descriptors with a value of
441: .Em number
442: or higher.
443: The plugin may optionally pass this, or another value, back in the
444: .Em command_info
445: list.
446: .El
447: .Pp
448: Additional settings may be added in the future so the plugin should
449: silently ignore settings that it does not recognize.
450: .It user_info
451: A vector of information about the user running the command in the form of
452: .Dq name=value
453: strings.
454: The vector is terminated by a
455: .Dv NULL
456: pointer.
457: .Pp
458: When parsing
459: .Em user_info ,
460: the plugin should split on the
461: .Sy first
462: equal sign
463: .Pq Ql =
464: since the
465: .Em name
466: field will never include one
467: itself but the
468: .Em value
469: might.
470: .Bl -tag -width 4n
471: .It pid=int
472: The process ID of the running
473: .Nm sudo
474: process.
475: Only available starting with API version 1.2
476: .It ppid=int
477: The parent process ID of the running
478: .Nm sudo
479: process.
480: Only available starting with API version 1.2
481: .It sid=int
482: The session ID of the running
483: .Nm sudo
484: process or 0 if
485: .Nm sudo
486: is
487: not part of a POSIX job control session.
488: Only available starting with API version 1.2
489: .It pgid=int
490: The ID of the process group that the running
491: .Nm sudo
492: process belongs
493: to.
494: Only available starting with API version 1.2
495: .It tcpgid=int
496: The ID of the forground process group associated with the terminal
497: device associcated with the
498: .Nm sudo
499: process or \-1 if there is no
500: terminal present.
501: Only available starting with API version 1.2
502: .It user=string
503: The name of the user invoking
504: .Nm sudo .
505: .It euid=uid_t
506: The effective user ID of the user invoking
507: .Nm sudo .
508: .It uid=uid_t
509: The real user ID of the user invoking
510: .Nm sudo .
511: .It egid=gid_t
512: The effective group ID of the user invoking
513: .Nm sudo .
514: .It gid=gid_t
515: The real group ID of the user invoking
516: .Nm sudo .
517: .It groups=list
518: The user's supplementary group list formatted as a string of
519: comma-separated group IDs.
520: .It cwd=string
521: The user's current working directory.
522: .It tty=string
523: The path to the user's terminal device.
524: If the user has no terminal device associated with the session,
525: the value will be empty, as in
526: .Dq Li tty= .
527: .It host=string
528: The local machine's hostname as returned by the
529: .Xr gethostname 2
530: system call.
531: .It lines=int
532: The number of lines the user's terminal supports.
533: If there is
534: no terminal device available, a default value of 24 is used.
535: .It cols=int
536: The number of columns the user's terminal supports.
537: If there is no terminal device available, a default value of 80 is used.
538: .El
539: .It user_env
540: The user's environment in the form of a
541: .Dv NULL Ns No -terminated vector of
542: .Dq name=value
543: strings.
544: .Pp
545: When parsing
546: .Em user_env ,
547: the plugin should split on the
548: .Sy first
549: equal sign
550: .Pq Ql =
551: since the
552: .Em name
553: field will never include one
554: itself but the
555: .Em value
556: might.
557: .It plugin_options
558: Any (non-comment) strings immediately after the plugin path are
559: treated as arguments to the plugin.
560: These arguments are split on a white space boundary and are passed to
561: the plugin in the form of a
562: .Dv NULL Ns No -terminated
563: array of strings.
564: If no arguments were
565: specified,
566: .Em plugin_options
567: will be the
568: .Dv NULL
569: pointer.
570: .Pp
571: NOTE: the
572: .Em plugin_options
573: parameter is only available starting with
574: API version 1.2.
575: A plugin
576: .Sy must
577: check the API version specified
578: by the
579: .Nm sudo
580: front end before using
581: .Em plugin_options .
582: Failure to do so may result in a crash.
583: .El
584: .It close
585: .Bd -literal -compact
586: void (*close)(int exit_status, int error);
587: .Ed
588: .Pp
589: The
590: .Fn close
591: function is called when the command being run by
592: .Nm sudo
593: finishes.
594: .Pp
595: The function arguments are as follows:
596: .Bl -tag -width 4n
597: .It exit_status
598: The command's exit status, as returned by the
599: .Xr wait 2
600: system call.
601: The value of
602: .Li exit_status
603: is undefined if
604: .Li error
605: is non-zero.
606: .It error
607: If the command could not be executed, this is set to the value of
608: .Li errno
609: set by the
610: .Xr execve 2
611: system call.
612: The plugin is responsible for displaying error information via the
613: .Fn conversation
614: or
615: .Fn plugin_printf
616: function.
617: If the command was successfully executed, the value of
618: .Li error
619: is 0.
620: .El
621: .It show_version
622: .Bd -literal -compact
623: int (*show_version)(int verbose);
624: .Ed
625: .Pp
626: The
627: .Fn show_version
628: function is called by
629: .Nm sudo
630: when the user specifies
631: the
632: .Fl V
633: option.
634: The plugin may display its version information to the user via the
635: .Fn conversation
636: or
637: .Fn plugin_printf
638: function using
639: .Dv SUDO_CONV_INFO_MSG .
640: If the user requests detailed version information, the verbose flag will be set.
641: .It check_policy
642: .Bd -literal -compact
643: int (*check_policy)(int argc, char * const argv[]
644: char *env_add[], char **command_info[],
645: char **argv_out[], char **user_env_out[]);
646: .Ed
647: .Pp
648: The
649: .Fn check_policy
650: function is called by
651: .Nm sudo
652: to determine
653: whether the user is allowed to run the specified commands.
654: .Pp
655: If the
656: .Em sudoedit
657: option was enabled in the
658: .Em settings
659: array
660: passed to the
661: .Fn open
662: function, the user has requested
663: .Em sudoedit
664: mode.
665: .Em sudoedit
666: is a mechanism for editing one or more files
667: where an editor is run with the user's credentials instead of with
668: elevated privileges.
669: .Nm sudo
670: achieves this by creating user-writable
671: temporary copies of the files to be edited and then overwriting the
672: originals with the temporary copies after editing is complete.
673: If the plugin supports
674: .Em sudoedit ,
675: it should choose the editor to be used, potentially from a variable
676: in the user's environment, such as
677: .Li EDITOR ,
678: and include it in
679: .Em argv_out
680: (note that environment
681: variables may include command line flags).
682: The files to be edited should be copied from
683: .Em argv
684: into
685: .Em argv_out ,
686: separated from the
687: editor and its arguments by a
688: .Dq Li --
689: element.
690: The
691: .Dq Li --
692: will
693: be removed by
694: .Nm sudo
695: before the editor is executed.
696: The plugin should also set
697: .Em sudoedit=true
698: in the
699: .Em command_info
700: list.
701: .Pp
702: The
703: .Fn check_policy
704: function returns 1 if the command is allowed,
705: 0 if not allowed, \-1 for a general error, or \-2 for a usage error
706: or if
707: .Em sudoedit
708: was specified but is unsupported by the plugin.
709: In the latter case,
710: .Nm sudo
711: will print a usage message before it
712: exits.
713: If an error occurs, the plugin may optionally call the
714: .Fn conversation
715: or
716: .Fn plugin_printf
717: function with
718: .Dv SUDO_CONF_ERROR_MSG
719: to present additional error information to the user.
720: .Pp
721: The function arguments are as follows:
722: .Bl -tag -width 4n
723: .It argc
724: The number of elements in
725: .Em argv ,
726: not counting the final
727: .Dv NULL
728: pointer.
729: .It argv
730: The argument vector describing the command the user wishes to run,
731: in the same form as what would be passed to the
732: .Xr execve 2
733: system call.
734: The vector is terminated by a
735: .Dv NULL
736: pointer.
737: .It env_add
738: Additional environment variables specified by the user on the command
739: line in the form of a
740: .Dv NULL Ns No -terminated
741: vector of
742: .Dq name=value
743: strings.
744: The plugin may reject the command if one or more variables
745: are not allowed to be set, or it may silently ignore such variables.
746: .Pp
747: When parsing
748: .Em env_add ,
749: the plugin should split on the
750: .Sy first
751: equal sign
752: .Pq Ql =
753: since the
754: .Em name
755: field will never include one
756: itself but the
757: .Em value
758: might.
759: .It command_info
760: Information about the command being run in the form of
761: .Dq name=value
762: strings.
763: These values are used by
764: .Nm sudo
765: to set the execution
766: environment when running a command.
767: The plugin is responsible for creating and populating the vector,
768: which must be terminated with a
769: .Dv NULL
770: pointer.
771: The following values are recognized by
772: .Nm sudo :
773: .Bl -tag -width 4n
774: .It command=string
775: Fully qualified path to the command to be executed.
776: .It runas_uid=uid
777: User ID to run the command as.
778: .It runas_euid=uid
779: Effective user ID to run the command as.
780: If not specified, the value of
781: .Em runas_uid
782: is used.
783: .It runas_gid=gid
784: Group ID to run the command as.
785: .It runas_egid=gid
786: Effective group ID to run the command as.
787: If not specified, the value of
788: .Em runas_gid
789: is used.
790: .It runas_groups=list
791: The supplementary group vector to use for the command in the form
792: of a comma-separated list of group IDs.
793: If
794: .Em preserve_groups
795: is set, this option is ignored.
796: .It login_class=string
797: BSD login class to use when setting resource limits and nice value
798: (optional).
799: This option is only set on systems that support login classes.
800: .It preserve_groups=bool
801: If set,
802: .Nm sudo
803: will preserve the user's group vector instead of
804: initializing the group vector based on
805: .Li runas_user .
806: .It cwd=string
807: The current working directory to change to when executing the command.
808: .It noexec=bool
809: If set, prevent the command from executing other programs.
810: .It chroot=string
811: The root directory to use when running the command.
812: .It nice=int
813: Nice value (priority) to use when executing the command.
814: The nice value, if specified, overrides the priority associated with the
815: .Em login_class
816: on BSD systems.
817: .It umask=octal
818: The file creation mask to use when executing the command.
819: .It selinux_role=string
820: SELinux role to use when executing the command.
821: .It selinux_type=string
822: SELinux type to use when executing the command.
823: .It timeout=int
824: Command timeout.
825: If non-zero then when the timeout expires the command will be killed.
826: .It sudoedit=bool
827: Set to true when in
828: .Em sudoedit
829: mode.
830: The plugin may enable
831: .Em sudoedit
832: mode even if
833: .Nm sudo
834: was not invoked as
835: .Nm sudoedit .
836: This allows the plugin to perform command substitution and transparently
837: enable
838: .Em sudoedit
839: when the user attempts to run an editor.
840: .It closefrom=number
841: If specified,
842: .Nm sudo
843: will close all files descriptors with a value
844: of
845: .Em number
846: or higher.
847: .It iolog_compress=bool
848: Set to true if the I/O logging plugins, if any, should compress the
849: log data.
850: This is a hint to the I/O logging plugin which may choose to ignore it.
851: .It iolog_path=string
852: Fully qualified path to the file or directory in which I/O log is
853: to be stored.
854: This is a hint to the I/O logging plugin which may choose to ignore it.
855: If no I/O logging plugin is loaded, this setting has no effect.
856: .It iolog_stdin=bool
857: Set to true if the I/O logging plugins, if any, should log the
858: standard input if it is not connected to a terminal device.
859: This is a hint to the I/O logging plugin which may choose to ignore it.
860: .It iolog_stdout=bool
861: Set to true if the I/O logging plugins, if any, should log the
862: standard output if it is not connected to a terminal device.
863: This is a hint to the I/O logging plugin which may choose to ignore it.
864: .It iolog_stderr=bool
865: Set to true if the I/O logging plugins, if any, should log the
866: standard error if it is not connected to a terminal device.
867: This is a hint to the I/O logging plugin which may choose to ignore it.
868: .It iolog_ttyin=bool
869: Set to true if the I/O logging plugins, if any, should log all
870: terminal input.
871: This only includes input typed by the user and not from a pipe or
872: redirected from a file.
873: This is a hint to the I/O logging plugin which may choose to ignore it.
874: .It iolog_ttyout=bool
875: Set to true if the I/O logging plugins, if any, should log all
876: terminal output.
877: This only includes output to the screen, not output to a pipe or file.
878: This is a hint to the I/O logging plugin which may choose to ignore it.
879: .It use_pty=bool
880: Allocate a pseudo-tty to run the command in, regardless of whether
881: or not I/O logging is in use.
882: By default,
883: .Nm sudo
884: will only run
885: the command in a pty when an I/O log plugin is loaded.
886: .It set_utmp=bool
887: Create a utmp (or utmpx) entry when a pseudo-tty is allocated.
888: By default, the new entry will be a copy of the user's existing utmp
889: entry (if any), with the tty, time, type and pid fields updated.
890: .It utmp_user=string
891: User name to use when constructing a new utmp (or utmpx) entry when
892: .Em set_utmp
893: is enabled.
894: This option can be used to set the user field in the utmp entry to
895: the user the command runs as rather than the invoking user.
896: If not set,
897: .Nm sudo
898: will base the new entry on
899: the invoking user's existing entry.
900: .El
901: .Pp
902: Unsupported values will be ignored.
903: .It argv_out
904: The
905: .Dv NULL Ns No -terminated
906: argument vector to pass to the
907: .Xr execve 2
908: system call when executing the command.
909: The plugin is responsible for allocating and populating the vector.
910: .It user_env_out
911: The
912: .Dv NULL Ns No -terminated
913: environment vector to use when executing the command.
914: The plugin is responsible for allocating and populating the vector.
915: .El
916: .It list
917: .Bd -literal -compact
918: int (*list)(int verbose, const char *list_user,
919: int argc, char * const argv[]);
920: .Ed
921: .Pp
922: List available privileges for the invoking user.
923: Returns 1 on success, 0 on failure and \-1 on error.
924: On error, the plugin may optionally call the
925: .Fn conversation
926: or
927: .Fn plugin_printf
928: function with
929: .Dv SUDO_CONF_ERROR_MSG
930: to present additional error information to
931: the user.
932: .Pp
933: Privileges should be output via the
934: .Fn conversation
935: or
936: .Fn plugin_printf
937: function using
938: .Dv SUDO_CONV_INFO_MSG ,
939: .Bl -tag -width 4n
940: .It verbose
941: Flag indicating whether to list in verbose mode or not.
942: .It list_user
943: The name of a different user to list privileges for if the policy
944: allows it.
945: If
946: .Dv NULL ,
947: the plugin should list the privileges of the invoking user.
948: .It argc
949: The number of elements in
950: .Em argv ,
951: not counting the final
952: .Dv NULL
953: pointer.
954: .It argv
955: If
956: .No non- Ns Dv NULL ,
957: an argument vector describing a command the user
958: wishes to check against the policy in the same form as what would
959: be passed to the
960: .Xr execve 2
961: system call.
962: If the command is permitted by the policy, the fully-qualified path
963: to the command should be displayed along with any command line arguments.
964: .El
965: .It validate
966: .Bd -literal -compact
967: int (*validate)(void);
968: .Ed
969: .Pp
970: The
971: .Fn validate
972: function is called when
973: .Nm sudo
974: is run with the
975: .Fl v
976: flag.
977: For policy plugins such as
978: .Em sudoers
979: that cache
980: authentication credentials, this function will validate and cache
981: the credentials.
982: .Pp
983: The
984: .Fn validate
985: function should be
986: .Dv NULL
987: if the plugin does not support credential caching.
988: .Pp
989: Returns 1 on success, 0 on failure and \-1 on error.
990: On error, the plugin may optionally call the
991: .Fn conversation
992: or
993: .Fn plugin_printf
994: function with
995: .Dv SUDO_CONF_ERROR_MSG
996: to present additional
997: error information to the user.
998: .It invalidate
999: .Bd -literal -compact
1000: void (*invalidate)(int remove);
1001: .Ed
1002: .Pp
1003: The
1004: .Fn invalidate
1005: function is called when
1006: .Nm sudo
1007: is called with
1008: the
1009: .Fl k
1010: or
1011: .Fl K
1012: flag.
1013: For policy plugins such as
1014: .Em sudoers
1015: that
1016: cache authentication credentials, this function will invalidate the
1017: credentials.
1018: If the
1019: .Em remove
1020: flag is set, the plugin may remove
1021: the credentials instead of simply invalidating them.
1022: .Pp
1023: The
1024: .Fn invalidate
1025: function should be
1026: .Dv NULL
1027: if the plugin does not support credential caching.
1028: .It init_session
1029: .Bd -literal -compact
1030: int (*init_session)(struct passwd *pwd, char **user_envp[);
1031: .Ed
1032: .Pp
1033: The
1034: .Fn init_session
1035: function is called before
1036: .Nm sudo
1037: sets up the
1038: execution environment for the command.
1039: It is run in the parent
1040: .Nm sudo
1041: process and before any uid or gid changes.
1042: This can be used to perform session setup that is not supported by
1043: .Em command_info ,
1044: such as opening the PAM session.
1045: The
1046: .Fn close
1047: function can be
1048: used to tear down the session that was opened by
1049: .Li init_session .
1050: .Pp
1051: The
1052: .Em pwd
1053: argument points to a passwd struct for the user the
1054: command will be run as if the uid the command will run as was found
1055: in the password database, otherwise it will be
1056: .Dv NULL .
1057: .Pp
1058: The
1059: .Em user_env
1060: argument points to the environment the command will
1061: run in, in the form of a
1062: .Dv NULL Ns No -terminated
1063: vector of
1064: .Dq name=value
1065: strings.
1066: This is the same string passed back to the front end via
1067: the Policy Plugin's
1068: .Em user_env_out
1069: parameter.
1070: If the
1071: .Fn init_session
1072: function needs to modify the user environment, it should update the
1073: pointer stored in
1074: .Em user_env .
1075: The expected use case is to merge the contents of the PAM environment
1076: (if any) with the contents of
1077: .Em user_env .
1078: NOTE: the
1079: .Em user_env
1080: parameter is only available
1081: starting with API version 1.2.
1082: A plugin
1083: .Sy must
1084: check the API
1085: version specified by the
1086: .Nm sudo
1087: front end before using
1088: .Em user_env .
1089: Failure to do so may result in a crash.
1090: .Pp
1091: Returns 1 on success, 0 on failure and \-1 on error.
1092: On error, the plugin may optionally call the
1093: .Fn conversation
1094: or
1095: .Fn plugin_printf
1096: function with
1097: .Dv SUDO_CONF_ERROR_MSG
1098: to present additional
1099: error information to the user.
1100: .It register_hooks
1101: .Bd -literal -compact
1102: void (*register_hooks)(int version,
1103: int (*register_hook)(struct sudo_hook *hook));
1104: .Ed
1105: .Pp
1106: The
1107: .Fn register_hooks
1108: function is called by the sudo front end to
1109: register any hooks the plugin needs.
1110: If the plugin does not support hooks,
1111: .Li register_hooks
1112: should be set to the
1113: .Dv NULL
1114: pointer.
1115: .Pp
1116: The
1117: .Em version
1118: argument describes the version of the hooks API
1119: supported by the
1120: .Nm sudo
1121: front end.
1122: .Pp
1123: The
1124: .Fn register_hook
1125: function should be used to register any supported
1126: hooks the plugin needs.
1127: It returns 0 on success, 1 if the hook type is not supported and \-1
1128: if the major version in
1129: .Li struct hook
1130: does not match the front end's major hook API version.
1131: .Pp
1132: See the
1133: .Sx Hook function API
1134: section below for more information
1135: about hooks.
1136: .Pp
1137: NOTE: the
1138: .Fn register_hooks
1139: function is only available starting
1140: with API version 1.2.
1141: If the
1142: .Nm sudo
1143: front end doesn't support API
1144: version 1.2 or higher,
1145: .Li register_hooks
1146: will not be called.
1147: .It deregister_hooks
1148: .Bd -literal -compact
1149: void (*deregister_hooks)(int version,
1150: int (*deregister_hook)(struct sudo_hook *hook));
1151: .Ed
1152: .Pp
1153: The
1154: .Fn deregister_hooks
1155: function is called by the sudo front end
1156: to deregister any hooks the plugin has registered.
1157: If the plugin does not support hooks,
1158: .Li deregister_hooks
1159: should be set to the
1160: .Dv NULL
1161: pointer.
1162: .Pp
1163: The
1164: .Em version
1165: argument describes the version of the hooks API
1166: supported by the
1167: .Nm sudo
1168: front end.
1169: .Pp
1170: The
1171: .Fn deregister_hook
1172: function should be used to deregister any
1173: hooks that were put in place by the
1174: .Fn register_hook
1175: function.
1176: If the plugin tries to deregister a hook that the front end does not support,
1177: .Li deregister_hook
1178: will return an error.
1179: .Pp
1180: See the
1181: .Sx Hook function API
1182: section below for more information
1183: about hooks.
1184: .Pp
1185: NOTE: the
1186: .Fn deregister_hooks
1187: function is only available starting
1188: with API version 1.2.
1189: If the
1190: .Nm sudo
1191: front end doesn't support API
1192: version 1.2 or higher,
1193: .Li deregister_hooks
1194: will not be called.
1195: .El
1196: .Pp
1197: .Em Policy Plugin Version Macros
1198: .Bd -literal
1199: /* Plugin API version major/minor. */
1200: #define SUDO_API_VERSION_MAJOR 1
1201: #define SUDO_API_VERSION_MINOR 2
1202: #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1203: #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e
1204: SUDO_API_VERSION_MINOR)
1205:
1206: /* Getters and setters for API version */
1207: #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1208: #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1209: #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
1210: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1211: } while(0)
1212: #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
1213: *(vp) = (*(vp) & 0xffff0000) | (n); \e
1214: } while(0)
1215: .Ed
1216: .Ss I/O plugin API
1217: .Bd -literal
1218: struct io_plugin {
1219: #define SUDO_IO_PLUGIN 2
1220: unsigned int type; /* always SUDO_IO_PLUGIN */
1221: unsigned int version; /* always SUDO_API_VERSION */
1222: int (*open)(unsigned int version, sudo_conv_t conversation
1223: sudo_printf_t plugin_printf, char * const settings[],
1224: char * const user_info[], int argc, char * const argv[],
1225: char * const user_env[], char * const plugin_options[]);
1226: void (*close)(int exit_status, int error); /* wait status or error */
1227: int (*show_version)(int verbose);
1228: int (*log_ttyin)(const char *buf, unsigned int len);
1229: int (*log_ttyout)(const char *buf, unsigned int len);
1230: int (*log_stdin)(const char *buf, unsigned int len);
1231: int (*log_stdout)(const char *buf, unsigned int len);
1232: int (*log_stderr)(const char *buf, unsigned int len);
1233: void (*register_hooks)(int version,
1234: int (*register_hook)(struct sudo_hook *hook));
1235: void (*deregister_hooks)(int version,
1236: int (*deregister_hook)(struct sudo_hook *hook));
1237: };
1238: .Ed
1239: .Pp
1240: When an I/O plugin is loaded,
1241: .Nm sudo
1242: runs the command in a pseudo-tty.
1243: This makes it possible to log the input and output from the user's
1244: session.
1245: If any of the standard input, standard output or standard error do not
1246: correspond to a tty,
1247: .Nm sudo
1248: will open a pipe to capture
1249: the I/O for logging before passing it on.
1250: .Pp
1251: The log_ttyin function receives the raw user input from the terminal
1252: device (note that this will include input even when echo is disabled,
1253: such as when a password is read).
1254: The log_ttyout function receives output from the pseudo-tty that is
1255: suitable for replaying the user's session at a later time.
1256: The
1257: .Fn log_stdin ,
1258: .Fn log_stdout
1259: and
1260: .Fn log_stderr
1261: functions are only called if the standard input, standard output
1262: or standard error respectively correspond to something other than
1263: a tty.
1264: .Pp
1265: Any of the logging functions may be set to the
1266: .Dv NULL
1267: pointer if no logging is to be performed.
1268: If the open function returns 0, no I/O will be sent to the plugin.
1269: .Pp
1270: The io_plugin struct has the following fields:
1271: .Bl -tag -width 4n
1272: .It type
1273: The
1274: .Li type
1275: field should always be set to
1276: .Dv SUDO_IO_PLUGIN .
1277: .It version
1278: The
1279: .Li version
1280: field should be set to
1281: .Dv SUDO_API_VERSION .
1282: .Pp
1283: This allows
1284: .Nm sudo
1285: to determine the API version the plugin was
1286: built against.
1287: .It open
1288: .Bd -literal -compact
1289: int (*open)(unsigned int version, sudo_conv_t conversation
1290: sudo_printf_t plugin_printf, char * const settings[],
1291: char * const user_info[], int argc, char * const argv[],
1292: char * const user_env[], char * const plugin_options[]);
1293: .Ed
1294: .Pp
1295: The
1296: .Fn open
1297: function is run before the
1298: .Fn log_input ,
1299: .Fn log_output
1300: or
1301: .Fn show_version
1302: functions are called.
1303: It is only called if the version is being requested or the
1304: .Fn check_policy
1305: function has
1306: returned successfully.
1307: It returns 1 on success, 0 on failure, \-1 if a general error occurred,
1308: or \-2 if there was a usage error.
1309: In the latter case,
1310: .Nm sudo
1311: will print a usage message before it exits.
1312: If an error occurs, the plugin may optionally call the
1313: .Fn conversation
1314: or
1315: .Fn plugin_printf
1316: function with
1317: .Dv SUDO_CONF_ERROR_MSG
1318: to present
1319: additional error information to the user.
1320: .Pp
1321: The function arguments are as follows:
1322: .Bl -tag -width 4n
1323: .It version
1324: The version passed in by
1325: .Nm sudo
1326: allows the plugin to determine the
1327: major and minor version number of the plugin API supported by
1328: .Nm sudo .
1329: .It conversation
1330: A pointer to the
1331: .Fn conversation
1332: function that may be used by the
1333: .Fn show_version
1334: function to display version information (see
1335: .Fn show_version
1336: below).
1337: The
1338: .Fn conversation
1339: function may also be used to display additional error message to the user.
1340: The
1341: .Fn conversation
1342: function returns 0 on success and \-1 on failure.
1343: .It plugin_printf
1344: A pointer to a
1345: .Fn printf Ns No -style
1346: function that may be used by the
1347: .Fn show_version
1348: function to display version information (see
1349: show_version below).
1350: The
1351: .Fn plugin_printf
1352: function may also be used to display additional error message to the user.
1353: The
1354: .Fn plugin_printf
1355: function returns number of characters printed on success and \-1 on failure.
1356: .It settings
1357: A vector of user-supplied
1358: .Nm sudo
1359: settings in the form of
1360: .Dq name=value
1361: strings.
1362: The vector is terminated by a
1363: .Dv NULL
1364: pointer.
1365: These settings correspond to flags the user specified when running
1366: .Nm sudo .
1367: As such, they will only be present when the corresponding flag has
1368: been specified on the command line.
1369: .Pp
1370: When parsing
1371: .Em settings ,
1372: the plugin should split on the
1373: .Sy first
1374: equal sign
1375: .Pq Ql =
1376: since the
1377: .Em name
1378: field will never include one
1379: itself but the
1380: .Em value
1381: might.
1382: .Pp
1383: See the
1384: .Sx Policy plugin API
1385: section for a list of all possible settings.
1386: .It user_info
1387: A vector of information about the user running the command in the form of
1388: .Dq name=value
1389: strings.
1390: The vector is terminated by a
1391: .Dv NULL
1392: pointer.
1393: .Pp
1394: When parsing
1395: .Em user_info ,
1396: the plugin should split on the
1397: .Sy first
1398: equal sign
1399: .Pq Ql =
1400: since the
1401: .Em name
1402: field will never include one
1403: itself but the
1404: .Em value
1405: might.
1406: .Pp
1407: See the
1408: .Sx Policy plugin API
1409: section for a list of all possible strings.
1410: .It argc
1411: The number of elements in
1412: .Em argv ,
1413: not counting the final
1414: .Dv NULL
1415: pointer.
1416: .It argv
1417: If
1418: .No non- Ns Dv NULL ,
1419: an argument vector describing a command the user
1420: wishes to run in the same form as what would be passed to the
1421: .Xr execve 2
1422: system call.
1423: .It user_env
1424: The user's environment in the form of a
1425: .Dv NULL Ns No -terminated
1426: vector of
1427: .Dq name=value
1428: strings.
1429: .Pp
1430: When parsing
1431: .Em user_env ,
1432: the plugin should split on the
1433: .Sy first
1434: equal sign
1435: .Pq Ql =
1436: since the
1437: .Em name
1438: field will never include one
1439: itself but the
1440: .Em value
1441: might.
1442: .It plugin_options
1443: Any (non-comment) strings immediately after the plugin path are
1444: treated as arguments to the plugin.
1445: These arguments are split on a white space boundary and are passed to
1446: the plugin in the form of a
1447: .Dv NULL Ns No -terminated
1448: array of strings.
1449: If no arguments were specified,
1450: .Em plugin_options
1451: will be the
1452: .Dv NULL
1453: pointer.
1454: .Pp
1455: NOTE: the
1456: .Em plugin_options
1457: parameter is only available starting with
1458: API version 1.2.
1459: A plugin
1460: .Sy must
1461: check the API version specified
1462: by the
1463: .Nm sudo
1464: front end before using
1465: .Em plugin_options .
1466: Failure to do so may result in a crash.
1467: .El
1468: .It close
1469: .Bd -literal -compact
1470: void (*close)(int exit_status, int error);
1471: .Ed
1472: .Pp
1473: The
1474: .Fn close
1475: function is called when the command being run by
1476: .Nm sudo
1477: finishes.
1478: .Pp
1479: The function arguments are as follows:
1480: .Bl -tag -width 4n
1481: .It exit_status
1482: The command's exit status, as returned by the
1483: .Xr wait 2
1484: system call.
1485: The value of
1486: .Li exit_status
1487: is undefined if
1488: .Li error
1489: is non-zero.
1490: .It error
1491: If the command could not be executed, this is set to the value of
1492: .Li errno
1493: set by the
1494: .Xr execve 2
1495: system call.
1496: If the command was successfully executed, the value of
1497: .Li error
1498: is 0.
1499: .El
1500: .It show_version
1501: .Bd -literal -compact
1502: int (*show_version)(int verbose);
1503: .Ed
1504: .Pp
1505: The
1506: .Fn show_version
1507: function is called by
1508: .Nm sudo
1509: when the user specifies
1510: the
1511: .Fl V
1512: option.
1513: The plugin may display its version information to the user via the
1514: .Fn conversation
1515: or
1516: .Fn plugin_printf
1517: function using
1518: .Dv SUDO_CONV_INFO_MSG .
1519: If the user requests detailed version information, the verbose flag will be set.
1520: .It log_ttyin
1521: .Bd -literal -compact
1522: int (*log_ttyin)(const char *buf, unsigned int len);
1523: .Ed
1524: .Pp
1525: The
1526: .Fn log_ttyin
1527: function is called whenever data can be read from
1528: the user but before it is passed to the running command.
1529: This allows the plugin to reject data if it chooses to (for instance
1530: if the input contains banned content).
1531: Returns 1 if the data should be passed to the command, 0 if the data
1532: is rejected (which will terminate the command) or \-1 if an error occurred.
1533: .Pp
1534: The function arguments are as follows:
1535: .Bl -tag -width 4n
1536: .It buf
1537: The buffer containing user input.
1538: .It len
1539: The length of
1540: .Em buf
1541: in bytes.
1542: .El
1543: .It log_ttyout
1544: .Bd -literal -compact
1545: int (*log_ttyout)(const char *buf, unsigned int len);
1546: .Ed
1547: .Pp
1548: The
1549: .Fn log_ttyout
1550: function is called whenever data can be read from
1551: the command but before it is written to the user's terminal.
1552: This allows the plugin to reject data if it chooses to (for instance
1553: if the output contains banned content).
1554: Returns 1 if the data should be passed to the user, 0 if the data is rejected
1555: (which will terminate the command) or \-1 if an error occurred.
1556: .Pp
1557: The function arguments are as follows:
1558: .Bl -tag -width 4n
1559: .It buf
1560: The buffer containing command output.
1561: .It len
1562: The length of
1563: .Em buf
1564: in bytes.
1565: .El
1566: .It log_stdin
1567: .Bd -literal -compact
1568: int (*log_stdin)(const char *buf, unsigned int len);
1569: .Ed
1570: .Pp
1571: The
1572: .Fn log_stdin
1573: function is only used if the standard input does
1574: not correspond to a tty device.
1575: It is called whenever data can be read from the standard input but
1576: before it is passed to the running command.
1577: This allows the plugin to reject data if it chooses to
1578: (for instance if the input contains banned content).
1579: Returns 1 if the data should be passed to the command, 0 if the data is
1580: rejected (which will terminate the command) or \-1 if an error occurred.
1581: .Pp
1582: The function arguments are as follows:
1583: .Bl -tag -width 4n
1584: .It buf
1585: The buffer containing user input.
1586: .It len
1587: The length of
1588: .Em buf
1589: in bytes.
1590: .El
1591: .It log_stdout
1592: .Bd -literal -compact
1593: int (*log_stdout)(const char *buf, unsigned int len);
1594: .Ed
1595: .Pp
1596: The
1597: .Fn log_stdout
1598: function is only used if the standard output does not correspond
1599: to a tty device.
1600: It is called whenever data can be read from the command but before
1601: it is written to the standard output.
1602: This allows the plugin to reject data if it chooses to
1603: (for instance if the output contains banned content).
1604: Returns 1 if the data should be passed to the user, 0 if the data is
1605: rejected (which will terminate the command) or \-1 if an error occurred.
1606: .Pp
1607: The function arguments are as follows:
1608: .Bl -tag -width 4n
1609: .It buf
1610: The buffer containing command output.
1611: .It len
1612: The length of
1613: .Em buf
1614: in bytes.
1615: .El
1616: .It log_stderr
1617: .Bd -literal -compact
1618: int (*log_stderr)(const char *buf, unsigned int len);
1619: .Ed
1620: .Pp
1621: The
1622: .Fn log_stderr
1623: function is only used if the standard error does
1624: not correspond to a tty device.
1625: It is called whenever data can be read from the command but before it
1626: is written to the standard error.
1627: This allows the plugin to reject data if it chooses to
1628: (for instance if the output contains banned content).
1629: Returns 1 if the data should be passed to the user, 0 if the data is
1630: rejected (which will terminate the command) or \-1 if an error occurred.
1631: .Pp
1632: The function arguments are as follows:
1633: .Bl -tag -width 4n
1634: .It buf
1635: The buffer containing command output.
1636: .It len
1637: The length of
1638: .Em buf
1639: in bytes.
1640: .El
1641: .It register_hooks
1642: See the
1643: .Sx Policy plugin API
1644: section for a description of
1645: .Li register_hooks .
1646: .It deregister_hooks
1647: See the
1648: .Sx Policy plugin API
1649: section for a description of
1650: .Li deregister_hooks.
1651: .El
1652: .Pp
1653: .Em I/O Plugin Version Macros
1654: .Pp
1655: Same as for the
1656: .Sx Policy plugin API .
1657: .Ss Hook function API
1658: Beginning with plugin API version 1.2, it is possible to install
1659: hooks for certain functions called by the
1660: .Nm sudo
1661: front end.
1662: .Pp
1663: Currently, the only supported hooks relate to the handling of
1664: environment variables.
1665: Hooks can be used to intercept attempts to get, set, or remove
1666: environment variables so that these changes can be reflected in
1667: the version of the environment that is used to execute a command.
1668: A future version of the API will support hooking internal
1669: .Nm sudo
1670: front end functions as well.
1671: .Pp
1672: .Em Hook structure
1673: .Pp
1674: Hooks in
1675: .Nm sudo
1676: are described by the following structure:
1677: .Bd -literal
1678: typedef int (*sudo_hook_fn_t)();
1679:
1680: struct sudo_hook {
1681: int hook_version;
1682: int hook_type;
1683: sudo_hook_fn_t hook_fn;
1684: void *closure;
1685: };
1686: .Ed
1687: .Pp
1688: The
1689: .Li sudo_hook
1690: structure has the following fields:
1691: .Bl -tag -width 4n
1692: .It hook_version
1693: The
1694: .Li hook_version
1695: field should be set to
1696: .Dv SUDO_HOOK_VERSION .
1697: .It hook_type
1698: The
1699: .Li hook_type
1700: field may be one of the following supported hook types:
1701: .Bl -tag -width 4n
1702: .It Dv SUDO_HOOK_SETENV
1703: The C library
1704: .Xr setenv 3
1705: function.
1706: Any registered hooks will run before the C library implementation.
1707: The
1708: .Li hook_fn
1709: field should
1710: be a function that matches the following typedef:
1711: .Bd -literal
1712: typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1713: const char *value, int overwrite, void *closure);
1714: .Ed
1715: .Pp
1716: If the registered hook does not match the typedef the results are
1717: unspecified.
1718: .It Dv SUDO_HOOK_UNSETENV
1719: The C library
1720: .Xr unsetenv 3
1721: function.
1722: Any registered hooks will run before the C library implementation.
1723: The
1724: .Li hook_fn
1725: field should
1726: be a function that matches the following typedef:
1727: .Bd -literal
1728: typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1729: void *closure);
1730: .Ed
1731: .It Dv SUDO_HOOK_GETENV
1732: The C library
1733: .Xr getenv 3
1734: function.
1735: Any registered hooks will run before the C library implementation.
1736: The
1737: .Li hook_fn
1738: field should
1739: be a function that matches the following typedef:
1740: .Bd -literal
1741: typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1742: char **value, void *closure);
1743: .Ed
1744: .Pp
1745: If the registered hook does not match the typedef the results are
1746: unspecified.
1747: .It Dv SUDO_HOOK_PUTENV
1748: The C library
1749: .Xr putenv 3
1750: function.
1751: Any registered hooks will run before the C library implementation.
1752: The
1753: .Li hook_fn
1754: field should
1755: be a function that matches the following typedef:
1756: .Bd -literal
1757: typedef int (*sudo_hook_fn_putenv_t)(char *string,
1758: void *closure);
1759: .Ed
1760: .Pp
1761: If the registered hook does not match the typedef the results are
1762: unspecified.
1763: .El
1764: .It hook_fn
1765: sudo_hook_fn_t hook_fn;
1766: .Pp
1767: The
1768: .Li hook_fn
1769: field should be set to the plugin's hook implementation.
1770: The actual function arguments will vary depending on the
1771: .Li hook_type
1772: (see
1773: .Li hook_type
1774: above).
1775: In all cases, the
1776: .Li closure
1777: field of
1778: .Li struct sudo_hook
1779: is passed as the last function parameter.
1780: This can be used to pass arbitrary data to the plugin's hook implementation.
1781: .Pp
1782: The function return value may be one of the following:
1783: .Bl -tag -width 4n
1784: .It Dv SUDO_HOOK_RET_ERROR
1785: The hook function encountered an error.
1786: .It Dv SUDO_HOOK_RET_NEXT
1787: The hook completed without error, go on to the next hook (including
1788: the native implementation if applicable).
1789: For example, a
1790: .Xr getenv 3
1791: hook might return
1792: .Dv SUDO_HOOK_RET_NEXT
1793: if the specified variable was not found in the private copy of the environment.
1794: .It Dv SUDO_HOOK_RET_STOP
1795: The hook completed without error, stop processing hooks for this invocation.
1796: This can be used to replace the native implementation.
1797: For example, a
1798: .Li setenv
1799: hook that operates on a private copy of
1800: the environment but leaves
1801: .Li environ
1802: unchanged.
1803: .El
1804: .El
1805: .Pp
1806: Note that it is very easy to create an infinite loop when hooking
1807: C library functions.
1808: For example, a
1809: .Xr getenv 3
1810: hook that calls the
1811: .Xr snprintf 3
1812: function may create a loop if the
1813: .Xr snprintf 3
1814: implementation calls
1815: .Xr getenv 3
1816: to check the locale.
1817: To prevent this, you may wish to use a static variable in the hook
1818: function to guard against nested calls.
1819: For example:
1820: .Bd -literal
1821: static int in_progress = 0; /* avoid recursion */
1822: if (in_progress)
1823: return SUDO_HOOK_RET_NEXT;
1824: in_progress = 1;
1825: \&...
1826: in_progress = 0;
1827: return SUDO_HOOK_RET_STOP;
1828: .Ed
1829: .Pp
1830: .Em Hook API Version Macros
1831: .Bd -literal
1832: /* Hook API version major/minor */
1833: #define SUDO_HOOK_VERSION_MAJOR 1
1834: #define SUDO_HOOK_VERSION_MINOR 0
1835: #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1836: #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e
1837: SUDO_HOOK_VERSION_MINOR)
1838:
1839: /* Getters and setters for hook API version */
1840: #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1841: #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1842: #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e
1843: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1844: } while(0)
1845: #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e
1846: *(vp) = (*(vp) & 0xffff0000) | (n); \e
1847: } while(0)
1848: .Ed
1849: .Ss Conversation API
1850: If the plugin needs to interact with the user, it may do so via the
1851: .Fn conversation
1852: function.
1853: A plugin should not attempt to read directly from the standard input
1854: or the user's tty (neither of which are guaranteed to exist).
1855: The caller must include a trailing newline in
1856: .Li msg
1857: if one is to be printed.
1858: .Pp
1859: A
1860: .Fn printf Ns No -style
1861: function is also available that can be used to display informational
1862: or error messages to the user, which is usually more convenient for
1863: simple messages where no use input is required.
1864: .Bd -literal
1865: struct sudo_conv_message {
1866: #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1867: #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1868: #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1869: #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1870: #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1871: #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1872: #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1873: int msg_type;
1874: int timeout;
1875: const char *msg;
1876: };
1877:
1878: struct sudo_conv_reply {
1879: char *reply;
1880: };
1881:
1882: typedef int (*sudo_conv_t)(int num_msgs,
1883: const struct sudo_conv_message msgs[],
1884: struct sudo_conv_reply replies[]);
1885:
1886: typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1887: .Ed
1888: .Pp
1889: Pointers to the
1890: .Fn conversation
1891: and
1892: .Fn printf Ns No -style
1893: functions are passed
1894: in to the plugin's
1895: .Fn open
1896: function when the plugin is initialized.
1897: .Pp
1898: To use the
1899: .Fn conversation
1900: function, the plugin must pass an array of
1901: .Li sudo_conv_message
1902: and
1903: .Li sudo_conv_reply
1904: structures.
1905: There must be a
1906: .Li struct sudo_conv_message
1907: and
1908: .Li struct sudo_conv_reply
1909: for
1910: each message in the conversation.
1911: The plugin is responsible for freeing the reply buffer filled in to the
1912: .Li struct sudo_conv_reply ,
1913: if any.
1914: .Pp
1915: The
1916: .Fn printf Ns No -style
1917: function uses the same underlying mechanism as the
1918: .Fn conversation
1919: function but only supports
1920: .Dv SUDO_CONV_INFO_MSG ,
1921: .Dv SUDO_CONV_ERROR_MSG
1922: and
1923: .Dv SUDO_CONV_DEBUG_MSG
1924: for the
1925: .Em msg_type
1926: parameter.
1927: It can be more convenient than using the
1928: .Fn conversation
1929: function if no user reply is needed and supports standard
1930: .Fn printf
1931: escape sequences.
1932: .Pp
1933: Unlike,
1934: .Dv SUDO_CONV_INFO_MSG
1935: and
1936: Dv SUDO_CONV_ERROR_MSG ,
1937: messages
1938: sent with the
1939: .Dv SUDO_CONV_DEBUG_MSG
1940: .Em msg_type
1941: are not directly
1942: user-visible.
1943: Instead, they are logged to the file specified in the
1944: .Li Debug
1945: statement (if any) in the
1946: .Pa @sysconfdir@/sudo.conf
1947: .Pp
1948: file.
1949: This allows a plugin to log debugging information and is intended
1950: to be used in conjunction with the
1951: .Em debug_flags
1952: setting.
1953: .Pp
1954: See the sample plugin for an example of the
1955: .Fn conversation
1956: function usage.
1957: .Ss Sudoers group plugin API
1958: The
1959: .Em sudoers
1960: module supports a plugin interface to allow non-Unix
1961: group lookups.
1962: This can be used to query a group source other than the standard Unix
1963: group database.
1964: A sample group plugin is bundled with
1965: .Nm sudo
1966: that implements file-based lookups.
1967: Third party group plugins include a QAS AD plugin available from Quest Software.
1968: .Pp
1969: A group plugin must declare and populate a
1970: .Li sudoers_group_plugin
1971: struct in the global scope.
1972: This structure contains pointers to the functions that implement plugin
1973: initialization, cleanup and group lookup.
1974: .Bd -literal
1975: struct sudoers_group_plugin {
1976: unsigned int version;
1977: int (*init)(int version, sudo_printf_t sudo_printf,
1978: char *const argv[]);
1979: void (*cleanup)(void);
1980: int (*query)(const char *user, const char *group,
1981: const struct passwd *pwd);
1982: };
1983: .Ed
1984: .Pp
1985: The
1986: .Li sudoers_group_plugin
1987: struct has the following fields:
1988: .Bl -tag -width 4n
1989: .It version
1990: The
1991: .Li version
1992: field should be set to GROUP_API_VERSION.
1993: .Pp
1994: This allows
1995: .Em sudoers
1996: to determine the API version the group plugin
1997: was built against.
1998: .It init
1999: .Bd -literal -compact
2000: int (*init)(int version, sudo_printf_t plugin_printf,
2001: char *const argv[]);
2002: .Ed
2003: .Pp
2004: The
2005: .Fn init
2006: function is called after
2007: .Em sudoers
2008: has been parsed but
2009: before any policy checks.
2010: It returns 1 on success, 0 on failure (or if the plugin is not configured),
2011: and \-1 if a error occurred.
2012: If an error occurs, the plugin may call the
2013: .Fn plugin_printf
2014: function with
2015: .Dv SUDO_CONF_ERROR_MSG
2016: to present additional error information
2017: to the user.
2018: .Pp
2019: The function arguments are as follows:
2020: .Bl -tag -width 4n
2021: .It version
2022: The version passed in by
2023: .Em sudoers
2024: allows the plugin to determine the
2025: major and minor version number of the group plugin API supported by
2026: .Em sudoers .
2027: .It plugin_printf
2028: A pointer to a
2029: .Fn printf Ns No -style
2030: function that may be used to display informational or error message to the user.
2031: Returns the number of characters printed on success and \-1 on failure.
2032: .It argv
2033: A
2034: .Dv NULL Ns No -terminated
2035: array of arguments generated from the
2036: .Em group_plugin
2037: option in
2038: .Em sudoers .
2039: If no arguments were given,
2040: .Em argv
2041: will be
2042: .Dv NULL .
2043: .El
2044: .It cleanup
2045: .Bd -literal -compact
2046: void (*cleanup)();
2047: .Ed
2048: .Pp
2049: The
2050: .Fn cleanup
2051: function is called when
2052: .Em sudoers
2053: has finished its
2054: group checks.
2055: The plugin should free any memory it has allocated and close open file handles.
2056: .It query
2057: .Bd -literal -compact
2058: int (*query)(const char *user, const char *group,
2059: const struct passwd *pwd);
2060: .Ed
2061: .Pp
2062: The
2063: .Fn query
2064: function is used to ask the group plugin whether
2065: .Em user
2066: is a member of
2067: .Em group .
2068: .Pp
2069: The function arguments are as follows:
2070: .Bl -tag -width 4n
2071: .It user
2072: The name of the user being looked up in the external group database.
2073: .It group
2074: The name of the group being queried.
2075: .It pwd
2076: The password database entry for
2077: .Em user ,
2078: if any.
2079: If
2080: .Em user
2081: is not
2082: present in the password database,
2083: .Em pwd
2084: will be
2085: .Dv NULL .
2086: .El
2087: .El
2088: .Pp
2089: .Em Group API Version Macros
2090: .Bd -literal
2091: /* Sudoers group plugin version major/minor */
2092: #define GROUP_API_VERSION_MAJOR 1
2093: #define GROUP_API_VERSION_MINOR 0
2094: #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
2095: GROUP_API_VERSION_MINOR)
2096:
2097: /* Getters and setters for group version */
2098: #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
2099: #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
2100: #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
2101: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2102: } while(0)
2103: #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
2104: *(vp) = (*(vp) & 0xffff0000) | (n); \e
2105: } while(0)
2106: .Ed
2107: .Sh PLUGIN API CHANGELOG
2108: The following revisions have been made to the Sudo Plugin API.
2109: .Bl -tag -width 4n
2110: .It Version 1.0
2111: Initial API version.
2112: .It Version 1.1
2113: The I/O logging plugin's
2114: .Fn open
2115: function was modified to take the
2116: .Li command_info
2117: list as an argument.
2118: .It Version 1.2
2119: The Policy and I/O logging plugins'
2120: .Fn open
2121: functions are now passed
2122: a list of plugin options if any are specified in
2123: .Pa @sysconfdir@/sudo.conf .
2124: .Pp
2125: A simple hooks API has been introduced to allow plugins to hook in to the
2126: system's environment handling functions.
2127: .Pp
2128: The
2129: .Li init_session
2130: Policy plugin function is now passed a pointer
2131: to the user environment which can be updated as needed.
2132: This can be used to merge in environment variables stored in the PAM
2133: handle before a command is run.
2134: .El
2135: .Sh SEE ALSO
2136: .Xr sudoers @mansectform@ ,
2137: .Xr sudo @mansectsu@
2138: .Sh BUGS
2139: If you feel you have found a bug in
2140: .Nm sudo ,
2141: please submit a bug report at http://www.sudo.ws/sudo/bugs/
2142: .Sh SUPPORT
2143: Limited free support is available via the sudo-users mailing list,
2144: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
2145: search the archives.
2146: .Sh DISCLAIMER
2147: .Nm sudo
2148: is provided
2149: .Dq AS IS
2150: and any express or implied warranties, including, but not limited
2151: to, the implied warranties of merchantability and fitness for a
2152: particular purpose are disclaimed.
2153: See the LICENSE file distributed with
2154: .Nm sudo
2155: or http://www.sudo.ws/sudo/license.html for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo_plugin.mdoc.in 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