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     ! 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.