auth.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 .