1 cfa37a7b 2004-04-10 devnull .TH AUTH 3
3 cfa37a7b 2004-04-10 devnull amount, newns, addns, login, noworld, auth_proxy, fauth_proxy, auth_allocrpc, auth_freerpc, auth_rpc, auth_getkey, amount_getkey, auth_freeAI, auth_chuid, auth_challenge, auth_response, auth_freechal, auth_respond, auth_userpasswd, auth_getuserpasswd, auth_getinfo\- routines for authenticating users
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
8 cfa37a7b 2004-04-10 devnull #include <u.h>
9 cfa37a7b 2004-04-10 devnull #include <libc.h>
10 cfa37a7b 2004-04-10 devnull #include <auth.h>
12 cfa37a7b 2004-04-10 devnull .ta 11n +4n +4n +4n +4n +4n +4n
15 cfa37a7b 2004-04-10 devnull int newns(char *user, char *nsfile);
18 cfa37a7b 2004-04-10 devnull int addns(char *user, char *nsfile);
21 cfa37a7b 2004-04-10 devnull int amount(int fd, char *old, int flag, char *aname);
24 cfa37a7b 2004-04-10 devnull int login(char *user, char *password, char *namespace);
27 cfa37a7b 2004-04-10 devnull int noworld(char *user);
30 cfa37a7b 2004-04-10 devnull AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
33 cfa37a7b 2004-04-10 devnull AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
35 cfa37a7b 2004-04-10 devnull .B char *params);
38 cfa37a7b 2004-04-10 devnull AuthRpc* auth_allocrpc(int afd);
41 cfa37a7b 2004-04-10 devnull void auth_freerpc(AuthRpc *rpc);
44 cfa37a7b 2004-04-10 devnull uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
47 cfa37a7b 2004-04-10 devnull int auth_getkey(char *proto, char *dom);
50 cfa37a7b 2004-04-10 devnull int (*amount_getkey)(char*, char*);
53 cfa37a7b 2004-04-10 devnull void auth_freeAI(AuthInfo *ai);
56 cfa37a7b 2004-04-10 devnull int auth_chuid(AuthInfo *ai, char *ns);
59 cfa37a7b 2004-04-10 devnull Chalstate* auth_challenge(char *fmt, ...);
62 cfa37a7b 2004-04-10 devnull AuthInfo* auth_response(Chalstate*);
65 cfa37a7b 2004-04-10 devnull void auth_freechal(Chalstate*);
68 cfa37a7b 2004-04-10 devnull int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
71 cfa37a7b 2004-04-10 devnull AuthInfo* auth_userpasswd(char*user, char*password);
74 cfa37a7b 2004-04-10 devnull UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
77 cfa37a7b 2004-04-10 devnull AuthInfo* auth_getinfo(int fd);
78 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
80 cfa37a7b 2004-04-10 devnull This library, in concert with
81 cfa37a7b 2004-04-10 devnull .IR factotum (4),
82 cfa37a7b 2004-04-10 devnull is used to authenticate users.
83 cfa37a7b 2004-04-10 devnull It provides the primary interface to
84 cfa37a7b 2004-04-10 devnull .IR factotum .
87 cfa37a7b 2004-04-10 devnull builds a name space for
88 cfa37a7b 2004-04-10 devnull .IR user .
89 cfa37a7b 2004-04-10 devnull It opens the file
90 cfa37a7b 2004-04-10 devnull .I nsfile
91 cfa37a7b 2004-04-10 devnull .RB ( /lib/namespace
92 cfa37a7b 2004-04-10 devnull is used if
93 cfa37a7b 2004-04-10 devnull .I nsfile
94 cfa37a7b 2004-04-10 devnull is null),
95 cfa37a7b 2004-04-10 devnull copies the old environment, erases the current name space,
96 cfa37a7b 2004-04-10 devnull sets the environment variables
99 cfa37a7b 2004-04-10 devnull .BR home ,
100 cfa37a7b 2004-04-10 devnull and interprets the commands in
101 cfa37a7b 2004-04-10 devnull .IR nsfile .
102 cfa37a7b 2004-04-10 devnull The format of
103 cfa37a7b 2004-04-10 devnull .I nsfile
104 cfa37a7b 2004-04-10 devnull is described in
105 cfa37a7b 2004-04-10 devnull .IR namespace (6).
107 cfa37a7b 2004-04-10 devnull .I Addns
108 cfa37a7b 2004-04-10 devnull also interprets and executes the commands in
109 cfa37a7b 2004-04-10 devnull .IR nsfile .
111 cfa37a7b 2004-04-10 devnull .I newns
112 cfa37a7b 2004-04-10 devnull it applies the command to the current name space
113 cfa37a7b 2004-04-10 devnull rather than starting from scratch.
115 cfa37a7b 2004-04-10 devnull .I Amount
117 cfa37a7b 2004-04-10 devnull .I mount
118 cfa37a7b 2004-04-10 devnull but performs any authentication required.
119 cfa37a7b 2004-04-10 devnull It should be used instead of
120 cfa37a7b 2004-04-10 devnull .I mount
121 cfa37a7b 2004-04-10 devnull whenever the file server being mounted requires authentication.
123 bf8a59fa 2004-04-11 devnull .IR bind (3)
124 cfa37a7b 2004-04-10 devnull for a definition of the arguments to
125 cfa37a7b 2004-04-10 devnull .I mount
127 cfa37a7b 2004-04-10 devnull .IR amount .
129 cfa37a7b 2004-04-10 devnull .I Login
130 cfa37a7b 2004-04-10 devnull changes the user id of the process
132 cfa37a7b 2004-04-10 devnull and recreates the namespace using the file
133 cfa37a7b 2004-04-10 devnull .I namespace
134 cfa37a7b 2004-04-10 devnull (default
135 cfa37a7b 2004-04-10 devnull .BR /lib/nnamespace ).
137 cfa37a7b 2004-04-10 devnull .I auth_userpassword
139 cfa37a7b 2004-04-10 devnull .IR auth_chuid .
141 cfa37a7b 2004-04-10 devnull .I Noworld
142 cfa37a7b 2004-04-10 devnull returns 1 if the user is in the group
143 cfa37a7b 2004-04-10 devnull .B noworld
145 cfa37a7b 2004-04-10 devnull .BR /adm/users .
146 cfa37a7b 2004-04-10 devnull Otherwise, it returns 0.
147 cfa37a7b 2004-04-10 devnull .I Noworld
148 cfa37a7b 2004-04-10 devnull is used by telnetd and ftpd to provide sandboxed
149 cfa37a7b 2004-04-10 devnull access for some users.
151 cfa37a7b 2004-04-10 devnull The following routines use the
152 cfa37a7b 2004-04-10 devnull .B AuthInfo
153 cfa37a7b 2004-04-10 devnull structure returned after a successful authentication by
154 cfa37a7b 2004-04-10 devnull .IR factotum (4).
158 cfa37a7b 2004-04-10 devnull .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
159 cfa37a7b 2004-04-10 devnull typedef struct
161 cfa37a7b 2004-04-10 devnull char *cuid; /* caller id */
162 cfa37a7b 2004-04-10 devnull char *suid; /* server id */
163 cfa37a7b 2004-04-10 devnull char *cap; /* capability */
164 cfa37a7b 2004-04-10 devnull int nsecret; /* length of secret */
165 cfa37a7b 2004-04-10 devnull uchar *secret; /* secret */
166 cfa37a7b 2004-04-10 devnull } AuthInfo;
169 cfa37a7b 2004-04-10 devnull The fields
173 cfa37a7b 2004-04-10 devnull point to the authenticated ids of the client and server.
175 cfa37a7b 2004-04-10 devnull is a capability returned only to the server.
176 cfa37a7b 2004-04-10 devnull It can be passed to the
177 cfa37a7b 2004-04-10 devnull .IR cap (3)
178 cfa37a7b 2004-04-10 devnull device to change the user id of the process.
179 cfa37a7b 2004-04-10 devnull .B Secret
181 cfa37a7b 2004-04-10 devnull .BR nsecret -byte
182 cfa37a7b 2004-04-10 devnull shared secret that can be used by the client and server to
183 cfa37a7b 2004-04-10 devnull create encryption and hashing keys for the rest of the
184 cfa37a7b 2004-04-10 devnull conversation.
186 cfa37a7b 2004-04-10 devnull .I Auth_proxy
187 cfa37a7b 2004-04-10 devnull proxies an authentication conversation between a remote
188 cfa37a7b 2004-04-10 devnull server reading and writing
191 cfa37a7b 2004-04-10 devnull .I factotum
192 cfa37a7b 2004-04-10 devnull file. The
193 cfa37a7b 2004-04-10 devnull .I factotum
194 cfa37a7b 2004-04-10 devnull file used is
195 cfa37a7b 2004-04-10 devnull .BR /mnt/factotum/rpc .
197 cfa37a7b 2004-04-10 devnull .B sprint
199 bf8a59fa 2004-04-11 devnull .IR print (3))
202 cfa37a7b 2004-04-10 devnull and the variable arg list yields a key template (see
203 cfa37a7b 2004-04-10 devnull .IR factotum (4))
204 cfa37a7b 2004-04-10 devnull specifying the key to use.
205 cfa37a7b 2004-04-10 devnull The template must specify at least the protocol (
206 cfa37a7b 2004-04-10 devnull .BI proto= xxx )
207 cfa37a7b 2004-04-10 devnull and the role (either
208 cfa37a7b 2004-04-10 devnull .B role=client
210 cfa37a7b 2004-04-10 devnull .BR role=server ).
211 cfa37a7b 2004-04-10 devnull .I Auth_proxy
212 cfa37a7b 2004-04-10 devnull either returns an allocated
213 cfa37a7b 2004-04-10 devnull .B AuthInfo
214 cfa37a7b 2004-04-10 devnull structure, or sets the error string and
215 cfa37a7b 2004-04-10 devnull returns nil.
217 cfa37a7b 2004-04-10 devnull .I Fauth_proxy
218 cfa37a7b 2004-04-10 devnull can be used instead of
219 cfa37a7b 2004-04-10 devnull .I auth_proxy
220 cfa37a7b 2004-04-10 devnull if a single connection to
221 cfa37a7b 2004-04-10 devnull .I factotum
222 cfa37a7b 2004-04-10 devnull will be used for multiple authentications.
223 cfa37a7b 2004-04-10 devnull This is necessary, for example, for
224 cfa37a7b 2004-04-10 devnull .I newns
225 cfa37a7b 2004-04-10 devnull which must open the
226 cfa37a7b 2004-04-10 devnull .I factotum
227 cfa37a7b 2004-04-10 devnull file before wiping out the namespace.
228 cfa37a7b 2004-04-10 devnull .I Fauth_proxy
229 cfa37a7b 2004-04-10 devnull takes as an argument a pointer to an
230 cfa37a7b 2004-04-10 devnull .B AuthRPC
231 cfa37a7b 2004-04-10 devnull structure which contains an fd for an open connection to
232 cfa37a7b 2004-04-10 devnull .I factotum
233 cfa37a7b 2004-04-10 devnull in addition to storage and state information for
234 cfa37a7b 2004-04-10 devnull the protocol.
236 cfa37a7b 2004-04-10 devnull .B AuthRPC
237 cfa37a7b 2004-04-10 devnull structure is obtained by calling
238 cfa37a7b 2004-04-10 devnull .I auth_allocrpc
239 cfa37a7b 2004-04-10 devnull with the fd of an open
240 cfa37a7b 2004-04-10 devnull .I factotum
241 cfa37a7b 2004-04-10 devnull connection.
242 cfa37a7b 2004-04-10 devnull It is freed using
243 cfa37a7b 2004-04-10 devnull .IR auth_freerpc .
244 cfa37a7b 2004-04-10 devnull Individual commands can be sent to
245 cfa37a7b 2004-04-10 devnull .IR factotum (4)
246 cfa37a7b 2004-04-10 devnull by invoking
247 cfa37a7b 2004-04-10 devnull .IR auth_rpc .
250 cfa37a7b 2004-04-10 devnull .I auth_proxy
252 cfa37a7b 2004-04-10 devnull .I fauth_proxy
253 cfa37a7b 2004-04-10 devnull take a pointer to a routine,
254 cfa37a7b 2004-04-10 devnull .IR getkey ,
255 cfa37a7b 2004-04-10 devnull to invoke should
256 cfa37a7b 2004-04-10 devnull .I factotum
257 cfa37a7b 2004-04-10 devnull not posess a key for the authentication. If
258 cfa37a7b 2004-04-10 devnull .I getkey
259 cfa37a7b 2004-04-10 devnull is nil, the authentication fails.
260 cfa37a7b 2004-04-10 devnull .I Getkey
261 cfa37a7b 2004-04-10 devnull is called with a key template for the desired
263 cfa37a7b 2004-04-10 devnull We have provided a generic routine,
264 cfa37a7b 2004-04-10 devnull .IR auth_getkey ,
265 cfa37a7b 2004-04-10 devnull which queries the user for
266 cfa37a7b 2004-04-10 devnull the key information and passes it to
267 cfa37a7b 2004-04-10 devnull .IR factotum .
268 cfa37a7b 2004-04-10 devnull This is the default for the global variable,
269 cfa37a7b 2004-04-10 devnull .IR amount_getkey ,
270 cfa37a7b 2004-04-10 devnull which holds a pointer to the key prompting routine used by
271 cfa37a7b 2004-04-10 devnull .IR amount .
273 cfa37a7b 2004-04-10 devnull .I Auth_chuid
274 cfa37a7b 2004-04-10 devnull uses the
278 cfa37a7b 2004-04-10 devnull fields of an
279 cfa37a7b 2004-04-10 devnull .B AuthInfo
280 cfa37a7b 2004-04-10 devnull structure to change the user id of the current
281 cfa37a7b 2004-04-10 devnull process and uses
282 cfa37a7b 2004-04-10 devnull .IR ns ,
284 cfa37a7b 2004-04-10 devnull .BR /lib/namespace ,
285 cfa37a7b 2004-04-10 devnull to build it a new name space.
287 cfa37a7b 2004-04-10 devnull .I Auth_challenge
289 cfa37a7b 2004-04-10 devnull .I auth_response
290 cfa37a7b 2004-04-10 devnull perform challenge/response protocols with
291 cfa37a7b 2004-04-10 devnull .IR factotum .
292 cfa37a7b 2004-04-10 devnull State between the challenge and response phase are
293 cfa37a7b 2004-04-10 devnull kept in the
294 cfa37a7b 2004-04-10 devnull .B Chalstate
295 cfa37a7b 2004-04-10 devnull structure:
298 cfa37a7b 2004-04-10 devnull struct Chalstate
300 cfa37a7b 2004-04-10 devnull char *user;
301 cfa37a7b 2004-04-10 devnull char chal[MAXCHLEN];
302 cfa37a7b 2004-04-10 devnull int nchal;
303 cfa37a7b 2004-04-10 devnull void *resp;
304 cfa37a7b 2004-04-10 devnull int nresp;
306 cfa37a7b 2004-04-10 devnull /* for implementation only */
307 cfa37a7b 2004-04-10 devnull int afd;
308 cfa37a7b 2004-04-10 devnull AuthRpc *rpc;
309 cfa37a7b 2004-04-10 devnull char userbuf[MAXNAMELEN];
310 cfa37a7b 2004-04-10 devnull int userinchal;
314 cfa37a7b 2004-04-10 devnull .I Auth_challenge
315 cfa37a7b 2004-04-10 devnull requires a key template generated by an
316 cfa37a7b 2004-04-10 devnull .B sprint
319 cfa37a7b 2004-04-10 devnull and the variable arguments. It must contain the protocol
320 cfa37a7b 2004-04-10 devnull (\fBproto=\fIxxx\fR)
321 cfa37a7b 2004-04-10 devnull and depending on the protocol, the user name (
322 cfa37a7b 2004-04-10 devnull .BI user= xxx \fR).\fP
326 cfa37a7b 2004-04-10 devnull expect the user specified as an attribute in
327 cfa37a7b 2004-04-10 devnull the key template and
328 cfa37a7b 2004-04-10 devnull .BR apop ,
329 cfa37a7b 2004-04-10 devnull .BR cram ,
331 cfa37a7b 2004-04-10 devnull .BR chap
332 cfa37a7b 2004-04-10 devnull expect it in the
334 cfa37a7b 2004-04-10 devnull field of the arg to
335 cfa37a7b 2004-04-10 devnull .IR auth_response .
336 cfa37a7b 2004-04-10 devnull For all protocols, the response is returned
338 cfa37a7b 2004-04-10 devnull .I auth_response
341 cfa37a7b 2004-04-10 devnull field of the
342 cfa37a7b 2004-04-10 devnull .BR Chalstate .
343 cfa37a7b 2004-04-10 devnull .I Chalstate.nresp
344 cfa37a7b 2004-04-10 devnull must be the length of the response.
346 cfa37a7b 2004-04-10 devnull Supply to
347 cfa37a7b 2004-04-10 devnull .I auth_respond
348 cfa37a7b 2004-04-10 devnull a challenge string and the fmt and args specifying a key,
349 cfa37a7b 2004-04-10 devnull and it will use
350 cfa37a7b 2004-04-10 devnull .I factotum
351 cfa37a7b 2004-04-10 devnull to return the proper user and response.
353 cfa37a7b 2004-04-10 devnull .I Auth_userpasswd
354 cfa37a7b 2004-04-10 devnull verifies a simple user/password pair.
355 cfa37a7b 2004-04-10 devnull .I Auth_getuserpasswd
356 cfa37a7b 2004-04-10 devnull retrieves a user/password pair from
357 cfa37a7b 2004-04-10 devnull .I factotum
358 cfa37a7b 2004-04-10 devnull if permitted.
360 cfa37a7b 2004-04-10 devnull .I Auth_getinfo
361 cfa37a7b 2004-04-10 devnull reads an
362 cfa37a7b 2004-04-10 devnull .B AuthInfo
363 cfa37a7b 2004-04-10 devnull message from
365 cfa37a7b 2004-04-10 devnull and converts it into a structure. It is only
366 cfa37a7b 2004-04-10 devnull used by the other routines in this library when
367 cfa37a7b 2004-04-10 devnull communicating with
368 cfa37a7b 2004-04-10 devnull .IR factotum .
372 cfa37a7b 2004-04-10 devnull .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
373 cfa37a7b 2004-04-10 devnull typedef struct UserPasswd {
374 cfa37a7b 2004-04-10 devnull char *user;
375 cfa37a7b 2004-04-10 devnull char *passwd;
376 cfa37a7b 2004-04-10 devnull } UserPasswd;
380 cfa37a7b 2004-04-10 devnull .I Auth_freeAI
381 cfa37a7b 2004-04-10 devnull is used to free an
382 cfa37a7b 2004-04-10 devnull .B AuthInfo
383 cfa37a7b 2004-04-10 devnull structure returned by one of these routines.
384 cfa37a7b 2004-04-10 devnull Similary
385 cfa37a7b 2004-04-10 devnull .I auth_freechal
386 cfa37a7b 2004-04-10 devnull frees a challenge/response state.
387 cfa37a7b 2004-04-10 devnull .SH SOURCE
388 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libauth
389 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
390 cfa37a7b 2004-04-10 devnull .IR factotum (4),
391 bf8a59fa 2004-04-11 devnull .IR authsrv (3),
392 bf8a59fa 2004-04-11 devnull .IR bind (3)
393 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
394 cfa37a7b 2004-04-10 devnull These routines set
395 cfa37a7b 2004-04-10 devnull .IR errstr .
