auth 7.4 KB

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