Return to API CVS log

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

Annotation of embedaddon/sudo/plugins/sudoers/auth/API, revision 1.1.1.1

1.1       misho       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.  (If log_error()
                     61:                        is called to do this, the NO_EXIT flag must be used.)
                     62:                        When verify_user() gets AUTH_FATAL from an auth
                     63:                        function it does an exit(1).
                     64: 
                     65: The functions in the struct are as follows:
                     66: 
                     67:     int init(struct passwd *pw, sudo_auth *auth)
                     68:         Function to do any one-time initialization for the auth
                     69:         method.  All of the "init" functions are run before anything
                     70:         else.
                     71: 
                     72:     int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
                     73:         Function to do method-specific setup.  All the "setup"
                     74:         routines are run before any of the "verify" routines.  A
                     75:         pointer to the prompt string may be used to add method-specific
                     76:         info to the prompt.
                     77: 
                     78:     int verify(struct passwd *pw, char *p, sudo_auth *auth)
                     79:         Function to do user verification for this auth method.  For
                     80:         standalone auth methods ``p'' is the prompt string.  For
                     81:         normal auth methods, ``p'' is the password the user entered.
                     82:         Note that standalone auth methods are responsible for
                     83:         rerading the password themselves.
                     84: 
                     85:     int cleanup(struct passwd *pw, sudo_auth *auth)
                     86:         Function to do per-auth method cleanup.  This is only run
                     87:         at the end of the authentication process, after the user
                     88:         has completely failed or succeeded to authenticate.
                     89:        The ``auth->status'' variable contains the result of the
                     90:        last authentication attempt which may be interesting.
                     91: 
                     92: A note about standalone methods.  Some authentication methods can't
                     93: coexist with any others.  This may be because they encapsulate other
                     94: methods (pam, sia) or because they have a special way of interacting
                     95: with the user (securid).
                     96: 
                     97: Adding a new authentication method:
                     98: 
                     99: Each method should live in its own file.  Add prototypes for the functions
                    100: in sudo_auth.h.
                    101: 
                    102: Add the method to the ``auth_switch'' in sudo_auth.c.  Note that
                    103: standalone methods must go first.  If ``fooauth'' is a normal auth
                    104: method, its entry would look like:
                    105: 
                    106: #ifdef HAVE_FOOAUTH
                    107: AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
                    108:     foo_cleanup, foo_begin_session, foo_end_session)
                    109: #endif
                    110: 
                    111: If this is a standalone method, it would be:
                    112: 
                    113: #ifdef HAVE_FOOAUTH
                    114: AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
                    115:     foo_cleanup, foo_begin_session, foo_end_session)
                    116: #endif
                    117: 
                    118: If the method needs to run as the user, not root, add FLAG_USER to
                    119: the second argument in the  AUTH_ENTRY line.  If you don't have an
                    120: init/setup/cleanup/begin/end routine, just use a NULL for that
                    121: field.