1 d93fca6a 2005-02-11 devnull .TH AUTH 3
3 83c4506a 2005-02-11 devnull 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, fsauth_proxy, fsfauth_proxy, fsamount, nsamount\- routines for authenticating users
4 d93fca6a 2005-02-11 devnull .SH SYNOPSIS
8 d93fca6a 2005-02-11 devnull #include <u.h>
9 d93fca6a 2005-02-11 devnull #include <libc.h>
10 d93fca6a 2005-02-11 devnull #include <auth.h>
12 d93fca6a 2005-02-11 devnull .ta 11n +4n +4n +4n +4n +4n +4n
15 d93fca6a 2005-02-11 devnull .\" int newns(char *user, char *nsfile);
18 d93fca6a 2005-02-11 devnull .\" int addns(char *user, char *nsfile);
21 d93fca6a 2005-02-11 devnull .\" int amount(int fd, char *old, int flag, char *aname);
24 d93fca6a 2005-02-11 devnull .\" int login(char *user, char *password, char *namespace);
27 d93fca6a 2005-02-11 devnull .\" int noworld(char *user);
30 d93fca6a 2005-02-11 devnull AuthInfo* auth_proxy(int fd, AuthGetkey *getkey, char *fmt, ...);
33 d93fca6a 2005-02-11 devnull AuthInfo* fauth_proxy(int fd, AuthRpc *rpc, AuthGetkey *getkey,
35 d93fca6a 2005-02-11 devnull .B char *params);
38 d93fca6a 2005-02-11 devnull AuthRpc* auth_allocrpc(void);
41 d93fca6a 2005-02-11 devnull void auth_freerpc(AuthRpc *rpc);
44 d93fca6a 2005-02-11 devnull uint auth_rpc(AuthRpc *rpc, char *verb, void *a, int n);
47 d93fca6a 2005-02-11 devnull int auth_getkey(char *proto, char *dom);
50 d93fca6a 2005-02-11 devnull int (*amount_getkey)(char*, char*);
53 d93fca6a 2005-02-11 devnull void auth_freeAI(AuthInfo *ai);
56 d93fca6a 2005-02-11 devnull int auth_chuid(AuthInfo *ai, char *ns);
59 d93fca6a 2005-02-11 devnull Chalstate* auth_challenge(char *fmt, ...);
62 d93fca6a 2005-02-11 devnull AuthInfo* auth_response(Chalstate*);
65 d93fca6a 2005-02-11 devnull void auth_freechal(Chalstate*);
68 d93fca6a 2005-02-11 devnull int auth_respond(void *chal, uint nchal, char *user, uint nuser, void *resp, uint nresp, AuthGetkey *getkey, char *fmt, ...);
71 d93fca6a 2005-02-11 devnull AuthInfo* auth_userpasswd(char*user, char*password);
74 d93fca6a 2005-02-11 devnull UserPasswd* auth_getuserpasswd(AuthGetkey *getkey, char*fmt, ...);
77 d93fca6a 2005-02-11 devnull AuthInfo* auth_getinfo(AuthRpc *rpc);
80 d93fca6a 2005-02-11 devnull #include <9pclient.h>
83 83c4506a 2005-02-11 devnull AuthInfo* fsauth_proxy(CFid *fid, AuthGetkey *getkey, char *fmt, ...);
86 83c4506a 2005-02-11 devnull AuthInfo* fsfauth_proxy(CFid *fid, AuthRpc *rpc, AuthGetkey *getkey,
88 83c4506a 2005-02-11 devnull .B char *params);
91 d93fca6a 2005-02-11 devnull CFsys* fsamount(int fd, char *aname);
94 d93fca6a 2005-02-11 devnull CFsys* nsamount(char *name, char *aname);
95 d93fca6a 2005-02-11 devnull .SH DESCRIPTION
97 d93fca6a 2005-02-11 devnull This library, in concert with
98 d32deab1 2020-08-16 rsc .MR factotum (4) ,
99 d93fca6a 2005-02-11 devnull is used to authenticate users.
100 d93fca6a 2005-02-11 devnull It provides the primary interface to
101 d93fca6a 2005-02-11 devnull .IR factotum .
103 d93fca6a 2005-02-11 devnull .\" .I Newns
104 d93fca6a 2005-02-11 devnull .\" builds a name space for
105 d93fca6a 2005-02-11 devnull .\" .IR user .
106 d93fca6a 2005-02-11 devnull .\" It opens the file
107 d93fca6a 2005-02-11 devnull .\" .I nsfile
108 d93fca6a 2005-02-11 devnull .\" .RB ( /lib/namespace
109 d93fca6a 2005-02-11 devnull .\" is used if
110 d93fca6a 2005-02-11 devnull .\" .I nsfile
111 d93fca6a 2005-02-11 devnull .\" is null),
112 d93fca6a 2005-02-11 devnull .\" copies the old environment, erases the current name space,
113 d93fca6a 2005-02-11 devnull .\" sets the environment variables
114 d93fca6a 2005-02-11 devnull .\" .B user
116 d93fca6a 2005-02-11 devnull .\" .BR home ,
117 d93fca6a 2005-02-11 devnull .\" and interprets the commands in
118 d93fca6a 2005-02-11 devnull .\" .IR nsfile .
119 d93fca6a 2005-02-11 devnull .\" The format of
120 d93fca6a 2005-02-11 devnull .\" .I nsfile
121 d93fca6a 2005-02-11 devnull .\" is described in
122 d93fca6a 2005-02-11 devnull .\" .IR namespace (6).
124 d93fca6a 2005-02-11 devnull .\" .I Addns
125 d93fca6a 2005-02-11 devnull .\" also interprets and executes the commands in
126 d93fca6a 2005-02-11 devnull .\" .IR nsfile .
127 d93fca6a 2005-02-11 devnull .\" Unlike
128 d93fca6a 2005-02-11 devnull .\" .I newns
129 d93fca6a 2005-02-11 devnull .\" it applies the command to the current name space
130 d93fca6a 2005-02-11 devnull .\" rather than starting from scratch.
132 d93fca6a 2005-02-11 devnull .\" .I Amount
133 d93fca6a 2005-02-11 devnull .\" is like
134 d93fca6a 2005-02-11 devnull .\" .I mount
135 d93fca6a 2005-02-11 devnull .\" but performs any authentication required.
136 d93fca6a 2005-02-11 devnull .\" It should be used instead of
137 d93fca6a 2005-02-11 devnull .\" .I mount
138 d93fca6a 2005-02-11 devnull .\" whenever the file server being mounted requires authentication.
140 d93fca6a 2005-02-11 devnull .\" .IR bind (2)
141 d93fca6a 2005-02-11 devnull .\" for a definition of the arguments to
142 d93fca6a 2005-02-11 devnull .\" .I mount
144 d93fca6a 2005-02-11 devnull .\" .IR amount .
146 d93fca6a 2005-02-11 devnull .\" .I Login
147 d93fca6a 2005-02-11 devnull .\" changes the user id of the process
148 d93fca6a 2005-02-11 devnull .\" .I user
149 d93fca6a 2005-02-11 devnull .\" and recreates the namespace using the file
150 d93fca6a 2005-02-11 devnull .\" .I namespace
151 d93fca6a 2005-02-11 devnull .\" (default
152 d93fca6a 2005-02-11 devnull .\" .BR /lib/nnamespace ).
153 d93fca6a 2005-02-11 devnull .\" It uses
154 d93fca6a 2005-02-11 devnull .\" .I auth_userpassword
156 d93fca6a 2005-02-11 devnull .\" .IR auth_chuid .
158 d93fca6a 2005-02-11 devnull .\" .I Noworld
159 d93fca6a 2005-02-11 devnull .\" returns 1 if the user is in the group
160 d93fca6a 2005-02-11 devnull .\" .B noworld
162 d93fca6a 2005-02-11 devnull .\" .BR /adm/users .
163 d93fca6a 2005-02-11 devnull .\" Otherwise, it returns 0.
164 d93fca6a 2005-02-11 devnull .\" .I Noworld
165 d93fca6a 2005-02-11 devnull .\" is used by telnetd and ftpd to provide sandboxed
166 d93fca6a 2005-02-11 devnull .\" access for some users.
168 d93fca6a 2005-02-11 devnull The following routines use the
169 d93fca6a 2005-02-11 devnull .B AuthInfo
170 d93fca6a 2005-02-11 devnull structure returned after a successful authentication by
171 d32deab1 2020-08-16 rsc .MR factotum (4) .
175 d93fca6a 2005-02-11 devnull .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
176 d93fca6a 2005-02-11 devnull typedef struct
178 d93fca6a 2005-02-11 devnull char *cuid; /* caller id */
179 d93fca6a 2005-02-11 devnull char *suid; /* server id */
180 d93fca6a 2005-02-11 devnull char *cap; /* capability */
181 d93fca6a 2005-02-11 devnull int nsecret; /* length of secret */
182 d93fca6a 2005-02-11 devnull uchar *secret; /* secret */
183 d93fca6a 2005-02-11 devnull } AuthInfo;
186 d93fca6a 2005-02-11 devnull The fields
190 d93fca6a 2005-02-11 devnull point to the authenticated ids of the client and server.
192 d93fca6a 2005-02-11 devnull is a capability returned only to the server.
193 d93fca6a 2005-02-11 devnull It is meaningful only on Plan 9.
194 d93fca6a 2005-02-11 devnull .\" It can be passed to the
195 d93fca6a 2005-02-11 devnull .\" .IR cap (3)
196 d93fca6a 2005-02-11 devnull .\" device to change the user id of the process.
197 d93fca6a 2005-02-11 devnull .B Secret
199 d93fca6a 2005-02-11 devnull .BR nsecret -byte
200 d93fca6a 2005-02-11 devnull shared secret that can be used by the client and server to
201 d93fca6a 2005-02-11 devnull create encryption and hashing keys for the rest of the
202 d93fca6a 2005-02-11 devnull conversation.
204 d93fca6a 2005-02-11 devnull .I Auth_proxy
205 d93fca6a 2005-02-11 devnull proxies an authentication conversation between a remote
206 d93fca6a 2005-02-11 devnull server reading and writing
209 d93fca6a 2005-02-11 devnull .I factotum
210 d93fca6a 2005-02-11 devnull file, as opened by
211 d93fca6a 2005-02-11 devnull .IR auth_allocrpc.
213 d93fca6a 2005-02-11 devnull .B sprint
215 d32deab1 2020-08-16 rsc .MR print (3) )
218 d93fca6a 2005-02-11 devnull and the variable arg list yields a key template (see
219 d32deab1 2020-08-16 rsc .MR factotum (4) )
220 d93fca6a 2005-02-11 devnull specifying the key to use.
221 d93fca6a 2005-02-11 devnull The template must specify at least the protocol (
222 d93fca6a 2005-02-11 devnull .BI proto= xxx )
223 d93fca6a 2005-02-11 devnull and the role (either
224 d93fca6a 2005-02-11 devnull .B role=client
226 d93fca6a 2005-02-11 devnull .BR role=server ).
227 d93fca6a 2005-02-11 devnull .I Auth_proxy
228 d93fca6a 2005-02-11 devnull either returns an allocated
229 d93fca6a 2005-02-11 devnull .B AuthInfo
230 d93fca6a 2005-02-11 devnull structure, or sets the error string and
231 d93fca6a 2005-02-11 devnull returns nil.
233 d93fca6a 2005-02-11 devnull .I Fauth_proxy
234 d93fca6a 2005-02-11 devnull can be used instead of
235 d93fca6a 2005-02-11 devnull .I auth_proxy
236 d93fca6a 2005-02-11 devnull if a single connection to
237 d93fca6a 2005-02-11 devnull .I factotum
238 d93fca6a 2005-02-11 devnull will be used for multiple authentications.
239 d93fca6a 2005-02-11 devnull This is necessary, for example, for
240 d93fca6a 2005-02-11 devnull .I newns
241 d93fca6a 2005-02-11 devnull which must open the
242 d93fca6a 2005-02-11 devnull .I factotum
243 d93fca6a 2005-02-11 devnull file before wiping out the namespace.
244 d93fca6a 2005-02-11 devnull .I Fauth_proxy
245 d93fca6a 2005-02-11 devnull takes as an argument a pointer to an
246 d93fca6a 2005-02-11 devnull .B AuthRpc
247 d93fca6a 2005-02-11 devnull structure which contains an fd for an open connection to
248 d93fca6a 2005-02-11 devnull .I factotum
249 d93fca6a 2005-02-11 devnull in addition to storage and state information for
250 d93fca6a 2005-02-11 devnull the protocol.
252 d93fca6a 2005-02-11 devnull .B AuthRpc
253 d93fca6a 2005-02-11 devnull structure is obtained by calling
254 d93fca6a 2005-02-11 devnull .IR auth_allocrpc .
255 d93fca6a 2005-02-11 devnull .I Auth_allocrpc
256 d93fca6a 2005-02-11 devnull arranges a connection to
257 d93fca6a 2005-02-11 devnull .IR factotum ,
258 d93fca6a 2005-02-11 devnull either by opening
259 d93fca6a 2005-02-11 devnull .B /mnt/factotum/rpc
260 d93fca6a 2005-02-11 devnull or by using
261 d32deab1 2020-08-16 rsc .MR 9pclient (3)
262 d93fca6a 2005-02-11 devnull to connect to a
263 d93fca6a 2005-02-11 devnull .B factotum
264 d93fca6a 2005-02-11 devnull service posted in the current name space.
265 d93fca6a 2005-02-11 devnull The returned connection
266 d93fca6a 2005-02-11 devnull is freed using
267 d93fca6a 2005-02-11 devnull .IR auth_freerpc .
268 d93fca6a 2005-02-11 devnull Individual commands can be sent to
269 d32deab1 2020-08-16 rsc .MR factotum (4)
270 d93fca6a 2005-02-11 devnull by invoking
271 d93fca6a 2005-02-11 devnull .IR auth_rpc .
274 d93fca6a 2005-02-11 devnull .I auth_proxy
276 d93fca6a 2005-02-11 devnull .I fauth_proxy
277 d93fca6a 2005-02-11 devnull take a pointer to a routine,
278 d93fca6a 2005-02-11 devnull .IR getkey ,
279 d93fca6a 2005-02-11 devnull to invoke should
280 d93fca6a 2005-02-11 devnull .I factotum
281 d93fca6a 2005-02-11 devnull not posess a key for the authentication. If
282 d93fca6a 2005-02-11 devnull .I getkey
283 d93fca6a 2005-02-11 devnull is nil, the authentication fails.
284 d93fca6a 2005-02-11 devnull .I Getkey
285 d93fca6a 2005-02-11 devnull is called with a key template for the desired
287 d93fca6a 2005-02-11 devnull We have provided a generic routine,
288 d93fca6a 2005-02-11 devnull .IR auth_getkey ,
289 d93fca6a 2005-02-11 devnull which queries the user for
290 d93fca6a 2005-02-11 devnull the key information and passes it to
291 d93fca6a 2005-02-11 devnull .IR factotum .
292 d93fca6a 2005-02-11 devnull This is the default for the global variable,
293 d93fca6a 2005-02-11 devnull .IR amount_getkey ,
294 d93fca6a 2005-02-11 devnull which holds a pointer to the key prompting routine used by
295 d93fca6a 2005-02-11 devnull .IR amount .
297 d93fca6a 2005-02-11 devnull .I Auth_chuid
298 d93fca6a 2005-02-11 devnull uses the
302 d93fca6a 2005-02-11 devnull fields of an
303 d93fca6a 2005-02-11 devnull .B AuthInfo
304 d93fca6a 2005-02-11 devnull structure to change the user id of the current
305 d93fca6a 2005-02-11 devnull process and uses
306 d93fca6a 2005-02-11 devnull .IR ns ,
308 d93fca6a 2005-02-11 devnull .BR /lib/namespace ,
309 d93fca6a 2005-02-11 devnull to build it a new name space.
311 d93fca6a 2005-02-11 devnull .I Auth_challenge
313 d93fca6a 2005-02-11 devnull .I auth_response
314 d93fca6a 2005-02-11 devnull perform challenge/response protocols with
315 d93fca6a 2005-02-11 devnull .IR factotum .
316 d93fca6a 2005-02-11 devnull State between the challenge and response phase are
317 d93fca6a 2005-02-11 devnull kept in the
318 d93fca6a 2005-02-11 devnull .B Chalstate
319 d93fca6a 2005-02-11 devnull structure:
322 d93fca6a 2005-02-11 devnull struct Chalstate
324 d93fca6a 2005-02-11 devnull char *user;
325 d93fca6a 2005-02-11 devnull char chal[MAXCHLEN];
326 d93fca6a 2005-02-11 devnull int nchal;
327 d93fca6a 2005-02-11 devnull void *resp;
328 d93fca6a 2005-02-11 devnull int nresp;
330 d93fca6a 2005-02-11 devnull /* for implementation only */
331 d93fca6a 2005-02-11 devnull int afd;
332 d93fca6a 2005-02-11 devnull AuthRpc *rpc;
333 d93fca6a 2005-02-11 devnull char userbuf[MAXNAMELEN];
334 d93fca6a 2005-02-11 devnull int userinchal;
338 d93fca6a 2005-02-11 devnull .I Auth_challenge
339 d93fca6a 2005-02-11 devnull requires a key template generated by an
340 d93fca6a 2005-02-11 devnull .B sprint
343 d93fca6a 2005-02-11 devnull and the variable arguments. It must contain the protocol
344 d93fca6a 2005-02-11 devnull (\fBproto=\fIxxx\fR)
345 d93fca6a 2005-02-11 devnull and depending on the protocol, the user name (
346 d93fca6a 2005-02-11 devnull .BI user= xxx \fR).\fP
350 d93fca6a 2005-02-11 devnull expect the user specified as an attribute in
351 d93fca6a 2005-02-11 devnull the key template and
352 d93fca6a 2005-02-11 devnull .BR apop ,
353 d93fca6a 2005-02-11 devnull .BR cram ,
355 d93fca6a 2005-02-11 devnull .BR chap
356 d93fca6a 2005-02-11 devnull expect it in the
358 d93fca6a 2005-02-11 devnull field of the arg to
359 d93fca6a 2005-02-11 devnull .IR auth_response .
360 d93fca6a 2005-02-11 devnull For all protocols, the response is returned
362 d93fca6a 2005-02-11 devnull .I auth_response
365 d93fca6a 2005-02-11 devnull field of the
366 d93fca6a 2005-02-11 devnull .BR Chalstate .
367 d93fca6a 2005-02-11 devnull .I Chalstate.nresp
368 d93fca6a 2005-02-11 devnull must be the length of the response.
370 d93fca6a 2005-02-11 devnull Supply to
371 d93fca6a 2005-02-11 devnull .I auth_respond
372 d93fca6a 2005-02-11 devnull a challenge string and the fmt and args specifying a key,
373 d93fca6a 2005-02-11 devnull and it will use
374 d93fca6a 2005-02-11 devnull .I factotum
375 d93fca6a 2005-02-11 devnull to return the proper user and response.
377 d93fca6a 2005-02-11 devnull .I Auth_userpasswd
378 d93fca6a 2005-02-11 devnull verifies a simple user/password pair.
379 d93fca6a 2005-02-11 devnull .I Auth_getuserpasswd
380 d93fca6a 2005-02-11 devnull retrieves a user/password pair from
381 d93fca6a 2005-02-11 devnull .I factotum
382 d93fca6a 2005-02-11 devnull if permitted.
384 d93fca6a 2005-02-11 devnull .I Auth_getinfo
385 d93fca6a 2005-02-11 devnull reads an
386 d93fca6a 2005-02-11 devnull .B AuthInfo
387 d93fca6a 2005-02-11 devnull message from factotum
388 d93fca6a 2005-02-11 devnull and converts it into a structure. It is only
389 d93fca6a 2005-02-11 devnull used by the other routines in this library when
390 d93fca6a 2005-02-11 devnull communicating with
391 d93fca6a 2005-02-11 devnull .IR factotum .
395 d93fca6a 2005-02-11 devnull .ta 4n +4n +4n +4n +4n +4n +4n +4n +4n
396 d93fca6a 2005-02-11 devnull typedef struct UserPasswd {
397 d93fca6a 2005-02-11 devnull char *user;
398 d93fca6a 2005-02-11 devnull char *passwd;
399 d93fca6a 2005-02-11 devnull } UserPasswd;
403 d93fca6a 2005-02-11 devnull .I Auth_freeAI
404 d93fca6a 2005-02-11 devnull is used to free an
405 d93fca6a 2005-02-11 devnull .B AuthInfo
406 d93fca6a 2005-02-11 devnull structure returned by one of these routines.
407 d93fca6a 2005-02-11 devnull Similary
408 d93fca6a 2005-02-11 devnull .I auth_freechal
409 d93fca6a 2005-02-11 devnull frees a challenge/response state.
411 83c4506a 2005-02-11 devnull .I Fsauth_proxy
413 83c4506a 2005-02-11 devnull .I fsfauth_proxy
414 83c4506a 2005-02-11 devnull are like
415 83c4506a 2005-02-11 devnull .I auth_proxy
417 83c4506a 2005-02-11 devnull .I fauth_proxy
418 83c4506a 2005-02-11 devnull but execute the protocol on a
419 83c4506a 2005-02-11 devnull .B CFid*
421 d32deab1 2020-08-16 rsc .MR 9pclient (3) )
422 83c4506a 2005-02-11 devnull instead of a file descriptor.
424 d93fca6a 2005-02-11 devnull .I Fsamount
426 d93fca6a 2005-02-11 devnull .I nsamount
427 d93fca6a 2005-02-11 devnull are like
428 d93fca6a 2005-02-11 devnull .I fsmount
430 d93fca6a 2005-02-11 devnull .I nsmount
432 d32deab1 2020-08-16 rsc .MR 9pclient (3) )
434 d93fca6a 2005-02-11 devnull .I factotum
435 d93fca6a 2005-02-11 devnull to authenticate to the file servers.
436 d93fca6a 2005-02-11 devnull .SH SOURCE
437 d93fca6a 2005-02-11 devnull .B \*9/src/libauth
438 d93fca6a 2005-02-11 devnull .SH SEE ALSO
439 d32deab1 2020-08-16 rsc .MR factotum (4) ,
440 d32deab1 2020-08-16 rsc .MR authsrv (3)
441 d93fca6a 2005-02-11 devnull .SH DIAGNOSTICS
442 d93fca6a 2005-02-11 devnull These routines set
443 d93fca6a 2005-02-11 devnull .IR errstr .
