|
1 #ifndef auth_h |
|
2 #define auth_h |
|
3 |
|
4 /* |
|
5 ** Copyright 1998 - 1999 Double Precision, Inc. See COPYING for |
|
6 ** distribution information. |
|
7 */ |
|
8 |
|
9 #if HAVE_CONFIG_H |
|
10 #include "config.h" |
|
11 #endif |
|
12 #include <sys/types.h> |
|
13 |
|
14 #ifdef __cplusplus |
|
15 extern "C" { |
|
16 #endif |
|
17 |
|
18 static const char auth_h_rcsid[]="$Id: auth.h,v 1.1 2000/04/13 17:55:05 bruce Exp $"; |
|
19 |
|
20 /* |
|
21 ** authcopyargv prepares the arguments to execv for a module that receives |
|
22 ** the next program to run, in a chain, via the command line. |
|
23 ** |
|
24 ** execv is documented to require a terminating null char **. The fact |
|
25 ** that argv is also null char ** is not always documented, and we can't |
|
26 ** assume that. |
|
27 ** |
|
28 ** authcopyargv receives the new argc/argv arguments, and allocates a |
|
29 ** new argv array. argv[0] is stripped of any path, and the original |
|
30 ** argv[0] is returned separately. |
|
31 */ |
|
32 |
|
33 extern char **authcopyargv(int, /* argc */ |
|
34 char **, /* argv */ |
|
35 char **); /* original argv[0] */ |
|
36 |
|
37 /* |
|
38 ** authchain - chain to the next authentication module via exec. |
|
39 ** |
|
40 ** Runs the next authentication module, and passes it a copy of the |
|
41 ** authentication request on file descriptor 3. |
|
42 ** |
|
43 ** authchain sets up a pipe on file descriptor 3, and forks. The parent |
|
44 ** runs the next authentication module. The child sends the authentication |
|
45 ** information down the pipe, and terminates. |
|
46 */ |
|
47 |
|
48 extern void authchain(int, /* argc */ |
|
49 char **, /* argv */ |
|
50 const char *); /* Authentication request */ |
|
51 |
|
52 /* |
|
53 ** The following functions are used by root to reset its user and group id |
|
54 ** to the authenticated user's. Various functions are provided to handle |
|
55 ** various situations. |
|
56 */ |
|
57 |
|
58 void authchangegroup(gid_t); /* Set the group id only. Also clear any |
|
59 ** auxiliary group ids */ |
|
60 |
|
61 void authchangeuidgid(uid_t, gid_t); |
|
62 /* Set both user id and group id. Also clear |
|
63 ** aux group ids */ |
|
64 |
|
65 void authchangeusername(const char *, const gid_t *); |
|
66 /* |
|
67 ** Set the userid to the indicate user's. If second argument is |
|
68 ** not null, it points to the groupid to set. If it's null, the |
|
69 ** group id is taken from the passwd file. Auxiliary IDs are set |
|
70 ** to any aux IDs set for the user in the group file. If there are |
|
71 ** no aux group IDs for the user, any AUX ids are cleared. |
|
72 */ |
|
73 |
|
74 /* |
|
75 ** Authentication functions must call authsuccess if the authentication |
|
76 ** request succeeds, and provide the following parameters. |
|
77 */ |
|
78 |
|
79 void authsuccess( |
|
80 const char *, /* home directory */ |
|
81 const char *, /* username */ |
|
82 const uid_t *, /* userid */ |
|
83 const gid_t *, /* group id */ |
|
84 |
|
85 const char *, /* AUTHADDR */ |
|
86 const char *); /* AUTHFULLNAME */ |
|
87 /* |
|
88 ** EITHER username or userid can be specified (leave the other pointer null). |
|
89 ** authmod_success changes to the home directory, and initializes the |
|
90 ** process's uid and gid. gid can be null if username is provided, in which |
|
91 ** case gid will be picked up from the password file. gid CANNOT be null |
|
92 ** if username is null. |
|
93 */ |
|
94 |
|
95 |
|
96 /* authcheckpassword is the general password validation routine. |
|
97 ** It returns 0 if the password matches the encrypted password. |
|
98 */ |
|
99 |
|
100 int authcheckpassword(const char *, /* password */ |
|
101 const char *); /* encrypted password */ |
|
102 |
|
103 /* Stub function */ |
|
104 |
|
105 extern void authexit(int); |
|
106 |
|
107 |
|
108 /* |
|
109 LOW LEVEL AUTHENTICATION DRIVERS. |
|
110 |
|
111 Each low level authentication driver provides three functions: |
|
112 |
|
113 1) Primary authentication function. This function is used to build a |
|
114 standalone authentication module based on the mod.h template (see mod.h). |
|
115 This function takes an authentication request. If its valid, it |
|
116 changes its userid/groupid to the one for the authenticated user, |
|
117 changes the current directory to the authenticated user's home directory, |
|
118 and sets the following environment variables: |
|
119 |
|
120 MAILDIR - nondefault mailbox location (optional). |
|
121 |
|
122 2) User lookup function. This function is prototyped as follows: |
|
123 |
|
124 int functionname(const char *userid, const char *service, |
|
125 int (*callback)(struct authinfo *, void *), |
|
126 void *); |
|
127 |
|
128 This function populates the following structure: |
|
129 */ |
|
130 |
|
131 struct authinfo { |
|
132 const char *sysusername; |
|
133 const uid_t *sysuserid; |
|
134 gid_t sysgroupid; |
|
135 const char *homedir; |
|
136 |
|
137 const char *address; |
|
138 const char *fullname; |
|
139 const char *maildir; |
|
140 const char *quota; |
|
141 |
|
142 const char *passwd; |
|
143 const char *clearpasswd; /* For authldap */ |
|
144 |
|
145 unsigned staticindex; /* When statically-linked functions are |
|
146 ** called, this holds the index of the |
|
147 ** authentication module in authstaticlist */ |
|
148 |
|
149 } ; |
|
150 |
|
151 /* |
|
152 Either sysusername or sysuserid may be NULL, but not both of them. |
|
153 They, and sysgroupid, specify the authenticated user's system |
|
154 userid and groupid. homedir points to the authenticated user's |
|
155 home directory. address, fullname, and maildir, are obvious. |
|
156 quota is populated with any maildir quota (see |
|
157 maildir/README.maildirquota). |
|
158 |
|
159 After populating this tructure, the lookup function calls the |
|
160 callback function that's specified in its second argument. The |
|
161 callback function receives a pointer to the authinfo structure. |
|
162 |
|
163 The callback function also receives a context pointer, which is |
|
164 the third argument to the lookup function. |
|
165 |
|
166 The lookup function should return a negative value if he userid |
|
167 does not exist, a positive value if there was a temporary error |
|
168 looking up the userid, or whatever is the return code from the |
|
169 callback function, if the user exists. |
|
170 |
|
171 |
|
172 NOTE: the passwd field is used internally by modules which implement |
|
173 the primary authentication function by sharing code with the lookup function. |
|
174 |
|
175 3) Cleanup function. This function should close any resources that were |
|
176 opened by the lookup function. Note that in applications which have a |
|
177 daemon process that uses this library it is possible for the lookup |
|
178 function to be called multiple times, before the cleanup function is |
|
179 called. |
|
180 */ |
|
181 |
|
182 #ifdef __cplusplus |
|
183 } |
|
184 #endif |
|
185 |
|
186 #endif |