home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / ice.txt < prev    next >
Text File  |  2001-06-27  |  53KB  |  2,311 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.         Inter-Client Exchange (ICE) Protocol
  12.  
  13.             Version 1.1
  14.  
  15.            X Consortium Standard
  16.  
  17.          X Version 11, Release 6.4
  18.  
  19.  
  20.  
  21.  
  22.               Robert Scheifler
  23.              X Consortium, Inc.
  24.  
  25.             Jordan Brown
  26.          Quarterdeck Office Systems
  27.  
  28.  
  29.  
  30.  
  31.  
  32.               ABSTRACT
  33.  
  34.  
  35.  
  36.      There are numerous possible protocols that can be
  37.      used for communication among clients.  They have
  38.      many similarities and common needs, including
  39.      authentication, version negotiation, data typing,
  40.      and connection management.  The Inter-Client
  41.      Exchange (ICE) protocol is intended to provide a
  42.      framework for building such protocols.  Using ICE
  43.      reduces the complexity of designing new protocols
  44.      and allows the sharing of many aspects of the
  45.      implementation.
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.        Copyright (c) 1993, 1994 X Consortium
  85.  
  86.  
  87.  
  88.  
  89.  
  90. Permission is hereby granted, free of charge, to any person
  91. obtaining a copy of this software and associated
  92. documentation files (the ``Software''), to deal in the
  93. Software without restriction, including without limitation
  94. the rights to use, copy, modify, merge, publish, distribute,
  95. sublicense, and/or sell copies of the Software, and to
  96. permit persons to whom the Software is furnished to do so,
  97. subject to the following conditions:
  98.  
  99. The above copyright notice and this permission notice shall
  100. be included in all copies or substantial portions of the
  101. Software.
  102.  
  103. THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY
  104. KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  105. WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  106. PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X
  107. CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  108. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
  109. OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  110. SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  111.  
  112. Except as contained in this notice, the name of the X
  113. Consortium shall not be used in advertising or otherwise to
  114. promote the sale, use or other dealings in this Software
  115. without prior written authorization from the X Consortium.
  116.  
  117.  
  118.  
  119.  
  120.  
  121. X Window System is a trademark of X Consortium, Inc.
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139. 1.  Purpose and Goals
  140.  
  141. In discussing a variety of protocols -- existing, under
  142. development, and hypothetical -- it was noted that they have
  143. many elements in common.  Most protocols need mechanisms for
  144. authentication, for version negotiation, and for setting up
  145. and taking down connections.  There are also cases where the
  146. same two parties need to talk to each other using multiple
  147. protocols.  For example, an embedding relationship between
  148. two parties is likely to require the simultaneous use of
  149. session management, data transfer, focus negotiation, and
  150. command notification protocols.  While these are logically
  151. separate protocols, it is desirable for them to share as
  152. many pieces of implementation as possible.
  153.  
  154. The Inter-Client Exchange (ICE) protocol provides a generic
  155. framework for building protocols on top of reliable, byte-
  156. stream transport connections.  It provides basic mechanisms
  157. for setting up and shutting down connections, for performing
  158. authentication, for negotiating versions, and for reporting
  159. errors.  The protocols running within an ICE connection are
  160. referred to here as subprotocols.  ICE provides facilities
  161. for each subprotocol to do its own version negotiation,
  162. authentication, and error reporting.  In addition, if two
  163. parties are communicating using several different
  164. subprotocols, ICE will allow them to share the same
  165. transport layer connection.
  166.  
  167. 2.  Overview of the protocol
  168.  
  169. Through some mechanism outside ICE, two parties make
  170. themselves known to each other and agree that they would
  171. like to communicate using an ICE subprotocol.  ICE assumes
  172. that this negotation includes some notion by which the
  173. parties will decide which is the "originating" party and
  174. which is the "answering" party.  The negotiation will also
  175. need to provide the originating party with a name or address
  176. of the answering party.  Examples of mechanisms by which
  177. parties can make themselves known to each other are the X
  178. selection mechanism, environment variables, and shared
  179. files.
  180.  
  181. The originating party first determines whether there is an
  182. existing ICE connection between the two parties.  If there
  183. is, it can re-use the existing connection and move directly
  184. to the setup of the subprotocol.  If no ICE connection
  185. exists, the originating party will open a transport
  186. connection to the answering party and will start ICE
  187. connection setup.
  188.  
  189. The ICE connection setup dialog consists of three major
  190. parts: byte order exchange, authentication, and connection
  191. information exchange.  The first message in each direction
  192. is a ByteOrder message telling which byte order will be used
  193.  
  194.  
  195.  
  196.                   1
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Inter-Client Exchange Protocol            X11, Release 6.4
  203.  
  204.  
  205. by the sending party in messages that it sends.  After that,
  206. the originating party sends a ConnectionSetup message giving
  207. information about itself (vendor name and release number)
  208. and giving a list of ICE version numbers it is capable of
  209. supporting and a list of authentication schemes it is
  210. willing to accept.  Authentication is optional.  If no
  211. authentication is required, the answering party responds
  212. with a ConnectionReply message giving information about
  213. itself, and the connection setup is complete.
  214.  
  215. If the connection setup is to be authenticated, the
  216. answering party will respond with an AuthenticationRequired
  217. message instead of a ConnectionReply message.  The parties
  218. then exchange AuthenticationReply and
  219. AuthenticationNextPhase messages until authentication is
  220. complete, at which time the answering party finally sends
  221. its ConnectionReply message.
  222.  
  223. Once an ICE connection is established (or an existing
  224. connection reused), the originating party starts subprotocol
  225. negotiation by sending a ProtocolSetup message.  This
  226. message gives the name of the subprotocol that the parties
  227. have agreed to use, along with the ICE major opcode that the
  228. originating party has assigned to that subprotocol.
  229. Authentication can also occur for the subprotocol,
  230. independently of authentication for the connection.
  231. Subprotocol authentication is optional.  If there is no
  232. subprotocol authentication, the answering party responds
  233. with a ProtocolReply message, giving the ICE major opcode
  234. that it has assigned for the subprotocol.
  235.  
  236. Subprotocols are authenticated independently of each other,
  237. because they may have differing security requirements.    If
  238. there is authentication for this particular subprotocol, it
  239. takes place before the answering party emits the
  240. ProtocolReply message, and it uses the
  241. AuthenticationRequired, AuthenticationReply, and
  242. AuthenticationNextPhase messages, just as for the connection
  243. authentication.  Only when subprotocol authentication is
  244. complete does the answering party send its ProtocolReply
  245. message.
  246.  
  247. When a subprotocol has been set up and authenticated, the
  248. two parties can communicate using messages defined by the
  249. subprotocol.  Each message has two opcodes: a major opcode
  250. and a minor opcode.  Each party will send messages using the
  251. major opcode it has assigned in its ProtocolSetup or
  252. ProtocolReply message.    These opcodes will, in general, not
  253. be the same.  For a particular subprotocol, each party will
  254. need to keep track of two major opcodes: the major opcode it
  255. uses when it sends messages, and the major opcode it expects
  256. to see in messages it receives.  The minor opcode values and
  257. semantics are defined by each individual subprotocol.
  258.  
  259.  
  260.  
  261.  
  262.                   2
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Inter-Client Exchange Protocol            X11, Release 6.4
  269.  
  270.  
  271. Each subprotocol will have one or more messages whose
  272. semantics are that the subprotocol is to be shut down.
  273. Whether this is done unilaterally or is performed through
  274. negotiation is defined by each subprotocol.  Once a
  275. subprotocol is shut down, its major opcodes are removed from
  276. use; no further messages on this subprotocol should be sent
  277. until the opcode is reestablished with ProtocolSetup.
  278.  
  279. ICE has a facility to negotiate the closing of the
  280. connection when there are no longer any active subprotocols.
  281. When either party decides that no subprotocols are active,
  282. it can send a WantToClose message.  If the other party
  283. agrees to close the connection, it can simply do so.  If the
  284. other party wants to keep the connection open, it can
  285. indicate its desire by replying with a NoClose message.
  286.  
  287. It should be noted that the party that initiates the
  288. connection isn't necessarily the same as the one that
  289. initiates setting up a subprotocol.  For example, suppose
  290. party A connects to party B.  Party A will issue the
  291. ConnectionSetup message and party B will respond with a
  292. ConnectionReply message.  (The authentication steps are
  293. omitted here for brevity.)  Typically, party A will also
  294. issue the ProtocolSetup message and expect a ProtocolReply
  295. from party B.  Once the connection is established, however,
  296. either party may initiate the negotiation of a subprotocol.
  297. Continuing this example, party B may decide that it needs to
  298. set up a subprotocol for communication with party A.  Party
  299. B would issue the ProtocolSetup message and expect a
  300. ProtocolReply from party A.
  301.  
  302. 3.  Data Types
  303.  
  304. ICE messages contain several types of data.  Byte order is
  305. negotiated in the initial connection messages; in general
  306. data is sent in the sender's byte order and the receiver is
  307. required to swap it appropriately.  In order to support
  308. 64-bit machines, ICE messages are padded to multiples of 8
  309. bytes.    All messages are designed so that fields are
  310. "naturally" aligned on 16-, 32-, and 64-bit boundaries.  The
  311. following formula gives the number of bytes necessary to pad
  312. E bytes to the next multiple of b:
  313.  
  314.      pad(E, b) = (b - (E mod b)) mod b
  315.  
  316.  
  317. 3.1.  Primitive Types
  318.  
  319.  
  320. -------------------------------------------------------------
  321. Type Name         Description
  322. -------------------------------------------------------------
  323. CARD8             8-bit unsigned integer
  324.  
  325.  
  326.  
  327.  
  328.                   3
  329.  
  330.  
  331.  
  332.  
  333.  
  334. Inter-Client Exchange Protocol            X11, Release 6.4
  335.  
  336.  
  337. -------------------------------------------------------------
  338. Type Name         Description
  339. -------------------------------------------------------------
  340. CARD16             16-bit unsigned integer
  341. CARD32             32-bit unsigned integer
  342. BOOL             False or True
  343. LPCE             A character from the X Portable
  344.              Character Set in Latin Portable
  345.              Character Encoding
  346. -------------------------------------------------------------
  347.  
  348.  
  349. 3.2.  Complex Types
  350.  
  351.  
  352. -------------------------------------------------------------
  353. Type Name         Type
  354. -------------------------------------------------------------
  355. VERSION          [Major, minor: CARD16]
  356. STRING             LISTofLPCE
  357. -------------------------------------------------------------
  358.  
  359. LISTof<type> denotes a counted collection of <type>.  The
  360. exact encoding varies depending on the context; see the
  361. encoding section.
  362.  
  363. 4.  Message Format
  364.  
  365. All ICE messages include the following information:
  366.  
  367. -------------------------------------------------------------
  368. Field Type        Description
  369. -------------------------------------------------------------
  370. CARD8            protocol major opcode
  371. CARD8            protocol minor opcode
  372. CARD32            length of remaining data in 8-byte units
  373. -------------------------------------------------------------
  374.  
  375.  
  376. The fields are as follows:
  377.  
  378. Protocol major opcode
  379.      This specifies what subprotocol the message is intended
  380.      for.  Major opcode 0 is reserved for ICE control
  381.      messages.    The major opcodes of other subprotocols are
  382.      dynamically assigned and exchanged at protocol
  383.      negotiation time.
  384.  
  385. Protocol minor opcode
  386.      This specifies what protocol-specific operation is to
  387.      be performed.  Minor opcode 0 is reserved for Errors;
  388.      other values are protocol-specific.
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                   4
  395.  
  396.  
  397.  
  398.  
  399.  
  400. Inter-Client Exchange Protocol            X11, Release 6.4
  401.  
  402.  
  403. Length of data in 8-byte units
  404.      This specifies the length of the information following
  405.      the first 8 bytes.  Each message-type has a different
  406.      format, and will need to be separately length-checked
  407.      against this value.  As every data item has either an
  408.      explicit length, or an implicit length, this can be
  409.      easily accomplished.  Messages that have too little or
  410.      too much data indicate a serious protocol failure, and
  411.      should result in a BadLength error.
  412.  
  413. 5.  Overall Protocol Description
  414.  
  415. Every message sent in a given direction has an implicit
  416. sequence number, starting with 1.  Sequence numbers are
  417. global to the connection; independent sequence numbers are
  418. not maintained for each protocol.
  419.  
  420. Messages of a given major-opcode (i.e., of a given protocol)
  421. must be responded to (if a response is called for) in order
  422. by the receiving party.  Messages from different protocols
  423. can be responded to in arbitrary order.
  424.  
  425. Minor opcode 0 in every protocol is for reporting errors.
  426. At most one error is generated per request.  If more than
  427. one error condition is encountered in processing a request,
  428. the choice of which error is returned is implementation-
  429. dependent.
  430. __
  431. |    Error
  432.  
  433.      offending-minor-opcode: CARD8
  434.  
  435.      severity: {CanContinue, FatalToProtocol,
  436.            FatalToConnection}
  437.  
  438.      sequence-number: CARD32
  439.  
  440.      class: CARD16
  441.  
  442.      value(s): <dependent on major/minor opcode and class>
  443. |__
  444.  
  445. This message is sent to report an error in response to a
  446. message from any protocol.  The Error message exists in all
  447. protocol major-opcode spaces; it is minor-opcode zero in
  448. every protocol.  The minor opcode of the message that caused
  449. the error is reported, as well as the sequence number of
  450. that message.  The severity indicates the sender's behavior
  451. following the identification of the error.  CanContinue
  452. indicates the sender is willing to accept additional
  453. messages for this protocol.  FatalToProcotol indicates the
  454. sender is unwilling to accept further messages for this
  455. protocol but that messages for other protocols may be
  456. accepted.  FatalToConnection indicates the sender is
  457.  
  458.  
  459.  
  460.                   5
  461.  
  462.  
  463.  
  464.  
  465.  
  466. Inter-Client Exchange Protocol            X11, Release 6.4
  467.  
  468.  
  469. unwilling to accept any further messages for any protocols
  470. on the connection.  The sender is required to conform to
  471. specified severity conditions for generic and ICE (major
  472. opcode 0) errors; see Sections 6.1 and 6.2.  The class
  473. defines the generic class of error.  Classes are specified
  474. separately for each protocol (numeric values can mean
  475. different things in different protocols).  The error values,
  476. if any, and their types vary with the specific error class
  477. for the protocol.
  478.  
  479.  
  480. 6.  ICE Control Subprotocol -- Major Opcode 0
  481.  
  482. Each of the ICE control opcodes is described below.  Most of
  483. the messages have additional information included beyond the
  484. description above.  The additional information is appended
  485. to the message header and the length field is computed
  486. accordingly.
  487.  
  488. In the following message descriptions, "Expected errors"
  489. indicates errors that may occur in the normal course of
  490. events.  Other errors (in particular BadMajor, BadMinor,
  491. BadState, BadLength, BadValue, ProtocolDuplicate, and
  492. MajorOpcodeDuplicate) might occur, but generally indicate a
  493. serious implementation failure on the part of the errant
  494. peer.
  495. __
  496. |    ByteOrder
  497.  
  498.      byte-order: {MSBfirst, LSBfirst}
  499. |__
  500.  
  501. Both parties must send this message before sending any
  502. other, including errors.  This message specifies the byte
  503. order that will be used on subsequent messages sent by this
  504. party.
  505.  
  506. Note:  If the receiver detects an error in this message, it
  507. must be sure to send its own ByteOrder message before
  508. sending the Error.
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                   6
  527.  
  528.  
  529.  
  530.  
  531.  
  532. Inter-Client Exchange Protocol            X11, Release 6.4
  533.  
  534. __
  535. |    ConnectionSetup
  536.  
  537.      versions: LISTofVERSION
  538.  
  539.      must-authenticate: BOOL
  540.  
  541.      authentication-protocol-names: LISTofSTRING
  542.  
  543.      vendor: STRING
  544.  
  545.      release: STRING
  546.  
  547.  
  548.      Responses: ConnectionReply, AuthenticationRequired.
  549.         (See note)
  550.  
  551.      Expected errors: NoVersion, SetupFailed,
  552.               NoAuthentication,
  553.               AuthenticationRejected,
  554.               AuthenticationFailed.
  555. |__
  556.  
  557. The party that initiates the connection (the one that does
  558. the "connect()") must send this message as the second
  559. message (after ByteOrder) on startup.
  560.  
  561. Versions gives a list, in decreasing order of preference, of
  562. the protocol versions this party is capable of speaking.
  563. This document specifies major version 1, minor version 0.
  564.  
  565. If must-authenticate is True, the initiating party demands
  566. authentication; the accepting party must pick an
  567. authentication scheme and use it.  In this case, the only
  568. valid response is AuthenticationRequired.
  569.  
  570. If must-authenticate is False, the accepting party may
  571. choose an authentication mechanism, use a host-address-based
  572. authentication scheme, or skip authentication.    When must-
  573. authenticate is False, ConnectionReply and
  574. AuthenticationRequired are both valid responses.  If a host-
  575. address-based authentication scheme is used,
  576. AuthenticationRejected and AuthenticationFailed errors are
  577. possible.
  578.  
  579. Authentication-protocol-names  specifies a (possibly null,
  580. if must-authenticate is False) list of authentication
  581. protocols the party is willing to perform.  If must-
  582. authenticate is True, presumably the party will offer only
  583. authentication mechanisms allowing mutual authentication.
  584.  
  585. Vendor gives the name of the vendor of this ICE
  586. implementation.
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                   7
  593.  
  594.  
  595.  
  596.  
  597.  
  598. Inter-Client Exchange Protocol            X11, Release 6.4
  599.  
  600.  
  601. Release gives the release identifier of this ICE
  602. implementation.
  603.  
  604. __
  605. |    AuthenticationRequired
  606.  
  607.      authentication-protocol-index: CARD8
  608.  
  609.      data: <specific to authentication protocol>
  610.  
  611.  
  612.      Response: AuthenticationReply.
  613.  
  614.      Expected errors: AuthenticationRejected,
  615.               AuthenticationFailed.
  616. |__
  617.  
  618. This message is sent in response to a ConnectionSetup or
  619. ProtocolSetup message to specify that authentication is to
  620. be done and what authentication mechanism is to be used.
  621.  
  622. The authentication protocol is specified by a 0-based index
  623. into the list of names given in the ConnectionSetup or
  624. ProtocolSetup.    Any protocol-specific data that might be
  625. required is also sent.
  626. __
  627. |    AuthenticationReply
  628.  
  629.      data: <specific to authentication protocol>
  630.  
  631.  
  632.      Responses: AuthenticationNextPhase, ConnectionReply,
  633.         ProtocolReply.
  634.  
  635.      Expected errors: AuthenticationRejected,
  636.               AuthenticationFailed, SetupFailed.
  637. |__
  638.  
  639. This message is sent in response to an
  640. AuthenticationRequired or AuthenticationNextPhase message,
  641. to supply authentication data as defined by the
  642. authentication protocol being used.
  643.  
  644. Note that this message is sent by the party that initiated
  645. the current negotiation -- the party that sent the
  646. ConnectionSetup or ProtocolSetup message.
  647.  
  648. AuthenticationNextPhase indicates that more is to be done to
  649. complete the authentication.  If the authentication is
  650. complete, ConnectionReply is appropriate if the current
  651. authentication handshake is the result of a ConnectionSetup,
  652. and a ProtocolReply is appropriate if it is the result of a
  653. ProtocolSetup.
  654.  
  655.  
  656.  
  657.  
  658.                   8
  659.  
  660.  
  661.  
  662.  
  663.  
  664. Inter-Client Exchange Protocol            X11, Release 6.4
  665.  
  666. __
  667. |    AuthenticationNextPhase
  668.  
  669.      data: <specific to authentication protocol>
  670.  
  671.  
  672.      Response: AuthenticationReply.
  673.  
  674.      Expected errors: AuthenticationRejected,
  675.               AuthenticationFailed.
  676. |__
  677.  
  678. This message is sent in response to an AuthenticationReply
  679. message, to supply authentication data as defined by the
  680. authentication protocol being used.
  681. __
  682. |    ConnectionReply
  683.  
  684.      version-index: CARD8
  685.  
  686.      vendor: STRING
  687.  
  688.      release: STRING
  689. |__
  690.  
  691. This message is sent in response to a ConnectionSetup or
  692. AuthenticationReply message to indicate that the
  693. authentication handshake is complete.
  694.  
  695. Version-index gives a 0-based index into the list of
  696. versions offered in the ConnectionSetup message; it
  697. specifies the version of the ICE protocol that both parties
  698. should speak for the duration of the connection.
  699.  
  700. Vendor gives the name of the vendor of this ICE
  701. implementation.
  702.  
  703. Release gives the release identifier of this ICE
  704. implementation.
  705.  
  706.  
  707.  
  708.  
  709.  
  710.  
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.                   9
  725.  
  726.  
  727.  
  728.  
  729.  
  730. Inter-Client Exchange Protocol            X11, Release 6.4
  731.  
  732. __
  733. |    ProtocolSetup
  734.  
  735.      protocol-name: STRING
  736.  
  737.      major-opcode: CARD8
  738.  
  739.      versions: LISTofVERSION
  740.  
  741.      vendor: STRING
  742.  
  743.      release: STRING
  744.  
  745.      must-authenticate: BOOL
  746.  
  747.      authentication-protocol-names: LISTofSTRING
  748.  
  749.  
  750.      Responses: AuthenticationRequired, ProtocolReply.
  751.  
  752.      Expected errors: UnknownProtocol, NoVersion,
  753.               SetupFailed, NoAuthentication,
  754.               AuthenticationRejected,
  755.               AuthenticationFailed.
  756. |__
  757.  
  758. This message is used to initiate negotiation of a protocol
  759. and establish any authentication specific to it.
  760.  
  761. Protocol-name gives the name of the protocol the party
  762. wishes to speak.
  763.  
  764. Major-opcode gives the opcode that the party will use in
  765. messages it sends.
  766.  
  767. Versions gives a list of version numbers, in decreasing
  768. order of preference, that the party is willing to speak.
  769.  
  770. Vendor and release are identification strings with semantics
  771. defined by the specific protocol being negotiated.
  772.  
  773. If must-authenticate is True, the initiating party demands
  774. authentication; the accepting party must pick an
  775. authentication scheme and use it.  In this case, the only
  776. valid response is AuthenticationRequired.
  777.  
  778. If must-authenticate is False, the accepting party may
  779. choose an authentication mechanism, use a host-address-based
  780. authentication scheme, or skip authentication.    When must-
  781. authenticate is False, ProtocolReply and
  782. AuthenticationRequired are both valid responses.  If a host-
  783. address-based authentication scheme is used,
  784. AuthenticationRejected and AuthenticationFailed errors are
  785. possible.
  786.  
  787.  
  788.  
  789.  
  790.                  10
  791.  
  792.  
  793.  
  794.  
  795.  
  796. Inter-Client Exchange Protocol            X11, Release 6.4
  797.  
  798.  
  799. Authentication-protocol-names  specifies a (possibly null,
  800. if must-authenticate is False) list of authentication
  801. protocols the party is willing to perform.  If must-
  802. authenticate is True, presumably the party will offer only
  803. authentication mechanisms allowing mutual authentication.
  804. __
  805. |    ProtocolReply
  806.  
  807.      major-opcode: CARD8
  808.  
  809.      version-index: CARD8
  810.  
  811.      vendor: STRING
  812.  
  813.      release: STRING
  814. |__
  815.  
  816. This message is sent in response to a ProtocolSetup or
  817. AuthenticationReply message to indicate that the
  818. authentication handshake is complete.
  819.  
  820. Major-opcode gives the opcode that this party will use in
  821. messages that it sends.
  822.  
  823. Version-index gives a 0-based index into the list of
  824. versions offered in the ProtocolSetup message; it specifies
  825. the version of the protocol that both parties should speak
  826. for the duration of the connection.
  827.  
  828. Vendor and release are identification strings with semantics
  829. defined by the specific protocol being negotiated.
  830.  
  831. __
  832. |    Ping
  833.  
  834.      Response: PingReply.
  835. |__
  836.  
  837. This message is used to test if the connection is still
  838. functioning.
  839. __
  840. |    PingReply
  841. |__
  842.  
  843. This message is sent in response to a Ping message,
  844. indicating that the connection is still functioning.
  845. __
  846. |    WantToClose
  847.  
  848.      Responses: WantToClose, NoClose, ProtocolSetup.
  849. |__
  850.  
  851. This message is used to initiate a possible close of the
  852. connection.  The sending party has noticed that, as a result
  853.  
  854.  
  855.  
  856.                  11
  857.  
  858.  
  859.  
  860.  
  861.  
  862. Inter-Client Exchange Protocol            X11, Release 6.4
  863.  
  864.  
  865. of mechanisms specific to each protocol, there are no active
  866. protocols left.  There are four possible scenarios arising
  867. from this request:
  868.  
  869. (1)  The receiving side noticed too, and has already sent a
  870.      WantToClose.  On receiving a WantToClose while already
  871.      attempting to shut down, each party should simply close
  872.      the connection.
  873.  
  874. (2)  The receiving side hasn't noticed, but agrees.  It
  875.      closes the connection.
  876.  
  877. (3)  The receiving side has a ProtocolSetup "in flight," in
  878.      which case it is to ignore WantToClose and the party
  879.      sending WantToClose is to abandon the shutdown attempt
  880.      when it receives the ProtocolSetup.
  881.  
  882. (4)  The receiving side wants the connection kept open for
  883.      some reason not specified by the ICE protocol, in which
  884.      case it sends NoClose.
  885.  
  886. See the state transition diagram for additional information.
  887. __
  888. |    NoClose
  889. |__
  890.  
  891. This message is sent in response to a WantToClose message to
  892. indicate that the responding party does not want the
  893. connection closed at this time.  The receiving party should
  894. not close the connection.  Either party may again initiate
  895. WantToClose at some future time.
  896.  
  897. 6.1.  Generic Error Classes
  898.  
  899. These errors should be used by all protocols, as applicable.
  900. For ICE (major opcode 0), FatalToProtocol should be
  901. interpreted as FatalToConnection.
  902. __
  903. |    BadMinor
  904.  
  905.      offending-minor-opcode: <any>
  906.  
  907.      severity: FatalToProtocol or CanContinue (protocol's
  908.            discretion)
  909.  
  910.      values: (none)
  911. |__
  912.  
  913. Received a message with an unknown minor opcode.
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.                  12
  923.  
  924.  
  925.  
  926.  
  927.  
  928. Inter-Client Exchange Protocol            X11, Release 6.4
  929.  
  930. __
  931. |    BadState
  932.  
  933.      offending-minor-opcode: <any>
  934.  
  935.      severity: FatalToProtocol or CanContinue (protocol's
  936.            discretion)
  937.  
  938.      values: (none)
  939. |__
  940.  
  941. Received a message with a valid minor opcode which is not
  942. appropriate for the current state of the protocol.
  943. __
  944. |    BadLength
  945.  
  946.      offending-minor-opcode: <any>
  947.  
  948.      severity: FatalToProtocol or CanContinue (protocol's
  949.            discretion)
  950.  
  951.      values: (none)
  952. |__
  953.  
  954. Received a message with a bad length.  The length of the
  955. message is longer or shorter than required to contain the
  956. data.
  957. __
  958. |    BadValue
  959.  
  960.      offending-minor-opcode: <any>
  961.  
  962.      severity: CanContinue
  963.  
  964.      values: CARD32 Byte offset to offending value in
  965.          offending message
  966.          CARD32 Length of offending value
  967.          <varies> Offending value
  968. |__
  969.  
  970. Received a message with a bad value specified.
  971.  
  972. 6.2.  ICE Error Classes
  973.  
  974. These errors are all major opcode 0 errors.
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.                  13
  989.  
  990.  
  991.  
  992.  
  993.  
  994. Inter-Client Exchange Protocol            X11, Release 6.4
  995.  
  996. __
  997. |    BadMajor
  998.  
  999.      offending-minor-opcode: <any>
  1000.  
  1001.      severity: CanContinue
  1002.  
  1003.      values: CARD8 Opcode
  1004. |__
  1005.  
  1006. The opcode given is not one that has been registered.
  1007. __
  1008. |    NoAuthentication
  1009.  
  1010.      offending-minor-opcode: ConnectionSetup, ProtocolSetup
  1011.  
  1012.      severity: ConnectionSetup -> FatalToConnection
  1013.            ProtocolSetup -> FatalToProtocol
  1014.  
  1015.      values: (none)
  1016. |__
  1017.  
  1018. None of the authentication protocols offered are available.
  1019. __
  1020. |    NoVersion
  1021.  
  1022.      offending-minor-opcode: ConnectionSetup, ProtocolSetup
  1023.  
  1024.      severity: ConnectionSetup -> FatalToConnection
  1025.            ProtocolSetup -> FatalToProtocol
  1026.  
  1027.      values: (none)
  1028. |__
  1029.  
  1030. None of the protocol versions offered are available.
  1031. __
  1032. |    SetupFailed
  1033.  
  1034.      offending-minor-opcode: ConnectionSetup, ProtocolSetup,
  1035.                  AuthenticationReply
  1036.  
  1037.      severity: ConnectionSetup -> FatalToConnection
  1038.            ProtocolSetup -> FatalToProtocol
  1039.            AuthenticationReply -> FatalToConnection if
  1040.            authenticating a connection, otherwise
  1041.            FatalToProtocol
  1042.  
  1043.      values: STRING reason
  1044. |__
  1045.  
  1046. The sending side is unable to accept the new connection or
  1047. new protocol for a reason other than authentication failure.
  1048. Typically this error will be a result of inability to
  1049. allocate additional resources on the sending side.  The
  1050. reason field will give a human-interpretable message
  1051.  
  1052.  
  1053.  
  1054.                  14
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060. Inter-Client Exchange Protocol            X11, Release 6.4
  1061.  
  1062.  
  1063. providing further detail on the type of failure.
  1064. __
  1065. |    AuthenticationRejected
  1066.  
  1067.      offending-minor-opcode: AuthenticationReply,
  1068.                  AuthenticationRequired,
  1069.                  AuthenticationNextPhase
  1070.  
  1071.      severity: FatalToProtocol
  1072.  
  1073.      values: STRING reason
  1074. |__
  1075.  
  1076. Authentication rejected.  The peer has failed to properly
  1077. authenticate itself.  The reason field will give a human-
  1078. interpretable message providing further detail.
  1079. __
  1080. |    AuthenticationFailed
  1081.  
  1082.      offending-minor-opcode: AuthenticationReply,
  1083.                  AuthenticationRequired,
  1084.                  AuthenticationNextPhase
  1085.  
  1086.      severity: FatalToProtocol
  1087.  
  1088.      values: STRING reason
  1089. |__
  1090.  
  1091. Authentication failed.    AuthenticationFailed does not imply
  1092. that the authentication was rejected, as
  1093. AuthenticationRejected does.  Instead it means that the
  1094. sender was unable to complete the authentication for some
  1095. other reason.  (For instance, it may have been unable to
  1096. contact an authentication server.)  The reason field will
  1097. give a human-interpretable message providing further detail.
  1098. __
  1099. |    ProtocolDuplicate
  1100.  
  1101.      offending-minor-opcode: ProtocolSetup
  1102.  
  1103.      severity: FatalToProtocol (but see note)
  1104.  
  1105.      values: STRING protocol name
  1106. |__
  1107.  
  1108. The protocol name was already registered.  This is fatal to
  1109. the "new" protocol being set up by ProtocolSetup, but it
  1110. does not affect the existing registration.
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.                  15
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126. Inter-Client Exchange Protocol            X11, Release 6.4
  1127.  
  1128. __
  1129. |    MajorOpcodeDuplicate
  1130.  
  1131.      offending-minor-opcode: ProtocolSetup
  1132.  
  1133.      severity: FatalToProtocol (but see note)
  1134.  
  1135.      values: CARD8 opcode
  1136. |__
  1137.  
  1138. The major opcode specified was already registered.  This is
  1139. fatal to the "new" protocol being set up by ProtocolSetup,
  1140. but it does not affect the existing registration.
  1141. __
  1142. |    UnknownProtocol
  1143.  
  1144.      offending-minor-opcode: ProtocolSetup
  1145.  
  1146.      severity: FatalToProtocol
  1147.  
  1148.      values: STRING protocol name
  1149. |__
  1150.  
  1151. The protocol specified is not supported.
  1152.  
  1153. 7.  State Diagrams
  1154.  
  1155. Here are the state diagrams for the party that initiates the
  1156. connection:
  1157.  
  1158. start:
  1159.      connect to other end, send ByteOrder, ConnectionSetup
  1160.      -> conn_wait
  1161.  
  1162.  
  1163. conn_wait:
  1164.      receive ConnectionReply -> stasis
  1165.      receive AuthenticationRequired -> conn_auth1
  1166.      receive Error -> quit
  1167.      receive <other>, send Error -> quit
  1168.  
  1169.  
  1170. conn_auth1:
  1171.      if good auth data, send AuthenticationReply ->
  1172.      conn_auth2
  1173.      if bad auth data, send Error -> quit
  1174.  
  1175.  
  1176. conn_auth2:
  1177.      receive ConnectionReply -> stasis
  1178.      receive AuthenticationNextPhase -> conn_auth1
  1179.      receive Error -> quit
  1180.      receive <other>, send Error -> quit
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                  16
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192. Inter-Client Exchange Protocol            X11, Release 6.4
  1193.  
  1194.  
  1195. Here are top-level state transitions for the party that
  1196. accepts connections.
  1197.  
  1198. listener:
  1199.      accept connection -> init_wait
  1200.  
  1201.  
  1202. init_wait:
  1203.      receive ByteOrder, ConnectionSetup -> auth_ask
  1204.      receive <other>, send Error -> quit
  1205.  
  1206.  
  1207. auth_ask:
  1208.      send ByteOrder, ConnectionReply -> stasis
  1209.      send AuthenticationRequired -> auth_wait
  1210.      send Error -> quit
  1211.  
  1212.  
  1213. auth_wait:
  1214.      receive AuthenticationReply -> auth_check
  1215.      receive <other>, send Error -> quit
  1216.  
  1217.  
  1218. auth_check:
  1219.      if no more auth needed, send ConnectionReply -> stasis
  1220.      if good auth data, send AuthenticationNextPhase ->
  1221.      auth_wait
  1222.      if bad auth data, send Error -> quit
  1223.  
  1224.  
  1225. Here are the top-level state transitions for all parties
  1226. after the initial connection establishment subprotocol.
  1227.  
  1228. Note:  this is not quite the truth for branches out from
  1229. stasis, in that multiple conversations can be interleaved on
  1230. the connection.
  1231.  
  1232. stasis:
  1233.      send ProtocolSetup -> proto_wait
  1234.      receive ProtocolSetup -> proto_reply
  1235.      send Ping -> ping_wait
  1236.      receive Ping, send PingReply -> stasis
  1237.      receive WantToClose -> shutdown_attempt
  1238.      receive <other>, send Error -> stasis
  1239.      all protocols shut down, send WantToClose -> close_wait
  1240.  
  1241.  
  1242. proto_wait:
  1243.      receive ProtocolReply -> stasis
  1244.      receive AuthenticationRequired -> give_auth1
  1245.      receive Error, give up on this protocol -> stasis
  1246.      receive WantToClose -> proto_wait
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.                  17
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258. Inter-Client Exchange Protocol            X11, Release 6.4
  1259.  
  1260.  
  1261. give_auth1:
  1262.      if good auth data, send AuthenticationReply ->
  1263.      give_auth2
  1264.      if bad auth data, send Error, give up on this protocol
  1265.      -> stasis
  1266.      receive WantToClose -> give_auth1
  1267.  
  1268.  
  1269. give_auth2:
  1270.      receive ProtocolReply -> stasis
  1271.      receive AuthenticationNextPhase -> give_auth1
  1272.      receive Error, give up on this protocol -> stasis
  1273.      receive WantToClose -> give_auth2
  1274.  
  1275.  
  1276. proto_reply:
  1277.      send ProtocolReply -> stasis
  1278.      send AuthenticationRequired -> take_auth1
  1279.      send Error, give up on this protocol -> stasis
  1280.  
  1281.  
  1282. take_auth1:
  1283.      receive AuthenticationReply -> take_auth2
  1284.      receive Error, give up on this protocol -> stasis
  1285.  
  1286.  
  1287. take_auth2:
  1288.      if good auth data -> take_auth3
  1289.      if bad auth data, send Error, give up on this protocol
  1290.      -> stasis
  1291.  
  1292.  
  1293. take_auth3:
  1294.      if no more auth needed, send ProtocolReply -> stasis
  1295.      if good auth data, send AuthenticationNextPhase ->
  1296.      take_auth1
  1297.      if bad auth data, send Error, give up on this protocol
  1298.      -> stasis
  1299.  
  1300.  
  1301. ping_wait:
  1302.      receive PingReply -> stasis
  1303.  
  1304.  
  1305. quit:
  1306.      -> close connection
  1307.  
  1308.  
  1309. Here are the state transitions for shutting down the
  1310. connection:
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.                  18
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. Inter-Client Exchange Protocol            X11, Release 6.4
  1325.  
  1326.  
  1327. shutdown_attempt:
  1328.      if want to stay alive anyway, send NoClose -> stasis
  1329.      else -> quit
  1330.  
  1331.  
  1332. close_wait:
  1333.      receive ProtocolSetup -> proto_reply
  1334.      receive NoClose -> stasis
  1335.      receive WantToClose -> quit
  1336.      connection close -> quit
  1337.  
  1338.  
  1339. 8.  Protocol Encoding
  1340.  
  1341. In the encodings below, the first column is the number of
  1342. bytes occupied.  The second column is either the type (if
  1343. the value is variable) or the actual value.  The third
  1344. column is the description of the value (e.g., the parameter
  1345. name).    Receivers must ignore bytes that are designated as
  1346. unused or pad bytes.
  1347.  
  1348. This document describes major version 1, minor version 0 of
  1349. the ICE protocol.
  1350.  
  1351. LISTof<type> indicates some number of repetitions of <type>,
  1352. with no additional padding.  The number of repetitions must
  1353. be specified elsewhere in the message.
  1354.  
  1355. 8.1.  Primitive Types
  1356.  
  1357.  
  1358. -------------------------------------------------------------
  1359. Type Name Length (bytes) Description
  1360. -------------------------------------------------------------
  1361. CARD8      1         8-bit unsigned integer
  1362. CARD16      2         16-bit unsigned integer
  1363. CARD32      4         32-bit unsigned integer
  1364. LPCE      1         A character from the X Portable
  1365.              Character Set in Latin Portable
  1366.              Character Encoding
  1367. -------------------------------------------------------------
  1368.  
  1369.  
  1370. 8.2.  Enumerations
  1371.  
  1372.  
  1373. -------------------------------------------------------------
  1374. Type Name     Value     Description
  1375. -------------------------------------------------------------
  1376. BOOL          0      False
  1377.           1      True
  1378. -------------------------------------------------------------
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.                  19
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390. Inter-Client Exchange Protocol            X11, Release 6.4
  1391.  
  1392.  
  1393. 8.3.  Compound Types
  1394.  
  1395.  
  1396. ---------------------------------------------------------------------
  1397. Type NameLength (bytes)Type     Description
  1398. ---------------------------------------------------------------------
  1399. VERSION
  1400.      2           CARD16     Major version number
  1401.      2           CARD16     Minor version number
  1402. STRING
  1403.      2           CARD16     length of string in bytes
  1404.      n           LISTofLPCEstring
  1405.      p             unused, p = pad(n+2, 4)
  1406. ---------------------------------------------------------------------
  1407.  
  1408.  
  1409. 8.4.  ICE Minor opcodes
  1410.  
  1411.  
  1412.      -----------------------------------
  1413.      Message Name           Encoding
  1414.      -----------------------------------
  1415.      Error               0
  1416.      ByteOrder               1
  1417.      ConnectionSetup           2
  1418.      AuthenticationRequired       3
  1419.      AuthenticationReply       4
  1420.      AuthenticationNextPhase       5
  1421.      ConnectionReply           6
  1422.      ProtocolSetup           7
  1423.      ProtocolReply           8
  1424.      Ping               9
  1425.      PingReply              10
  1426.      WantToClose          11
  1427.      NoClose              12
  1428.      -----------------------------------
  1429.  
  1430.  
  1431. 8.5.  Message Encoding
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.                  20
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456. Inter-Client Exchange Protocol            X11, Release 6.4
  1457.  
  1458.  
  1459. Error
  1460.   1  CARD8        major-opcode
  1461.   1  0            Error
  1462.   2  CARD16        class
  1463.   4  (n+p)/8+1        length
  1464.   1  CARD8        offending-minor-opcode
  1465.   1            severity:
  1466.      0               CanContinue
  1467.      1               FatalToProtocol
  1468.      2               FatalToConnection
  1469.   2            unused
  1470.   4  CARD32        sequence number of erroneous message
  1471.   n  <varies>        value(s)
  1472.   p            pad, p = pad(n,8)
  1473.  
  1474.  
  1475. ByteOrder
  1476.   1  0            ICE
  1477.   1  1            ByteOrder
  1478.   1            byte-order:
  1479.      0               LSBfirst
  1480.      1               MSBfirst
  1481.   1            unused
  1482.   4  0            length
  1483.  
  1484.  
  1485. ConnectionSetup
  1486.   1  0            ICE
  1487.   1  2            ConnectionSetup
  1488.   1  CARD8        Number of versions offered
  1489.   1  CARD8        Number of authentication protocol names offered
  1490.   4  (i+j+k+m+p)/8+1length
  1491.   1  BOOL        must-authenticate
  1492.   7            unused
  1493.   i  STRING        vendor
  1494.   j  STRING        release
  1495.   k  LISTofSTRING   authentication-protocol-names
  1496.   m  LISTofVERSION  version-list
  1497.   p            unused, p = pad(i+j+k+m,8)
  1498.  
  1499.  
  1500. AuthenticationRequired
  1501.   1  0            ICE
  1502.   1  3            AuthenticationRequired
  1503.   1  CARD8        authentication-protocol-index
  1504.   1            unused
  1505.   4  (n+p)/8+1        length
  1506.   2  n            length of authentication data
  1507.   6            unused
  1508.   n  <varies>        data
  1509.   p            unused, p = pad(n,8)
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.                  21
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522. Inter-Client Exchange Protocol            X11, Release 6.4
  1523.  
  1524.  
  1525. AuthenticationReply
  1526.   1  0            ICE
  1527.   1  4            AuthenticationReply
  1528.   2            unused
  1529.   4  (n+p)/8+1        length
  1530.   2  n            length of authentication data
  1531.   6            unused
  1532.   n  <varies>        data
  1533.   p            unused, p = pad(n,8)
  1534.  
  1535.  
  1536. AuthenticationNextPhase
  1537.   1  0            ICE
  1538.   1  5            AuthenticationNextPhase
  1539.   2            unused
  1540.   4  (n+p)/8+1        length
  1541.   2  n            length of authentication data
  1542.   6            unused
  1543.   n  <varies>        data
  1544.   p            unused, p = pad(n,8)
  1545.  
  1546.  
  1547. ConnectionReply
  1548.   1  0            ICE
  1549.   1  6            ConnectionReply
  1550.   1  CARD8        version-index
  1551.   1            unused
  1552.   4  (i+j+p)/8        length
  1553.   i  STRING        vendor
  1554.   j  STRING        release
  1555.   p            unused, p = pad(i+j,8)
  1556.  
  1557.  
  1558. ProtocolSetup
  1559.   1  0            ICE
  1560.   1  7            ProtocolSetup
  1561.   1  CARD8        major-opcode
  1562.   1  BOOL        must-authenticate
  1563.   4  (i+j+k+m+n+p)/8+1length
  1564.   1  CARD8        Number of versions offered
  1565.   1  CARD8        Number of authentication protocol names offered
  1566.   6            unused
  1567.   i  STRING        protocol-name
  1568.   j  STRING        vendor
  1569.   k  STRING        release
  1570.   m  LISTofSTRING   authentication-protocol-names
  1571.   n  LISTofVERSION  version-list
  1572.   p            unused, p = pad(i+j+k+m+n,8)
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.                  22
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588. Inter-Client Exchange Protocol            X11, Release 6.4
  1589.  
  1590.  
  1591. ProtocolReply
  1592.   1  0            ICE
  1593.   1  8            ProtocolReply
  1594.   1  CARD8        version-index
  1595.   1  CARD8        major-opcode
  1596.   4  (i+j+p)/8        length
  1597.   i  STRING        vendor
  1598.   j  STRING        release
  1599.   p            unused, p = pad(i+j, 8)
  1600.  
  1601.  
  1602. Ping
  1603.   1  0            ICE
  1604.   1  9            Ping
  1605.   2  0            unused
  1606.   4  0            length
  1607.  
  1608.  
  1609. PingReply
  1610.   1  0            ICE
  1611.   1  10         PingReply
  1612.   2  0            unused
  1613.   4  0            length
  1614.  
  1615.  
  1616. WantToClose
  1617.   1  0            ICE
  1618.   1  11         WantToClose
  1619.   2  0            unused
  1620.   4  0            length
  1621.  
  1622.  
  1623. NoClose
  1624.   1  0            ICE
  1625.   1  12         NoClose
  1626.   2  0            unused
  1627.   4  0            length
  1628.  
  1629.  
  1630. 8.6.  Error Class Encoding
  1631.  
  1632. Generic errors have classes in the range 0x8000-0xFFFF, and
  1633. subprotocol-specific errors are in the range 0x0000-0x7FFF.
  1634.  
  1635. 8.6.1.    Generic Error Class Encoding
  1636.  
  1637.  
  1638. ---------------------
  1639. Class        Encoding
  1640. ---------------------
  1641. BadMinor     0x8000
  1642. BadState     0x8001
  1643. BadLength    0x8002
  1644.  
  1645.  
  1646.  
  1647.  
  1648.                  23
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654. Inter-Client Exchange Protocol            X11, Release 6.4
  1655.  
  1656.  
  1657. BadValue     0x8003
  1658. ---------------------
  1659.  
  1660.  
  1661. 8.6.2.    ICE-specific Error Class Encoding
  1662.  
  1663.  
  1664. ----------------------------------
  1665. Class             Encoding
  1666. ----------------------------------
  1667. BadMajor            0
  1668. NoAuthentication        1
  1669. NoVersion            2
  1670. SetupFailed            3
  1671. AuthenticationRejected        4
  1672. AuthenticationFailed        5
  1673. ProtocolDuplicate        6
  1674. MajorOpcodeDuplicate        7
  1675. UnknownProtocol         8
  1676. ----------------------------------
  1677.  
  1678.  
  1679.  
  1680.  
  1681.  
  1682.  
  1683.  
  1684.  
  1685.  
  1686.  
  1687.  
  1688.  
  1689.  
  1690.  
  1691.  
  1692.  
  1693.  
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.                  24
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720. Inter-Client Exchange Protocol            X11, Release 6.4
  1721.  
  1722.  
  1723.  
  1724.  
  1725.              Appendix A
  1726.  
  1727.  
  1728. A.  Modification History
  1729.  
  1730. A.1.  Release 6 to Release 6.1
  1731.  
  1732. Release 6.1 added the ICE X rendezvous protocol (Appendix B)
  1733. and updated the document version to 1.1.
  1734.  
  1735. A.2.  Release 6.1 to Release 6.3
  1736.  
  1737. Release 6.3 added the listen on well known ports feature.
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.                  25
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786. Inter-Client Exchange Protocol            X11, Release 6.4
  1787.  
  1788.  
  1789.  
  1790.  
  1791.              Appendix B
  1792.  
  1793.  
  1794. B.  ICE X Rendezvous Protocol
  1795.  
  1796. B.1.  Introduction
  1797.  
  1798. The ICE X rendezvous protocol is designed to answer the need
  1799. posed in Section 2 for one mechanism by which two clients
  1800. interested in communicating via ICE are able to exchange the
  1801. necessary information.    This protocol is appropriate for any
  1802. two ICE clients who also have X connections to the same X
  1803. server.
  1804.  
  1805. B.2.  Overview of ICE X Rendezvous
  1806.  
  1807. The ICE X Rendezvous Mechanism requires clients willing to
  1808. act as ICE originating parties to pre-register the ICE
  1809. subprotocols they support in an ICE_PROTOCOLS property on
  1810. their top-level window.  Clients willing to act as ICE
  1811. answering parties then send an ICE_PROTOCOLS X ClientMessage
  1812. event to the ICE originating parties.  This ClientMessage
  1813. event identifies the ICE network IDs of the ICE answering
  1814. party as well as the ICE subprotocol it wishes to speak.
  1815. Upon receipt of this message the ICE originating party uses
  1816. the information to establish an ICE connection with the ICE
  1817. answering party.
  1818.  
  1819. B.3.  Registering Known Protocols
  1820.  
  1821. Clients willing to act as ICE originating parties
  1822. preregister the ICE subprotocols they support in a list of
  1823. atoms held by an ICE_PROTOCOLS property on their top-level
  1824. window.  The name of each atom listed in ICE_PROTOCOLS must
  1825. be of the form ICE_INITIATE_pname where pname is the name of
  1826. the ICE subprotocol the ICE originating party is willing to
  1827. speak, as would be specified in an ICE ProtocolSetup
  1828. message.
  1829.  
  1830. Clients with an ICE_INITIATE_pname atom in the ICE_PROTOCOLS
  1831. property on their top-level windows must respond to
  1832. ClientMessage events of type ICE_PROTOCOLS specifying
  1833. ICE_INITIATE_pname.  If a client does not want to respond to
  1834. these client message events, it should remove the
  1835. ICE_INITIATE_pname atom from its ICE_PROTOCOLS property or
  1836. remove the ICE_PROTOCOLS property entirely.
  1837.  
  1838. B.4.  Initiating the Rendezvous
  1839.  
  1840. To initiate the rendezvous a client acting as an ICE
  1841. answering party sends an X ClientMessage event of type
  1842. ICE_PROTOCOLS to an ICE originating party.  This
  1843.  
  1844.  
  1845.  
  1846.                  26
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852. Inter-Client Exchange Protocol            X11, Release 6.4
  1853.  
  1854.  
  1855. ICE_PROTOCOLS client message contains the information the
  1856. ICE originating party needs to identify the ICE subprotocol
  1857. the two parties will use as well as the ICE network
  1858. identification string of the ICE answering party.
  1859.  
  1860. Before the ICE answering party sends the client message
  1861. event it must define a text property on one of its windows.
  1862. This text property contains the ICE answering party's ICE
  1863. network identification string and will be used by ICE
  1864. originating parties to determine the ICE answering party's
  1865. list of ICE network IDs.
  1866.  
  1867. The property name will normally be ICE_NETWORK_IDS, but may
  1868. be any name of the ICE answering party's choosing.  The
  1869. format for this text property is as follows:
  1870.  
  1871. --------------------------------------------------------
  1872. Field           Value
  1873. --------------------------------------------------------
  1874. type           XA_STRING
  1875. format           8
  1876. value           comma-separated list of ICE network IDs
  1877. --------------------------------------------------------
  1878.  
  1879.  
  1880. Once the ICE answering party has established this text
  1881. property on one of its windows, it initiates the rendezvous
  1882. by sending an ICE_PROTOCOLS ClientMessage event to an ICE
  1883. originating party's top-level window.  This event has the
  1884. following format and must only be sent to windows that have
  1885. pre-registered the ICE subprotocol in an ICE_PROTOCOLS
  1886. property on their top-level window.
  1887.  
  1888. -------------------------------------------------------------
  1889. Field           Value
  1890. -------------------------------------------------------------
  1891. message_type   Atom = "ICE_PROTOCOLS"
  1892. format           32
  1893. data.l[0]      Atom identifying the ICE subprotocol to speak
  1894. data.l[1]      Timestamp
  1895. data.l[2]      ICE answering party's window ID with ICE
  1896.            network IDs text property
  1897. data.l[3]      Atom naming text property containing the ICE
  1898.            answering party's ICE network IDs
  1899. data.l[4]      Reserved.  Must be 0.
  1900. -------------------------------------------------------------
  1901.  
  1902. The name of the atom in data.l[0] must be of the form
  1903. ICE_INITIATE_pname, where pname is the name of the ICE
  1904. subprotocol the ICE answering party wishes to speak.
  1905.  
  1906. When an ICE originating party receives a ClientMessage event
  1907. of type ICE_PROTOCOLS specifying ICE_INITIATE_pname it can
  1908. initiate an ICE connection with the ICE answering party.  To
  1909.  
  1910.  
  1911.  
  1912.                  27
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918. Inter-Client Exchange Protocol            X11, Release 6.4
  1919.  
  1920.  
  1921. open this connection the client retrieves the ICE answering
  1922. party's ICE network IDs from the window specified in
  1923. data.l[2] using the text property specified in data.l[3].
  1924.  
  1925. If the connection attempt fails for any reason, the client
  1926. must respond to the client message event by sending a return
  1927. ClientMessage event to the window specified in data.l[2].
  1928. This return event has the following format:
  1929.  
  1930. --------------------------------------------------------------
  1931. Field           Value
  1932. --------------------------------------------------------------
  1933. message_type   Atom = "ICE_INITIATE_FAILED"
  1934. format           32
  1935. data.l[0]      Atom identifying the ICE subprotocol requested
  1936. data.l[1]      Timestamp
  1937. data.l[2]      Initiating party's window ID (holding
  1938.            ICE_PROTOCOLS)
  1939. data.l[3]      int: reason for failure
  1940. data.l[4]      Reserved, must be 0
  1941. --------------------------------------------------------------
  1942.  
  1943. The values of data.l[0] and data.l[1] are copied directly
  1944. from the client message event the client received.
  1945.  
  1946. The value in data.l[2] is the id of the window to which the
  1947. ICE_PROTOCOLS.ICE_INITIATE_pname client message event was
  1948. sent.
  1949.  
  1950. Data.l[3] has one of the following values:
  1951.  
  1952.  
  1953. ---------------------------------------------------------------------------
  1954. Value               Encoding   Description
  1955. ---------------------------------------------------------------------------
  1956. OpenFailed          1      The client was unable to open the
  1957.                   connection (e.g. a call to
  1958.                   IceOpenConnection() failed).    If the
  1959.                   client is able to distinguish
  1960.                   authentication or authorization errors
  1961.                   from general errors, then the preferred
  1962.                   reply is AuthenticationFailed for
  1963.                   authorization errors.
  1964. AuthenticationFailed      2      Authentication or authorization of the
  1965.                   connection or protocol setup was
  1966.                   refused.  This reply will be given only
  1967.                   if the client is able to distinguish it
  1968.                   from OpenFailed; otherwise OpenFailed
  1969.                   will be returned.
  1970. SetupFailed          3      The client was unable to initiate the
  1971.                   specified protocol on the connection
  1972.                   (e.g. a call to IceProtocolSetup()
  1973.                   failed).
  1974.  
  1975.  
  1976.  
  1977.  
  1978.                  28
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984. Inter-Client Exchange Protocol            X11, Release 6.4
  1985.  
  1986.  
  1987. UnknownProtocol       4      The client does not recognize the
  1988.                   requested protocol.  (This represents a
  1989.                   semantic error on the part of the
  1990.                   answering party.)
  1991. Refused           5      The client was in the process of
  1992.                   removing ICE_INITIATE_pname from its
  1993.                   ICE_PROTOCOLS list when the client
  1994.                   message was sent; the client no longer
  1995.                   is willing to establish the specified
  1996.                   ICE communication.
  1997. ---------------------------------------------------------------------------
  1998.  
  1999.  
  2000.  
  2001.            Advice to Implementors
  2002.  
  2003.      Clients willing to act as ICE originating parties
  2004.      must update the ICE_PROTOCOLS property on their
  2005.      top-level windows to include the
  2006.      ICE_INITIATE_pname atom(s) identifying the ICE
  2007.      subprotocols they speak.  The method a client uses
  2008.      to update the ICE_PROTOCOLS property to include
  2009.      ICE_INITIATE_pname atoms is implementation
  2010.      dependent, but the client must ensure the
  2011.      integrity of the list to prevent the accidental
  2012.      omission of any atoms previously in the list.
  2013.  
  2014.      When setting up the ICE network IDs text property
  2015.      on one of its windows, the ICE answering party can
  2016.      determine its comma-separated list of ICE network
  2017.      IDs by calling IceComposeNetworkIdList() after
  2018.      making a call to IceListenForConnections().  The
  2019.      method an ICE answering party uses to find the
  2020.      top-level windows of clients willing to act as ICE
  2021.      originating parties is dependent upon the nature
  2022.      of the answering party.  Some may wish to use the
  2023.      approach of requiring the user to click on a
  2024.      client's window.  Others wishing to find existing
  2025.      clients without requiring user interaction might
  2026.      use something similar to the XQueryTree() method
  2027.      used by several freely-available applications.  In
  2028.      order for the ICE answering party to become
  2029.      automatically aware of new clients willing to
  2030.      originate ICE connections, the ICE answering party
  2031.      might register for SubstructureNotify events on
  2032.      the root window of the display.  When it receives
  2033.      a SubstructureNotify event, the ICE answering
  2034.      party can check to see if it was the result of the
  2035.      creation of a new client top-level window with an
  2036.      ICE_PROTOCOLS property.
  2037.  
  2038.      In any case, before attempting to use this ICE X
  2039.      Rendezvous Mechanism ICE answering parties wishing
  2040.      to speak ICE subprotocol pname should check for
  2041.  
  2042.  
  2043.  
  2044.                  29
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050. Inter-Client Exchange Protocol            X11, Release 6.4
  2051.  
  2052.  
  2053.      the ICE_INITIATE_pname atom in the ICE_PROTOCOLS
  2054.      property on a client's top-level window.  A client
  2055.      that does not include an ICE_INITIATE_pname atom
  2056.      in a ICE_PROTOCOLS property on some top-level
  2057.      window should be assumed to ignore ClientMessage
  2058.      events of type ICE_PROTOCOLS specifying
  2059.      ICE_INITIATE_pname for ICE subprotocol pname.
  2060.  
  2061.  
  2062. B.5.  ICE Subprotocol Versioning
  2063.  
  2064. Although the version of the ICE subprotocol could be passed
  2065. in the client message event, ICE provides more a flexible
  2066. version negotiation mechanism than will fit within a single
  2067. ClientMessage event.  Because of this, ICE subprotocol
  2068. versioning is handled within the ICE protocol setup phase.
  2069.  
  2070.               Example
  2071.  
  2072.      Clients wish to communicate with each other via an
  2073.      ICE subprotocol known as "RAP V1.0".  In RAP
  2074.      terminology one party, the "agent", communicates
  2075.      with other RAP-enabled applications on demand.
  2076.      The user may direct the agent to establish
  2077.      communication with a specific application by
  2078.      clicking on the application's window, or the agent
  2079.      may watch for new application windows to be
  2080.      created and automatically establish communication.
  2081.  
  2082.      During startup the ICE answering party (the agent)
  2083.      first calls IceRegisterForProtocolReply() with a
  2084.      list of the versions (i.e., 1.0) of RAP the agent
  2085.      can speak.  The answering party then calls
  2086.      IceListenForConnections() followed by
  2087.      IceComposeNetworkIdList() and stores the resulting
  2088.      ICE network IDs string in a text property on one
  2089.      of its windows.
  2090.  
  2091.      When the answering party (agent) finds a client
  2092.      with which it wishes to speak, it checks to see if
  2093.      the ICE_INITIATE_RAP atom is in the ICE_PROTOCOLS
  2094.      property on the client's top-level window.  If it
  2095.      is present the agent sends the client's top-level
  2096.      window an ICE_PROTOCOLS client message event as
  2097.      described above.  When the client receives the
  2098.      client message event and is willing to originate
  2099.      an ICE connection using RAP, it performs an
  2100.      IceRegisterForProtocolSetup() with a list of the
  2101.      versions of RAP the client can speak.  The client
  2102.      then retrieves the agent's ICE network ID from the
  2103.      property and window specified by the agent in the
  2104.      client message event and calls
  2105.      IceOpenConnection().  After this call succeeds the
  2106.      client calls IceProtocolSetup() specifying the RAP
  2107.  
  2108.  
  2109.  
  2110.                  30
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116. Inter-Client Exchange Protocol            X11, Release 6.4
  2117.  
  2118.  
  2119.      protocol.    During this process, ICE calls the RAP
  2120.      protocol routines that handle the version
  2121.      negotiation.
  2122.  
  2123.      Note that it is not necessary for purposes of this
  2124.      rendezvous that the client application call any
  2125.      ICElib functions prior to receipt of the client
  2126.      message event.
  2127.  
  2128.  
  2129.  
  2130.  
  2131.  
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154.  
  2155.  
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.                  31
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182. Inter-Client Exchange Protocol            X11, Release 6.4
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.  
  2189.  
  2190.  
  2191.  
  2192.  
  2193.  
  2194.  
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.  
  2206.  
  2207.  
  2208.  
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.  
  2216.  
  2217.  
  2218.  
  2219.  
  2220.  
  2221.  
  2222.  
  2223.  
  2224.  
  2225.  
  2226.  
  2227.  
  2228.  
  2229.  
  2230.  
  2231.  
  2232.  
  2233.  
  2234.  
  2235.  
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.                  32
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.              Table of Contents
  2252.  
  2253.  
  2254. 1. Purpose and Goals . . . . . . . . . . . . . . . . . .   1
  2255. 2. Overview of the protocol  . . . . . . . . . . . . . .   1
  2256. 3. Data Types  . . . . . . . . . . . . . . . . . . . . .   3
  2257. 3.1. Primitive Types . . . . . . . . . . . . . . . . . .   3
  2258. 3.2. Complex Types . . . . . . . . . . . . . . . . . . .   4
  2259. 4. Message Format  . . . . . . . . . . . . . . . . . . .   4
  2260. 5. Overall Protocol Description  . . . . . . . . . . . .   5
  2261. 6. ICE Control Subprotocol -- Major Opcode 0 . . . . . .   6
  2262. 6.1. Generic Error Classes . . . . . . . . . . . . . . .  12
  2263. 6.2. ICE Error Classes . . . . . . . . . . . . . . . . .  13
  2264. 7. State Diagrams  . . . . . . . . . . . . . . . . . . .  16
  2265. 8. Protocol Encoding . . . . . . . . . . . . . . . . . .  19
  2266. 8.1. Primitive Types . . . . . . . . . . . . . . . . . .  19
  2267. 8.2. Enumerations  . . . . . . . . . . . . . . . . . . .  19
  2268. 8.3. Compound Types  . . . . . . . . . . . . . . . . . .  19
  2269. 8.4. ICE Minor opcodes . . . . . . . . . . . . . . . . .  20
  2270. 8.5. Message Encoding  . . . . . . . . . . . . . . . . .  20
  2271. 8.6. Error Class Encoding  . . . . . . . . . . . . . . .  23
  2272. 8.6.1. Generic Error Class Encoding  . . . . . . . . . .  23
  2273. 8.6.2. ICE-specific Error Class Encoding . . . . . . . .  24
  2274. A. Modification History  . . . . . . . . . . . . . . . .  25
  2275. A.1. Release 6 to Release 6.1  . . . . . . . . . . . . .  25
  2276. A.2. Release 6.1 to Release 6.3  . . . . . . . . . . . .  25
  2277. B. ICE X Rendezvous Protocol . . . . . . . . . . . . . .  26
  2278. B.1. Introduction  . . . . . . . . . . . . . . . . . . .  26
  2279. B.2. Overview of ICE X Rendezvous  . . . . . . . . . . .  26
  2280. B.3. Registering Known Protocols . . . . . . . . . . . .  26
  2281. B.4. Initiating the Rendezvous . . . . . . . . . . . . .  26
  2282. B.5. ICE Subprotocol Versioning  . . . . . . . . . . . .  30
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.                   i
  2309.  
  2310.  
  2311.