sys/man/2/auth

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