summaryrefslogtreecommitdiffstats
path: root/plugins/sudoers/auth/API
blob: 9d588277d4be2d97576a0937789677a914392a12 (plain)
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
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 {
    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, 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.

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_FATAL		A fatal error occurred.  The routine should have
			written an error message to stderr and optionally
			sent mail to the administrator.
			When verify_user() gets AUTH_FATAL from an auth
			function it does an exit(1).

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.