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