authsrv 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726
  1. .TH AUTHSRV 6
  2. .SH NAME
  3. authsrv, p9any, p9sk1, p9sk2 \- authentication protocols
  4. .SH DESCRIPTION
  5. This manual page describes
  6. the protocols used to authorize connections, confirm the identities
  7. of users and machines, and maintain the associated databases.
  8. The machine that provides these services is called the
  9. .I authentication server
  10. (AS).
  11. The AS may be a stand-alone machine or a general-use machine such as a CPU server.
  12. The network database
  13. .IR ndb (6)
  14. holds for each public machine, such as a CPU server or
  15. file server, the name of the authentication server that machine uses.
  16. .PP
  17. Each machine contains three values important to authentication; a 56-bit DES
  18. key, a 28-byte authentication ID, and a 48-byte authentication domain name.
  19. The ID is a user name and identifies who is currently responsible for the
  20. kernel running on that machine.
  21. The domain name identifies the machines across which the ID is valid.
  22. Together, the ID and domain name identify the owner of a key.
  23. .PP
  24. When a terminal boots,
  25. .IR factotum (4)
  26. prompts for user name and password.
  27. The user name becomes the terminal's authentication ID.
  28. The password is converted using
  29. .I passtokey
  30. (see
  31. .IR authsrv (2))
  32. into a 56-bit DES key and saved in memory.
  33. The authentication domain is set to the null string.
  34. If possible,
  35. .I factotum
  36. validates the key with the AS
  37. before saving it.
  38. For Internet machines the correct AS to ask is found using
  39. .IR dhcpd (8).
  40. .PP
  41. When a CPU or file server boots,
  42. .I factotum
  43. reads the key, ID, and domain name from
  44. non-volatile RAM.
  45. This allows servers to reboot without operator intervention.
  46. .PP
  47. The details of any authentication are mixed with the semantics
  48. of the particular service they are authenticating so we describe
  49. them one case at a time. The following definitions will be used
  50. in the descriptions:
  51. .TF nullx
  52. .TP
  53. .I Ks
  54. server's host ID's key
  55. .TP
  56. .I Kc
  57. client's host ID's key
  58. .TP
  59. .I Kn
  60. a nonce key created for a ticket
  61. .RB ( key )
  62. .TP
  63. .IR K { m }
  64. message
  65. .I m
  66. encrypted with key
  67. .I K
  68. .TP
  69. .I CHc
  70. an 8-byte random challenge from a client
  71. .RB ( chal )
  72. .TP
  73. .I CHs
  74. an 8-byte random challenge from a server
  75. .RB ( chal )
  76. .TP
  77. .I IDs
  78. server's ID
  79. .RB ( authid )
  80. .TP
  81. .I DN
  82. server's authentication domain name
  83. .RB ( authdom )
  84. .TP
  85. .I IDc
  86. client's ID
  87. .RB ( hostid ,
  88. .BR cuid )
  89. .TP
  90. .I IDr
  91. client's desired ID on server
  92. .RB ( uid ,
  93. .BR suid )
  94. .PD
  95. .PP
  96. The parenthesized names are the ones used in the
  97. .B Ticketreq
  98. and
  99. .B Ticket
  100. structures in
  101. .BR <authsrv.h> .
  102. .PP
  103. The message type constants
  104. .IR AuthTreq ,
  105. .IR AuthChal ,
  106. .IR AuthPass ,
  107. .IR AuthOK ,
  108. .IR AuthErr ,
  109. .IR AuthMod ,
  110. .IR AuthApop ,
  111. .IR AuthOKvar ,
  112. .IR AuthChap ,
  113. .IR AuthMSchap ,
  114. .IR AuthCram ,
  115. and
  116. .IR AuthVNC
  117. .RB ( type )
  118. are defined in
  119. .BR <authsrv.h> ,
  120. as are the encrypted message types
  121. .IR AuthTs ,
  122. .IR AuthAs ,
  123. .IR AuthAc ,
  124. .IR AuthTp ,
  125. and
  126. .IR AuthHr
  127. .RB ( num ).
  128. .SS "Ticket Service
  129. When a client and server wish to authenticate to each other,
  130. they do so using
  131. .I tickets
  132. issued by the AS.
  133. Obtaining tickets from the AS
  134. is the client's responsibility.
  135. .PP
  136. The protocol to obtain a ticket pair is:
  137. .TP
  138. .IR C \(-> A
  139. .IR AuthTreq ,
  140. .IR IDs ,
  141. .IR DN ,
  142. .IR CHs ,
  143. .IR IDc ,
  144. .IR IDr
  145. .sp -\n(PDu
  146. .TP
  147. .IR A \(-> C
  148. .IR AuthOK ,
  149. .IR Kc { AuthTc ,
  150. .IR CHs ,
  151. .IR IDc ,
  152. .IR IDr ,
  153. .IR Kn },
  154. .IR Ks { AuthTs ,
  155. .IR CHs ,
  156. .IR IDc ,
  157. .IR IDr ,
  158. .IR Kn }
  159. .PP
  160. The two tickets are identical except for their type fields
  161. and the keys with which they are encrypted.
  162. The client and server can each decrypt one of the tickets,
  163. establishing a shared secret
  164. .IR Kn .
  165. .PP
  166. The
  167. tickets can be viewed as a statement by the
  168. AS that
  169. ``a client possessing the
  170. .I Kn
  171. key is allowed to authenticate as
  172. .IR IDr .''
  173. .PP
  174. The presence of the server challenge
  175. .I CHs
  176. in the ticket allows the server to verify the freshness
  177. of the ticket pair.
  178. .PP
  179. The AS sets the
  180. .I IDr
  181. in the tickets to the requested
  182. .I IDr
  183. only if
  184. .I IDc
  185. is allowed to
  186. .I "speak for
  187. .RI ( q.v. )
  188. .IR IDr .
  189. If not,
  190. the AS sets
  191. .I IDr
  192. to the empty string.
  193. .PP
  194. If the users
  195. .I IDc
  196. or
  197. .I IDs
  198. do not exist,
  199. the AS silently generates one-time
  200. random keys to use in place of
  201. .I Kc
  202. or
  203. .IR Ks ,
  204. so that clients cannot probe the AS
  205. to learn whether a user name is valid.
  206. .SS "P9sk1
  207. The Plan 9 shared key protocol
  208. .I p9sk1
  209. allows a client and server to authenticate each other.
  210. The protocol is:
  211. .TP
  212. .IR C \(-> S
  213. .I CHc
  214. .br
  215. The client starts by sending a random challenge to the server.
  216. .TP
  217. .IR S \(-> C
  218. .IR AuthTreq ,
  219. .IR IDs ,
  220. .IR DN ,
  221. .IR CHs ,
  222. .IR \- ,
  223. .IR \-
  224. .br
  225. The server replies with a ticket request giving its
  226. id and authentication domain along with its own
  227. random challenge.
  228. .TP
  229. .IR C \(-> S
  230. .IR Ks { AuthTs ,
  231. .IR CHs ,
  232. .IR IDc ,
  233. .IR IDr ,
  234. .IR Kn },
  235. .IR Kn { AuthAc ,
  236. .IR CHs }
  237. .br
  238. The client adds
  239. .I IDc
  240. and
  241. .I IDr
  242. to the ticket request and obtains a ticket pair
  243. from the AS as described above.
  244. The client relays the server's ticket along with
  245. an
  246. .IR authenticator ,
  247. the
  248. .I AuthAc
  249. message.
  250. The authenticator proves to the server that the
  251. client knows
  252. .I Kn
  253. and is therefore allowed to authenticate as
  254. .IR IDr .
  255. (The inclusion of
  256. .IR CHs
  257. in the authenticator avoids replay attacks.)
  258. .TP
  259. .IR S \(-> C
  260. .IR Kn { AuthAs ,
  261. .IR CHc }
  262. .br
  263. The server replies with its own authenticator,
  264. proving to the client that it also knows
  265. .I Kn
  266. and therefore
  267. .I Ks .
  268. .PD
  269. .PP
  270. .I P9sk2
  271. is an older variant of
  272. .I p9sk1
  273. used only when connecting to pre-9P2000 remote
  274. execution services.
  275. It omits the first message and last
  276. messages and therefore does not
  277. authenticate the server to the client.
  278. .SS "P9any
  279. .I P9any
  280. is the standard Plan 9 authentication protocol.
  281. It consists of a negotiation to determine a common
  282. protocol, followed by the agreed-upon protocol.
  283. .PP
  284. The negotiation protocol is:
  285. .TP
  286. .IR S \(-> C
  287. .B v.2
  288. .IB proto@authdom
  289. .IB proto@authdom
  290. .I ...
  291. .sp -\n(PDu
  292. .TP
  293. .IR C \(-> S
  294. .I proto
  295. .I dom
  296. .sp -\n(PDu
  297. .TP
  298. .IR S \(-> C
  299. .B OK
  300. .PP
  301. Each message is a NUL-terminated UTF string.
  302. The server begins by sending a list of
  303. .IR proto ,
  304. .I authdom
  305. pairs it is willing to use.
  306. The client
  307. responds with its choice.
  308. Requiring the client to wait for the final
  309. .B OK
  310. ensures that the client will not start
  311. the chosen protocol until the server is ready.
  312. .PP
  313. The above is version 2 of the protocol.
  314. Version 1,
  315. no longer used,
  316. omitted the first message's
  317. .B v.2
  318. prefix
  319. and the
  320. .B OK
  321. message.
  322. .PP
  323. The
  324. .I p9any
  325. protocol is the protocol used by all
  326. Plan 9 services.
  327. The file server runs it over special
  328. authentication files
  329. (see
  330. .IR fauth (2)
  331. and
  332. .IR attach (5)).
  333. Other services, such as
  334. .IR cpu (1)
  335. and
  336. .IR exportfs (4),
  337. run
  338. .I p9any
  339. over the network and then
  340. use
  341. .I Kn
  342. to derive an
  343. .IR ssl (3)
  344. key to encrypt the rest of their communications.
  345. .SS "Password Change
  346. Users connect directly to the AS
  347. to change their passwords.
  348. The protocol is:
  349. .TP
  350. .IR C \(-> A
  351. .IR AuthPass ,
  352. .IR IDc ,
  353. .IR DN ,
  354. .IR CHc ,
  355. .IR IDc ,
  356. .IR IDc
  357. .br
  358. The client sends a password change ticket request.
  359. .TP
  360. .IR A \(-> C
  361. .IR Kc { AuthTp ,
  362. .IR CHc ,
  363. .IR IDc ,
  364. .IR IDc ,
  365. .IR Kn }
  366. .br
  367. The server responds with a ticket containing the key
  368. .I Kn
  369. encrypted with the client's key
  370. .IR Kc
  371. .TP
  372. .IR C \(-> A
  373. .IR Kn { AuthPass ,
  374. .IR old ,
  375. .IR new ,
  376. .IR changesecret ,
  377. .IR secret }
  378. .br
  379. The client decrypts the ticket using the old password
  380. and then sends back an encrypted password request
  381. .RB ( Passwordreq
  382. structure)
  383. containing the old password and the new password.
  384. If
  385. .I changesecret
  386. is set, the AS also changes
  387. the user's
  388. .IR secret ,
  389. the password used for non-Plan 9 authentications.
  390. .TP
  391. .IR A \(-> C
  392. .I AuthOK
  393. or
  394. .IR AuthErr ,
  395. 64-byte error message
  396. .br
  397. The AS responds with simply
  398. .I AuthOK
  399. or with
  400. .I AuthErr
  401. followed by a 64-byte error message.
  402. .SS "Authentication Database
  403. An
  404. .IR ndb (2)
  405. database file
  406. .B /lib/ndb/auth
  407. exists for the AS.
  408. This database maintains ``speaks for'' relationships, i.e.,
  409. it lists which users may speak for other users when
  410. authtenticating.
  411. The attribute types used by the AS are
  412. .B hostid
  413. and
  414. .BR uid .
  415. The value in the
  416. .B hostid
  417. is a client host's ID.
  418. The values in the
  419. .B uid
  420. pairs in the same entry list which users that host ID
  421. make speak for.
  422. A uid value of
  423. .B *
  424. means the host ID may speak for all users.
  425. A uid value of
  426. .BI ! user
  427. means the host ID may not speak for
  428. .IR user .
  429. For example:
  430. .PP
  431. .EX
  432. hostid=bootes
  433. uid=!sys uid=!adm uid=*
  434. .EE
  435. .PP
  436. is interpreted as
  437. .B bootes
  438. may speak for any user except
  439. .B sys
  440. and
  441. .BR adm .
  442. This property is used heavily on CPU servers.
  443. .SS "Foreign Protocols
  444. The AS accepts ticket request
  445. messages of types other than
  446. .I AuthTreq
  447. to allow users to
  448. authenticate using non-Plan 9 protocols.
  449. In these situations, the server communicates
  450. directly with the AS.
  451. Some protocols must begin without knowing the
  452. client's name. They ignore the client name in the
  453. ticket request.
  454. All the protocols end
  455. with the AS sending
  456. an
  457. .I AuthOK
  458. message containing a server ticket and authenticator.
  459. .PP
  460. .I AuthOK
  461. messages
  462. always have a fixed but context-dependent size.
  463. The occasional variable-length OK message starts with a
  464. .I AuthOKvar
  465. byte and a five-byte space-padded decimal length of the
  466. data that follows.
  467. .PP
  468. Anywhere an
  469. .I AuthOK
  470. message is expected, a
  471. .I AuthErr
  472. message may be substituted.
  473. .de Ok
  474. .sp -\n(PDu
  475. .TP
  476. .IR A \(-> S
  477. .IR AuthOK ,
  478. .IR Ks { \\$1 ,
  479. .IR IDs ,
  480. .IR DN ,
  481. .IR CHs ,
  482. .IR IDs ,
  483. .IR IDc ,
  484. .IR Kn },
  485. .IR Kn { AuthTs ,
  486. .IR CHs }
  487. ..
  488. .PP
  489. .TP
  490. .IR S \(-> A
  491. .IR AuthChal ,
  492. .IR IDs ,
  493. .IR DN ,
  494. .IR CHs ,
  495. .IR IDs ,
  496. .IR IDc
  497. .sp -\n(PDu
  498. .TP
  499. .IR A \(-> S
  500. .IR AuthOK ,
  501. .IR challenge
  502. .sp -\n(PDu
  503. .TP
  504. .IR S \(-> A
  505. .IR response
  506. .Ok AuthChal
  507. .IP
  508. This protocol allows the use of
  509. handheld authenticators such as SecureNet
  510. keys and SecureID tokens
  511. in programs such as
  512. .IR ssh (1)
  513. and
  514. .I ftpd
  515. (see
  516. .IR ipserv (8)).
  517. .IP
  518. .I Challenge
  519. and
  520. .I response
  521. are text strings,
  522. .SM NUL -padded
  523. to 16 bytes
  524. .RB ( NETCHLEN ).
  525. The
  526. .I challenge
  527. is a random five-digit decimal number.
  528. When using a SecureNet key or
  529. .I netkey
  530. (see
  531. .IR passwd (1)),
  532. the
  533. .I response
  534. is an eight-digit decimal or hexadecimal number
  535. that is an encryption of the challenge
  536. using the user's DES key.
  537. .IP
  538. When using a SecureID token,
  539. the challenge is ignored.
  540. The response is the user's PIN followed by
  541. the six-digit number currently displayed
  542. on the token.
  543. In this case, the AS
  544. queries an external RADIUS server
  545. to check the response.
  546. Use of a RADIUS server requires an entry in
  547. the authentication database. For example:
  548. .IP
  549. .EX
  550. radius=server-name secret=xyzzy
  551. uid=howard rid=trickey
  552. uid=sape rid=smullender
  553. .EE
  554. .IP
  555. In this example, the secret
  556. .B xyzzy
  557. is the hash key used in talking to the RADIUS server.
  558. The
  559. .BR uid / rid
  560. lines map from Plan 9 user ids to RADIUS ids.
  561. Users not listed are assumed to have the
  562. same id in both places.
  563. .TP
  564. .IR S \(-> A
  565. AuthApop ,
  566. .IR IDs ,
  567. .IR DN ,
  568. .IR CHs ,
  569. .IR \- ,
  570. .IR \-
  571. .sp -\n(PDu
  572. .TP
  573. .IR A \(-> S
  574. .IR AuthOKvar ,
  575. .IR challenge
  576. .sp -\n(PDu
  577. .TP
  578. .IR S \(-> A
  579. AuthApop ,
  580. .IR IDs ,
  581. .IR DN ,
  582. .IR CHs ,
  583. .IR IDc ,
  584. .IR IDc ;
  585. hexadecimal MD5 checksum
  586. .Ok AuthApop
  587. .IP
  588. This protocol implements APOP authentication
  589. (see
  590. .IR pop3 (8)).
  591. After receiving a ticket request of type
  592. .IR AuthApop ,
  593. the AS generates a random challenge
  594. of the form
  595. .BI < random @ domain >\fR.
  596. The client then replies with a new ticket request
  597. giving the user name
  598. followed by the MD5 checksum of
  599. the challenge concatenated with the user's secret.
  600. If the response is correct, the authentication
  601. server sends back a ticket
  602. and authenticator.
  603. If the response is incorrect, the client may repeat the
  604. ticket request/MD5 checksum message to try again.
  605. .IP
  606. The
  607. .I AuthCram
  608. protocol runs identically to the
  609. .I AuthApop
  610. protocol, except that the expected MD5 checksum
  611. is the keyed MD5 hash using the user's secret as the key
  612. (see
  613. .I hmac_md5
  614. in
  615. .IR sechash (2)).
  616. .TP
  617. .IR S \(-> A
  618. .IR AuthChap ,
  619. .IR IDs ,
  620. .IR DN ,
  621. .IR CHs ,
  622. .IR \- ,
  623. .IR \-
  624. .sp -\n(PDu
  625. .TP
  626. .IR A \(-> S
  627. .I challenge
  628. .sp -\n(PDu
  629. .TP
  630. .IR S \(-> A
  631. .IR pktid ,
  632. .IR IDc ,
  633. .IR response
  634. .Ok AuthChap
  635. .IP
  636. This protocol implements CHAP authentication
  637. (see
  638. .IR ppp (8)).
  639. The
  640. .I challenge
  641. is eight random bytes.
  642. The response is a 16-byte MD5 checksum
  643. over the packet id, user's secret, and challenge.
  644. The reply packet is defined as
  645. .B OChapreply
  646. in
  647. .BR <authsrv.h> .
  648. .TP
  649. .IR S \(-> A
  650. .IR AuthMSchap ,
  651. .IR IDs ,
  652. .IR DN ,
  653. .IR CHs ,
  654. .IR \- ,
  655. .IR \-
  656. .sp -\n(PDu
  657. .TP
  658. .IR A \(-> S
  659. .I challenge
  660. .sp -\n(PDu
  661. .TP
  662. .IR S \(-> A
  663. .IR IDc ,
  664. .IR lm-response ,
  665. .IR nt-response
  666. .Ok AuthMschap
  667. .IP
  668. This protocol implements Microsoft's MS-CHAP
  669. authentication
  670. (see
  671. .IR ppp (8)).
  672. The
  673. .I challenge
  674. is eight random bytes.
  675. The two responses are Microsofts LM and NT hashes.
  676. Only the NT hash may be used to authenticate,
  677. as the LM hash is considered too weak.
  678. The reply packet is defined as
  679. .B OMSchapreply
  680. in
  681. .BR <authsrv.h> .
  682. .TP
  683. .IR S \(-> A
  684. .IR AuthVNC ,
  685. .IR IDs ,
  686. .IR DN ,
  687. .IR CHs ,
  688. .IR IDs ,
  689. .IR IDc
  690. .sp -\n(PDu
  691. .TP
  692. .IR A \(-> S
  693. .IR AuthOKvar ,
  694. .I challenge
  695. .sp -\n(PDu
  696. .TP
  697. .IR S \(-> A
  698. .I response
  699. .Ok
  700. .IP
  701. This protocol implements VNC authentication
  702. (see
  703. .I vncs
  704. in
  705. .IR vnc (1)).
  706. The challenge is 16 random bytes, and the response
  707. is a DES ECB encryption of the challenge.
  708. The method by which VNC converts the user's
  709. secret into a DES key is weak,
  710. considering only the first eight bytes of the secret.
  711. .PD
  712. .SH FILES
  713. .TF /lib/ndb/auth.*xxx
  714. .TP
  715. .B /lib/ndb/auth
  716. database file
  717. .TP
  718. .B /lib/ndb/auth.*
  719. hash files for
  720. .B /lib/ndb/auth
  721. .SH SEE ALSO
  722. .IR auth (2),
  723. .IR fauth (2),
  724. .IR cons (3),
  725. .IR attach (5),
  726. .IR auth (8)