"Fossies" - the Fresh Open Source Software Archive

Member "sudo-1.9.11p3/plugins/sudoers/auth/API" (12 Jun 2022, 6037 Bytes) of package /linux/misc/sudo-1.9.11p3.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 NOTE: the Sudo auth API is subject to change
    3 Purpose: to provide a simple API for authentication methods that
    4          encapsulates things nicely without turning into a maze
    5 	 of #ifdef's
    7 The sudo_auth struct looks like this:
    9 typedef struct sudo_auth {
   10     int flags;                  /* various flags, see below */
   11     int status;                 /* status from verify routine */
   12     char *name;			/* name of the method in string form */
   13     void *data;                 /* method-specific data pointer */
   15     int (*init)(struct passwd *pw, sudo_auth *auth);
   16     int (*setup)(struct passwd *pw, char **prompt, sudo_auth *auth);
   17     int (*verify)(struct passwd *pw, char *p, sudo_auth *auth, struct sudo_conv_callback *callback);
   18     int (*approval)(struct passwd *pw, sudo_auth *auth);
   19     int (*cleanup)(struct passwd *pw, sudo_auth *auth, bool force);
   20     int (*begin_session)(struct passwd *pw, char **user_env[], struct sudo_auth *auth);
   21     int (*end_session)(struct passwd *pw, struct sudo_auth *auth);
   22 } sudo_auth;
   24 The variables in the struct are as follows:
   25     flags	Bitwise binary flags, see below.
   27     status	Contains the return value from the last run of
   28 		the "verify" function.  Starts out as AUTH_FAILURE.
   30     name	The name of the authentication method as a C string.
   32     data	A pointer to method-specific data.  This is passed to
   33 		all the functions of an auth method and is usually
   34 		initialized in the "init" or "setup" routines.
   36 Possible values of sudo_auth.flags:
   37     FLAG_DISABLED	Set if an "init" or "setup" function fails.
   39     FLAG_STANDALONE	If set, this indicates that the method must
   40 			be the only auth method configured, and that
   41 			it will prompt for the password itself.
   43     FLAG_ONEANDONLY	If set, this indicates that the method is the
   44 			only one in use.  Can be used by auth functions
   45 			to determine whether to return a fatal or nonfatal
   46 			error.
   48     FLAG_NONINTERACTIVE	If set, this indicates that the user invoked
   49 			sudo with the -n option and no user interaction
   50 			is allowed.
   52 The member functions can return the following values:
   53     AUTH_SUCCESS	Function succeeded.  For a ``verify'' function
   54 			this means the user correctly authenticated.
   56     AUTH_FAILURE	Function failed.  If this is an ``init'' or
   57 			``setup'' routine, the auth method will be
   58 			marked as !configured.
   60     AUTH_FATAL		A fatal error occurred.  The routine should have
   61 			written an error message to stderr and optionally
   62 			sent mail to the administrator.
   63 			When verify_user() gets AUTH_FATAL from an auth
   64 			function it does an exit(1).
   66     AUTH_INTR		An attempt to read the password read was interrupted.
   67 			Usually this means the user entered ^C at the
   68 			password prompt.
   70     AUTH_NONINTERACTIVE	Function failed because user interaction was
   71 			required but sudo was run in non-interactive
   72 			mode.
   74 The functions in the struct are as follows:
   76     int init(struct passwd *pw, sudo_auth *auth)
   77         Function to do any one-time initialization for the auth
   78         method.  All of the "init" functions are run before anything
   79         else.
   81     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
   82         Function to do method-specific setup.  All the "setup"
   83         routines are run before any of the "verify" routines.  A
   84         pointer to the prompt string may be used to add method-specific
   85         info to the prompt.
   87     int verify(struct passwd *pw, char *p, sudo_auth *auth, struct sudo_conv_callback *callback)
   88         Function to do user verification for this auth method.  For
   89         standalone auth methods ``p'' is the prompt string.  For
   90         normal auth methods, ``p'' is the password the user entered.
   91 	The callback should be passed to auth_getpass() to allow sudoers
   92 	to unlock the ticket file when sudo is suspended.
   93         Note that standalone auth methods are responsible for
   94         rerading the password themselves.
   96     int approval(struct passwd *pw, struct sudo_auth *auth)
   97 	Function to perform account management and approval *after*
   98 	the user has authenticated successfully.  This function may
   99 	check for expired accounts, perform time of day restrictions, etc.
  100 	For PAM, this calls pam_acct_mgmt().  For BSD auth, it calls
  101 	auth_approval().
  103     int cleanup(struct passwd *pw, sudo_auth *auth, bool force)
  104         Function to do per-auth method cleanup.  This is only run
  105         at the end of the authentication process, after the user
  106         has completely failed or succeeded to authenticate.
  107 	The ``auth->status'' variable contains the result of the
  108 	last authentication attempt which may be interesting.
  109 	If the force flag is set, cleanup should happen immediately.
  111     int begin_session(struct passwd *pw, char **user_env[], struct sudo_auth *auth)
  112 	Function to begin a user session.  This is used for session handling
  113 	in PAM and SIA.
  115     int end_session(struct passwd *pw, struct sudo_auth *auth)
  116 	Function to end a user session.  This is used for session handling
  117 	in PAM and SIA.
  119 A note about standalone methods.  Some authentication methods can't
  120 coexist with any others.  This may be because they encapsulate other
  121 methods (pam, sia) or because they have a special way of interacting
  122 with the user (securid).
  124 Adding a new authentication method:
  126 Each method should live in its own file.  Add prototypes for the functions
  127 in sudo_auth.h.
  129 Add the method to the ``auth_switch'' in sudo_auth.c.  Note that
  130 standalone methods must go first.  If ``fooauth'' is a normal auth
  131 method, its entry would look like:
  133 #ifdef HAVE_FOOAUTH
  134 AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
  135     foo_cleanup, foo_begin_session, foo_end_session)
  136 #endif
  138 If this is a standalone method, it would be:
  140 #ifdef HAVE_FOOAUTH
  141 AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
  142     foo_cleanup, foo_begin_session, foo_end_session)
  143 #endif
  145 If the method needs to run as the user, not root, add FLAG_USER to
  146 the second argument in the  AUTH_ENTRY line.  If you don't have an
  147 init/setup/cleanup/begin/end routine, just use a NULL for that
  148 field.