1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
NOTE: the Sudo auth API is subject to change
Purpose: to provide a simple API for authentication methods that
encapsulates things nicely without turning into a maze
of #ifdef's
The sudo_auth struct looks like this:
typedef struct sudo_auth {
unsigned int flags; /* various flags, see below */
int status; /* status from verify routine */
char *name; /* name of the method in string form */
void *data; /* method-specific data pointer */
int (*init)(struct passwd *pw, sudo_auth *auth);
int (*setup)(struct passwd *pw, char **prompt, sudo_auth *auth);
int (*verify)(struct passwd *pw, const char *p, sudo_auth *auth, struct sudo_conv_callback *callback);
int (*approval)(struct passwd *pw, sudo_auth *auth);
int (*cleanup)(struct passwd *pw, sudo_auth *auth, bool force);
int (*begin_session)(struct passwd *pw, char **user_env[], struct sudo_auth *auth);
int (*end_session)(struct passwd *pw, struct sudo_auth *auth);
} sudo_auth;
The variables in the struct are as follows:
flags Bitwise binary flags, see below.
status Contains the return value from the last run of
the "verify" function. Starts out as AUTH_FAILURE.
name The name of the authentication method as a C string.
data A pointer to method-specific data. This is passed to
all the functions of an auth method and is usually
initialized in the "init" or "setup" routines.
Possible values of sudo_auth.flags:
FLAG_DISABLED Set if an "init" or "setup" function fails.
FLAG_STANDALONE If set, this indicates that the method must
be the only auth method configured, and that
it will prompt for the password itself.
FLAG_ONEANDONLY If set, this indicates that the method is the
only one in use. Can be used by auth functions
to determine whether to return a fatal or nonfatal
error.
FLAG_NONINTERACTIVE If set, this indicates that the user invoked
sudo with the -n option and no user interaction
is allowed.
The member functions can return the following values:
AUTH_SUCCESS Function succeeded. For a ``verify'' function
this means the user correctly authenticated.
AUTH_FAILURE Function failed. If this is an ``init'' or
``setup'' routine, the auth method will be
marked as !configured.
AUTH_ERROR A fatal error occurred. The routine should have
written an error message to stderr and optionally
sent mail to the administrator. When verify_user()
receives AUTH_ERROR from an auth function it stops
authenticating and returns an error.
AUTH_INTR An attempt to read the password read was interrupted.
Usually this means the user entered ^C at the
password prompt.
AUTH_NONINTERACTIVE Function failed because user interaction was
required but sudo was run in non-interactive
mode.
The functions in the struct are as follows:
int init(struct passwd *pw, sudo_auth *auth)
Function to do any one-time initialization for the auth
method. All of the "init" functions are run before anything
else.
int setup(struct passwd *pw, char **prompt, sudo_auth *auth)
Function to do method-specific setup. All the "setup"
routines are run before any of the "verify" routines. A
pointer to the prompt string may be used to add method-specific
info to the prompt.
int verify(struct passwd *pw, char *p, sudo_auth *auth, struct sudo_conv_callback *callback)
Function to do user verification for this auth method. For
standalone auth methods ``p'' is the prompt string. For
normal auth methods, ``p'' is the password the user entered.
The callback should be passed to auth_getpass() to allow sudoers
to unlock the ticket file when sudo is suspended.
Note that standalone auth methods are responsible for
rerading the password themselves.
int approval(struct passwd *pw, struct sudo_auth *auth)
Function to perform account management and approval *after*
the user has authenticated successfully. This function may
check for expired accounts, perform time of day restrictions, etc.
For PAM, this calls pam_acct_mgmt(). For BSD auth, it calls
auth_approval().
int cleanup(struct passwd *pw, sudo_auth *auth, bool force)
Function to do per-auth method cleanup. This is only run
at the end of the authentication process, after the user
has completely failed or succeeded to authenticate.
The ``auth->status'' variable contains the result of the
last authentication attempt which may be interesting.
If the force flag is set, cleanup should happen immediately.
int begin_session(struct passwd *pw, char **user_env[], struct sudo_auth *auth)
Function to begin a user session. This is used for session handling
in PAM and SIA.
int end_session(struct passwd *pw, struct sudo_auth *auth)
Function to end a user session. This is used for session handling
in PAM and SIA.
A note about standalone methods. Some authentication methods can't
coexist with any others. This may be because they encapsulate other
methods (pam, sia) or because they have a special way of interacting
with the user (securid).
Adding a new authentication method:
Each method should live in its own file. Add prototypes for the functions
in sudo_auth.h.
Add the method to the ``auth_switch'' in sudo_auth.c. Note that
standalone methods must go first. If ``fooauth'' is a normal auth
method, its entry would look like:
#ifdef HAVE_FOOAUTH
AUTH_ENTRY("foo", 0, foo_init, foo_setup, foo_verify,
foo_cleanup, foo_begin_session, foo_end_session)
#endif
If this is a standalone method, it would be:
#ifdef HAVE_FOOAUTH
AUTH_ENTRY("foo", FLAG_STANDALONE, foo_init, foo_setup, foo_verify,
foo_cleanup, foo_begin_session, foo_end_session)
#endif
If the method needs to run as the user, not root, add FLAG_USER to
the second argument in the AUTH_ENTRY line. If you don't have an
init/setup/cleanup/begin/end routine, just use a NULL for that
field.
|
