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