home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / X / mit / doc / XDMCP / xdmcp.ms < prev    next >
Encoding:
Text File  |  1991-07-28  |  47.3 KB  |  1,891 lines
  1. .\" Use eqn, tbl, and -ms
  2. .\" $XConsortium: xdmcp.ms,v 1.18 91/07/28 15:48:25 rws Exp $
  3. .EQ
  4. delim @@
  5. define oc % "\\fR{\\fP" %
  6. define cc % "\\fR}\\fP" %
  7. .EN
  8. .de PT
  9. ..
  10. .de BT
  11. ..
  12. .fp 6 I
  13. .fp 7 C
  14. .fp 8 CB
  15. .ps 10
  16. .nr PS 10
  17. \&
  18. .TL
  19. \s+2\fBX Display Manager Control Protocol\fP\s-2
  20. .sp
  21. Version 1.0
  22. .sp
  23. MIT X Consortium Standard
  24. .sp
  25. X Version 11, Release 5
  26. .AU
  27. Keith Packard
  28. .AI
  29. X Consortium
  30. Laboratory for Computer Science
  31. Massachusetts Institute of Technology
  32. .AB
  33. .LP
  34. Since the X Display Manager (xdm) may be used to manage remote displays (such
  35. as X terminals), a protocol for requesting service over the network is
  36. needed.  Since the display manager is a scarce resource, the X Display
  37. Manager Control Protocol (also called XDMCP) is designed to use unreliable
  38. datagrams and places the bulk of the burden for sequencing and retransmission
  39. on the display.  A standard byte order and synchronous responses reduces the
  40. complexity of the protocol.
  41. .AE
  42. .LP
  43. .DS C
  44. Copyright \(co 1989 by the Massachusetts Institute of Technology
  45. .DE
  46. .sp 3
  47. .LP
  48. Permission to use, copy, modify, and distribute this documentation for any
  49. purpose and without fee is hereby granted, provided that the above copyright
  50. notice and this permission notice appear in all copies.  MIT makes no
  51. representations about the suitability for any purpose of the information in
  52. this document.  This documentation is provided ``as is'' without express or
  53. implied warranty.
  54. .de PT
  55. .ie o .tl 'XDMCP''X Display Manager Control Protocol '
  56. .el .tl 'X Display Manager Control Protocol ''XDMCP'
  57. ..
  58. .bp 1
  59. .de BT
  60. .tl ''\fB % \fP''
  61. ..
  62. .NH 1
  63. Purpose and Goals
  64. .LP
  65. The purpose of XDMCP is to provide a uniform mechanism for an autonomous
  66. display to request login service from a remote host.  By "autonomous" we mean
  67. the display consists of hardware and processes that are independent of any
  68. particular host where login service is desired.  (For example, the server
  69. cannot simply be started by a fork/exec sequence on the host.)  An "X terminal"
  70. (screen, keyboard, mouse, processor, network interface) is a prime example of
  71. an autonomous display.
  72. .LP
  73. From the point of view of the end user, it is very important to make
  74. autonomous displays as easy to use as traditional hardwired character
  75. terminals.  Specifically, you can typically just power on a hardwired
  76. terminal, and be greeted with a login prompt.  The same should be possible
  77. with autonomous displays.  However, in a network environment with multiple
  78. hosts, the end user may want to choose which host(s) to connect to.  In an
  79. environment with many displays and many hosts, a site administrator may want
  80. to associate particular collections of hosts with particular displays.  We
  81. would like to support the following options:
  82. .RS
  83. .LP
  84. The display has a "hardwired" host that it should connect to.  It should be
  85. possible to "power on" the display and receive a login prompt, without user
  86. intervention.
  87. .LP
  88. Any one of several hosts on a (sub)net may be acceptable for accepting login
  89. from the display.  (For example, the user's file systems can be mounted onto
  90. any such host, providing comparable environments.)  It should be possible
  91. for the display to "broadcast" to find such hosts, and to have the display
  92. either automatically choose a host, or present the possible hosts to the
  93. user for selection.
  94. .LP
  95. The display has a fixed set of hosts that it can connect to.  It should be
  96. possible for the display to have that set "wired in", but it should also be
  97. possible for a site administrator to be able to maintain host sets for a
  98. large number of displays using a centralized facility, without having to
  99. interact (physically or electronically) with each individual display.
  100. Particular hosts should be allowed to refuse login service, based on
  101. whatever local criteria are desired.
  102. .RE
  103. .LP
  104. The control protocol should be designed in such a way that it can be used over
  105. a reasonable variety of communication transport layers.  In fact, it is quite
  106. desirable if every major network protocol family that supports the standard X
  107. protocol is also capable of supporting XDMCP, since the end result of XDMCP
  108. negotiation will be standard X protocol connections to the display.  However,
  109. since the number of displays per host may be large, a connection-based protocol
  110. appears less desirable than a connection-less protocol.
  111. .LP
  112. In order to keep the burden on displays at a minimum (since display cost is not
  113. a factor that can be ignored), it is desirable that displays not be required to
  114. maintain permanent state (across power cycles) for the purposes of the control
  115. protocol, and it is desirable to keep required state at a minimum while the
  116. display is powered on.
  117. .LP
  118. Security is an important consideration, and must be an integral part of the
  119. design.  The important of security goals in the context of XDMCP are:
  120. .RS
  121. .LP
  122. It should be possible for the display to verify that it is communicating
  123. with a legitimate host login service.  Since the user will present
  124. credentials (e.g. password) to this service, it is important to avoid spoof
  125. attacks.
  126. .LP
  127. It should be possible for the display and the login service to negotiate the
  128. authorization mechanism to be used for the standard X protocol.
  129. .LP
  130. It should be possible to provide the same level of security in verifying the
  131. login service as is provided by the negotiated authorization mechanism.
  132. .LP
  133. Since there are no firm standards yet in the area of security, XDMCP must be
  134. flexible enough to accomodate a variety of security mechanisms.
  135. .RE
  136. .NH 1
  137. Overview of the protocol
  138. .LP
  139. XDMCP is designed to provide authenticated access to display management
  140. services for remote displays.  A new network server, called a \fBDisplay
  141. Manager\fP will use XDMCP to communicate with displays to negotiate the
  142. startup of X sessions.  The protocol allows the display to authenticate the
  143. manager.  It also allows most of the configuration information to be
  144. centralized with the manager, to ease the burden of system administration in
  145. a large network of displays.  The essential goal is to provide plug-and-play
  146. services similar to those provided in the familiar mainframe/terminal world.
  147. .LP
  148. Displays may be turned off by the user at any time.  Any existing session
  149. running on a display which has been turned off must be identifiable.  This
  150. is made possible by requiring a three-way handshake to start a session.  If
  151. the handshake succeeds, any existing session is terminated immediately and a
  152. new session started.  There is the problem (at least with TCP) that
  153. connections may not be closed when the display is turned off.  In most
  154. environments, the manager should reduce this problem by periodically XSync'ing
  155. on its own connection, perhaps every five to ten minutes, and terminating the
  156. session if its own connection ever closes.
  157. .LP
  158. Displays should not be required to retain permanent state for purposes of
  159. the control protocol.  One solution to packets received out of sequence
  160. would be to use monotonically-increasing message identifiers in each message
  161. to allow both sides to ignore messages which arrive out-of-sequence.  For
  162. this to work, displays would at a minimum have to increment a stable "crash
  163. count" each time they are powered on, and use that number as part of a
  164. larger sequence number.  But if displays cannot retain permanent state this
  165. cannot work.  Instead, the manager assumes the responsibility for permanent
  166. state by generating unique numbers which identify a particular session and
  167. the protocol simply ignores packets which correspond to an invalid session.
  168. .LP
  169. The Manager must not be responsible for packet reception.  To prevent the
  170. Manager from becoming stuck because of a hostile display, no portion of the
  171. protocol requires the Manager to retransmit a packet.  Part of this means
  172. that any valid packet which the Manager does receive \fImust\fP be
  173. acknowledged in some way, to prevent the display from continuously resending
  174. packets.  The display can keep the protocol running as it will always know
  175. when the Manager has received (at least one copy of) a packet.  On the
  176. Manager side, this means that any packet may be received more than once (if
  177. the response was lost) and duplicates must be ignored.
  178. .NH 1
  179. Data Types
  180. .LP
  181. XDMCP packets contain several types of data.  Integer values are always
  182. stored most significant byte first in the packet (``Big Endian'' order).
  183. As XDMCP will not be used to transport large quantities of data, this
  184. restriction will not substantially hamper the efficiency of any
  185. implementation.  Also, no padding of any sort will occur within the packets.
  186. .TS
  187. expand;
  188. c c c
  189. c c c
  190. l l l.
  191. Type Name    Length    Description
  192.     (in bytes)
  193. CARD8    1    A single byte unsigned integer
  194. CARD16    2    Two byte unsigned integer
  195. CARD32    4    Four byte unsigned integer
  196. ARRAY8    n+2    This is actually a CARD16 followed by
  197.         a collection of CARD8.  The value of the CARD16
  198.         field (n) specifies the number of CARD8 values to
  199.         follow
  200. ARRAY16    2*m+1    This is a CARD8 (m) which specifies the
  201.         number of CARD16 values to follow
  202. ARRAY32    4*l+1    This is a CARD8 (l) which specifies the
  203.         number of CARD32 values to follow
  204. ARRAYofARRAY8    ?    This is a CARD8 which specifies the
  205.         number of ARRAY8 values to follow.
  206.         
  207. .TE
  208. .NH 1
  209. Packet Format
  210. .LP
  211. All XDMCP packets have the following information:
  212. .TS
  213. expand;
  214. c c c c
  215. c c c c
  216. _ _ _
  217. | c l l | c
  218. | c l l | c
  219. | c l l | c
  220. _ _ _
  221. c l l c.
  222. Length in    Field    Description of field
  223. Bytes    Type    
  224.  
  225. 2    CARD16    version number
  226. 2    CARD16    opcode    packet header
  227. 2    CARD16    n = length of remaining data in bytes
  228.  
  229. n    ???    packet-specific data
  230. .TE
  231. .LP
  232. The fields are as follows:
  233. .LP
  234. Version Number
  235. .RS
  236. This specifies the version of XDMCP that generated this packet in
  237. case changes in this protocol are required.  Displays and
  238. managers may choose to support older versions for compatibility.
  239. This field will initially be 1.
  240. .RE
  241. .LP
  242. Opcode
  243. .RS
  244. This specifies what step of the protocol this packet represents and should
  245. contain one of the following values (encoding provided in section below):
  246. \f8BroadcastQuery\fP, \f8Query\fP, \f8IndirectQuery\fP, \f8ForwardQuery\fP,
  247. \f8Willing\fP, \f8Unwilling\fP, \f8Request\fP, \f8Accept\fP, \f8Decline\fP,
  248. \f8Manage\fP, \f8Refuse\fP, \f8Failed\fP, \f8KeepAlive\fP, \f8Alive\fP.
  249. .RE
  250. .LP
  251. Length of data in bytes
  252. .RS
  253. This specifies the length of the information following the first 6 bytes.
  254. Each packet-type has a different format, and will need to be separately
  255. length-checked against this value.  As every data item has either an
  256. explicit length, or an implicit length, this can be easily accomplished.
  257. Packets that have too little or too much data should be ignored.
  258. .RE
  259. .LP    
  260. Packets should be checked to make sure that they satisfy the following
  261. conditions:
  262. .RS
  263. .IP 1
  264. They must contain valid opcodes.
  265. .IP 2
  266. The length of the remaining data should correspond to the sum of the 
  267. lengths of the individual remaining data items.
  268. .IP 3
  269. The
  270. \f7opcode\fP
  271. should be expected (a finite state diagram is given
  272. in a later section).
  273. .IP 4
  274. If the packet is of type \f8Manage\fP or \f8Refuse\fP, the \f7Session ID\fP
  275. should match the value sent in the preceding \f8Accept\fP packet.
  276. .RE
  277. .NH 1
  278. Protocol
  279. .LP
  280. Each of the opcodes is described below.  Since a given packet type is only
  281. ever sent one way, each packet description below indicates the direction.
  282. Most of the packets have additional information included beyond the
  283. description above.  The additional information is appended to the packet
  284. header in the order described without padding, and the length field is
  285. computed accordingly.
  286. .LP
  287. \f8Query\fP
  288. .br
  289. \f8BroadcastQuery\fP
  290. .br
  291. \f8IndirectQuery\fP
  292. .RS
  293. Display \(-> Manager
  294. .br
  295. Additional Fields:
  296. .RS
  297. \f7Authentication Names\fP:
  298. ARRAYofARRAY8
  299. .RS
  300. A list of authentication names which the display supports.  The manager will
  301. choose one of these and return it in the \f8Willing\fP packet.
  302. .RE
  303. .RE
  304. Semantics:
  305. .RS
  306. A \f8Query\fP packet is sent from the display to a specific host to ask if
  307. that host is willing to provide management services to this display.  The
  308. host should respond with \f8Willing\fP if it is willing to service the
  309. display or \f8Unwilling\fP if it is not.
  310. .LP
  311. A \f8BroadcastQuery\fP packet is similar to the \f8Query\fP packet except
  312. that it is intended to be received by all hosts on the network (or
  313. sub-network).  However, unlike \f8Query\fP requests, hosts that are not
  314. willing to service the display should simply ignore \f8BroadcastQuery\fP
  315. requests.
  316. .LP
  317. An \f8IndirectQuery\fP packet is sent to a well-known manager which forwards
  318. the request to a larger collection of secondary managers using
  319. \f8ForwardQuery\fP packets.  In this way, the collection of managers which
  320. respond can be grouped on other than network boundaries; the use of a
  321. central manager reduces system administrative overhead.  The primary manager
  322. may also send a \f8Willing\fP packet in response to this packet.
  323. .LP
  324. Each packet type has slightly different semantics:
  325. .IP
  326. The \f8Query\fP packet is destined only for a single host.  If the display
  327. is instructed to \f8Query\fP multiple managers, it will send multiple
  328. \f8Query\fP packets.  The \f8Query\fP packet also demands a response from
  329. the manager, either \f8Willing\fP or \f8Unwilling\fP.
  330. .IP
  331. The \f8BroadcastQuery\fP packet is sent to many hosts.  Each manager which
  332. receives this packet will not respond with an \f8Unwilling\fP packet.
  333. .IP
  334. The \f8IndirectQuery\fP packet is sent to only one manager, with the request
  335. that the request be forwarded to a larger list of managers using
  336. \f8ForwardQuery\fP packets.  This list is expected to be maintained at one
  337. central site to reduce administrative overhead.  The function of this packet
  338. type is similar to \f8BroadcastQuery\fP except that \f8BroadcastQuery\fP is
  339. not forwarded.
  340. .RE
  341. Valid Responses:
  342. .RS
  343. \f8Willing\fP, \f8Unwilling\fP
  344. .RE
  345. Problems/Solutions:
  346. .RS
  347. Problem:
  348. .RS
  349. Not all managers receive the query packet.
  350. .RE
  351. .RS
  352. Indication:
  353. .RS
  354. none if \f8BroadcastQuery\fP or \f8IndirectQuery\fP was sent, else failure
  355. to receive \f8Willing\fP.
  356. .RE
  357. Solution:
  358. .RS
  359. Repeatedly send the packet while waiting for user to choose a manager.
  360. .RE
  361. .RE
  362. .RE
  363. Timeout/Retransmission policy:
  364. .RS
  365. An exponential backoff algorithm should be used here to reduce network load
  366. for long-standing idle displays.  Start at 2 seconds, back off by factors of
  367. 2 to 32 seconds and discontinue retransmit after 126 seconds.  The display
  368. should reset the timeout when user-input is detected.  In this way, the
  369. display will ``wakeup'' when touched by the user.
  370. .RE
  371. .RE
  372. .LP
  373. \f8ForwardQuery\fP
  374. .RS
  375. Primary Manager \(-> Secondary Manager
  376. .br
  377. Additional Fields:
  378. .RS
  379. \f7Client Address\fP:
  380. ARRAY8
  381. .RS
  382. The network address of the client display.
  383. .RE
  384. \f7Client Port\fP:
  385. ARRAY8
  386. .RS
  387. An identification of the client task on the client display.
  388. .RE
  389. \f7Authentication Names\fP:
  390. ARRAYofARRAY8
  391. .RS
  392. This is a duplicate of \f7Authentication Names\fP array which was received
  393. in the \f8IndirectQuery\fP
  394. packet.
  395. .RE
  396. .RE
  397. Semantics:
  398. .RS
  399. When primary manager receives a \f8IndirectQuery\fP packet, it is
  400. responsible for sending \f8ForwardQuery\fP packets to an appropriate list of
  401. managers which can provide service to the display using the same network
  402. type as the one the original \f8IndirectQuery\fP packet was received from.
  403. The \f7Client Address\fP and \f7Client Port\fP fields must contain an
  404. address which the secondary manager can use to reach the display also using
  405. this same network.  Each secondary manager sends a \f8Willing\fP packet to
  406. the display if it is willing to provide service.
  407. .LP
  408. \f8ForwardQuery\fP packets are similar to \f8BroadcastQuery\fP packets in
  409. that managers which are not willing to service particular displays should
  410. not send a \f8Unwilling\fP packet.
  411. .RE
  412. Valid Responses:
  413. .RS
  414. \f8Willing\fP
  415. .RE
  416. Problems/Solutions:
  417. .RS
  418. Identical to \f8BroadcastQuery\fP
  419. .RE
  420. Timeout/Retransmission policy:
  421. .RS
  422. Like all packets sent from a manager, this packet should never be
  423. retransmitted.
  424. .RE
  425. .RE
  426. .RE
  427. .LP
  428. \f8Willing\fP
  429. .RS
  430. Manager \(-> Display
  431. .br
  432. Additional Fields:
  433. .RS
  434. \f7Authentication Name\fP:
  435. ARRAY8
  436. .RS
  437. This specifies the authentication method, selected from the list offered in
  438. the \f8Query\fP, \f8BroadcastQuery\fP or \f8IndirectQuery\fP packet that the
  439. manger expects the display to use in the subsequent \f8Request\fP packet.
  440. This choice should remain as constant as feasible so that displays which
  441. send multiple \f8Query\fP packets can use the \f7Authentication Name\fP from
  442. any \f8Willing\fP packet which arrives.
  443. .LP
  444. The display is free to ignore managers which request an insufficient level
  445. of authentication.
  446. .RE
  447. \f7Hostname\fP:
  448. ARRAY8
  449. .RS
  450. A human readable string describing the host from which the packet was sent.
  451. The protocol specifies no interpretation of the data in this field.
  452. .RE
  453. \f7Status\fP:
  454. ARRAY8
  455. .RS
  456. A human readable string describing the ``status'' of the host.  This could
  457. include load average/number of users connected or other information.  The
  458. protocol specifies no interpretation of the data in this field.
  459. .RE
  460. .RE
  461. Semantics:
  462. .RS
  463. A \f8Willing\fP packet is sent by managers that may service connections from
  464. this display.  It is sent in response to either a \f8Query\fP,
  465. \f8BroadcastQuery\fP or \f8ForwardQuery\fP but does not imply a commitment
  466. to provide service (e.g. it may later decide that it has accepted enough
  467. connections already).
  468. .RE
  469. Problems/Solutions:
  470. .RS
  471. Problem:
  472. .RS
  473. \f8Willing\fP not received by the display.
  474. .br
  475. Indication:
  476. .RS
  477. none if \f8BroadcastQuery\fP or \f8IndirectQuery\fP was sent, else failure to
  478. receive \f8Willing\fP.
  479. .RE
  480. Solution:
  481. .RS
  482. The display should continue to send the query until a response is received.
  483. .RE
  484. .RE
  485. .RE
  486. Timeout/Retransmission policy:
  487. .RS
  488. Like all packets sent from the manager to the display, this packet should
  489. never be retransmitted.
  490. .RE
  491. .RE
  492. .LP
  493. \f8Unwilling\fP
  494. .RS
  495. Manager \(-> Display
  496. .br
  497. Additional Fields:
  498. .RS
  499. The same fields as in the \f8Willing\fP packet.  The \f7Status\fP field
  500. should indicate to the user a reason for the refusal of service.
  501. .RE
  502. Semantics:
  503. .RS
  504. An \f8Unwilling\fP packet is sent by managers in response to direct
  505. \f8Query\fP requests (as opposed to \f8BroadcastQuery\fP or
  506. \f8IndirectQuery\fP requests) if the manager will not accept requests for
  507. management.  This is typically sent by managers that wish to only service
  508. particular displays or which handle a limited number of displays at once.
  509. .RE
  510. Problems/Solutions:
  511. .RS
  512. Problem:
  513. .RS
  514. \f8Unwilling\fP not received by the display.
  515. .br
  516. Indication:
  517. .RS
  518. Display fails to receive \f8Unwilling\fP.
  519. .RE
  520. Solution:
  521. .RS
  522. The display should continue to send \f8Query\fP messages until a response is
  523. received.
  524. .RE
  525. .RE
  526. .RE
  527. Timeout/Retransmission policy:
  528. .RS
  529. Like all packets sent from the manager to the display, this packet should
  530. never be retransmitted.
  531. .RE
  532. .RE
  533. .LP
  534. \f8Request\fP
  535. .br
  536. .RS
  537. Display \(-> Manager
  538. .br
  539. Additional Fields:
  540. .RS
  541. \f7Display Number\fP:
  542. CARD16
  543. .RS
  544. The index of this particular server for the host on which the display is
  545. resident.  This value will be zero for most autonomous displays.
  546. .RE
  547. \f7Connection Types\fP:
  548. ARRAY16
  549. .RS
  550. An array indicating the stream services accepted by the display.  If the
  551. high-order byte in a particular entry is zero, the low-order byte
  552. corresponds to an X-protocol host family type.
  553. .RE
  554. \f7Connection Addresses\fP:
  555. ARRAYofARRAY8
  556. .RS
  557. For each connection type in the previous array, the corresponding entry in
  558. this array indicates the network address of the display device.
  559. .RE
  560. \f7Authentication Name\fP:
  561. ARRAY8
  562. .br
  563. \f7Authentication Data\fP:
  564. ARRAY8
  565. .RS
  566. This specifies the authentication protocol that the display expects
  567. the manager to validate itself with.  The Authentication Data is
  568. expected to contain data which the manager will interpret, modify
  569. and use to authenticate itself.
  570. .RE
  571. \f7Authorization Names\fP:
  572. ARRAYofARRAY8
  573. .RS
  574. This array specifies which types of authorization the display supports.  The
  575. manager may decide to reject displays with which it cannot perform
  576. authorization.
  577. .RE
  578. \f7Manufacturer Display ID\fP:
  579. ARRAY8
  580. .RS
  581. This field can be used by the manager to determine how to decrypt the
  582. Authentication Data field in this packet.  See the section below on
  583. Manufacturer Display ID Format.
  584. .RE
  585. .RE
  586. Semantics:
  587. .RS
  588. A \f8Request\fP packet is sent by a display to a specific host to request a
  589. session id in preparation for a establishing a connection.  If the manager
  590. is willing to service a connection to this display, it should return an
  591. \f8Accept\fP packet with a valid session id and should be ready for a
  592. subsequent Manage request.  Otherwise, it should return a \f8Decline\fP
  593. packet.
  594. .RE
  595. Valid Responses:
  596. .RS
  597. \f8Accept\fP, \f8Decline\fP
  598. .RE
  599. Problems/Solutions:
  600. .RS
  601. Problem:
  602. .RS
  603. Request not received by manager.
  604. .br
  605. Indication:
  606. .RS
  607. Display timeout waiting for response.
  608. .RE
  609. Solution:
  610. .RS
  611. Display resends \f8Request\fP message.
  612. .RE
  613. .RE
  614. Problem:
  615. .RS
  616. Message received out of order by manager.
  617. .br
  618. Indication:
  619. .RS
  620. none
  621. .RE
  622. Solution:
  623. .RS
  624. Each time a \f8Request\fP is sent, the manager sends the \f7Session ID\fP
  625. associated with the next session in the \f8Acknowledge\fP.  If that next
  626. session is not yet started, the manager will simply resend with the same
  627. \f7Session ID\fP.  If the session is in progress, the manager will reply
  628. with a new \f7Session ID\fP; in which case, the \f8Acknowledge\fP will be
  629. discarded by the display.
  630. .RE
  631. .RE
  632. .RE
  633. Timeout/Retransmission policy:
  634. .RS
  635. Timeout after 2 seconds, exponential backoff to 32 seconds.  After no more
  636. than 126 seconds, give up and report an error to the user.
  637. .RE
  638. .RE
  639. .LP
  640. \f8Accept\fP
  641. .RS
  642. Manager \(-> Display
  643. .br
  644. Additional Fields:
  645. .RS
  646. \f7Session ID\fP:
  647. CARD32
  648. .RS
  649. This identifies the session which can be started by the manager.
  650. .RE
  651. \f7Authentication Name\fP:
  652. ARRAY8
  653. .br
  654. \f7Authentication Data\fP:
  655. ARRAY8
  656. .RS
  657. This data is sent back to the display to authenticate the manager.
  658. If the Authentication Data is not the value expected by the display, it
  659. should terminate the protocol at this point and display an error to the user.
  660. .RE
  661. \f7Authorization Name\fP:
  662. ARRAY8
  663. .br
  664. \f7Authorization Data\fP:
  665. ARRAY8
  666. .RS
  667. This data is sent to the display to indicate the type of authorization the
  668. manager will be using in the first XOpenDisplay request after the
  669. Manage packet is received.
  670. .RE
  671. .RE
  672. Semantics:
  673. .RS
  674. An \f8Accept\fP packet is sent by a manager in response to a \f8Request\fP
  675. packet if the manager is willing to establish a connection for the display.
  676. The \f7Session ID\fP is used to identify this connection from any preceding
  677. ones and will be used by the display in its subsequent \f8Manage\fP packet.
  678. The \f7Session ID\fP is a 32 bit number which is incremented each time an
  679. \f8Accept\fP packet is sent as it must be reasonably unique over a long
  680. period of time.
  681. .LP
  682. If the authentication information is invalid, a \f8Decline\fP packet will be
  683. returned with an appropriate \f7Status\fP message.
  684. .RE
  685. Problems/Solutions:
  686. .RS
  687. Problem:
  688. .RS
  689. \f8Accept\fP or \f8Decline\fP not received by display.
  690. .br
  691. Indication:
  692. .RS
  693. Display timeout waiting for response to \f8Request\fP.
  694. .RE
  695. Solution:
  696. .RS
  697. Display resends \f8Request\fP message.
  698. .RE
  699. .RE
  700. Problem:
  701. .RS
  702. Message received out of order by display.
  703. .br
  704. Indication:
  705. .RS
  706. Display receives \f8Accept\fP after \f8Manage\fP has been sent.
  707. .RE
  708. Solution:
  709. .RS
  710. Display discards \f8Accept\fP messages after it has sent a \f8Manage\fP
  711. message.
  712. .RE
  713. .RE
  714. .RE
  715. Timeout/Retransmission policy:
  716. .RS
  717. Like all packets sent from the manager to the display, this packet should
  718. never be retransmitted.
  719. .RE
  720. .RE
  721. .LP
  722. \f8Decline\fP
  723. .RS
  724. Manager \(-> Display
  725. .br
  726. Additional Fields:
  727. .RS
  728. \f7Status\fP:
  729. ARRAY8
  730. .RS
  731. This is a human readable string indicating the reason for refusal of
  732. service.
  733. .RE
  734. \f7Authentication Name\fP:
  735. ARRAY8
  736. .br
  737. \f7Authentication Data\fP:
  738. ARRAY8
  739. .RS
  740. This data is sent back to the display to authenticate the manager.  If the
  741. \f7Authentication Data\fP is not the value expected by the display, it
  742. should terminate the protocol at this point and display an error to the user.
  743. .RE
  744. .RE
  745. Semantics:
  746. .RS
  747. A \f8Decline\fP packet is sent by a manager in response to a \f8Request\fP
  748. packet if the manager is unwilling to establish a connection for the
  749. display.  This is allowed even if the manager had responded \f8Willing\fP to
  750. a previous query.
  751. .RE
  752. Problems/Solutions:
  753. .RS
  754. same as for
  755. \f8Accept\fP.
  756. .RE
  757. Timeout/Retransmission policy:
  758. .RS
  759. Like all packets sent from a manager to a display, this packet should never
  760. be retransmitted.
  761. .RE
  762. .RE
  763. .LP
  764. \f8Manage\fP
  765. .RS
  766. Display \(-> Manager
  767. .br
  768. Additional Fields:
  769. .RS
  770. \f7Session ID\fP:
  771. CARD32
  772. .RS
  773. This field should contain the non-zero session id returned
  774. in the
  775. \f8Accept\fP
  776. packet.
  777. .RE
  778. \f7Display Number\fP:
  779. CARD16
  780. .RS
  781. This field must match the value sent in the previous
  782. \f8Request\fP
  783. packet.
  784. .RE
  785. \f7Display Class\fP:
  786. ARRAY8
  787. .RS
  788. This array specifies the class of the display.  Please refer to the section
  789. below (Display Class Format) which discusses the format of this field.
  790. .RE
  791. .RE
  792. Semantics:
  793. .RS
  794. A \f8Manage\fP packet is sent by a display to ask the manager to begin a
  795. session on the display.  If the \f7Session ID\fP is correct the manager
  796. should open a connection, otherwise it should respond with a \f8Refuse\fP or
  797. \f8Failed\fP packet, unless the \f7Session ID\fP matches a currently
  798. running session, or a session which has not yet successfully opened the
  799. display but has not given up the attempt.  In this latter case, the
  800. \f8Manage\fP packet should be ignored.  This will work as stream connections
  801. give positive success indication to both halves of the stream, and positive
  802. failure indication to the connection initiator (which will eventually
  803. generate a \f8Failed\fP packet).
  804. .RE
  805. Valid Responses:
  806. .RS
  807. X connection with correct auth info,
  808. \f8Refuse\fP,
  809. \f8Failed\fP.
  810. .RE
  811. Problems/Solutions:
  812. .RS
  813. Problem:
  814. .RS
  815. \f8Manage\fP
  816. not received by manager.
  817. .br
  818. Indication:
  819. .RS
  820. Display timeout waiting for response.
  821. .RE
  822. Solution:
  823. .RS
  824. Display resends
  825. \f8Manage\fP
  826. message.
  827. .RE
  828. .RE
  829. Problem:
  830. .RS
  831. \f8Manage\fP received out of order by manager.
  832. .br
  833. Indication:
  834. .RS
  835. session already in progress with matching \f7Session ID\fP.
  836. .RE
  837. Solution:
  838. .RS
  839. \f8Manage\fP packet ignored.
  840. .RE
  841. Indication:
  842. .RS
  843. \f7Session ID\fP doesn't match next \f7Session ID\fP
  844. .RE
  845. Solution:
  846. .RS
  847. \f8Refuse\fP message is sent.
  848. .RE
  849. .RE
  850. Problem:
  851. .RS
  852. Display cannot be opened on selected stream.
  853. .br
  854. Indication:
  855. .RS
  856. open display fails.
  857. .RE
  858. Solution:
  859. .RS
  860. \f8Failed\fP message is sent including a human readable reason.
  861. .RE
  862. .RE
  863. Problem:
  864. .RS
  865. Display open does not succeed before a second manage packet is received
  866. because of a timeout occuring in the display.
  867. .br
  868. Indication:
  869. .RS
  870. \f8Manage\fP packet received with \f7Session ID\fP matching the session
  871. attempting to connect to the display.
  872. .RE
  873. Solution:
  874. .RS
  875. \f8Manage\fP packet is ignored.  As the stream connection will either
  876. succeed, which will result in an active session, or the stream will
  877. eventually give up hope of connecting and send a \f7Failed\fP packet, no
  878. response to this \f8Manage\fP packet is necessary.
  879. .RE
  880. .RE
  881. .RE
  882. Timeout/Retransmission policy:
  883. .RS
  884. Timeout after 2 seconds, exponential backoff to 32 seconds.  After no more
  885. than 126 seconds, give up and report an error to the user.
  886. .RE
  887. .RE
  888. .LP
  889. \f8Refuse\fP
  890. .RS
  891. Manager \(-> Display
  892. .br
  893. Additional Fields:
  894. .RS
  895. \f7Session ID\fP:
  896. .RS
  897. This field should be set to the
  898. \f7Session ID\fP
  899. received in the
  900. \f8Manage\fP
  901. packet.
  902. .RE
  903. .RE
  904. Semantics:
  905. .RS
  906. A \f8Refuse\fP packet is sent by a manager when the \f7Session ID\fP
  907. received in the \f8Manage\fP packet does not match the current \f7Session
  908. ID\fP.  The display should assume that it received an old \f8Accept\fP
  909. packet and should resend its \f8Request\fP packet.
  910. .RE
  911. Problems/Solutions:
  912. .RS
  913. Problem:
  914. .RS
  915. Error message is lost.
  916. .br
  917. Indication:
  918. .RS
  919. display times out waiting for OpenDisplay, \f8Refuse\fP or \f8Failed\fP.
  920. .RE
  921. Solution:
  922. .RS
  923. display resends \f8Manage\fP message.
  924. .RE
  925. .RE
  926. .RE
  927. Timeout/Retransmission policy:
  928. .RS
  929. Like all packets sent from a manager to a display, this packet should never be
  930. retransmitted.
  931. .RE
  932. .RE
  933. .LP
  934. \f8Failed\fP
  935. .RS
  936. Manager \(-> Display
  937. .br
  938. Additional Fields:
  939. .RS
  940. \f7Session ID\fP:
  941. CARD32
  942. .RS
  943. This field should be set to the \f7Session ID\fP received in the
  944. \f8Manage\fP packet.
  945. .RE
  946. \f7Status\fP:
  947. ARRAY8
  948. .RS
  949. A human readable string indicating the reason for failure.
  950. .RE
  951. .RE
  952. Semantics:
  953. .RS
  954. A \f8Failed\fP packet is sent by a manager when it has problems establishing
  955. the initial X connection in response to the \f8Manage\fP packet.
  956. .RE
  957. Problems/Solutions
  958. .RS
  959. Same as for \f8Refuse\fP.
  960. .RE
  961. .RE
  962. .LP
  963. \f8KeepAlive\fP
  964. .RS
  965. Display \(-> Manager
  966. .br
  967. Additional Fields:
  968. .RS
  969. \f7Display Number\fP:
  970. CARD16
  971. .RS
  972. Set to the display index for the display host.
  973. .RE
  974. .RE
  975. .RS
  976. \f7Session ID\fP:
  977. CARD32
  978. .RS
  979. This field should be set to the \f7Session ID\fP received in the
  980. \f8Manage\fP packet during the negotiation for the current session.
  981. .RE
  982. .RE
  983. Sematics:
  984. .RS
  985. A \f8KeepAlive\fP packet can be sent at any time during the session by a
  986. display to discover if the manager is running.  The manager should respond
  987. with \f8Alive\fP whenever it receives this type of packet.
  988. .LP
  989. This allows the display to discover when the manager host is no longer running.
  990. A display is not required to send \f8KeepAlive\fP packets, and, upon lack of
  991. receipt of \f8Alive\fP packets, is not required to perform any specific action.
  992. .LP
  993. The expected use of this packet is to terminate an active session when the
  994. manager host or network link fails.  The display should keep track of the
  995. time since any packet has been received from the manager host and
  996. use \f8KeepAlive\fP packets when a substantial time has elapsed since the
  997. most recent packet.
  998. .RE
  999. Valid Responses:
  1000. .RS
  1001. \f8Alive\fP
  1002. .RE
  1003. Problems/Solutions:
  1004. .RS
  1005. Problem:
  1006. .RS
  1007. Manager doesn't receive the packet or display doesn't receive the response.
  1008. .RE
  1009. .RS
  1010. Indication:
  1011. .RS
  1012. No \f8Alive\fP packet returned
  1013. .RE
  1014. Solution:
  1015. .RS
  1016. Retransmit the packet with an exponential backoff; start at 2 seconds and
  1017. assume the host is not up after no less than 30 seconds.
  1018. .RE
  1019. .RE
  1020. .RE
  1021. .RE
  1022. .LP
  1023. \f8Alive\fP
  1024. .RS
  1025. Manager \(-> Display
  1026. .br
  1027. Additional Fields:
  1028. .RS
  1029. \f7Session Running\fP:
  1030. CARD8
  1031. .RS
  1032. This field indicates that the session indicated by \f7Session ID\fP is
  1033. currently active.  The value is 0 if no session is active, 1 if a session
  1034. is active.
  1035. .RE
  1036. \f7Session ID\fP:
  1037. CARD32
  1038. .RS
  1039. The ID of the currently running session; if any.  When no session is active
  1040. this field should be zero.
  1041. .RE
  1042. .RE
  1043. Semantics:
  1044. .RS
  1045. An \f8Alive\fP packet is sent in response to a \f8KeepAlive\fP request.  If
  1046. a session is currently active on the display, the manager includes the
  1047. \f7Session ID\fP in the packet.  The display can use this information to
  1048. determine the status of the manager.
  1049. .RE
  1050. .RE
  1051. .RE
  1052. .NH 1
  1053. Session Termination
  1054. .LP
  1055. When the session is over, the initial connection with the display (the one
  1056. which ack's the \f8Manage\fP packet) will be closed by the manager.  If only
  1057. a single session was active on the display, all other connections should be
  1058. closed by the display and the display should be reset.  If multiple sessions
  1059. are active simultaneously, and the display can identify which connections
  1060. belong to the terminated sesssion, those connections should be closed.
  1061. Otherwise all connections should be closed and the display reset only when
  1062. all sessions have been terminated (i.e. all initial connections closed).
  1063. .LP
  1064. The session may also be terminated at any time by the display if the
  1065. managing host no longer responds to \f8KeepAlive\fP packets.  The exact
  1066. time-outs for sending \f8KeepAlive\fP packets is not specified in this
  1067. protocol as the trade off should not be fixed between loading an otherwise
  1068. idle system with spurious \f8KeepAlive\fP packets and not noticing that the
  1069. manager host is down for a long time.
  1070. .NH 1
  1071. State Diagrams
  1072. .LP
  1073. These state diagrams are designed to cover all actions of both
  1074. the display and the manager.  Any packet which is received out-of-sequence
  1075. will be ignored.
  1076. .LP
  1077. Display:
  1078.  
  1079. .RS
  1080. .LP
  1081. \f6start\fP:
  1082. .RS
  1083. user-requested connect to one host \(-> \f6query\fP
  1084.  
  1085. .br
  1086. user-requested connect to some host \(-> \f6broadcast\fP
  1087.  
  1088. .br
  1089. user-requested connect to site host-list \(-> \f6indirect\fP
  1090. .RE
  1091.  
  1092. .LP
  1093. \f6query\fP:
  1094. .RS
  1095. Send \f8Query\fP packet
  1096. .br
  1097. \(-> \f6collect-query\fP
  1098. .RE
  1099.  
  1100. .LP
  1101. \f6collect-query\fP:
  1102. .RS
  1103. receive \f8Willing\fP \(-> \f6start-connection\fP
  1104.  
  1105. .br
  1106. receive \f8Unwilling\fP \(-> \f6stop-connection\fP
  1107.  
  1108. .br
  1109. timeout \(-> \f6query\fP
  1110. .RE    
  1111.  
  1112. .LP
  1113. \f6broadcast\fP:
  1114. .RS
  1115. Send \f8BroadcastQuery\fP packet
  1116. .br
  1117. \(-> \f6collect-broadcast-query\fP
  1118. .RE
  1119.  
  1120. .LP
  1121. \f6collect-broadcast-query\fP:
  1122. .RS
  1123. receive \f8Willing\fP \(-> \f6update-broadcast-willing\fP
  1124.  
  1125. .br
  1126. user-requested connect to one host \(-> \f6start-connection\fP
  1127.  
  1128. .br
  1129. timeout \(-> \f6broadcast\fP
  1130. .RE
  1131.  
  1132. .LP
  1133. \f6update-broadcast-willing\fP:
  1134. .RS
  1135. Add new host to the host list presented to the user.
  1136. .br
  1137. \(-> \f6collect-broadcast-query\fP
  1138. .RE
  1139.  
  1140. .LP
  1141. \f6indirect\fP:
  1142. .RS
  1143. Send \f8IndirectQuery\fP packet
  1144. .br
  1145. \(-> \f6collect-indirect-query\fP
  1146. .RE
  1147.  
  1148. .LP
  1149. \f6collect-indirect-query\fP:
  1150. .RS
  1151. receive \f8Willing\fP \(-> \f6update-indirect-willing\fP
  1152.  
  1153. .br
  1154. user-requested connect to one host \(-> \f6start-connection\fP
  1155.  
  1156. .br
  1157. timeout \(-> \f6indirect\fP
  1158. .RE
  1159.  
  1160. .LP
  1161. \f6update-indirect-willing\fP:
  1162. .RS
  1163. Add new host to the host list presented to the user.
  1164. .br
  1165. \(-> \f6collect-indirect-query\fP
  1166. .RE
  1167.  
  1168. .LP
  1169. \f6start-connection\fP:
  1170. .RS
  1171. Send \f8Request\fP packet
  1172. .br
  1173. \(-> \f6await-request-response\fP
  1174. .RE
  1175.  
  1176. .LP
  1177. \f6await-request-response\fP:
  1178. .RS
  1179. receive \f8Accept\fP \(-> \f6manage\fP
  1180.  
  1181. .br
  1182. receive \f8Decline\fP \(-> \f6stop-connection\fP
  1183.  
  1184. .br
  1185. timeout \(-> \f6start-connection\fP
  1186. .RE
  1187.  
  1188. .LP
  1189. \f6manage\fP:
  1190. .RS
  1191. Save \f7Session ID\fP
  1192. .br
  1193. Send \f8Manage\fP packet with \f7Session ID\fP
  1194. .br
  1195. \(-> \f6await-manage-response\fP
  1196. .RE    
  1197.  
  1198. .LP
  1199. \f6await-manage-response\fP:
  1200. .RS
  1201. receive XOpenDisplay: \(-> \f6run-session\fP
  1202.  
  1203. .br
  1204. receive \f8Refuse\fP with matching \f7Session ID\fP \(-> \f6start-connection\fP
  1205.  
  1206. .br
  1207. receive \f8Failed\fP with matching \f7Session ID\fP \(-> \f6stop-connection\fP
  1208.  
  1209. .br
  1210. timeout \(-> \f6manage\fP
  1211. .RE
  1212.  
  1213. .LP
  1214. \f6stop-connection\fP:
  1215. .RS
  1216. Display cause of termination to user
  1217. .br
  1218. \(-> \f6start\fP
  1219.  
  1220. .RE    
  1221.  
  1222. \f6run-session\fP:
  1223. .RS
  1224. Decide to send \f8KeepAlive\fP packet \(-> \f6keep-alive\fP
  1225.  
  1226. await close of first display connection
  1227.  
  1228. .br
  1229. \(-> \f6reset-display\fP
  1230. .RE    
  1231.  
  1232. .LP
  1233. \f6keep-alive\fP:
  1234. .RS
  1235. send \f8KeepAlive\fP packet with current \f7Session ID\fP
  1236.  
  1237. .br
  1238. \(-> \f6await-alive\fP
  1239. .RE
  1240.  
  1241. .LP
  1242. \f6await-alive\fP:
  1243. .RS
  1244. Receive \f8Alive\fP with matching \f7Session ID\fP \(-> \f6run-session\fP
  1245.  
  1246. .br
  1247. Receive \f8Alive\fP with non-matching \f7Session ID\fP or
  1248. FALSE \f7Session Running\fP \(-> \f6reset-display\fP
  1249.  
  1250. .br
  1251. Final Timeout without receiving \f8Alive\fP packet \(-> \f6reset-display\fP
  1252.  
  1253. .br
  1254. timeout \(-> \f6keep-alive\fP
  1255. .RE
  1256.  
  1257. .LP
  1258. \f6reset-display\fP:
  1259. .RS
  1260. (if possible) \(-> close all display connections associated with this session
  1261.  
  1262. .br
  1263. last session \(-> close all display connections
  1264.  
  1265. .br
  1266. \(-> \f6start\fP
  1267. .RE
  1268.  
  1269. .RE
  1270. .LP
  1271. Manager:
  1272. .RS
  1273.  
  1274. .LP
  1275. \f6idle\fP:
  1276. .RS
  1277. receive \f8Query\fP \(-> \f6query-respond\fP
  1278.  
  1279. .br
  1280. receive \f8BroadcastQuery\fP \(-> \f6broadcast-respond\fP
  1281.  
  1282. .br
  1283. receive \f8IndirectQuery\fP \(-> \f6indirect-respond\fP
  1284.  
  1285. .br
  1286. receive \f8ForwardQuery\fP \(-> \f6forward-respond\fP
  1287.  
  1288. .br
  1289. receive \f8Request\fP \(-> \f6request-respond\fP
  1290.  
  1291. .br
  1292. receive \f8Manage\fP \(-> \f6manage\fP
  1293.  
  1294. .br
  1295. an active session terminates \(-> \f6finish-session\fP
  1296.  
  1297. .br
  1298. receive \f8KeepAlive\fP \(-> \f6send-alive\fP
  1299.  
  1300. .br
  1301. \(-> \f6idle\fP
  1302. .RE    
  1303.  
  1304. .LP
  1305. \f6query-respond\fP:
  1306. .RS
  1307. if willing to manage \(-> \f6send-willing\fP
  1308.  
  1309. .br
  1310. \(-> \f6send-unwilling\fP
  1311. .RE
  1312.  
  1313. .LP
  1314. \f6broadcast-respond\fP:
  1315. .RS
  1316. if willing to manage \(-> \f6send-willing\fP
  1317.  
  1318. .br
  1319. \(-> \f6idle\fP
  1320. .RE
  1321.  
  1322. .LP
  1323. \f6indirect-respond\fP:
  1324. .RS
  1325. Send \f8ForwardQuery\fP packets to all managers on redirect list.
  1326. .br
  1327. if willing to manage \(-> \f6send-willing\fP
  1328.  
  1329. .br
  1330. \(-> \f6idle\fP
  1331. .RE
  1332.  
  1333. .LP
  1334. \f6forward-respond\fP:
  1335. .RS
  1336. Decode destination address, if willing to manage \(-> \f6send-willing\fP
  1337.  
  1338. .br
  1339. \(-> \f6idle\fP
  1340. .RE
  1341.  
  1342. .LP
  1343. \f6send-willing\fP:
  1344. .RS
  1345. Send \f8Willing\fP packet
  1346. .br
  1347. \(-> \f6idle\fP
  1348. .RE
  1349.  
  1350. .LP
  1351. \f6send-unwilling\fP:
  1352. .RS
  1353. Send \f8Unwilling\fP packet
  1354. .br
  1355. \(-> \f6idle\fP
  1356. .RE
  1357.  
  1358. .LP
  1359. \f6request-respond\fP:
  1360. .RS
  1361. if manager is willing to allow a session on display \(-> \f6accept-session\fP
  1362.  
  1363. .br
  1364. \(-> \f6decline-session\fP
  1365. .RE
  1366.  
  1367. .LP
  1368. \f6accept-session\fP:
  1369. .RS
  1370. Generate \f7Session ID\fP.  Save \f7Session ID\fP, display address and
  1371. display number somewhere
  1372. .br
  1373. Send \f8Accept\fP packet
  1374. .br
  1375. \(-> \f6idle\fP
  1376. .RE        
  1377.  
  1378. .LP
  1379. \f6decline-session\fP:
  1380. .RS
  1381. Send \f8Decline\fP packet
  1382. .br
  1383. \(-> \f6idle\fP
  1384. .RE    
  1385.  
  1386. .LP
  1387. \f6manage\fP:
  1388. .RS
  1389. If \f7Session ID\fP matches saved \f7Session ID\fP \(-> \f6run-session\fP
  1390. .br
  1391. If \f7Session ID\fP matches \f7Session ID\fP of session in process of
  1392. starting up, or currently active session \(-> \f6idle\fP
  1393.  
  1394. .br
  1395. \(-> \f6refuse\fP
  1396.  
  1397. .RE    
  1398. .LP
  1399.  
  1400. \f6refuse\fP:
  1401. .RS
  1402. Send
  1403. \f8Refuse\fP
  1404. packet
  1405. .br
  1406. \(-> 
  1407. \f6idle\fP
  1408.  
  1409. .RE    
  1410.  
  1411. .LP
  1412. \f6run-session\fP:
  1413. .RS
  1414. Terminate any session in progress
  1415. .br
  1416. XOpenDisplay
  1417. .br
  1418. open display succeeds \(-> 
  1419. \f6start-session\fP
  1420.  
  1421. .br
  1422. \(-> 
  1423. \f6failed\fP
  1424. .RE
  1425.  
  1426. .LP
  1427. \f6failed\fP:
  1428. .RS
  1429. send \f8Failed\fP packet
  1430. .br
  1431. \(-> \f6idle\fP
  1432. .RE    
  1433.  
  1434. .LP
  1435. \f6start-session\fP:
  1436. .RS
  1437. Start a new session
  1438. .br
  1439. \(-> \f6idle\fP
  1440. .RE
  1441.  
  1442. .LP
  1443. \f6finish-session\fP:
  1444. .RS
  1445. XCloseDisplay
  1446.  
  1447. .br
  1448. \(-> \f6idle\fP
  1449. .RE
  1450.  
  1451. .LP
  1452. \f6send-alive\fP:
  1453. .RS
  1454. Send \f8Alive\fP packet containing current status.
  1455.  
  1456. .br
  1457. \(-> \f6idle\fP
  1458. .RE
  1459.  
  1460. .RE
  1461. .NH 1
  1462. Protocol Encoding
  1463. .LP
  1464. When XDMCP is implemented on top of UDP (the Internet User Datagram Protocol),
  1465. port number 177 is to be used.
  1466. .LP
  1467. The version number in all packets will be 1.
  1468. .LP
  1469. Packet opcodes are 16 bit integers.
  1470. .RS
  1471. .TS
  1472. c c
  1473. l l.
  1474. Packet Name    Encoding
  1475. _
  1476. BroadcastQuery    1
  1477. Query    2
  1478. IndirectQuery    3
  1479. ForwardQuery    4
  1480. Willing    5
  1481. Unwilling    6
  1482. Request    7
  1483. Accept    8
  1484. Decline    9
  1485. Manage    10
  1486. Refuse    11
  1487. Failed    12
  1488. Alive    13
  1489. KeepAlive    14
  1490. .TE
  1491. .RE
  1492. .LP
  1493. Per packet information follows:
  1494. .LP
  1495. \f8Query\fP
  1496. .br
  1497. \f8BroadcastQuery\fP
  1498. .br
  1499. \f8IndirectQuery\fP
  1500. .RS
  1501. These packets are identical except for the opcode field.
  1502. .TS
  1503. c c c
  1504. c l l.
  1505. Length    Type    Description
  1506. _
  1507. 2    CARD16    version number (always 1)
  1508. 2    CARD16    opcode (always \f8Query\fP, \f8BroadcastQuery\fP or \f8IndirectQuery\fP)
  1509. 2    CARD16    length
  1510. 1    CARD8    number of \f7Authentication Names\fP sent (m)
  1511. 2    CARD16    length of first \f7Authentication Name\fP (m\d\s-21\s+2\u)
  1512. m\d\s-21\s+2\u    CARD8    first \f7Authentication Name\fP
  1513. \&...        Other \f7Authentication Names\fP
  1514. .TE
  1515. .RE
  1516. .LP
  1517. \f8ForwardQuery\fP
  1518. .RS
  1519. .TS
  1520. c c c
  1521. c l l.
  1522. Length    Type    Description
  1523. _
  1524. 2    CARD16    version number (always 1)
  1525. 2    CARD16    opcode (always \f8ForwardQuery\fP)
  1526. 2    CARD16    length
  1527. 2    CARD16    length of \f7Client Address\fP (m)
  1528. m    CARD8    \f7Client Address\fP
  1529. 2    CARD16    length of \f7Client Port\fP (n)
  1530. n    CARD8    \f7Client Port\fP
  1531. 1    CARD8    number of \f7Authentication Names\fP sent (o)
  1532. 2    CARD16    length of first \f7Authentication Name\fP (o\d\s-21\s+2\u)
  1533. o\d\s-21\s+2\u    CARD8    first \f7Authentication Name\fP
  1534. \&...        Other \f7Authentication Names\fP
  1535. .TE
  1536. .RE
  1537. .LP
  1538. \f8Willing\fP
  1539. .RS
  1540. .TS
  1541. c c c
  1542. c l l.
  1543. Length    Type    Description
  1544. _
  1545. 2    CARD16    version number (always 1)
  1546. 2    CARD16    opcode (always \f8Willing\fP)
  1547. 2    CARD16    length (6 + m + n + o)
  1548. 2    CARD16    Length of \f7Authentication Name\fP (m)
  1549. m    CARD8    \f7Authentication Name\fP
  1550. 2    CARD16    \f7Hostname\fP length (n)
  1551. n    CARD8    \f7Hostname\fP
  1552. 2    CARD16    \f7Status\fP length (o)
  1553. o    CARD8    \f7Status\fP
  1554. .TE
  1555. .RE
  1556. .LP
  1557. \f8Unwilling\fP
  1558. .RS
  1559. .TS
  1560. c c c
  1561. c l l.
  1562. Length    Type    Description
  1563. _
  1564. 2    CARD16    version number (always 1)
  1565. 2    CARD16    opcode (always \f8Unwilling\fP)
  1566. 2    CARD16    length (4 + m + n)
  1567. 2    CARD16    \f7Hostname\fP length (m)
  1568. m    CARD8    \f7Hostname\fP
  1569. 2    CARD16    \f7Status\fP length (n)
  1570. n    CARD8    \f7Status\fP
  1571. .TE
  1572. .RE
  1573. .LP
  1574. \f8Request\fP
  1575. .RS
  1576. .TS
  1577. c c c
  1578. c l l.
  1579. Length    Type    Description
  1580. _
  1581. 2    CARD16    version number (always 1)
  1582. 2    CARD16    opcode (always \f8Request\fP)
  1583. 2    CARD16    length
  1584. 2    CARD16    \f7Display Number\fP
  1585. 1    CARD8    Count of \f7Connection Types\fP (m)
  1586. 2 \(mu m    CARD16    \f7Connection Types\fP
  1587. 1    CARD8    Count of \f7Connection Addresses\fP (n)
  1588. 2    CARD16    Length of first \f7Connection Address\fP (n\s-2\d1\u\s+2)
  1589. n\s-2\d1\u\s+2    CARD8    First \f7Connection Address\fP
  1590. \&...        Other connection addresses
  1591. 2    CARD16    Length of \f7Authentication Name\fP (o)
  1592. o    CARD8    \f7Authentication Name\fP
  1593. 2    CARD16    Length of \f7Authentication Data\fP (p)
  1594. p    CARD8    \f7Authentication Data\fP
  1595. 1    CARD8    Count of \f7Authorization Names\fP (q)
  1596. 2    CARD16    Length of first \f7Authorization Name\fP (q\s-2\d1\u\s+2)
  1597. q\s-2\d1\u\s+2    CARD8    First \f7Authorization Name\fP
  1598. \&...        Other authorization names
  1599. 2    CARD16    Length of \f7Manufacturer Display ID\fP (r)
  1600. r    CARD8    \f7Manufacturer Display ID\fP
  1601. .TE
  1602. .RE
  1603. .LP
  1604. \f8Accept\fP
  1605. .RS
  1606. .TS
  1607. c c c
  1608. c l l.
  1609. Length    Type    Description
  1610. _
  1611. 2    CARD16    version number (always 1)
  1612. 2    CARD16    opcode (always \f8Accept\fP)
  1613. 2    CARD16    length (12 + n + m + o + p)
  1614. 4    CARD32    \f7Session ID\fP
  1615. 2    CARD16    Length of \f7Authentication Name\fP (n)
  1616. n    CARD8    \f7Authentication Name\fP
  1617. 2    CARD16    Length of \f7Authentication Data\fP (m)
  1618. m    CARD8    \f7Authentication Data\fP
  1619. 2    CARD16    Length of \f7Authorization Name\fP (o)
  1620. o    CARD8    \f7Authorization Name\fP
  1621. 2    CARD16    Length of \f7Authorization Data\fP (p)
  1622. p    CARD8    \f7Authorization Data\fP
  1623. .TE
  1624. .RE
  1625. .LP
  1626. \f8Decline\fP
  1627. .RS
  1628. .TS
  1629. c c c
  1630. c l l.
  1631. Length    Type    Description
  1632. _
  1633. 2    CARD16    version number (always 1)
  1634. 2    CARD16    opcode (always \f8Decline\fP)
  1635. 2    CARD16    length (6 + m + n + o)
  1636. 2    CARD16    Length of \f7Status\fP (m)
  1637. m    CARD8    \f7Status\fP
  1638. 2    CARD16    Length of \f7Authentication Name\fP (n)
  1639. n    CARD8    \f7Authentication Name\fP
  1640. 2    CARD16    Length of \f7Authentication Data\fP (o)
  1641. o    CARD8    \f7Authentication Data\fP
  1642. .TE
  1643. .RE
  1644. .LP
  1645. \f8Manage\fP
  1646. .RS
  1647. .TS
  1648. c c c
  1649. c l l.
  1650. Length    Type    Description
  1651. _
  1652. 2    CARD16    version number (always 1)
  1653. 2    CARD16    opcode (always \f8Manage\fP)
  1654. 2    CARD16    length (8 + m)
  1655. 4    CARD32    \f7Session ID\fP
  1656. 2    CARD16    \f7Display Number\fP
  1657. 2    CARD16    Length of \f7Display Class\fP (m)
  1658. m    CARD8    \f7Display Class\fP
  1659. .TE
  1660. .RE
  1661. .LP
  1662. \f8Refuse\fP
  1663. .RS
  1664. .TS
  1665. c c c
  1666. c l l.
  1667. Length    Type    Description
  1668. _
  1669. 2    CARD16    version number (always 1)
  1670. 2    CARD16    opcode (always \f8Refuse\fP)
  1671. 2    CARD16    length (4)
  1672. 4    CARD32    \f7Session ID\fP
  1673. .TE
  1674. .RE
  1675. .LP
  1676. \f8Failed\fP
  1677. .RS
  1678. .TS
  1679. c c c
  1680. c l l.
  1681. Length    Type    Description
  1682. _
  1683. 2    CARD16    version number (always 1)
  1684. 2    CARD16    opcode (always \f8Failed\fP)
  1685. 2    CARD16    length (6 + m)
  1686. 4    CARD32    \f7Session ID\fP
  1687. 2    CARD16    Length of \f7Status\fP (m)
  1688. m    CARD8    \f7Status\fP
  1689. .TE
  1690. .RE
  1691. .LP
  1692. \f8KeepAlive\fP
  1693. .RS
  1694. .TS
  1695. c c c
  1696. c l l.
  1697. Length    Type    Description
  1698. _
  1699. 2    CARD16    version number (always 1)
  1700. 2    CARD16    opcode (always \f8KeepAlive\fP)
  1701. 2    CARD16    length (6)
  1702. 2    CARD16    \f7Display Number\fP
  1703. 4    CARD32    \f7Session ID\fP
  1704. .TE
  1705. .RE
  1706. .LP
  1707. \f8Alive\fP
  1708. .RS
  1709. .TS
  1710. c c c
  1711. c l l.
  1712. Length    Type    Description
  1713. _
  1714. 2    CARD16    version number (always 1)
  1715. 2    CARD16    opcode (always \f8Alive\fP)
  1716. 2    CARD16    length (5)
  1717. 1    CARD8    \f7Session Running\fP (0: not running 1: running)
  1718. 4    CARD32    \f7Session ID\fP (0: not running)
  1719. .TE
  1720. .RE
  1721. .NH 1
  1722. Display Class Format
  1723. .LP
  1724. The \f7Display Class\fP field of the \f8Manage\fP packet is used by the
  1725. display manager to collect common sorts of
  1726. displays into manageable groups.  This field is a string encoded of
  1727. ISO-LATIN-1 characters in the following format:
  1728. .nf
  1729. .sp
  1730. .ta 1i
  1731.     ManufacturerID-ModelNumber
  1732. .fi
  1733. .sp
  1734. .LP
  1735. Both elements of this string must exclude characters of the set { \fB-\fP,
  1736. \&\fB.\fP, \fB:\fP, \fB*\fP, \fB?\fP, \fI<space>\fP }.  The ManufacturerID is a
  1737. string which should be registered with the X Consortium.  The ModelNumber is
  1738. designed to identify characteristics of the display within the manufacturer's
  1739. product line.  This string should be documented in the users manual for the
  1740. particular device.  This string should probably not be specifiable by the
  1741. display user to avoid unexpected configuration errors.
  1742. .NH 1
  1743. Manufacturer Display ID Format
  1744. .LP
  1745. To authenticate the manager, the display and manager will share a private
  1746. key.  The manager, then, must be able to discover which key to use for a
  1747. particular device.
  1748. The \f7Manufacturer Display ID\fP field of the \f8Request\fP packet is
  1749. intended for this purpose.  Typically, the manager host will
  1750. contain a map between this number and the key.  This field is intended to be
  1751. unique per display, possibly the ethernet address of the display in the form:
  1752. .nf
  1753. .sp
  1754. .ta 1i
  1755.     -Ethernet-8:0:2b:a:f:d2
  1756. .sp
  1757. .fi
  1758. or string
  1759. of the form:
  1760. .nf
  1761. .sp
  1762. .ta 1i
  1763.     ManufacturerID-ModelNumber-SerialNumber
  1764. .sp
  1765. .fi
  1766. where ManufacturerID, ModelNumber and SerialNumber are encoded using
  1767. ISO-LATIN-1 characters, excluding  { \fB-\fP,
  1768. \&\fB.\fP, \fB*\fP, \fB?\fP, \fI<space>\fP }
  1769. .LP
  1770. When the display is shipped to a customer, it should include both the
  1771. \f7Manufacturer Display ID\fP
  1772. and the private key in the documentation set.  This information should not
  1773. be modifiable by the display user.
  1774. .NH 1
  1775. Authentication
  1776. .LP
  1777. In an environment where authentication is not needed, XDMCP can disable
  1778. authentication by having the display send empty \f7Authentication Name\fP
  1779. and \f7Authentication Data\fP fields in the \f8Request\fP packet.  In this
  1780. case, the manager will not attempt to authenticate itself.  Other
  1781. authentication protocols may be developed, depending on local needs.
  1782. .LP
  1783. In an unsecure environment, the display must be able to verify that the
  1784. source of the various packets is a trusted manager.  These packets will
  1785. contain authentication information.  As an example of such a system, the
  1786. following discussion describes the "XDM-AUTHENTICATION-1" authentication
  1787. system.  This system uses a 56 bit shared private key, and 64 bits of
  1788. authentication data.  An associated example X authorization protocol
  1789. "XDM-AUTHORIZATION-1" will also be discussed.  The 56 bit key is represented
  1790. as a 64 bit number in network order (big endian).  This means that the first
  1791. octet in the representation will be zero.  When incrementing a 64 bit value,
  1792. the 8 octets of data will be interpreted in network order (big endian). I.e.
  1793. the last octet will be incremented, subsequent carries propogate towards the
  1794. first octet.
  1795. .LP
  1796. Assumptions:
  1797. .IP
  1798. The display and manager share a private key.  This key could be programmed
  1799. into the display by the manufacturer and shipped with the unit.  It must not
  1800. be available from the display itself, but should allow the value to be
  1801. modified in some way.  The system administrator would be responsible for
  1802. managing a database of terminal keys.
  1803. .IP
  1804. The display can generate random authentication numbers.
  1805. .LP
  1806. Some definitions first:
  1807. .EQ
  1808. oc D cc sup kappa mark = "encryption of plain text " D " by key " kappa
  1809. .EN C
  1810. .EQ
  1811. oc DELTA cc * sup kappa lineup = "decryption of crypto text " DELTA " with key " kappa
  1812. .EN C
  1813. .EQ
  1814. { tau } lineup = "private key shared by display and manager"
  1815. .EN C
  1816. .EQ
  1817. rho lineup = "64 bit random number generated by display"
  1818. .EN C
  1819. .EQ
  1820. alpha lineup = "authentication data in XDMCP packets"
  1821. .EN C
  1822. .EQ
  1823. sigma lineup = "per-session private key, generated by manager"
  1824. .EN C
  1825. .EQ
  1826. beta lineup = "authorization data"
  1827. .EN
  1828. .LP
  1829. Encryption will use the DES; blocks shorter than 64 bits will be zero-filled
  1830. on the right to 64 bits.  Blocks longer than 64 bits will use block chaining:
  1831. .EQ
  1832. oc { D } cc sup kappa lineup = oc { D sub 1 } cc sup kappa " "
  1833. oc { D sub 2 } " " xor " " oc { D sub 1 } cc sup kappa cc sup kappa
  1834. .EN
  1835. .LP
  1836. The display generates the first authentication data in the
  1837. \f8Request\fP
  1838. packet:
  1839. .EQ
  1840. alpha sub roman Request mark = oc rho cc sup tau
  1841. .EN
  1842. .LP
  1843. For the
  1844. \f8Accept\fP
  1845. packet, the manager decrypts the initial message and returns
  1846. @alpha sub roman Accept@:
  1847. .EQ
  1848. rho lineup = oc alpha sub roman Request cc * sup tau
  1849. .EN C
  1850. .EQ
  1851. alpha sub roman Accept lineup = oc rho + 1 cc sup tau
  1852. .EN
  1853. .LP
  1854. The \f8Accept\fP packet also contains the authorization intended for use by
  1855. the X server.  A description of authorization type ``XDM-AUTHORIZATION-1''
  1856. follows:
  1857. .LP
  1858. The \f8Accept\fP packet contains the authorization name
  1859. ``XDM-AUTHORIZATION-1''.  The authorization data is the string:
  1860. .EQ
  1861. beta sub Accept mark = oc sigma cc sup tau
  1862. .EN
  1863. .LP
  1864. To create authorization information for connection setup with the X server
  1865. using the XDM-AUTHORIZATION-1 authorization protocol, the client computes the
  1866. following:
  1867. .EQ
  1868. N mark = "X client identifier"
  1869. .EN C
  1870. .EQ
  1871. T lineup = "Current time in seconds on client host (32 bits)"
  1872. .EN
  1873. .EQ C
  1874. beta lineup = oc rho N T cc sup sigma
  1875. .EN
  1876. .LP
  1877. For TCP connections @N@ is 48 bits long and contains the 32 bit IP address of
  1878. the client host followed by the 16 bit port number of the client socket.
  1879. Formats for other connections must be registered.
  1880. The resulting value, @beta@, is 192 bits of authorization data which is sent
  1881. in the connection setup to the server.  The server receives the packet,
  1882. decrypts the contents.  To accept the connection, the following must hold:
  1883. .IP 1
  1884. @rho@ must match the value generated for the most recent XDMCP negotiation.
  1885. .IP 2
  1886. @T@ must be within 1200 seconds of the internally stored time.  If no time
  1887. been received before, the current time is set to @T@.
  1888. .IP 3
  1889. No packet containing the same pair (@N@, @T@) can have been received
  1890. in the last 1200 seconds (20 minutes).
  1891.