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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>