1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
6 <!-- lifted from troff+ms+XMan by doclifter -->
10 <title>Inter-Client Exchange (ICE) Protocol</title>
11 <subtitle>X Consortium Standard</subtitle>
12 <releaseinfo>X Version 11, Release 6.4</releaseinfo>
15 <firstname>Robert</firstname><surname>Scheifler</surname>
18 <firstname>Jordan</firstname><surname>Brown</surname>
19 <affiliation><orgname>Quarterdeck Office Systems</orgname></affiliation>
22 <corpname>X Consortium Standard</corpname>
23 <copyright><year>1993</year><holder>X Consortium</holder></copyright>
24 <copyright><year>1994</year><holder>X Consortium</holder></copyright>
25 <releaseinfo>Version 1.0</releaseinfo>
26 <affiliation><orgname>X Consortium</orgname></affiliation>
27 <productnumber>X Version 11, Release 7</productnumber>
30 <para>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</para>
32 <para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para>
34 <para>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para>
36 <para>Except as contained in this notice, the name of the X Consortium shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from the X Consortium.</para>
38 <para>X Window System is a trademark of X Consortium, Inc.</para>
43 There are numerous possible protocols that can be used for communication
44 among clients. They have many similarities and common needs, including
45 authentication, version negotiation, data typing, and connection management. The <emphasis remap='I'> Inter-Client Exchange</emphasis> (ICE) protocol
46 is intended to provide a framework for building such protocols. Using
47 ICE reduces the complexity of designing new protocols and
48 allows the sharing of many aspects of the implementation.
53 <chapter id="purpose_and_goals">
54 <title>Purpose and Goals</title>
57 In discussing a variety of protocols -- existing, under development, and
58 hypothetical -- it was noted that they have many elements in common. Most
59 protocols need mechanisms for authentication, for
61 and for setting up and taking down connections. There are also
62 cases where the same two parties need to talk to each other using multiple
63 protocols. For example, an embedding relationship between two parties is
64 likely to require the simultaneous use of session management, data transfer,
65 focus negotiation, and command notification protocols. While these are
66 logically separate protocols, it is desirable for them to share as many
67 pieces of implementation as possible.</para>
73 (ICE) protocol provides a generic framework for building protocols on top of
74 reliable, byte-stream transport connections. It provides basic mechanisms
75 for setting up and shutting down connections, for performing authentication,
78 and for reporting errors. The
79 protocols running within an ICE connection are referred to here as
80 <emphasis remap='I'>subprotocols.</emphasis>
81 ICE provides facilities for each subprotocol to do its own version
82 negotiation, authentication, and error reporting. In addition, if two
83 parties are communicating using several different subprotocols, ICE will
84 allow them to share the same transport layer connection.</para>
88 <chapter id="overview_of_the_protocol">
89 <title>Overview of the Protocol</title>
92 <para>Through some mechanism outside ICE, two parties make themselves known to
93 each other and agree that they would like to communicate using an ICE
94 subprotocol. ICE assumes that this negotation includes some notion by which
95 the parties will decide which is the \*Qoriginating\*U party and which is
96 the \*Qanswering\*U party. The negotiation will also need to provide the
97 originating party with a name or address of the answering party. Examples
98 of mechanisms by which parties can make themselves known to each other are
99 the X selection mechanism, environment
100 variables, and shared files.</para>
102 <para>The originating party first determines whether there is an existing ICE
103 connection between the two parties. If there is, it can re-use the existing
104 connection and move directly to the setup of the subprotocol. If no ICE
105 connection exists, the originating party will open a transport connection to
106 the answering party and will start ICE connection setup.</para>
108 <para>The ICE connection setup dialog consists of three major parts: byte order
109 exchange, authentication, and connection information exchange. The first
110 message in each direction is a
111 <function>ByteOrder</function>
112 message telling which byte order will be used by the sending party in
113 messages that it sends. After that, the originating party sends a
114 <function>ConnectionSetup</function>
115 message giving information about itself (vendor name and release number) and
116 giving a list of ICE version numbers it is capable of supporting and a list
117 of authentication schemes it is willing to accept. Authentication is
118 optional. If no authentication is required, the answering party responds
120 <function>ConnectionReply</function>
121 message giving information about itself, and the connection setup is complete.</para>
123 <para>If the connection setup is to be authenticated, the answering party will
125 <function>AuthenticationRequired</function>
127 <function>ConnectionReply</function>
128 message. The parties then exchange
129 <function>AuthenticationReply</function>
131 <function>AuthenticationNextPhase</function>
132 messages until authentication is complete, at which time the answering party
134 <function>ConnectionReply</function>
137 <para>Once an ICE connection is established (or an existing connection reused),
138 the originating party starts subprotocol negotiation by sending a
139 <function>ProtocolSetup</function>
140 message. This message gives the name of the subprotocol that the parties
141 have agreed to use, along with the ICE major opcode that the originating
142 party has assigned to that subprotocol. Authentication can also occur for
143 the subprotocol, independently of authentication for the connection.
144 Subprotocol authentication is optional. If there is no subprotocol
145 authentication, the answering party responds with a
146 <function>ProtocolReply</function>
147 message, giving the ICE major opcode that it has assigned
148 for the subprotocol.</para>
150 <para>Subprotocols are authenticated independently of each other, because they may
151 have differing security requirements. If there is authentication for this
152 particular subprotocol, it takes place before the answering party emits the
153 <function>ProtocolReply</function>
154 message, and it uses the
155 <function>AuthenticationRequired</function>
156 <function>AuthenticationReply</function>
158 <function>AuthenticationNextPhase</function>
159 messages, just as for the connection authentication. Only when subprotocol
160 authentication is complete does the answering party send its
161 <function>ProtocolReply</function>
164 <para>When a subprotocol has been set up and authenticated, the two parties can
165 communicate using messages defined by the subprotocol. Each message has two
166 opcodes: a major opcode and a minor opcode. Each party will send messages
167 using the major opcode it has assigned in its
168 <function>ProtocolSetup</function>
170 <function>ProtocolReply</function>
171 message. These opcodes will, in general, not be the same. For a particular
172 subprotocol, each party will need to keep track of two major opcodes: the
173 major opcode it uses when it sends messages, and the major opcode it expects
174 to see in messages it receives. The minor opcode values and semantics are
175 defined by each individual subprotocol.</para>
177 <para>Each subprotocol will have one or more messages whose semantics are that the
178 subprotocol is to be shut down. Whether this is done unilaterally or is
179 performed through negotiation is defined by each subprotocol. Once a
180 subprotocol is shut down, its major opcodes are removed from
181 use; no further messages on this subprotocol should be sent until the
182 opcode is reestablished with
183 <function>ProtocolSetup</function>
186 <para>ICE has a facility to negotiate the closing of the connection when there are
187 no longer any active subprotocols. When either party decides that no
188 subprotocols are active, it can send a
189 <function>WantToClose</function>
190 message. If the other party agrees to close the connection, it can simply
191 do so. If the other party wants to keep the connection open, it can
192 indicate its desire by replying with a
193 <function>NoClose</function>
195 <!-- XXX \- Note that it's likely that both parties will WantToClose at once. -->
197 <para>It should be noted that the party that initiates the connection isn't
198 necessarily the same as the one that initiates setting up a subprotocol.
199 For example, suppose party A connects to party B. Party A will issue the
200 <function>ConnectionSetup</function>
201 message and party B will respond with a
202 <function>ConnectionReply</function>
203 message. (The authentication steps are omitted here for brevity.)
204 Typically, party A will also issue the
205 <function>ProtocolSetup</function>
207 <function>ProtocolReply</function>
208 from party B. Once the connection is established, however, either party may
209 initiate the negotiation of a subprotocol. Continuing this example, party B
210 may decide that it needs to set up a subprotocol for communication with
211 party A. Party B would issue the
212 <function>ProtocolSetup</function>
214 <function>ProtocolReply</function>
216 <!-- .nH 1 "Data Types" -->
219 <chapter id="data_types">
220 <title>Data Types</title>
222 <para>ICE messages contain several types of data. Byte order is negotiated in
223 the initial connection messages; in general data is sent in the sender's
224 byte order and the receiver is required to swap it appropriately.
225 In order to support 64-bit machines, ICE messages
226 are padded to multiples of 8 bytes. All messages are designed so that
227 fields are \*Qnaturally\*U aligned on 16-, 32-, and 64-bit boundaries.
228 The following formula gives the number of bytes necessary
229 to pad <emphasis remap='I'>E</emphasis> bytes to the next multiple of
230 <emphasis remap='I'>b</emphasis>:</para>
231 <literallayout remap='DS'>
233 pad(<emphasis remap='I'>E</emphasis>, <emphasis remap='I'>b</emphasis>) = (<emphasis remap='I'>b</emphasis> - (<emphasis remap='I'>E</emphasis> mod <emphasis remap='I'>b</emphasis>)) mod <emphasis remap='I'>b</emphasis>
236 <sect1 id="primitive_types">
237 <title>Primitive Types</title>
239 <informaltable pgwide='1' frame='none'>
240 <tgroup cols='2' align='center'>
241 <colspec colname='c1'/>
242 <colspec colname='c2'/>
245 <entry align='left'>Type Name</entry>
246 <entry align='left'>Description</entry>
251 <entry align='left'>CARD8</entry>
252 <entry align='left'>8-bit unsigned integer</entry>
255 <entry align='left'>CARD16</entry>
256 <entry align='left'>16-bit unsigned integer</entry>
259 <entry align='left'>CARD32</entry>
260 <entry align='left'>32-bit unsigned integer</entry>
263 <entry align='left'>BOOL</entry>
264 <entry align='left'><para><function>False</function>
266 <function>True</function></para></entry>
269 <entry align='left'>LPCE</entry>
270 <entry align='left'>A character from the X Portable Character Set in Latin Portable Character
279 <sect1 id="complex_types">
280 <title>Complex Types</title>
282 <informaltable pgwide='1' frame='none'>
283 <tgroup cols='2' align='center'>
284 <colspec colname='c1'/>
285 <colspec colname='c2'/>
288 <entry align='left'>Type Name</entry>
289 <entry align='left'>Type</entry>
292 <entry align='left'>.TH</entry>
293 <entry align='left'></entry>
298 <entry align='left'>VERSION</entry>
299 <entry align='left'>[Major, minor: CARD16]</entry>
302 <entry align='left'>STRING</entry>
303 <entry align='left'>LISTofLPCE</entry>
310 <para>LISTof<type> denotes a counted collection of <type>. The exact encoding
311 varies depending on the context; see the encoding section.</para>
312 <!-- .nH 1 "Message Format" -->
315 <sect1 id="message_format">
316 <title>Message Format</title>
318 <para>All ICE messages include the following information:</para>
320 <informaltable pgwide='1' frame='none'>
321 <tgroup cols='2' align='center'>
322 <colspec colname='c1'/>
323 <colspec colname='c2'/>
326 <entry>Field Type</entry>
327 <entry>Description</entry>
332 <entry align='left'>CARD8</entry>
333 <entry align='left'>protocol major opcode</entry>
336 <entry align='left'>CARD8</entry>
337 <entry align='left'>protocol minor opcode</entry>
340 <entry align='left'>CARD32</entry>
341 <entry align='left'>length of remaining data in 8-byte units</entry>
348 <para>The fields are as follows:</para>
352 <term>Protocol major opcode</term>
355 This specifies what subprotocol the message is intended for. Major opcode
356 0 is reserved for ICE control messages. The major opcodes of other
357 subprotocols are dynamically assigned and exchanged at protocol
363 <term>Protocol minor opcode</term>
366 This specifies what protocol-specific operation is to be performed.
367 Minor opcode 0 is reserved for Errors; other values are protocol-specific.
372 <term>Length of data in 8-byte units</term>
375 This specifies the length of the information following the first 8 bytes.
376 Each message-type has a different format, and will need to be separately
377 length-checked against this value. As every data item has either an
378 explicit length, or an implicit length, this can be easily accomplished.
379 Messages that have too little or too much data indicate a serious
380 protocol failure, and should result in a <function>BadLength</function>
390 <chapter id="overall_protocol_description">
391 <title>Overall Protocol Description</title>
394 Every message sent in a given direction has an implicit sequence number,
395 starting with 1. Sequence numbers are global to the connection; independent
396 sequence numbers are <emphasis remap='I'>not</emphasis> maintained for each protocol.</para>
398 <para>Messages of a given major-opcode (i.e., of a given protocol) must be
399 responded to (if a response is called for) in order by the receiving party.
400 Messages from different protocols can be responded to in arbitrary order.</para>
402 <para>Minor opcode 0 in every protocol is for reporting errors. At most one error
403 is generated per request. If more than one error condition is encountered
404 in processing a request, the choice of which error is returned is
405 implementation-dependent.
408 <para><function>Error</function></para>
409 <variablelist remap='IP'>
411 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
417 <term><emphasis remap='I'>severity</emphasis>:</term>
420 {<symbol role='Pn'>CanContinue</symbol>,
421 <function>FatalToProtocol</function>
422 <function>FatalToConnection</function>
427 <term><emphasis remap='I'>sequence-number</emphasis>:</term>
433 <term><emphasis remap='I'>class</emphasis>:</term>
439 <term><emphasis remap='I'>value(s)</emphasis>:</term>
441 <para><dependent on major/minor opcode and class></para>
447 This message is sent to report an error in response to a message
448 from any protocol. The <function>Error</function> message
449 exists in all protocol major-opcode spaces; it
450 is minor-opcode zero in every protocol. The minor opcode of the
451 message that caused the error is reported, as well as the sequence
452 number of that message.
453 The severity indicates the sender's behavior following
454 the identification of the error. <function>CanContinue</function>
455 indicates the sender is willing to accept additional messages for this
456 protocol. <function>FatalToProcotol</function>
457 indicates the sender is unwilling to accept further messages for this
458 protocol but that messages for other protocols may be accepted.
459 <function>FatalToConnection</function>
460 indicates the sender is unwilling to accept any further
461 messages for any protocols on the connection. The sender
462 is required to conform to specified severity conditions
463 for generic and ICE (major opcode 0) errors; see
464 <link linkend="generic_error_classes">
465 <xref linkend="generic_error_classes"></xref></link> and
466 <link linkend="ice_error_classes">
467 <xref linkend="ice_error_classes"></xref></link>.
469 The class defines the generic class of
470 error. Classes are specified separately for each protocol (numeric
471 values can mean different things in different protocols). The error
472 values, if any, and their types vary with the specific error class
477 <chapter id="ice_control_subprotocol__major_opcode_0">
478 <title>ICE Control Subprotocol -- Major Opcode 0</title>
481 Each of the ICE control opcodes is described below.
482 Most of the messages have additional information included beyond the
483 description above. The additional information is appended to the message
484 header and the length field is computed accordingly.
488 In the following message descriptions, \*QExpected errors\*U indicates
489 errors that may occur in the normal course of events. Other errors
491 <function>BadMajor</function>
492 <function>BadMinor</function>
493 <function>BadState</function>
494 <function>BadLength</function>
495 <function>BadValue</function>
496 <function>ProtocolDuplicate</function> and
497 <function>MajorOpcodeDuplicate</function>
498 might occur, but generally indicate a serious implementation failure on
499 the part of the errant peer.
501 <para><function>ByteOrder</function></para>
505 <term><emphasis remap='I'>byte-order</emphasis>:</term>
508 {<symbol role='Pn'>MSBfirst</symbol>,
509 <function>LSBfirst</function>
516 Both parties must send this message before sending any other,
517 including errors. This message specifies the byte order that
518 will be used on subsequent messages sent by this party.
523 Note: If the receiver detects an error in this message,
524 it must be sure to send its own
525 <function>ByteOrder</function> message before sending the
526 <function>Error</function>.
530 <para><function>ConnectionSetup</function></para>
534 <term><emphasis remap='I'>versions</emphasis>:</term>
536 <para>LISTofVERSION</para>
540 <term><emphasis remap='I'>must-authenticate</emphasis>:</term>
546 <term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
548 <para>LISTofSTRING</para>
552 <term><emphasis remap='I'>vendor</emphasis>:</term>
558 <term><emphasis remap='I'>release</emphasis>:</term>
564 <term>Responses:</term>
567 <function>ConnectionReply</function>,
568 <function>AuthenticationRequired</function> (See note)
573 <term>Expected errors:</term>
576 <function>NoVersion</function>,
577 <function>SetupFailed</function>,
578 <function>NoAuthentication</function>,
579 <function>AuthenticationRejected</function>,
580 <function>AuthenticationFailed</function>
587 The party that initiates the connection (the one that does the
588 "connect()") must send this message as the second message (after
589 <function>ByteOrder</function> on startup.
593 Versions gives a list, in decreasing order of preference, of the
594 protocol versions this party is capable of speaking. This document
595 specifies major version 1, minor version 0.
599 If must-authenticate is <function>True</function> the initiating
600 party demands authentication; the accepting party
601 <emphasis remap='I'>must</emphasis> pick an authentication scheme
602 and use it. In this case, the only valid response is
603 <function>AuthenticationRequired</function>
607 If must-authenticate is <function>False</function> the accepting
608 party may choose an authentication mechanism, use a host-address-based
609 authentication scheme, or skip authentication. When must-authenticate
610 is <function>False</function> <function>ConnectionReply</function> and
611 <function>AuthenticationRequired</function> are both valid responses.
612 If a host-address-based authentication scheme is used,
613 <function>AuthenticationRejected</function> and
614 <function>AuthenticationFailed</function> errors are possible.
618 Authentication-protocol-names specifies a (possibly null, if
619 must-authenticate is <function>False</function>
620 list of authentication protocols the party is willing to perform. If
621 must-authenticate is <function>True</function>
622 presumably the party will offer only authentication mechanisms
623 allowing mutual authentication.
627 Vendor gives the name of the vendor of this ICE implementation.
631 Release gives the release identifier of this ICE implementation.
634 <para><function>AuthenticationRequired</function></para>
638 <term><emphasis remap='I'>authentication-protocol-index</emphasis>:</term>
644 <term><emphasis remap='I'>data</emphasis>:</term>
646 <para><specific to authentication protocol></para>
650 <term>Response:</term>
652 <para><function>AuthenticationReply</function></para>
656 <term>Expected errors:</term>
659 <function>AuthenticationRejected</function>,
660 <function>AuthenticationFailed</function>
667 This message is sent in response to a <function>ConnectionSetup</function>
668 or <function>ProtocolSetup</function>
669 message to specify that authentication is to be done and what
670 authentication mechanism is to be used.
674 The authentication protocol is specified by a 0-based index into the list
675 of names given in the <function>ConnectionSetup</function> or
676 <function>ProtocolSetup</function>
677 Any protocol-specific data that might be required is also sent.
681 <para><function>AuthenticationReply</function></para>
684 <term><emphasis remap='I'>data</emphasis>:</term>
686 <para><specific to authentication protocol></para>
690 <term>Responses:</term>
693 <function>AuthenticationNextPhase</function>,
694 <function>ConnectionReply</function>,
695 <function>ProtocolReply</function>
700 <term>Expected errors:</term>
703 <function>AuthenticationRejected</function>,
704 <function>AuthenticationFailed</function>,
705 <function>SetupFailed</function>
712 This message is sent in response to an
713 <function>AuthenticationRequired</function> or
714 <function>AuthenticationNextPhase</function> message, to
715 supply authentication data as defined by the authentication protocol
720 Note that this message is sent by the party that initiated the current
721 negotiation -- the party that sent the
722 <function>ConnectionSetup</function> or
723 <function>ProtocolSetup</function> message.
727 <function>AuthenticationNextPhase</function>
728 indicates that more is to be done to complete the authentication.
729 If the authentication is complete,
730 <function>ConnectionReply</function>
731 is appropriate if the current authentication handshake is the result of a
732 <function>ConnectionSetup</function> and a
733 <function>ProtocolReply</function>
734 is appropriate if it is the result of a
735 <function>ProtocolSetup</function>.
738 <para><function>AuthenticationNextPhase</function></para>
742 <term><emphasis remap='I'>data</emphasis>:</term>
744 <para><specific to authentication protocol></para>
748 <term>Response:</term>
750 <para><function>AuthenticationReply</function></para>
754 <term>Expected errors:</term>
757 <function>AuthenticationRejected</function>,
758 <function>AuthenticationFailed</function>
765 This message is sent in response to an
766 <function>AuthenticationReply</function>
767 message, to supply authentication data as defined by the authentication
771 <para><function>ConnectionReply</function></para>
774 <term><emphasis remap='I'>version-index</emphasis>:</term>
780 <term><emphasis remap='I'>vendor</emphasis>:</term>
786 <term><emphasis remap='I'>release</emphasis>:</term>
794 This message is sent in response to a
795 <function>ConnectionSetup</function> or
796 <function>AuthenticationReply</function>
797 message to indicate that the authentication handshake is complete.
801 Version-index gives a 0-based index into the list of versions offered in
802 the <function>ConnectionSetup</function> message; it specifies the
803 version of the ICE protocol that both parties
804 should speak for the duration of the connection.
807 <para>Vendor gives the name of the vendor of this ICE implementation.</para>
810 Release gives the release identifier of this ICE implementation.
813 <para><function>ProtocolSetup</function></para>
817 <term><emphasis remap='I'>protocol-name</emphasis>:</term>
823 <term><emphasis remap='I'>major-opcode</emphasis>:</term>
829 <term><emphasis remap='I'>versions</emphasis>:</term>
831 <para>LISTofVERSION</para>
835 <term><emphasis remap='I'>vendor</emphasis>:</term>
841 <term><emphasis remap='I'>release</emphasis>:</term>
847 <term><emphasis remap='I'>must-authenticate</emphasis>:</term>
853 <term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
855 <para>LISTofSTRING</para>
859 <term>Responses:</term>
862 <function>AuthenticationRequired</function>,
863 <function>ProtocolReply</function>
868 <term>Expected errors:</term>
871 <function>UnknownProtocol</function>,
872 <function>NoVersion</function>,
873 <function>SetupFailed</function>,
874 <function>NoAuthentication</function>,
875 <function>AuthenticationRejected</function>,
876 <function>AuthenticationFailed</function>
883 This message is used to initiate negotiation of a protocol and
884 establish any authentication specific to it.
888 Protocol-name gives the name of the protocol the party wishes
893 Major-opcode gives the opcode that the party will use in messages
898 Versions gives a list of version numbers, in decreasing order of
899 preference, that the party is willing to speak.
903 Vendor and release are identification strings with semantics defined
904 by the specific protocol being negotiated.
908 If must-authenticate is <function>True</function>,
909 the initiating party demands authentication; the accepting party
910 <emphasis remap='I'>must</emphasis> pick an authentication scheme
911 and use it. In this case, the only valid response is
912 <function>AuthenticationRequired</function>
916 If must-authenticate is <function>False</function>,
917 the accepting party may choose an authentication mechanism, use a
918 host-address-based authentication scheme, or skip authentication.
919 When must-authenticate is <function>False</function>,
920 <function>ProtocolReply</function> and
921 <function>AuthenticationRequired</function>
922 are both valid responses. If a host-address-based authentication
923 scheme is used, <function>AuthenticationRejected</function> and
924 <function>AuthenticationFailed</function> errors are possible.
928 Authentication-protocol-names specifies a (possibly null, if
929 must-authenticate is <function>False</function>
930 list of authentication protocols the party is willing to perform. If
931 must-authenticate is <function>True</function>
932 presumably the party will offer only authentication mechanisms
933 allowing mutual authentication.
936 <para><function>ProtocolReply</function></para>
939 <term><emphasis remap='I'>major-opcode</emphasis>:</term>
945 <term><emphasis remap='I'>version-index</emphasis>:</term>
951 <term><emphasis remap='I'>vendor</emphasis>:</term>
957 <term><emphasis remap='I'>release</emphasis>:</term>
965 This message is sent in response to a <function>ProtocolSetup</function>
966 or <function>AuthenticationReply</function>
967 message to indicate that the authentication handshake is complete.
971 Major-opcode gives the opcode that this party will use in
972 messages that it sends.
976 Version-index gives a 0-based index into the list of versions offered in the
977 <function>ProtocolSetup</function> message; it specifies the version
978 of the protocol that both parties should speak for the duration of
983 Vendor and release are identification strings with semantics defined
984 by the specific protocol being negotiated.
987 <para><function>Ping</function></para>
990 <term>Response:</term>
992 <para><function>PingReply</function></para>
998 This message is used to test if the connection is still functioning.
1001 <para><function>PingReply</function></para>
1004 This message is sent in response to a <function>Ping</function>
1005 message, indicating that the connection is still functioning.
1008 <para><function>WantToClose</function></para>
1011 <term>Responses:</term>
1014 <function>WantToClose</function>,
1015 <function>NoClose</function>,
1016 <function>ProtocolSetup</function>
1024 This message is used to initiate a possible close of the connection.
1025 The sending party has noticed that, as a result of mechanisms specific
1026 to each protocol, there are no active protocols left.
1027 There are four possible scenarios arising from this request:
1033 The receiving side noticed too, and has already sent a
1034 <function>WantToClose</function> On receiving a
1035 <function>WantToClose</function> while already attempting to
1036 shut down, each party should simply close the connection.
1041 The receiving side hasn't noticed, but agrees. It closes the connection.
1046 The receiving side has a <function>ProtocolSetup</function>
1047 "in flight," in which case it is to ignore
1048 <function>WantToClose</function> and the party sending
1049 <function>WantToClose</function> is to abandon the shutdown attempt
1050 when it receives the <function>ProtocolSetup</function>
1055 The receiving side wants the connection kept open for some
1056 reason not specified by the ICE protocol, in which case it
1057 sends <function>NoClose</function>
1063 See the state transition diagram for additional information.
1066 <para><function>NoClose</function></para>
1069 This message is sent in response to a <function>WantToClose</function>
1070 message to indicate that the responding party does not want the
1071 connection closed at this time. The receiving party should not close the
1072 connection. Either party may again initiate
1073 <function>WantToClose</function> at some future time.
1076 <sect1 id="generic_error_classes">
1077 <title>Generic Error Classes</title>
1080 These errors should be used by all protocols, as applicable.
1081 For ICE (major opcode 0), <function>FatalToProtocol</function>
1082 should be interpreted as <function>FatalToConnection</function>.
1085 <para><function>BadMinor</function></para>
1089 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1091 <para><any></para>
1095 <term><emphasis remap='I'>severity</emphasis>:</term>
1098 <function>FatalToProtocol</function> or
1099 <function>CanContinue</function>
1100 (protocol's discretion)
1105 <term><emphasis remap='I'>values</emphasis>:</term>
1113 Received a message with an unknown minor opcode.
1116 <para><function>BadState</function></para>
1119 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1121 <para><any></para>
1125 <term><emphasis remap='I'>severity</emphasis>:</term>
1128 <function>FatalToProtocol</function> or
1129 <function>CanContinue</function> (protocol's discretion)
1134 <term><emphasis remap='I'>values</emphasis>:</term>
1142 Received a message with a valid minor opcode which is not appropriate
1143 for the current state of the protocol.
1146 <para><function>BadLength</function></para>
1150 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1152 <para><any></para>
1156 <term><emphasis remap='I'>severity</emphasis>:</term>
1159 <function>FatalToProtocol</function> or
1160 <function>CanContinue</function> (protocol's discretion)
1165 <term><emphasis remap='I'>values</emphasis>:</term>
1173 Received a message with a bad length. The length of the message is
1174 longer or shorter than required to contain the data.
1177 <para><function>BadValue</function></para>
1181 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1183 <para><any></para>
1187 <term><emphasis remap='I'>severity</emphasis>:</term>
1189 <para><function>CanContinue</function></para>
1193 <term><emphasis remap='I'>values</emphasis>:</term>
1196 CARD32 Byte offset to offending value in offending message.
1197 CARD32 Length of offending value.
1198 <varies> Offending value
1204 <para>Received a message with a bad value specified.</para>
1208 <sect1 id="ice_error_classes">
1209 <title>ICE Error Classes</title>
1211 <para>These errors are all major opcode 0 errors.</para>
1213 <para><function>BadMajor</function></para>
1216 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1218 <para><any></para>
1222 <term><emphasis remap='I'>severity</emphasis>:</term>
1224 <para><function>CanContinue</function></para>
1228 <term><emphasis remap='I'>values</emphasis>:</term>
1230 <para>CARD8 Opcode</para>
1235 <para>The opcode given is not one that has been registered.</para>
1238 <para><function>NoAuthentication</function></para>
1242 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1245 <function>ConnectionSetup</function>,
1246 <function>ProtocolSetup</function>
1251 <term><emphasis remap='I'>severity</emphasis>:</term>
1254 <function>ConnectionSetup</function> \(->
1255 <function>FatalToConnection</function>
1256 <function>ProtocolSetup</function> \(->
1257 <function>FatalToProtocol</function>
1262 <term><emphasis remap='I'>values</emphasis>:</term>
1269 <para>None of the authentication protocols offered are available.</para>
1271 <para><function>NoVersion</function></para>
1275 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1278 <function>ConnectionSetup</function>,
1279 <function>ProtocolSetup</function>
1284 <term><emphasis remap='I'>severity</emphasis>:</term>
1287 <function>ConnectionSetup</function> \(->
1288 <function>FatalToConnection</function>
1289 <function>ProtocolSetup</function> \(->
1290 <function>FatalToProtocol</function>
1295 <term><emphasis remap='I'>values</emphasis>:</term>
1302 <para>None of the protocol versions offered are available.</para>
1304 <para><function>SetupFailed</function></para>
1308 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1311 <function>ConnectionSetup</function>,
1312 <function>ProtocolSetup</function>,
1313 <function>AuthenticationReply</function>
1318 <term><emphasis remap='I'>severity</emphasis>:</term>
1321 <function>ConnectionSetup</function> \(->
1322 <function>FatalToConnection</function>
1323 <function>ProtocolSetup</function> \(->
1324 <function>FatalToProtocol</function>
1325 <function>AuthenticationReply</function> \(->
1326 <function>FatalToConnection</function> if authenticating a connection,
1327 otherwise <function>FatalToProtocol</function>
1332 <term><emphasis remap='I'>values</emphasis>:</term>
1334 <para>STRING reason</para>
1340 The sending side is unable to accept the
1341 new connection or new protocol for a reason other than authentication
1342 failure. Typically this error will be a result of inability to allocate
1343 additional resources on the sending side. The reason field will give a
1344 human-interpretable message providing further detail on the type of failure.
1347 <para><function>AuthenticationRejected</function></para>
1350 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1353 <function>AuthenticationReply</function>,
1354 <function>AuthenticationRequired</function>,
1355 <function>AuthenticationNextPhase</function>
1360 <term><emphasis remap='I'>severity</emphasis>:</term>
1362 <para><function>FatalToProtocol</function></para>
1366 <term><emphasis remap='I'>values</emphasis>:</term>
1368 <para>STRING reason</para>
1374 Authentication rejected. The peer has failed to properly
1375 authenticate itself. The reason field will give a human-interpretable
1376 message providing further detail.
1379 <para><function>AuthenticationFailed</function></para>
1382 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1385 <function>AuthenticationReply</function>,
1386 <function>AuthenticationRequired</function>,
1387 <function>AuthenticationNextPhase</function>
1392 <term><emphasis remap='I'>severity</emphasis>:</term>
1394 <para><function>FatalToProtocol</function></para>
1398 <term><emphasis remap='I'>values</emphasis>:</term>
1400 <para>STRING reason</para>
1406 Authentication failed. <function>AuthenticationFailed</function>
1407 does not imply that the authentication was rejected, as
1408 <function>AuthenticationRejected</function>
1409 does. Instead it means that the sender was unable to complete
1410 the authentication for some other reason. (For instance, it
1411 may have been unable to contact an authentication server.)
1412 The reason field will give a human-interpretable message
1413 providing further detail.
1416 <para><function>ProtocolDuplicate</function></para>
1419 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1421 <para><function>ProtocolSetup</function></para>
1425 <term><emphasis remap='I'>severity</emphasis>:</term>
1427 <para><function>FatalToProtocol</function> (but see note)</para>
1431 <term><emphasis remap='I'>values</emphasis>:</term>
1433 <para>STRING protocol name</para>
1439 The protocol name was already registered. This is fatal to
1440 the "new" protocol being set up by <function>ProtocolSetup</function>
1441 but it does not affect the existing registration.
1444 <para><function>MajorOpcodeDuplicate</function></para>
1447 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1449 <para><function>ProtocolSetup</function></para>
1453 <term><emphasis remap='I'>severity</emphasis>:</term>
1455 <para><function>FatalToProtocol</function> (but see note)</para>
1459 <term><emphasis remap='I'>values</emphasis>:</term>
1461 <para>CARD8 opcode</para>
1467 The major opcode specified was already registered. This is
1468 fatal to the \*Qnew\*U protocol being set up by
1469 <function>ProtocolSetup</function> but it does not affect the
1470 existing registration.
1473 <para><function>UnknownProtocol</function></para>
1476 <term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1478 <para><function>ProtocolSetup</function></para>
1482 <term><emphasis remap='I'>severity</emphasis>:</term>
1484 <para><function>FatalToProtocol</function></para>
1488 <term><emphasis remap='I'>values</emphasis>:</term>
1490 <para>STRING protocol name</para>
1495 <para>The protocol specified is not supported.</para>
1500 <chapter id="state_diagrams">
1501 <title>State Diagrams</title>
1504 Here are the state diagrams for the party that initiates the connection:
1508 <emphasis remap='C'>start</emphasis>:
1509 connect to other end, send <function>ByteOrder</function> <function>ConnectionSetup</function> -> <emphasis remap='C'>conn_wait</emphasis>
1511 <emphasis remap='C'>conn_wait</emphasis>:
1512 receive <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis>
1513 receive <function>AuthenticationRequired</function> -> <emphasis remap='C'>conn_auth1</emphasis>
1514 receive <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1515 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1517 <emphasis remap='C'>conn_auth1</emphasis>:
1518 if good auth data, send <function>AuthenticationReply</function> -> <emphasis remap='C'>conn_auth2</emphasis>
1519 if bad auth data, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1521 <emphasis remap='C'>conn_auth2</emphasis>:
1522 receive <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis>
1523 receive <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>conn_auth1</emphasis>
1524 receive <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1525 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1529 Here are top-level state transitions for the party
1530 that accepts connections.
1534 <emphasis remap='C'>listener</emphasis>:
1535 accept connection -> <emphasis remap='C'>init_wait</emphasis>
1537 <emphasis remap='C'>init_wait</emphasis>:
1538 receive <function>ByteOrder</function> <function>ConnectionSetup</function> -> <emphasis remap='C'>auth_ask</emphasis>
1539 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1541 <emphasis remap='C'>auth_ask</emphasis>:
1542 send <function>ByteOrder</function> <function>ConnectionReply</function>
1543 -> <emphasis remap='C'>stasis</emphasis>
1545 send <function>AuthenticationRequired</function> -> <emphasis remap='C'>auth_wait</emphasis>
1547 send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1549 <emphasis remap='C'>auth_wait</emphasis>:
1550 receive <function>AuthenticationReply</function> -> <emphasis remap='C'>auth_check</emphasis>
1552 receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1554 <emphasis remap='C'>auth_check</emphasis>:
1555 if no more auth needed, send <function>ConnectionReply</function> -> <emphasis remap='C'>stasis</emphasis>
1556 if good auth data, send <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>auth_wait</emphasis>
1557 if bad auth data, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1561 Here are the top-level state transitions for all parties after the initial
1562 connection establishment subprotocol.
1567 Note: this is not quite the truth for branches out from stasis, in
1568 that multiple conversations can be interleaved on the connection.
1573 <emphasis remap='C'>stasis</emphasis>:
1574 send <function>ProtocolSetup</function> -> <emphasis remap='C'>proto_wait</emphasis>
1575 receive <function>ProtocolSetup</function> -> <emphasis remap='C'>proto_reply</emphasis>
1576 send <function>Ping</function> -> <emphasis remap='C'>ping_wait</emphasis>
1577 receive <function>Ping</function> send <function>PingReply</function> -> <emphasis remap='C'>stasis</emphasis>
1578 receive <function>WantToClose</function> -> <emphasis remap='C'>shutdown_attempt</emphasis>
1579 receive <other>, send <function>Error</function> -> <emphasis remap='C'>stasis</emphasis>
1580 all protocols shut down, send <function>WantToClose</function> -> <emphasis remap='C'>close_wait</emphasis>
1582 <emphasis remap='C'>proto_wait</emphasis>:
1583 receive <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis>
1584 receive <function>AuthenticationRequired</function> -> <emphasis remap='C'>give_auth1</emphasis>
1585 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1586 receive <function>WantToClose</function> -> <emphasis remap='C'>proto_wait</emphasis>
1588 <emphasis remap='C'>give_auth1</emphasis>:
1589 if good auth data, send <function>AuthenticationReply</function> -> <emphasis remap='C'>give_auth2</emphasis>
1590 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1591 receive <function>WantToClose</function> -> <emphasis remap='C'>give_auth1</emphasis>
1593 <emphasis remap='C'>give_auth2</emphasis>:
1594 receive <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis>
1595 receive <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>give_auth1</emphasis>
1596 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1597 receive <function>WantToClose</function> -> <emphasis remap='C'>give_auth2</emphasis>
1599 <emphasis remap='C'>proto_reply</emphasis>:
1600 send <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis>
1601 send <function>AuthenticationRequired</function> -> <emphasis remap='C'>take_auth1</emphasis>
1602 send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1604 <emphasis remap='C'>take_auth1</emphasis>:
1605 receive <function>AuthenticationReply</function> -> <emphasis remap='C'>take_auth2</emphasis>
1606 receive <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1608 <emphasis remap='C'>take_auth2</emphasis>:
1609 if good auth data \(-> <emphasis remap='C'>take_auth3</emphasis>
1610 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1612 <emphasis remap='C'>take_auth3</emphasis>:
1613 if no more auth needed, send <function>ProtocolReply</function> -> <emphasis remap='C'>stasis</emphasis>
1614 if good auth data, send <function>AuthenticationNextPhase</function> -> <emphasis remap='C'>take_auth1</emphasis>
1615 if bad auth data, send <function>Error</function> give up on this protocol -> <emphasis remap='C'>stasis</emphasis>
1617 <emphasis remap='C'>ping_wait</emphasis>:
1618 receive <function>PingReply</function> -> <emphasis remap='C'>stasis</emphasis>
1620 <emphasis remap='C'>quit</emphasis>:
1621 -> close connection
1625 Here are the state transitions for shutting down the connection:
1629 <emphasis remap='C'>shutdown_attempt</emphasis>:
1630 if want to stay alive anyway, send <function>NoClose</function> -> <emphasis remap='C'>stasis</emphasis>
1631 else -> <emphasis remap='C'>quit</emphasis>
1633 <emphasis remap='C'>close_wait</emphasis>:
1634 receive <function>ProtocolSetup</function> -> <emphasis remap='C'>proto_reply</emphasis>
1635 receive <function>NoClose</function> -> <emphasis remap='C'>stasis</emphasis>
1636 receive <function>WantToClose</function> -> <emphasis remap='C'>quit</emphasis>
1637 connection close -> <emphasis remap='C'>quit</emphasis>
1640 <chapter id="protocol_encoding">
1641 <title>Protocol Encoding</title>
1644 In the encodings below, the first column is the number of bytes occupied.
1645 The second column is either the type (if the value is variable) or the
1646 actual value. The third column is the description of the value (e.g.,
1647 the parameter name). Receivers must ignore bytes that are designated
1648 as unused or pad bytes.
1652 This document describes major version 1, minor version 0
1653 of the ICE protocol.
1657 LISTof<type> indicates some number of repetitions of
1658 <type>, with no
1659 additional padding. The number of repetitions must be specified elsewhere
1663 <sect1 id="primitives">
1664 <title>Primitives</title>
1666 <informaltable pgwide='1' frame='none'>
1667 <tgroup cols='3' align='center'>
1668 <colspec colname='c1'/>
1669 <colspec colname='c2'/>
1670 <colspec colname='c3'/>
1673 <entry align='left'>Type Name</entry>
1674 <entry align='left'>Length (bytes)</entry>
1675 <entry align='left'>Description</entry>
1680 <entry align='left'>CARD8</entry>
1681 <entry align='left'>1</entry>
1682 <entry align='left'>8-bit unsigned integer</entry>
1685 <entry align='left'>CARD16</entry>
1686 <entry align='left'>2</entry>
1687 <entry align='left'>16-bit unsigned integer</entry>
1690 <entry align='left'>CARD32</entry>
1691 <entry align='left'>4</entry>
1692 <entry align='left'>32-bit unsigned integer</entry>
1695 <entry align='left'>LPCE</entry>
1696 <entry align='left'>1</entry>
1697 <entry align='left'><para>A character from the X Portable Character Set in Latin Portable Character
1698 Encoding</para></entry>
1706 <sect1 id="enumerations">
1707 <title>Enumerations</title>
1710 <informaltable pgwide='1' frame='none'>
1711 <tgroup cols='3' align='center'>
1712 <colspec colname='c1'/>
1713 <colspec colname='c2'/>
1714 <colspec colname='c3'/>
1717 <entry align='left'>Type Name</entry>
1718 <entry align='left'>Value</entry>
1719 <entry align='left'>Description</entry>
1724 <entry align='left'>BOOL</entry>
1725 <entry align='left'>0</entry>
1726 <entry align='left'>False</entry>
1729 <entry align='left'></entry>
1730 <entry align='left'>1</entry>
1731 <entry align='left'>True</entry>
1739 <sect1 id="compound_types">
1740 <title>Compound Types</title>
1742 <informaltable pgwide='1' frame='none'>
1743 <tgroup cols='4' align='center'>
1744 <colspec colname='c1'/>
1745 <colspec colname='c2'/>
1746 <colspec colname='c3'/>
1747 <colspec colname='c4'/>
1750 <entry align='left'>Type Name</entry>
1751 <entry align='left'>Length (bytes)</entry>
1752 <entry align='left'>Type</entry>
1753 <entry align='left'>Description</entry>
1758 <entry align='left'>VERSION</entry>
1759 <entry align='left'></entry>
1760 <entry align='left'></entry>
1761 <entry align='left'></entry>
1764 <entry align='left'></entry>
1765 <entry align='left'>2</entry>
1766 <entry align='left'>CARD16</entry>
1767 <entry align='left'>Major version number</entry>
1770 <entry align='left'></entry>
1771 <entry align='left'>2</entry>
1772 <entry align='left'>CARD16</entry>
1773 <entry align='left'>Minor version number</entry>
1776 <entry align='left'>STRING</entry>
1777 <entry align='left'></entry>
1778 <entry align='left'></entry>
1779 <entry align='left'></entry>
1782 <entry align='left'></entry>
1783 <entry align='left'>2</entry>
1784 <entry align='left'>CARD16</entry>
1785 <entry align='left'>length of string in bytes</entry>
1788 <entry align='left'></entry>
1789 <entry align='left'>n</entry>
1790 <entry align='left'>LISTofLPCE</entry>
1791 <entry align='left'>string</entry>
1794 <entry align='left'></entry>
1795 <entry align='left'>p</entry>
1796 <entry align='left'></entry>
1797 <entry align='left'>unused, p = pad(n+2, 4)</entry>
1805 <sect1 id="ice_minor_opcodes">
1806 <title>ICE Minor opcodes</title>
1808 <informaltable pgwide='0' frame='none'>
1809 <tgroup cols='2' align='center'>
1810 <colspec colname='c1'/>
1811 <colspec colname='c2'/>
1814 <entry align='left'>Message Name</entry>
1815 <entry align='right'>Encoding</entry>
1820 <entry align='left'>Error</entry>
1821 <entry align='right'>0</entry>
1824 <entry align='left'>ByteOrder</entry>
1825 <entry align='right'>1</entry>
1828 <entry align='left'>ConnectionSetup</entry>
1829 <entry align='right'>2</entry>
1832 <entry align='left'>AuthenticationRequired</entry>
1833 <entry align='right'>3</entry>
1836 <entry align='left'>AuthenticationReply</entry>
1837 <entry align='right'>4</entry>
1840 <entry align='left'>AuthenticationNextPhase</entry>
1841 <entry align='right'>5</entry>
1844 <entry align='left'>ConnectionReply</entry>
1845 <entry align='right'>6</entry>
1848 <entry align='left'>ProtocolSetup</entry>
1849 <entry align='right'>7</entry>
1852 <entry align='left'>ProtocolReply</entry>
1853 <entry align='right'>8</entry>
1856 <entry align='left'>Ping</entry>
1857 <entry align='right'>9</entry>
1860 <entry align='left'>PingReply</entry>
1861 <entry align='right'>10</entry>
1864 <entry align='left'>WantToClose</entry>
1865 <entry align='right'>11</entry>
1868 <entry align='left'>NoClose</entry>
1869 <entry align='right'>12</entry>
1877 <sect1 id="message_encoding">
1878 <title>Message Encoding</title>
1880 <literallayout class="monospaced">
1881 <function>Error</function>
1882 1 CARD8 major-opcode
1886 1 CARD8 offending-minor-opcode
1892 4 CARD32 sequence number of erroneous message
1893 n <varies> value(s)
1898 <literallayout class="monospaced">
1899 <function>ByteOrder</function>
1909 <literallayout class="monospaced">
1910 <function>ConnectionSetup</function>
1913 1 CARD8 Number of versions offered
1914 1 CARD8 Number of authentication protocol names offered
1915 4 (i+j+k+m+p)/8+1 length
1916 1 BOOL must-authenticate
1920 k LISTofSTRING authentication-protocol-names
1921 m LISTofVERSION version-list
1922 p unused, p = pad(i+j+k+m,8)
1925 <literallayout class="monospaced">
1926 <function>AuthenticationRequired</function>
1928 1 3 AuthenticationRequired
1929 1 CARD8 authentication-protocol-index
1932 2 n length of authentication data
1934 n <varies> data
1935 p unused, p = pad(n,8)
1938 <literallayout class="monospaced">
1939 <function>AuthenticationReply</function>
1941 1 4 AuthenticationReply
1944 2 n length of authentication data
1946 n <varies> data
1947 p unused, p = pad(n,8)
1950 <literallayout class="monospaced">
1951 <function>AuthenticationNextPhase</function>
1953 1 5 AuthenticationNextPhase
1956 2 n length of authentication data
1958 n <varies> data
1959 p unused, p = pad(n,8)
1962 <literallayout class="monospaced">
1963 <function>ConnectionReply</function>
1966 1 CARD8 version-index
1971 p unused, p = pad(i+j,8)
1974 <literallayout class="monospaced">
1975 <function>ProtocolSetup</function>
1978 1 CARD8 major-opcode
1979 1 BOOL must-authenticate
1980 4 (i+j+k+m+n+p)/8+1 length
1981 1 CARD8 Number of versions offered
1982 1 CARD8 Number of authentication protocol names offered
1984 i STRING protocol-name
1987 m LISTofSTRING authentication-protocol-names
1988 n LISTofVERSION version-list
1989 p unused, p = pad(i+j+k+m+n,8)
1992 <literallayout class="monospaced">
1993 <function>ProtocolReply</function>
1996 1 CARD8 version-index
1997 1 CARD8 major-opcode
2001 p unused, p = pad(i+j, 8)
2004 <literallayout class="monospaced">
2005 <function>Ping</function>
2012 <literallayout class="monospaced">
2013 <function>PingReply</function>
2020 <literallayout class="monospaced">
2021 <function>WantToClose</function>
2028 <literallayout class="monospaced">
2029 <function>NoClose</function>
2038 <sect1 id="error_class_encoding">
2039 <title>Error Class Encoding</title>
2042 Generic errors have classes in the range 0x8000-0xFFFF, and
2043 subprotocol-specific errors are in the range 0x0000-0x7FFF.
2046 <sect2 id="generic_error_class_encoding">
2047 <title>Generic Error Class Encoding</title>
2049 <informaltable pgwide='0' frame='none'>
2050 <tgroup cols='2' align='center'>
2051 <colspec colname='c1'/>
2052 <colspec colname='c2'/>
2055 <entry align='left'>Class</entry>
2056 <entry align='center'>Encoding</entry>
2061 <entry align='left'>BadMinor</entry>
2062 <entry align='right'>0x8000</entry>
2065 <entry align='left'>BadState</entry>
2066 <entry align='right'>0x8001</entry>
2069 <entry align='left'>BadLength</entry>
2070 <entry align='right'>0x8002</entry>
2073 <entry align='left'>BadValue</entry>
2074 <entry align='right'>0x8003</entry>
2081 <sect2 id="ice_specific_error_class_encoding">
2082 <title>ICE-specific Error Class Encoding</title>
2084 <informaltable pgwide='0' frame='none'>
2085 <tgroup cols='2' align='center'>
2086 <colspec colname='c1'/>
2087 <colspec colname='c2'/>
2090 <entry align='left'>Class</entry>
2091 <entry align='center'>Encoding</entry>
2096 <entry align='left'>BadMajor</entry>
2097 <entry align='right'>0</entry>
2100 <entry align='left'>NoAuthentication</entry>
2101 <entry align='right'>1</entry>
2104 <entry align='left'>NoVersion</entry>
2105 <entry align='right'>2</entry>
2108 <entry align='left'>SetupFailed</entry>
2109 <entry align='right'>3</entry>
2112 <entry align='left'>AuthenticationRejected</entry>
2113 <entry align='right'>4</entry>
2116 <entry align='left'>AuthenticationFailed</entry>
2117 <entry align='right'>5</entry>
2120 <entry align='left'>ProtocolDuplicate</entry>
2121 <entry align='right'>6</entry>
2124 <entry align='left'>MajorOpcodeDuplicate</entry>
2125 <entry align='right'>7</entry>
2128 <entry align='left'>UnknownProtocol</entry>
2129 <entry align='right'>8</entry>
2139 <appendix id="modification_history">
2141 <title>Modification History</title>
2143 <sect1 id="release_6_to_release_6_1">
2144 <title>Release 6 to Release 6.1</title>
2146 Release 6.1 added the ICE X rendezvous protocol (Appendix B) and
2147 updated the document version to 1.1.
2151 <sect1 id="release_6_1_to_release_6_3">
2152 <title>Release 6.1 to Release 6.3</title>
2153 <para>Release 6.3 added the listen on well known ports feature.</para>
2158 <appendix id="ice_x_rendezvous_protocol">
2159 <title>ICE X Rendezvous Protocol</title>
2161 <sect1 id="introduction">
2162 <title>Introduction</title>
2164 The ICE X rendezvous protocol is designed to answer the need posed
2165 in Section 2 for one mechanism by which two clients interested in
2166 communicating via ICE are able to exchange the necessary information.
2167 This protocol is appropriate for any two ICE clients who also have X
2168 connections to the same X server.
2172 <sect1 id="overview_of_ice_x_rendezvous">
2173 <title>Overview of ICE X Rendezvous</title>
2176 The ICE X Rendezvous Mechanism requires clients willing to act as ICE
2177 originating parties to pre-register the ICE subprotocols they support in an
2178 ICE_PROTOCOLS property on their top-level window. Clients willing to
2179 act as ICE answering parties then send an ICE_PROTOCOLS X
2180 <function>ClientMessage</function>
2181 event to the ICE originating parties. This
2182 <function>ClientMessage</function>
2184 the ICE network IDs of the ICE answering party as well as the ICE
2185 subprotocol it wishes to speak. Upon receipt of this message the ICE
2186 originating party uses the information to establish an ICE connection
2187 with the ICE answering party.
2191 <sect1 id="registering_known_protocols">
2192 <title>Registering Known Protocols</title>
2195 Clients willing to act as ICE originating parties preregister
2196 the ICE subprotocols they support in a list of atoms held by an
2197 ICE_PROTOCOLS property on their top-level window. The name of each
2198 atom listed in ICE_PROTOCOLS must be of the form
2199 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> where
2200 <emphasis remap='I'>pname</emphasis> is the name of the ICE
2201 subprotocol the ICE originating party is willing to speak, as would be
2203 <function>ProtocolSetup</function>
2208 Clients with an ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom
2209 in the ICE_PROTOCOLS property on their top-level windows must respond to
2210 <function>ClientMessage</function> events of
2211 type ICE_PROTOCOLS specifying ICE_INITIATE_
2212 <emphasis remap='I'>pname</emphasis>. If a client does not
2213 want to respond to these client message events, it should
2214 remove the ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2215 atom from its ICE_PROTOCOLS property
2216 or remove the ICE_PROTOCOLS property entirely.
2220 <sect1 id="initiating_the_rendezvoud">
2221 <title>Initiating the Rendezvous</title>
2224 To initiate the rendezvous a client acting as an ICE answering
2226 <function>ClientMessage</function>
2227 event of type ICE_PROTOCOLS to an ICE
2228 originating party. This ICE_PROTOCOLS client message contains the
2229 information the ICE originating party needs to identify the ICE
2230 subprotocol the two parties will use as well as the ICE network
2231 identification string of the ICE answering party.
2235 Before the ICE answering party sends the client message event it must
2236 define a text property on one of its windows. This text property
2237 contains the ICE answering party's ICE network identification string
2238 and will be used by ICE originating parties to determine the ICE
2239 answering party's list of ICE network IDs.
2243 The property name will normally be ICE_NETWORK_IDS, but may be any
2244 name of the ICE answering party's choosing. The format for this text
2245 property is as follows:
2248 <informaltable pgwide='0' frame='none'>
2249 <tgroup cols='2' align='center'>
2250 <colspec colname='c1'/>
2251 <colspec colname='c2'/>
2254 <entry align='left'>Field</entry>
2255 <entry align='left'>Value</entry>
2260 <entry align='left'>type</entry>
2261 <entry align='left'>XA_STRING</entry>
2264 <entry align='left'>format</entry>
2265 <entry align='left'>8</entry>
2268 <entry align='left'>value</entry>
2269 <entry align='left'>comma-separated list of ICE network IDs</entry>
2278 Once the ICE answering party has established this text property on one
2279 of its windows, it initiates the rendezvous by sending an
2281 <function>ClientMessage</function>
2282 event to an ICE originating party's
2283 top-level window. This event has the following format
2284 and must only be sent to windows that have pre-registered the ICE
2285 subprotocol in an ICE_PROTOCOLS property on their top-level window.
2288 <informaltable pgwide='0' frame='none'>
2289 <tgroup cols='2' align='center'>
2290 <colspec colname='c1'/>
2291 <colspec colname='c2'/>
2294 <entry align='left'>Field</entry>
2295 <entry align='left'>Value</entry>
2300 <entry align='left'>message_type</entry>
2301 <entry align='left'>Atom = "ICE_PROTOCOLS"</entry>
2304 <entry align='left'>format</entry>
2305 <entry align='left'>32</entry>
2308 <entry align='left'>data.l[0]</entry>
2309 <entry align='left'>Atom identifying the ICE subprotocol to speak</entry>
2312 <entry align='left'>data.l[1]</entry>
2313 <entry align='left'>Timestamp</entry>
2316 <entry align='left'>data.l[2]</entry>
2317 <entry align='left'><para>ICE answering party's window ID with
2318 ICE network IDs text property</para></entry>
2321 <entry align='left'>data.l[3]</entry>
2322 <entry align='left'>Atom naming text property containing the ICE
2323 answering party's ICE network IDs</entry>
2326 <entry align='left'>data.l[4]</entry>
2327 <entry align='left'>Reserved. Must be 0.</entry>
2335 The name of the atom in data.l[0] must be of the form
2336 ICE_INITIATE_<emphasis remap='I'>pname</emphasis>, where
2337 <emphasis remap='I'>pname</emphasis> is the name of the ICE
2338 subprotocol the ICE answering party wishes to speak.
2342 When an ICE originating party receives a
2343 <function>ClientMessage</function>
2345 ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2346 it can initiate an ICE connection with the ICE answering party.
2347 To open this connection the client retrieves the ICE answering
2348 party's ICE network IDs from the window specified in data.l[2] using
2349 the text property specified in data.l[3].
2353 If the connection attempt fails for any reason, the client must
2354 respond to the client message event by sending a return
2355 <function>ClientMessage</function>
2356 event to the window specified in data.l[2]. This return
2357 event has the following format:
2360 <informaltable pgwide='0' frame='none'>
2361 <tgroup cols='2' align='center'>
2362 <colspec colname='c1'/>
2363 <colspec colname='c2'/>
2366 <entry align='left'>Field</entry>
2367 <entry align='left'>Value</entry>
2372 <entry align='left'>message_type</entry>
2373 <entry align='left'>Atom = "ICE_INITIATE_FAILED"</entry>
2376 <entry align='left'>format</entry>
2377 <entry align='left'>32</entry>
2380 <entry align='left'>data.l[0]</entry>
2381 <entry align='left'>Atom identifying the ICE subprotocol requested</entry>
2384 <entry align='left'>data.l[1]</entry>
2385 <entry align='left'>Timestamp</entry>
2388 <entry align='left'>data.l[2]</entry>
2389 <entry align='left'><para>Initiating party's window ID
2390 (holding ICE_PROTOCOLS)</para></entry>
2393 <entry align='left'>data.l[3]</entry>
2394 <entry align='left'>int: reason for failure</entry>
2397 <entry align='left'>data.l[4]</entry>
2398 <entry align='left'>Reserved, must be 0</entry>
2406 The values of data.l[0] and data.l[1] are copied directly from the
2407 client message event the client received.
2411 The value in data.l[2] is
2412 the id of the window to which the
2413 ICE_PROTOCOLS.ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2414 client message event was sent.
2417 <para>Data.l[3] has one of the following values:</para>
2421 <informaltable pgwide='0' frame='none'>
2422 <tgroup cols='3' align='center'>
2423 <colspec colname='c1'/>
2424 <colspec colname='c2'/>
2425 <colspec colname='c3'/>
2428 <entry align='left'>Value</entry>
2429 <entry align='left'>Encoding</entry>
2430 <entry align='left'>Description</entry>
2435 <entry align='left'>OpenFailed</entry>
2436 <entry align='center'>1</entry>
2437 <entry align='left'>
2438 The client was unable to open the connection
2439 (e.g. a call to IceOpenConnection() failed). If the
2440 client is able to distinguish authentication or
2441 authorization errors from general errors, then
2442 the preferred reply is <function>AuthenticationFailed</function>
2443 for authorization errors.
2447 <entry align='left'>AuthenticationFailed</entry>
2448 <entry align='center'>2</entry>
2449 <entry align='left'>Authentication or authorization of the
2450 connection or protocol setup was refused.
2451 This reply will be given only if the client is
2452 able to distinguish it from
2453 <function>OpenFailed</function>
2455 <function>OpenFailed</function>
2456 will be returned.</entry>
2459 <entry align='left'>SetupFailed</entry>
2460 <entry align='center'>3</entry>
2461 <entry align='left'>The client was unable to initiate the specified
2462 protocol on the connection (e.g. a call to
2463 IceProtocolSetup() failed).</entry>
2466 <entry align='left'>UnknownProtocol</entry>
2467 <entry align='center'>4</entry>
2468 <entry align='left'>The client does not recognize the requested
2469 protocol. (This represents a semantic error
2470 on the part of the answering party.)</entry>
2473 <entry align='left'>Refused</entry>
2474 <entry align='center'>5</entry>
2475 <entry align='left'>
2476 The client was in the process of removing
2477 ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2478 from its ICE_PROTOCOLS list
2479 when the client message was sent; the client no
2480 longer is willing to establish the specified ICE
2481 communication.</entry>
2490 Clients willing to act as ICE originating parties must update the
2491 ICE_PROTOCOLS property on their top-level windows to include the
2492 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom(s) identifying
2493 the ICE subprotocols they
2494 speak. The method a client uses to update the ICE_PROTOCOLS property
2495 to include ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atoms is
2496 implementation dependent, but
2497 the client must ensure the integrity of the list to prevent the
2498 accidental omission of any atoms previously in the list.
2502 When setting up the ICE network IDs text property on one of its
2503 windows, the ICE answering party can determine its comma-separated
2504 list of ICE network IDs by calling IceComposeNetworkIdList() after
2505 making a call to IceListenForConnections(). The method an ICE
2506 answering party uses to find the top-level windows of clients willing
2507 to act as ICE originating parties is dependent upon the nature of the
2508 answering party. Some may wish to use the approach of requiring the
2509 user to click on a client's window. Others wishing to find existing
2510 clients without requiring user interaction might use something similar
2511 to the XQueryTree() method used by several freely-available
2512 applications. In order for the ICE answering party to become
2513 automatically aware of new clients willing to originate ICE
2514 connections, the ICE answering party might register for
2515 SubstructureNotify events on the root window of the display. When it
2516 receives a SubstructureNotify event, the ICE answering party can check
2517 to see if it was the result of the creation of a new client top-level
2518 window with an ICE_PROTOCOLS property.
2522 In any case, before attempting to use this ICE X Rendezvous Mechanism
2523 ICE answering parties wishing to speak ICE subprotocol
2524 <emphasis remap='I'>pname</emphasis> should
2525 check for the ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom
2526 in the ICE_PROTOCOLS property on
2527 a client's top-level window. A client that does not include an
2528 ICE_INITIATE_<emphasis remap='I'>pname</emphasis> atom in a
2529 ICE_PROTOCOLS property on some top-level window should be assumed to ignore
2530 <function>ClientMessage</function>
2532 ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2533 for ICE subprotocol <emphasis remap='I'>pname</emphasis>.
2538 <sect1 id="ice_subprotocol_versioning">
2539 <title>ICE Subprotocol Versioning</title>
2542 Although the version of the ICE subprotocol could be passed in the
2543 client message event, ICE provides more a flexible version negotiation
2544 mechanism than will fit within a single
2545 <function>ClientMessage</function>
2547 of this, ICE subprotocol versioning is handled within the ICE protocol
2550 <para>Clients wish to communicate with each other via an ICE subprotocol
2551 known as "RAP V1.0". In RAP terminology one party, the "agent",
2552 communicates with other RAP-enabled applications on demand. The
2553 user may direct the agent to establish communication with a specific
2554 application by clicking on the application's window, or the agent may
2555 watch for new application windows to be created and automatically
2556 establish communication.
2560 During startup the ICE answering party (the agent) first calls
2561 IceRegisterForProtocolReply() with a list of
2562 the versions (i.e., 1.0) of RAP the agent can speak. The answering
2563 party then calls IceListenForConnections() followed by
2564 IceComposeNetworkIdList() and stores the resulting ICE network IDs
2565 string in a text property on one of its windows.
2569 When the answering party (agent) finds a client with which it wishes to
2570 speak, it checks to see if the ICE_INITIATE_RAP atom is in the ICE_PROTOCOLS
2571 property on the client's top-level window. If it is present the agent
2572 sends the client's top-level window an ICE_PROTOCOLS client
2573 message event as described above. When the client receives the client
2574 message event and is willing to originate an ICE connection using RAP,
2575 it performs an IceRegisterForProtocolSetup() with a list of the
2576 versions of RAP the client can speak. The client then retrieves
2577 the agent's ICE network ID from the property and window specified by
2578 the agent in the client message event and calls IceOpenConnection().
2579 After this call succeeds the client calls IceProtocolSetup() specifying
2580 the RAP protocol. During this
2581 process, ICE calls the RAP protocol routines that handle the version
2586 Note that it is not necessary for purposes of this rendezvous that
2587 the client application call any ICElib functions prior to receipt
2588 of the client message event.