Annotation of embedaddon/sudo/plugins/sudoers/auth/API, revision 1.1.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>