62c21d063e613596e840285c37f69249fed3ee3a
[debian/sudo] / plugins / sudoers / auth / API
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.