1 NOTE: the Sudo auth API is subject to change
3 Purpose: to provide a simple API for authentication methods that
4 encapsulates things nicely without turning into a maze
7 The sudo_auth struct looks like this:
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 */
15 int (*init)(struct passwd *pw, char **prompt, 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);
23 The variables in the struct are as follows:
24 flags Bitwise binary flags, see below.
26 status Contains the return value from the last run of
27 the "verify" function. Starts out as AUTH_FAILURE.
29 name The name of the authentication method as a C string.
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.
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.
39 FLAG_DISABLED Set if an "init" or "setup" function fails.
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.
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
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.
54 AUTH_FAILURE Function failed. If this is an ``init'' or
55 ``setup'' routine, the auth method will be
56 marked as !configured.
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).
65 The functions in the struct are as follows:
67 int init(struct passwd *pw, char **prompt, 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. A pointer to the prompt string may be used to add
71 method-specific info to the prompt.
73 int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
74 Function to do method-specific setup. All the "setup"
75 routines are run before any of the "verify" routines. A
76 pointer to the prompt string may be used to add method-specific
79 int verify(struct passwd *pw, char *p, sudo_auth *auth)
80 Function to do user verification for this auth method. For
81 standalone auth methods ``p'' is the prompt string. For
82 normal auth methods, ``p'' is the password the user entered.
83 Note that standalone auth methods are responsible for
84 rerading the password themselves.
86 int cleanup(struct passwd *pw, sudo_auth *auth)
87 Function to do per-auth method cleanup. This is only run
88 at the end of the authentication process, after the user
89 has completely failed or succeeded to authenticate.
90 The ``auth->status'' variable contains the result of the
91 last authentication attempt which may be interesting.
93 A note about standalone methods. Some authentication methods can't
94 coexist with any others. This may be because they encapsulate other
95 methods (pam, sia) or because they have a special way of interacting
96 with the user (securid).
98 Adding a new authentication method:
100 Each method should live in its own file. Add prototypes for the functions
103 Add the method to the ``auth_switch'' in sudo_auth.c. Note that
104 standalone methods must go first. If ``fooauth'' is a normal auth
105 method, its entry would look like:
108 AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
109 foo_cleanup, foo_begin_session, foo_end_session)
112 If this is a standalone method, it would be:
115 AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
116 foo_cleanup, foo_begin_session, foo_end_session)
119 If the method needs to run as the user, not root, add FLAG_USER to
120 the second argument in the AUTH_ENTRY line. If you don't have an
121 init/setup/cleanup/begin/end routine, just use a NULL for that