"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
    2 
    3 Purpose: to provide a simple API for authentication methods that
    4          encapsulates things nicely without turning into a maze
    5 	 of #ifdef's
    6 
    7 The sudo_auth struct looks like this:
    8 
    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 */
   14 
   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;
   23 
   24 The variables in the struct are as follows:
   25     flags	Bitwise binary flags, see below.
   26 
   27     status	Contains the return value from the last run of
   28 		the "verify" function.  Starts out as AUTH_FAILURE.
   29 
   30     name	The name of the authentication method as a C string.
   31 
   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.
   35 
   36 Possible values of sudo_auth.flags:
   37     FLAG_DISABLED	Set if an "init" or "setup" function fails.
   38 
   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.
   42 
   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.
   47 
   48     FLAG_NONINTERACTIVE	If set, this indicates that the user invoked
   49 			sudo with the -n option and no user interaction
   50 			is allowed.
   51 
   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.
   55 
   56     AUTH_FAILURE	Function failed.  If this is an ``init'' or
   57 			``setup'' routine, the auth method will be
   58 			marked as !configured.
   59 
   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).
   65 
   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.
   69 
   70     AUTH_NONINTERACTIVE	Function failed because user interaction was
   71 			required but sudo was run in non-interactive
   72 			mode.
   73 
   74 The functions in the struct are as follows:
   75 
   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.
   80 
   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.
   86 
   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.
   95 
   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().
  102 
  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.
  110 
  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.
  114 
  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.
  118 
  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).
  123 
  124 Adding a new authentication method:
  125 
  126 Each method should live in its own file.  Add prototypes for the functions
  127 in sudo_auth.h.
  128 
  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:
  132 
  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
  137 
  138 If this is a standalone method, it would be:
  139 
  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
  144 
  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.