factotum 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728
  1. .TH FACTOTUM 4
  2. .SH NAME
  3. factotum, fgui \- authentication agent
  4. .SH SYNOPSIS
  5. .B auth/factotum
  6. [
  7. .B -DdknpuS
  8. ] [
  9. .B -a asaddr
  10. ] [
  11. .B -s
  12. .I srvname
  13. ] [
  14. .B -m
  15. .I mtpt
  16. ]
  17. .PP
  18. .B auth/factotum
  19. .B -g
  20. .IB attribute = value
  21. .B ...
  22. .IB attribute ?
  23. .B ...
  24. .PP
  25. .B auth/fgui
  26. .SH DESCRIPTION
  27. .I Factotum
  28. is a user-level file system that
  29. acts as the authentication agent for a user.
  30. It does so by managing a set of
  31. .IR keys .
  32. A key is a collection of information used to authenticate a particular action.
  33. Stored as a list of
  34. .IB attribute = value
  35. pairs, a key typically contains a user, an authentication domain, a protocol, and
  36. some secret data.
  37. .PP
  38. .I Factotum
  39. presents a two level directory. The first
  40. level contains a single directory
  41. .BR factotum ,
  42. which in turn contains:
  43. .TF needkey
  44. .TP
  45. .B rpc
  46. each open represents a new private channel to
  47. .I factotum
  48. .TP
  49. .B proto
  50. when read lists the protocols available
  51. .TP
  52. .B confirm
  53. for confiming the use of key
  54. .TP
  55. .B needkey
  56. allows external programs to control the addition of new keys
  57. .TP
  58. .B log
  59. a log of actions
  60. .TP
  61. .B ctl
  62. for maintaining keys; when read, it returns a list of keys.
  63. For secret attributes, only the attribute name follow by a
  64. .L ?
  65. is returned.
  66. .PD
  67. .PP
  68. In any authentication, the caller typically acts as a client
  69. and the callee as a server. The server determines
  70. the authentication domain, sometimes after a negotiation with
  71. the client. Authentication always requires the client to
  72. prove its identity to the server. Under some protocols, the
  73. authentication is mutual.
  74. Proof is accomplished using secret information kept by factotum
  75. in conjunction with a cryptographic protocol.
  76. .PP
  77. .I Factotum
  78. can act in the role of client for any process possessing the
  79. same user id as it. For select protocols such as
  80. .B p9sk1
  81. it can also act as a client for other processes provided
  82. its user id may speak for the other process' user id (see
  83. .IR authsrv (6)).
  84. .I Factotum
  85. can act in the role of server for any process.
  86. .PP
  87. .IR Factotum 's
  88. structure is independent of
  89. any particular authentication protocol.
  90. .I Factotum
  91. supports the following protocols:
  92. .TF mschap
  93. .TP
  94. .B p9any
  95. a metaprotocol used to negotiate which actual protocol to use.
  96. .TP
  97. .B p9sk1
  98. a Plan 9 shared key protocol described in
  99. .IR authsrv (6)'s
  100. ``File Service'' section.
  101. .TP
  102. .B p9sk2
  103. a variant of
  104. .B p9sk1
  105. described in
  106. .IR authsrv (6)'s
  107. ``Remote Execution'' section.
  108. .TP
  109. .B p9cr
  110. a Plan 9 protocol that can use either
  111. .B p9sk1
  112. keys or SecureID tokens.
  113. .TP
  114. .B apop
  115. the challenge/response protocol used by POP3 mail servers.
  116. .TP
  117. .B cram
  118. the challenge/response protocol also used by POP3 mail servers.
  119. .TP
  120. .B chap
  121. the challenge/response protocols used by PPP and PPTP.
  122. .TP
  123. .B mschap
  124. a proprietary Microsoft protocol also used by PPP and PPTP.
  125. .TP
  126. .B rsa
  127. RSA public key decryption, used by SSH and TLS.
  128. .TP
  129. .B pass
  130. passwords in the clear.
  131. .TP
  132. .B vnc
  133. .IR vnc (1)'s
  134. challenge/response.
  135. .TP
  136. .B wep
  137. WEP passwords for wireless ethernet cards.
  138. .PD
  139. .PP
  140. The options are:
  141. .TP
  142. .B \-a
  143. supplies the address of the authentication server to use.
  144. Without this option, it will attempt to find an authentication server by
  145. querying the connection server, the file
  146. .BR <mtpt>/ndb ,
  147. and finally the network database in
  148. .BR /lib/ndb .
  149. .TP
  150. .B \-m
  151. specifies the mount point to use, by default
  152. .BR /mnt .
  153. .TP
  154. .B \-s
  155. specifies the service name to use.
  156. Without this option,
  157. .I factotum
  158. does not create a service file in
  159. .BR /srv .
  160. .TP
  161. .B \-D
  162. turns on 9P tracing, written to standard error.
  163. .TP
  164. .B \-d
  165. turns on debugging, written to standard error.
  166. .TP
  167. .B \-g
  168. causes the agent to prompt for the key, write it
  169. to the
  170. .B ctl
  171. file, and exit.
  172. The agent will prompt for values for any of the
  173. attributes ending with a question mark
  174. .RB ( ? )
  175. and will append all the supplied
  176. .I attribute = value
  177. pairs. See the section on key templates below.
  178. .TP
  179. .B \-n
  180. don't look for a secstore.
  181. .TP
  182. .B \-S
  183. indicates that the agent is running on a
  184. CPU server. On starting, it will attempt to get a
  185. .B p9sk1
  186. key from NVRAM using
  187. .B readnvram
  188. (see
  189. .IR authsrv (2)),
  190. prompting for anything it needs.
  191. It will never subsequently prompt for a
  192. key that it doesn't have.
  193. This option is typically used by
  194. the kernel at boot time.
  195. .TP
  196. .B \-k
  197. causes the NVRAM to be written.
  198. It is only valid with the
  199. .B \-S
  200. option.
  201. This option is typically used by
  202. the kernel at boot time.
  203. .TP
  204. .B \-u
  205. causes the agent to prompt for user
  206. id and writes it to
  207. .BR /dev/hostowner .
  208. It is mutually exclusive with
  209. .B \-k
  210. and
  211. .BR \-S .
  212. This option is typically used by
  213. the kernel at boot time.
  214. .TP
  215. .B \-p
  216. causes the agent not to mark itself `private'
  217. via
  218. .IR proc (3),
  219. so that it can be debugged.
  220. It is implied by
  221. .BR \-d .
  222. .PD
  223. .PP
  224. .I Fgui
  225. is a graphic user interface for confirming key usage and
  226. entering new keys. It hides the window in which it starts
  227. and waits reading requests from
  228. .B confirm
  229. and
  230. .BR needkey .
  231. For each requests, it unhides itself and waits for
  232. user input.
  233. See the sections on key confirmation and key prompting below.
  234. .SS "Key Tuples
  235. .PP
  236. A
  237. .I "key tuple
  238. is a space delimited list of
  239. .IB attribute = value
  240. pairs. An attribute whose name begins with an exclamation point
  241. .RB ( ! )
  242. does not appear when reading the
  243. .B ctl
  244. file.
  245. The required attributes depend on the authentication protocol.
  246. .PP
  247. .BR P9sk1 ,
  248. .BR p9sk2 ,
  249. and
  250. .BR p9cr
  251. all require a key with
  252. .BR proto = p9sk1 ,
  253. a
  254. .B dom
  255. attribute identifying the authentication domain, a
  256. .B user
  257. name valid in that domain, and either a
  258. .B !password
  259. or
  260. .B !hex
  261. attribute specifying the password or hexadecimal secret
  262. to be used. Here is an example:
  263. .PP
  264. .EX
  265. proto=p9sk1 dom=avayalabs.com user=presotto !password=lucent
  266. .EE
  267. .PP
  268. .BR Apop ,
  269. .BR cram ,
  270. .BR chap ,
  271. and
  272. .BR mschap ,
  273. require a key with a
  274. .B proto
  275. attribute whose value matches the protocol,
  276. in addition to
  277. .BR server ,
  278. .BR user ,
  279. and
  280. .B !password
  281. attributes;
  282. e.g.
  283. .PP
  284. .EX
  285. proto=apop server=mit.edu user=rsc !password=nerdsRus
  286. .EE
  287. Vnc is similar but does not require a
  288. .B user
  289. attribute.
  290. .PP
  291. .B Pass
  292. requires a key with
  293. .B proto=pass
  294. in addition to
  295. .B user
  296. and
  297. .B !password
  298. attributes; e.g.
  299. .PP
  300. .EX
  301. proto=pass user=tb !password=does.it.matter
  302. .EE
  303. .PP
  304. .B Rsa
  305. requires a key with
  306. .B proto=rsa
  307. in addition to all the hex attributes defining an RSA key:
  308. .BR ek ,
  309. .BR n ,
  310. .BR !p ,
  311. .BR !q ,
  312. .BR !kp ,
  313. .BR !kq ,
  314. .BR !c2 ,
  315. and
  316. .BR !dk .
  317. By convention, programs using the RSA protocol also require a
  318. .B service
  319. attribute set to
  320. .BR ssh ,
  321. .BR sshserve ,
  322. or
  323. .BR tls .
  324. .PP
  325. .B Wep
  326. requires a
  327. .BR key1 ,
  328. .BR key2 ,
  329. or
  330. .BR key3
  331. set to the password to be used.
  332. Starting the protocol causes
  333. .I factotum
  334. to configure the wireless ethernet card
  335. .B #l/ether0
  336. for WEP encryption with the given password.
  337. .PP
  338. All keys can have additional attributes that act either as comments
  339. or as selectors to distinguish them in the
  340. .IR auth (2)
  341. library calls.
  342. .PP
  343. The factotum owner can use any key stored by factotum.
  344. Any key may have one or more
  345. .B owner
  346. attributes listing the users who can use the key
  347. as though they were the owner.
  348. For example, the TLS and SSH host keys on a server
  349. often have an attribute
  350. .B owner=*
  351. to allow any user (and in particular,
  352. .LR none )
  353. to run the TLS or SSH server-side protocol.
  354. .PP
  355. Any key may have a
  356. .B role
  357. attribute for restricting how it can be used.
  358. If this attribute is missing, the key can be used in any role.
  359. The possible values are:
  360. .TP
  361. .B client
  362. for authenticating outbound calls
  363. .TP
  364. .B server
  365. for authenticating inbound calls
  366. .TP
  367. .B speakfor
  368. for authenticating processes whose
  369. user id does not match
  370. .IR factotum 's.
  371. .PP
  372. If a key has a
  373. .B disabled
  374. attribute (with any value), the key is not used
  375. during any protocols. Factotum automatically marks
  376. keys with
  377. .B disabled=by.factotum
  378. when they fail during certain authentication
  379. protocols (in particular, the Plan 9 ones).
  380. .PD
  381. .PP
  382. Whenever
  383. .I factotum
  384. runs as a server, it must have a
  385. .B p9sk1
  386. key in order to communicate with the authentication
  387. server for validating passwords and challenge/responses of
  388. other users.
  389. .SS "Key Templates
  390. Key templates are used by routines that interface to
  391. .I factotum
  392. such as
  393. .B auth_proxy
  394. and
  395. .B auth_challenge
  396. (see
  397. .IR auth (2))
  398. to specify which key and protocol to use for an authentication.
  399. Like a key tuple, a key template is also a list of
  400. .IB attribute = value
  401. pairs.
  402. It must specify at least the protocol and enough
  403. other attributes to uniquely identify a key, or set of keys, to use.
  404. The keys chosen are those that match all the attributes specified
  405. in the template. The possible attribute/value formats are:
  406. .TP 1i
  407. .IB attr = val
  408. The attribute
  409. .I attr
  410. must exist in the key and its value must exactly
  411. match
  412. .I val
  413. .TP 1i
  414. .IB attr ?
  415. The attribute
  416. .I attr
  417. must exist in the key but its value doesn't matter.
  418. .TP 1i
  419. .I attr
  420. The attribute
  421. .I attr
  422. must exist in the key with a null value
  423. .PD
  424. .PP
  425. Key templates are also used by factotum to request a key either via
  426. an RPC error or via the
  427. .B needkey
  428. interface.
  429. The possible attribute/value formats are:
  430. .TP 1i
  431. .IB attr = val
  432. This pair must remain unchanged
  433. .TP 1i
  434. .IB attr ?
  435. This attribute needs a value
  436. .TP 1i
  437. .I attr
  438. The pair must remain unchanged
  439. .PD
  440. .SS "Control and Key Management
  441. .PP
  442. A number of messages can be written to the control file.
  443. The messages are:
  444. .TP
  445. .B "key \fIattribute-value-list\fP
  446. add a new key. This will replace any old key whose
  447. public, i.e. non ! attributes, match.
  448. .TP
  449. .B "delkey \fIattribute-value-list\fP
  450. delete a key whose attributes match those given.
  451. .TP
  452. .B debug
  453. toggle debugging on and off, i.e., the debugging also
  454. turned on by the
  455. .B \-d
  456. option.
  457. .PP
  458. By default when factotum starts it looks for a
  459. .IR secstore (1)
  460. account on $auth for the user and, if one exists,
  461. prompts for a secstore password in order to fetch
  462. the file
  463. .IR factotum ,
  464. which should contain control file commands.
  465. An example would be
  466. .EX
  467. key dom=x.com proto=p9sk1 user=boyd !hex=26E522ADE2BBB2A229
  468. key proto=rsa service=ssh size=1024 ek=3B !dk=...
  469. .EE
  470. where the first line sets a password for
  471. challenge/response authentication, strong against dictionary
  472. attack by being a long random string, and the second line
  473. sets a public/private keypair for ssh authentication,
  474. generated by
  475. .B ssh_genkey
  476. (see
  477. .IR ssh (1)).
  478. .PD
  479. .SS "Confirming key use
  480. .PP
  481. The
  482. .B confirm
  483. file provides a connection from
  484. .I factotum
  485. to a confirmation server, normally the program
  486. .IR auth/fgui .
  487. Whenever a key with the
  488. .B confirm
  489. attribute is used,
  490. .I factotum
  491. requires confirmation of its use. If no process has
  492. .B confirm
  493. opened, use of the key will be denied.
  494. However, if the file is opened a request can be read from it
  495. with the following format:
  496. .PP
  497. .B confirm
  498. .BI tag= tagno
  499. .I "<key template>
  500. .PP
  501. The reply, written back to
  502. .BR confirm ,
  503. consists of string:
  504. .PP
  505. .BI tag= tagno
  506. .BI answer= xxx
  507. .PP
  508. If
  509. .I xxx
  510. is the string
  511. .B yes
  512. then the use is confirmed and the authentication will proceed.
  513. Otherwise, it fails.
  514. .PP
  515. .B Confirm
  516. is exclusive open and can only be opened by a process with
  517. the same user id as
  518. .IR factotum .
  519. .SS "Prompting for keys
  520. .PP
  521. The
  522. .B needkey
  523. file provides a connection from
  524. .I factotum
  525. to a key server, normally the program
  526. .IR auth/fgui .
  527. Whenever
  528. .I factotum
  529. needs a new key, it first checks to see if
  530. .B needkey
  531. is opened. If it isn't, it returns a error to its client.
  532. If the file is opened a request can be read from it
  533. with the following format:
  534. .PP
  535. .B needkey
  536. .BI tag= tagno
  537. .I "<key template>
  538. .PP
  539. It is up to the reader to then query the user for any missing fields,
  540. write the key tuple into the
  541. .B ctl
  542. file, and then reply by writing into the
  543. .B needkey
  544. file the string:
  545. .PP
  546. .BI tag= tagno
  547. .PP
  548. .B Needkey
  549. is exclusive open and can only be opened by a process with
  550. the same user id as
  551. .IR factotum .
  552. .SS "The RPC Protocol
  553. Authentication is performed by
  554. .IP 1)
  555. opening
  556. .BR rpc
  557. .IP 2)
  558. setting up the protocol and key to be used (see the
  559. .B start
  560. RPC below),
  561. .IP 3)
  562. shuttling messages back and forth between
  563. .IR factotum
  564. and the other party (see the
  565. .B read
  566. and
  567. .B write
  568. RPC's) until done
  569. .IP 4)
  570. if successful, reading back an
  571. .I AuthInfo
  572. structure (see
  573. .IR authsrv (2)).
  574. .PP
  575. The RPC protocol is normally embodied by one of the
  576. routines in
  577. .IR auth (2).
  578. We describe it here should anyone want to extend
  579. the library.
  580. .PP
  581. An RPC consists of writing a request message to
  582. .B rpc
  583. followed by reading a reply message back.
  584. RPC's are strictly ordered; requests and replies of
  585. different RPC's cannot be interleaved.
  586. Messages consist of a verb, a single space, and data.
  587. The data format depends on the verb. The request verbs are:
  588. .TP
  589. .B "start \fIattribute-value-list\fP
  590. start a new authentication.
  591. .I Attribute-value-pair-list
  592. must include a
  593. .B proto
  594. attribute, a
  595. .B role
  596. attribute with value
  597. .B client
  598. or
  599. .BR server ,
  600. and enough other attributes to uniquely identify a key to use.
  601. A
  602. .B start
  603. RPC is required before any others. The possible replies are:
  604. .RS
  605. .TP
  606. .B ok
  607. start succeeded.
  608. .TP
  609. .B "error \fIstring\fP
  610. where
  611. .I string
  612. is the reason.
  613. .RE
  614. .PD
  615. .TP
  616. .B read
  617. get data from
  618. .I factotum
  619. to send to the other party. The possible replies are:
  620. .RS
  621. .TP
  622. .B ok
  623. read succeeded, this is zero length message.
  624. .TP
  625. .B "ok \fIdata\fP
  626. read succeeded, the data follows the space and is
  627. unformatted.
  628. .TP
  629. .B "done
  630. authentication has succeeded, no further RPC's are
  631. necessary
  632. .TP
  633. .B "done haveai
  634. authentication has succeeded, an
  635. .B AuthInfo
  636. structure (see
  637. .IR auth (2))
  638. can be retrieved with an
  639. .B authinfo
  640. RPC
  641. .TP
  642. .B "phase \fIstring\fP
  643. its not your turn to read, get some data from
  644. the other party and return it with a write RPC.
  645. .TP
  646. .B "error \fIstring\fP
  647. authentication failed,
  648. .I string
  649. is the reason.
  650. .TP
  651. .B "protocol not started
  652. a
  653. .B start
  654. RPC needs to precede reads and writes
  655. .TP
  656. .B "needkey \fIattribute-value-list\fP
  657. a key matching the argument is needed. This argument
  658. may be passed as an argument to
  659. .I factotum
  660. .B -g
  661. in order to prompt for a key. After that, the
  662. authentication may proceed, i.e., the read restarted.
  663. .PD
  664. .RE
  665. .TP
  666. .B "write \fIdata\fP
  667. send data from the other party to
  668. .IR factotum .
  669. The possible replies are:
  670. .RS
  671. .TP
  672. .B "ok
  673. the write succeeded
  674. .TP
  675. .B "needkey \fIattribute-value-list\fP
  676. see above
  677. .TP
  678. .B "toosmall \fIn\fP
  679. the write is too short, get more data from the
  680. other party and retry the write.
  681. .I n
  682. specifies the maximun total number of bytes.
  683. .TP
  684. .B "phase \fIstring\fP
  685. its not your turn to write, get some data from
  686. .I factotum
  687. first.
  688. .TP
  689. .B "done
  690. see above
  691. .TP
  692. .B "done haveai
  693. see above
  694. .RE
  695. .TP
  696. .B authinfo
  697. retrieve the AuthInfo structure.
  698. The possible replies are:
  699. .RS
  700. .TP
  701. .B "ok \fIdata\fP
  702. .I data
  703. is a marshaled form of the AuthInfo structure.
  704. .TP
  705. .B "error \fIstring\fP
  706. where
  707. .I string
  708. is the reason for the error.
  709. .PD
  710. .RE
  711. .TP
  712. .B attr
  713. retrieve the attributes used in the
  714. .B start
  715. RPC.
  716. The possible replies are:
  717. .RS
  718. .TP
  719. .B "ok \fIattribute-value-list\fP
  720. .TP
  721. .B "error \fIstring\fP
  722. where
  723. .I string
  724. is the reason for the error.
  725. .PD
  726. .RE
  727. .SH SOURCE
  728. .B /sys/src/cmd/auth/factotum