1NOTE: the Sudo auth API is subject to change
2
3Purpose: to provide a simple API for authentication methods that
4         encapsulates things nicely without turning into a maze
5	 of #ifdef's
6
7The sudo_auth struct looks like this:
8
9typedef struct sudo_auth {
10    short flags;                /* various flags, see below */
11    short 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) __P((struct passwd *pw, char **prompt, sudo_auth *auth));
16    int (*setup) __P((struct passwd *pw, char **prompt, sudo_auth *auth));
17    int (*verify) __P((struct passwd *pw, char *p, sudo_auth *auth));
18    int (*cleanup) __P((struct passwd *pw, sudo_auth *auth));
19} sudo_auth;
20
21The variables in the struct are as follows:
22    flags	Bitwise binary flags, see below.
23
24    status	Contains the return value from the last run of
25		the "verify" function.  Starts out as AUTH_FAILURE.
26
27    name	The name of the authentication method as a C string.
28
29    data	A pointer to method-specific data.  This is passed to
30		all the functions of an auth method and is usually
31		initialized in the "init" or "setup" routines.
32
33Possible values of sudo_auth.flags:
34    FLAG_USER		Whether or not the auth functions should run with
35			the euid of the invoking user instead of 0.
36
37    FLAG_CONFIGURED	If set then the auth method is assumed to have been
38			configured successfully.  All auth methods start out
39			with this set.  If an "init" or "setup" function
40			fails, this bit is cleared.
41
42    FLAG_ONEANDONLY	If set, this indicates that the method is the
43			only one in use.  Can be used by auth functions
44			to determine whether to return a fatal or nonfatal
45			error.
46
47The member functions can return the following values:
48    AUTH_SUCCESS	Function succeeded.  For a ``verify'' function
49			this means the user correctly authenticated.
50
51    AUTH_FAILURE	Function failed.  If this is an ``init'' or
52			``setup'' routine, the auth method will be
53			marked as !configured.
54
55    AUTH_FATAL		A fatal error occurred.  The routine should have
56			written an error message to stderr and optionally
57			sent mail to the administrator.  (If log_error()
58			is called to do this, the NO_EXIT flag must be used.)
59			When verify_user() gets AUTH_FATAL from an auth
60			function it does an exit(1).
61
62The functions in the struct are as follows:
63
64    int init(struct passwd *pw, char **prompt, sudo_auth *auth)
65        Function to do any one-time initialization for the auth
66        method.  All of the "init" functions are run before anything
67        else.  A pointer to the prompt string may be used to add
68        method-specific info to the prompt.
69
70    int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
71        Function to do method-specific setup.  All the "setup"
72        routines are run before any of the "verify" routines.  A
73        pointer to the prompt string may be used to add method-specific
74        info to the prompt.
75
76    int verify(struct passwd *pw, char *p, sudo_auth *auth)
77        Function to do user verification for this auth method.  For
78        standalone auth methods ``p'' is the prompt string.  For
79        normal auth methods, ``p'' is the password the user entered.
80        Note that standalone auth methods are responsible for
81        rerading the password themselves.
82
83    int cleanup(struct passwd *pw, sudo_auth *auth)
84        Function to do per-auth method cleanup.  This is only run
85        at the end of the authentication process, after the user
86        has completely failed or succeeded to authenticate.
87	The ``auth->status'' variable contains the result of the
88	last authentication attempt which may be interesting.
89
90A note about standalone methods.  Some authentication methods can't
91coexist with any others.  This may be because they encapsulate other
92methods (pam, sia) or because they have a special way of interacting
93with the user (securid).
94
95Adding a new authentication method:
96
97Each method should live in its own file.  Add prototypes for the functions
98in sudo_auth.h.
99
100If this is a standalone method, add it to the standalone #if cascade
101in sudo_auth.h.  For instance, for a method, ``fooauth'', add:
102
103#elif defined(HAVE_FOOAUTH)
104#  define AUTH_STANDALONE \
105        AUTH_ENTRY(0, "foo", \
106	    foo_init, foo_setup, foo_verify, foo_cleanup)
107
108If the method needs to run as the user, not root, replace the first
109parameter to AUTH_ENTRY (0) with FLAG_USER.  If you don't have a
110init/setup/cleanup routine, just use a NULL for that field.
111
112For a normal authentication method, add it to the ``auth_switch'' in
113sudo_auth.c.  If ``fooauth'' is a normal auth method, its entry
114would look like:
115
116#  ifdef HAVE_FOOAUTH
117    AUTH_ENTRY(0, "foo", foo_init, foo_setup, foo_verify, foo_cleanup)
118#  endif
119
120Again, if the method doesn't need to run as root, replace the 0 with
121FLAG_USER.  Likewise, if you don't have a init/setup/cleanup routine,
122just use a NULL for that field.
123
124NOTE:  You should not make a method both ``standalone'' and
125       ``normal''.  Just use the --without-passwd configure argument
126       to disable passwd/shadow file checking and then have your
127       auth routines check the FLAG_ONEANDONLY flag to see if
128       they are running standalone and act accordingly.
129