Return to API CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / plugins / sudoers / auth

1.8.7

    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);
   18:     int (*cleanup)(struct passwd *pw, sudo_auth *auth);
   19:     int (*begin_session)(struct passwd *pw, sudo_auth *auth);
   20:     int (*end_session)(sudo_auth *auth);
   21: } sudo_auth;
   22: 
   23: The variables in the struct are as follows:
   24:     flags	Bitwise binary flags, see below.
   25: 
   26:     status	Contains the return value from the last run of
   27: 		the "verify" function.  Starts out as AUTH_FAILURE.
   28: 
   29:     name	The name of the authentication method as a C string.
   30: 
   31:     data	A pointer to method-specific data.  This is passed to
   32: 		all the functions of an auth method and is usually
   33: 		initialized in the "init" or "setup" routines.
   34: 
   35: Possible values of sudo_auth.flags:
   36:     FLAG_USER		Whether or not the auth functions should run with
   37: 			the euid of the invoking user instead of 0.
   38: 
   39:     FLAG_DISABLED	Set if an "init" or "setup" function fails.
   40: 
   41:     FLAG_STANDALONE	If set, this indicates that the method must
   42: 			be the only auth method configured, and that
   43: 			it will prompt for the password itself.
   44: 
   45:     FLAG_ONEANDONLY	If set, this indicates that the method is the
   46: 			only one in use.  Can be used by auth functions
   47: 			to determine whether to return a fatal or nonfatal
   48: 			error.
   49: 
   50: The member functions can return the following values:
   51:     AUTH_SUCCESS	Function succeeded.  For a ``verify'' function
   52: 			this means the user correctly authenticated.
   53: 
   54:     AUTH_FAILURE	Function failed.  If this is an ``init'' or
   55: 			``setup'' routine, the auth method will be
   56: 			marked as !configured.
   57: 
   58:     AUTH_FATAL		A fatal error occurred.  The routine should have
   59: 			written an error message to stderr and optionally
   60: 			sent mail to the administrator.
   61: 			When verify_user() gets AUTH_FATAL from an auth
   62: 			function it does an exit(1).
   63: 
   64: The functions in the struct are as follows:
   65: 
   66:     int init(struct passwd *pw, sudo_auth *auth)
   67:         Function to do any one-time initialization for the auth
   68:         method.  All of the "init" functions are run before anything
   69:         else.
   70: 
   71:     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
   72:         Function to do method-specific setup.  All the "setup"
   73:         routines are run before any of the "verify" routines.  A
   74:         pointer to the prompt string may be used to add method-specific
   75:         info to the prompt.
   76: 
   77:     int verify(struct passwd *pw, char *p, sudo_auth *auth)
   78:         Function to do user verification for this auth method.  For
   79:         standalone auth methods ``p'' is the prompt string.  For
   80:         normal auth methods, ``p'' is the password the user entered.
   81:         Note that standalone auth methods are responsible for
   82:         rerading the password themselves.
   83: 
   84:     int cleanup(struct passwd *pw, sudo_auth *auth)
   85:         Function to do per-auth method cleanup.  This is only run
   86:         at the end of the authentication process, after the user
   87:         has completely failed or succeeded to authenticate.
   88: 	The ``auth->status'' variable contains the result of the
   89: 	last authentication attempt which may be interesting.
   90: 
   91: A note about standalone methods.  Some authentication methods can't
   92: coexist with any others.  This may be because they encapsulate other
   93: methods (pam, sia) or because they have a special way of interacting
   94: with the user (securid).
   95: 
   96: Adding a new authentication method:
   97: 
   98: Each method should live in its own file.  Add prototypes for the functions
   99: in sudo_auth.h.
  100: 
  101: Add the method to the ``auth_switch'' in sudo_auth.c.  Note that
  102: standalone methods must go first.  If ``fooauth'' is a normal auth
  103: method, its entry would look like:
  104: 
  105: #ifdef HAVE_FOOAUTH
  106: AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
  107:     foo_cleanup, foo_begin_session, foo_end_session)
  108: #endif
  109: 
  110: If this is a standalone method, it would be:
  111: 
  112: #ifdef HAVE_FOOAUTH
  113: AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
  114:     foo_cleanup, foo_begin_session, foo_end_session)
  115: #endif
  116: 
  117: If the method needs to run as the user, not root, add FLAG_USER to
  118: the second argument in the  AUTH_ENTRY line.  If you don't have an
  119: init/setup/cleanup/begin/end routine, just use a NULL for that
  120: field.