« back to all changes in this revision
Viewing changes to specs/ice.xml
- browse files at revision 0.2.7
- compare with another revision
- download diff
- download tarball
- view history from revision 0.2.7
- Committer: Bazaar Package Importer
- Author(s): Cyril Brulebois
- Date: 2010-11-08 01:24:07 UTC
- mfrom: (0.3.4 upstream)
- mto: This revision was merged to the branch mainline in revision 14.
- Revision ID: james.westby@ubuntu.com-20101108012407-0gmik0z1xrm11dcr
* New upstream release.
* Drop 0001-Set-the-close-on-exec-flag-for-listening-sockets.patch
* Bump xutils-dev build-dep for new macros.
* Add xmlto, xorg-sgml-doctools, and w3m build-dep for the doc.
* Kill *.xml in the doc directory, no point in shipping them.
* Ship *.html, *.css, and *.txt from the doc directory.
* Switch from --list-missing to --fail-missing for additional safety.
* Drop 0001-Set-the-close-on-exec-flag-for-listening-sockets.patch
* Bump xutils-dev build-dep for new macros.
* Add xmlto, xorg-sgml-doctools, and w3m build-dep for the doc.
* Kill *.xml in the doc directory, no point in shipping them.
* Ship *.html, *.css, and *.txt from the doc directory.
* Switch from --list-missing to --fail-missing for additional safety.
added
removed
specs/ice.xml
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">
4
5
6
<!-- lifted from troff+ms+XMan by doclifter -->
7
<book id="ice">
8
9
<bookinfo>
10
<title>Inter-Client Exchange (ICE) Protocol</title>
11
<subtitle>X Consortium Standard</subtitle>
12
<releaseinfo>X Version 11, Release 6.4</releaseinfo>
13
<authorgroup>
14
<author>
15
<firstname>Robert</firstname><surname>Scheifler</surname>
16
</author>
17
<othercredit>
18
<firstname>Jordan</firstname><surname>Brown</surname>
19
<affiliation><orgname>Quarterdeck Office Systems</orgname></affiliation>
20
</othercredit>
21
</authorgroup>
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>
28
29
<legalnotice>
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>
31
32
<para>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</para>
33
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>
35
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>
37
38
<para>X Window System is a trademark of X Consortium, Inc.</para>
39
</legalnotice>
40
41
<abstract>
42
<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.
49
</para>
50
</abstract>
51
</bookinfo>
52
53
<chapter id="purpose_and_goals">
54
<title>Purpose and Goals</title>
55
56
<para>
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
60
version negotiation,
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>
68
69
<para>The
70
<emphasis remap='I'>
71
Inter-Client Exchange
72
</emphasis>
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,
76
for negotiating
77
versions,
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>
85
86
</chapter>
87
88
<chapter id="overview_of_the_protocol">
89
<title>Overview of the Protocol</title>
90
91
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>
101
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>
107
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
119
with a
120
<function>ConnectionReply</function>
121
message giving information about itself, and the connection setup is complete.</para>
122
123
<para>If the connection setup is to be authenticated, the answering party will
124
respond with an
125
<function>AuthenticationRequired</function>
126
message instead of a
127
<function>ConnectionReply</function>
128
message. The parties then exchange
129
<function>AuthenticationReply</function>
130
and
131
<function>AuthenticationNextPhase</function>
132
messages until authentication is complete, at which time the answering party
133
finally sends its
134
<function>ConnectionReply</function>
135
message.</para>
136
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>
149
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>
157
and
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>
162
message.</para>
163
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>
169
or
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>
176
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>
184
</para>
185
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>
194
message.</para>
195
<!-- XXX \- Note that it's likely that both parties will WantToClose at once. -->
196
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>
206
message and expect a
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>
213
message and expect a
214
<function>ProtocolReply</function>
215
from party A.</para>
216
<!-- .nH 1 "Data Types" -->
217
</chapter>
218
219
<chapter id="data_types">
220
<title>Data Types</title>
221
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'>
232
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>
234
</literallayout>
235
236
<sect1 id="primitive_types">
237
<title>Primitive Types</title>
238
239
<informaltable pgwide='1' frame='none'>
240
<tgroup cols='2' align='center'>
241
<colspec colname='c1'/>
242
<colspec colname='c2'/>
243
<thead>
244
<row>
245
<entry align='left'>Type Name</entry>
246
<entry align='left'>Description</entry>
247
</row>
248
</thead>
249
<tbody>
250
<row>
251
<entry align='left'>CARD8</entry>
252
<entry align='left'>8-bit unsigned integer</entry>
253
</row>
254
<row>
255
<entry align='left'>CARD16</entry>
256
<entry align='left'>16-bit unsigned integer</entry>
257
</row>
258
<row>
259
<entry align='left'>CARD32</entry>
260
<entry align='left'>32-bit unsigned integer</entry>
261
</row>
262
<row>
263
<entry align='left'>BOOL</entry>
264
<entry align='left'><para><function>False</function>
265
or
266
<function>True</function></para></entry>
267
</row>
268
<row>
269
<entry align='left'>LPCE</entry>
270
<entry align='left'>A character from the X Portable Character Set in Latin Portable Character
271
Encoding</entry>
272
</row>
273
</tbody>
274
</tgroup>
275
</informaltable>
276
277
</sect1>
278
279
<sect1 id="complex_types">
280
<title>Complex Types</title>
281
282
<informaltable pgwide='1' frame='none'>
283
<tgroup cols='2' align='center'>
284
<colspec colname='c1'/>
285
<colspec colname='c2'/>
286
<thead>
287
<row>
288
<entry align='left'>Type Name</entry>
289
<entry align='left'>Type</entry>
290
</row>
291
<row>
292
<entry align='left'>.TH</entry>
293
<entry align='left'></entry>
294
</row>
295
</thead>
296
<tbody>
297
<row>
298
<entry align='left'>VERSION</entry>
299
<entry align='left'>[Major, minor: CARD16]</entry>
300
</row>
301
<row>
302
<entry align='left'>STRING</entry>
303
<entry align='left'>LISTofLPCE</entry>
304
</row>
305
</tbody>
306
</tgroup>
307
</informaltable>
308
309
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" -->
313
</sect1>
314
315
<sect1 id="message_format">
316
<title>Message Format</title>
317
318
<para>All ICE messages include the following information:</para>
319
320
<informaltable pgwide='1' frame='none'>
321
<tgroup cols='2' align='center'>
322
<colspec colname='c1'/>
323
<colspec colname='c2'/>
324
<thead>
325
<row>
326
<entry>Field Type</entry>
327
<entry>Description</entry>
328
</row>
329
</thead>
330
<tbody>
331
<row>
332
<entry align='left'>CARD8</entry>
333
<entry align='left'>protocol major opcode</entry>
334
</row>
335
<row>
336
<entry align='left'>CARD8</entry>
337
<entry align='left'>protocol minor opcode</entry>
338
</row>
339
<row>
340
<entry align='left'>CARD32</entry>
341
<entry align='left'>length of remaining data in 8-byte units</entry>
342
</row>
343
</tbody>
344
</tgroup>
345
</informaltable>
346
347
348
<para>The fields are as follows:</para>
349
350
<variablelist>
351
<varlistentry>
352
<term>Protocol major opcode</term>
353
<listitem>
354
<para>
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
358
negotiation time.
359
</para>
360
</listitem>
361
</varlistentry>
362
<varlistentry>
363
<term>Protocol minor opcode</term>
364
<listitem>
365
<para>
366
This specifies what protocol-specific operation is to be performed.
367
Minor opcode 0 is reserved for Errors; other values are protocol-specific.
368
</para>
369
</listitem>
370
</varlistentry>
371
<varlistentry>
372
<term>Length of data in 8-byte units</term>
373
<listitem>
374
<para>
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>
381
error.
382
</para>
383
</listitem>
384
</varlistentry>
385
</variablelist>
386
</sect1>
387
388
</chapter>
389
390
<chapter id="overall_protocol_description">
391
<title>Overall Protocol Description</title>
392
393
<para>
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>
397
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>
401
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.
406
</para>
407
408
<para><function>Error</function></para>
409
<variablelist remap='IP'>
410
<varlistentry>
411
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
412
<listitem>
413
<para>CARD8</para>
414
</listitem>
415
</varlistentry>
416
<varlistentry>
417
<term><emphasis remap='I'>severity</emphasis>:</term>
418
<listitem>
419
<para>
420
{<symbol role='Pn'>CanContinue</symbol>,
421
<function>FatalToProtocol</function>
422
<function>FatalToConnection</function>
423
</para>
424
</listitem>
425
</varlistentry>
426
<varlistentry>
427
<term><emphasis remap='I'>sequence-number</emphasis>:</term>
428
<listitem>
429
<para>CARD32</para>
430
</listitem>
431
</varlistentry>
432
<varlistentry>
433
<term><emphasis remap='I'>class</emphasis>:</term>
434
<listitem>
435
<para>CARD16</para>
436
</listitem>
437
</varlistentry>
438
<varlistentry>
439
<term><emphasis remap='I'>value(s)</emphasis>:</term>
440
<listitem>
441
<para><dependent on major/minor opcode and class></para>
442
</listitem>
443
</varlistentry>
444
</variablelist>
445
446
<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>.
468
.
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
473
for the protocol.
474
</para>
475
</chapter>
476
477
<chapter id="ice_control_subprotocol__major_opcode_0">
478
<title>ICE Control Subprotocol -- Major Opcode 0</title>
479
480
<para>
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.
485
</para>
486
487
<para>
488
In the following message descriptions, \*QExpected errors\*U indicates
489
errors that may occur in the normal course of events. Other errors
490
(in particular
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.
500
</para>
501
<para><function>ByteOrder</function></para>
502
503
<variablelist>
504
<varlistentry>
505
<term><emphasis remap='I'>byte-order</emphasis>:</term>
506
<listitem>
507
<para>
508
{<symbol role='Pn'>MSBfirst</symbol>,
509
<function>LSBfirst</function>
510
</para>
511
</listitem>
512
</varlistentry>
513
</variablelist>
514
515
<para>
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.
519
</para>
520
521
<note>
522
<para>
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>.
527
</para>
528
</note>
529
530
<para><function>ConnectionSetup</function></para>
531
532
<variablelist>
533
<varlistentry>
534
<term><emphasis remap='I'>versions</emphasis>:</term>
535
<listitem>
536
<para>LISTofVERSION</para>
537
</listitem>
538
</varlistentry>
539
<varlistentry>
540
<term><emphasis remap='I'>must-authenticate</emphasis>:</term>
541
<listitem>
542
<para>BOOL</para>
543
</listitem>
544
</varlistentry>
545
<varlistentry>
546
<term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
547
<listitem>
548
<para>LISTofSTRING</para>
549
</listitem>
550
</varlistentry>
551
<varlistentry>
552
<term><emphasis remap='I'>vendor</emphasis>:</term>
553
<listitem>
554
<para>STRING</para>
555
</listitem>
556
</varlistentry>
557
<varlistentry>
558
<term><emphasis remap='I'>release</emphasis>:</term>
559
<listitem>
560
<para>STRING</para>
561
</listitem>
562
</varlistentry>
563
<varlistentry>
564
<term>Responses:</term>
565
<listitem>
566
<para>
567
<function>ConnectionReply</function>,
568
<function>AuthenticationRequired</function> (See note)
569
</para>
570
</listitem>
571
</varlistentry>
572
<varlistentry>
573
<term>Expected errors:</term>
574
<listitem>
575
<para>
576
<function>NoVersion</function>,
577
<function>SetupFailed</function>,
578
<function>NoAuthentication</function>,
579
<function>AuthenticationRejected</function>,
580
<function>AuthenticationFailed</function>
581
</para>
582
</listitem>
583
</varlistentry>
584
</variablelist>
585
586
<para>
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.
590
</para>
591
592
<para>
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.
596
</para>
597
598
<para>
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>
604
</para>
605
606
<para>
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.
615
</para>
616
617
<para>
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.
624
</para>
625
626
<para>
627
Vendor gives the name of the vendor of this ICE implementation.
628
</para>
629
630
<para>
631
Release gives the release identifier of this ICE implementation.
632
</para>
633
634
<para><function>AuthenticationRequired</function></para>
635
636
<variablelist>
637
<varlistentry>
638
<term><emphasis remap='I'>authentication-protocol-index</emphasis>:</term>
639
<listitem>
640
<para>CARD8</para>
641
</listitem>
642
</varlistentry>
643
<varlistentry>
644
<term><emphasis remap='I'>data</emphasis>:</term>
645
<listitem>
646
<para><specific to authentication protocol></para>
647
</listitem>
648
</varlistentry>
649
<varlistentry>
650
<term>Response:</term>
651
<listitem>
652
<para><function>AuthenticationReply</function></para>
653
</listitem>
654
</varlistentry>
655
<varlistentry>
656
<term>Expected errors:</term>
657
<listitem>
658
<para>
659
<function>AuthenticationRejected</function>,
660
<function>AuthenticationFailed</function>
661
</para>
662
</listitem>
663
</varlistentry>
664
</variablelist>
665
666
<para>
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.
671
</para>
672
673
<para>
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.
678
</para>
679
680
681
<para><function>AuthenticationReply</function></para>
682
<variablelist>
683
<varlistentry>
684
<term><emphasis remap='I'>data</emphasis>:</term>
685
<listitem>
686
<para><specific to authentication protocol></para>
687
</listitem>
688
</varlistentry>
689
<varlistentry>
690
<term>Responses:</term>
691
<listitem>
692
<para>
693
<function>AuthenticationNextPhase</function>,
694
<function>ConnectionReply</function>,
695
<function>ProtocolReply</function>
696
</para>
697
</listitem>
698
</varlistentry>
699
<varlistentry>
700
<term>Expected errors:</term>
701
<listitem>
702
<para>
703
<function>AuthenticationRejected</function>,
704
<function>AuthenticationFailed</function>,
705
<function>SetupFailed</function>
706
</para>
707
</listitem>
708
</varlistentry>
709
</variablelist>
710
711
<para>
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
716
being used.
717
</para>
718
719
<para>
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.
724
</para>
725
726
<para>
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>.
736
</para>
737
738
<para><function>AuthenticationNextPhase</function></para>
739
740
<variablelist>
741
<varlistentry>
742
<term><emphasis remap='I'>data</emphasis>:</term>
743
<listitem>
744
<para><specific to authentication protocol></para>
745
</listitem>
746
</varlistentry>
747
<varlistentry>
748
<term>Response:</term>
749
<listitem>
750
<para><function>AuthenticationReply</function></para>
751
</listitem>
752
</varlistentry>
753
<varlistentry>
754
<term>Expected errors:</term>
755
<listitem>
756
<para>
757
<function>AuthenticationRejected</function>,
758
<function>AuthenticationFailed</function>
759
</para>
760
</listitem>
761
</varlistentry>
762
</variablelist>
763
764
<para>
765
This message is sent in response to an
766
<function>AuthenticationReply</function>
767
message, to supply authentication data as defined by the authentication
768
protocol being used.
769
</para>
770
771
<para><function>ConnectionReply</function></para>
772
<variablelist>
773
<varlistentry>
774
<term><emphasis remap='I'>version-index</emphasis>:</term>
775
<listitem>
776
<para>CARD8</para>
777
</listitem>
778
</varlistentry>
779
<varlistentry>
780
<term><emphasis remap='I'>vendor</emphasis>:</term>
781
<listitem>
782
<para>STRING</para>
783
</listitem>
784
</varlistentry>
785
<varlistentry>
786
<term><emphasis remap='I'>release</emphasis>:</term>
787
<listitem>
788
<para>STRING</para>
789
</listitem>
790
</varlistentry>
791
</variablelist>
792
793
<para>
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.
798
</para>
799
800
<para>
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.
805
</para>
806
807
<para>Vendor gives the name of the vendor of this ICE implementation.</para>
808
809
<para>
810
Release gives the release identifier of this ICE implementation.
811
</para>
812
813
<para><function>ProtocolSetup</function></para>
814
815
<variablelist>
816
<varlistentry>
817
<term><emphasis remap='I'>protocol-name</emphasis>:</term>
818
<listitem>
819
<para>STRING</para>
820
</listitem>
821
</varlistentry>
822
<varlistentry>
823
<term><emphasis remap='I'>major-opcode</emphasis>:</term>
824
<listitem>
825
<para>CARD8</para>
826
</listitem>
827
</varlistentry>
828
<varlistentry>
829
<term><emphasis remap='I'>versions</emphasis>:</term>
830
<listitem>
831
<para>LISTofVERSION</para>
832
</listitem>
833
</varlistentry>
834
<varlistentry>
835
<term><emphasis remap='I'>vendor</emphasis>:</term>
836
<listitem>
837
<para>STRING</para>
838
</listitem>
839
</varlistentry>
840
<varlistentry>
841
<term><emphasis remap='I'>release</emphasis>:</term>
842
<listitem>
843
<para>STRING</para>
844
</listitem>
845
</varlistentry>
846
<varlistentry>
847
<term><emphasis remap='I'>must-authenticate</emphasis>:</term>
848
<listitem>
849
<para>BOOL</para>
850
</listitem>
851
</varlistentry>
852
<varlistentry>
853
<term><emphasis remap='I'>authentication-protocol-names</emphasis>:</term>
854
<listitem>
855
<para>LISTofSTRING</para>
856
</listitem>
857
</varlistentry>
858
<varlistentry>
859
<term>Responses:</term>
860
<listitem>
861
<para>
862
<function>AuthenticationRequired</function>,
863
<function>ProtocolReply</function>
864
</para>
865
</listitem>
866
</varlistentry>
867
<varlistentry>
868
<term>Expected errors:</term>
869
<listitem>
870
<para>
871
<function>UnknownProtocol</function>,
872
<function>NoVersion</function>,
873
<function>SetupFailed</function>,
874
<function>NoAuthentication</function>,
875
<function>AuthenticationRejected</function>,
876
<function>AuthenticationFailed</function>
877
</para>
878
</listitem>
879
</varlistentry>
880
</variablelist>
881
882
<para>
883
This message is used to initiate negotiation of a protocol and
884
establish any authentication specific to it.
885
</para>
886
887
<para>
888
Protocol-name gives the name of the protocol the party wishes
889
to speak.
890
</para>
891
892
<para>
893
Major-opcode gives the opcode that the party will use in messages
894
it sends.
895
</para>
896
897
<para>
898
Versions gives a list of version numbers, in decreasing order of
899
preference, that the party is willing to speak.
900
</para>
901
902
<para>
903
Vendor and release are identification strings with semantics defined
904
by the specific protocol being negotiated.
905
</para>
906
907
<para>
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>
913
</para>
914
915
<para>
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.
925
</para>
926
927
<para>
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.
934
</para>
935
936
<para><function>ProtocolReply</function></para>
937
<variablelist>
938
<varlistentry>
939
<term><emphasis remap='I'>major-opcode</emphasis>:</term>
940
<listitem>
941
<para>CARD8</para>
942
</listitem>
943
</varlistentry>
944
<varlistentry>
945
<term><emphasis remap='I'>version-index</emphasis>:</term>
946
<listitem>
947
<para>CARD8</para>
948
</listitem>
949
</varlistentry>
950
<varlistentry>
951
<term><emphasis remap='I'>vendor</emphasis>:</term>
952
<listitem>
953
<para>STRING</para>
954
</listitem>
955
</varlistentry>
956
<varlistentry>
957
<term><emphasis remap='I'>release</emphasis>:</term>
958
<listitem>
959
<para>STRING</para>
960
</listitem>
961
</varlistentry>
962
</variablelist>
963
964
<para>
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.
968
</para>
969
970
<para>
971
Major-opcode gives the opcode that this party will use in
972
messages that it sends.
973
</para>
974
975
<para>
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
979
the connection.
980
</para>
981
982
<para>
983
Vendor and release are identification strings with semantics defined
984
by the specific protocol being negotiated.
985
</para>
986
987
<para><function>Ping</function></para>
988
<variablelist>
989
<varlistentry>
990
<term>Response:</term>
991
<listitem>
992
<para><function>PingReply</function></para>
993
</listitem>
994
</varlistentry>
995
</variablelist>
996
997
<para>
998
This message is used to test if the connection is still functioning.
999
</para>
1000
1001
<para><function>PingReply</function></para>
1002
1003
<para>
1004
This message is sent in response to a <function>Ping</function>
1005
message, indicating that the connection is still functioning.
1006
</para>
1007
1008
<para><function>WantToClose</function></para>
1009
<variablelist>
1010
<varlistentry>
1011
<term>Responses:</term>
1012
<listitem>
1013
<para>
1014
<function>WantToClose</function>,
1015
<function>NoClose</function>,
1016
<function>ProtocolSetup</function>
1017
</para>
1018
</listitem>
1019
</varlistentry>
1020
</variablelist>
1021
1022
1023
<para>
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:
1028
</para>
1029
1030
<orderedlist>
1031
<listitem>
1032
<para>
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.
1037
</para>
1038
</listitem>
1039
<listitem>
1040
<para>
1041
The receiving side hasn't noticed, but agrees. It closes the connection.
1042
</para>
1043
</listitem>
1044
<listitem>
1045
<para>
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>
1051
</para>
1052
</listitem>
1053
<listitem>
1054
<para>
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>
1058
</para>
1059
</listitem>
1060
</orderedlist>
1061
1062
<para>
1063
See the state transition diagram for additional information.
1064
</para>
1065
1066
<para><function>NoClose</function></para>
1067
1068
<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.
1074
</para>
1075
1076
<sect1 id="generic_error_classes">
1077
<title>Generic Error Classes</title>
1078
1079
<para>
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>.
1083
</para>
1084
1085
<para><function>BadMinor</function></para>
1086
1087
<variablelist>
1088
<varlistentry>
1089
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1090
<listitem>
1091
<para><any></para>
1092
</listitem>
1093
</varlistentry>
1094
<varlistentry>
1095
<term><emphasis remap='I'>severity</emphasis>:</term>
1096
<listitem>
1097
<para>
1098
<function>FatalToProtocol</function> or
1099
<function>CanContinue</function>
1100
(protocol's discretion)
1101
</para>
1102
</listitem>
1103
</varlistentry>
1104
<varlistentry>
1105
<term><emphasis remap='I'>values</emphasis>:</term>
1106
<listitem>
1107
<para>(none)</para>
1108
</listitem>
1109
</varlistentry>
1110
</variablelist>
1111
1112
<para>
1113
Received a message with an unknown minor opcode.
1114
</para>
1115
1116
<para><function>BadState</function></para>
1117
<variablelist>
1118
<varlistentry>
1119
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1120
<listitem>
1121
<para><any></para>
1122
</listitem>
1123
</varlistentry>
1124
<varlistentry>
1125
<term><emphasis remap='I'>severity</emphasis>:</term>
1126
<listitem>
1127
<para>
1128
<function>FatalToProtocol</function> or
1129
<function>CanContinue</function> (protocol's discretion)
1130
</para>
1131
</listitem>
1132
</varlistentry>
1133
<varlistentry>
1134
<term><emphasis remap='I'>values</emphasis>:</term>
1135
<listitem>
1136
<para>(none)</para>
1137
</listitem>
1138
</varlistentry>
1139
</variablelist>
1140
1141
<para>
1142
Received a message with a valid minor opcode which is not appropriate
1143
for the current state of the protocol.
1144
</para>
1145
1146
<para><function>BadLength</function></para>
1147
1148
<variablelist>
1149
<varlistentry>
1150
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1151
<listitem>
1152
<para><any></para>
1153
</listitem>
1154
</varlistentry>
1155
<varlistentry>
1156
<term><emphasis remap='I'>severity</emphasis>:</term>
1157
<listitem>
1158
<para>
1159
<function>FatalToProtocol</function> or
1160
<function>CanContinue</function> (protocol's discretion)
1161
</para>
1162
</listitem>
1163
</varlistentry>
1164
<varlistentry>
1165
<term><emphasis remap='I'>values</emphasis>:</term>
1166
<listitem>
1167
<para>(none)</para>
1168
</listitem>
1169
</varlistentry>
1170
</variablelist>
1171
1172
<para>
1173
Received a message with a bad length. The length of the message is
1174
longer or shorter than required to contain the data.
1175
</para>
1176
1177
<para><function>BadValue</function></para>
1178
1179
<variablelist>
1180
<varlistentry>
1181
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1182
<listitem>
1183
<para><any></para>
1184
</listitem>
1185
</varlistentry>
1186
<varlistentry>
1187
<term><emphasis remap='I'>severity</emphasis>:</term>
1188
<listitem>
1189
<para><function>CanContinue</function></para>
1190
</listitem>
1191
</varlistentry>
1192
<varlistentry>
1193
<term><emphasis remap='I'>values</emphasis>:</term>
1194
<listitem>
1195
<para>
1196
CARD32 Byte offset to offending value in offending message.
1197
CARD32 Length of offending value.
1198
<varies> Offending value
1199
</para>
1200
</listitem>
1201
</varlistentry>
1202
</variablelist>
1203
1204
<para>Received a message with a bad value specified.</para>
1205
1206
</sect1>
1207
1208
<sect1 id="ice_error_classes">
1209
<title>ICE Error Classes</title>
1210
1211
<para>These errors are all major opcode 0 errors.</para>
1212
1213
<para><function>BadMajor</function></para>
1214
<variablelist>
1215
<varlistentry>
1216
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1217
<listitem>
1218
<para><any></para>
1219
</listitem>
1220
</varlistentry>
1221
<varlistentry>
1222
<term><emphasis remap='I'>severity</emphasis>:</term>
1223
<listitem>
1224
<para><function>CanContinue</function></para>
1225
</listitem>
1226
</varlistentry>
1227
<varlistentry>
1228
<term><emphasis remap='I'>values</emphasis>:</term>
1229
<listitem>
1230
<para>CARD8 Opcode</para>
1231
</listitem>
1232
</varlistentry>
1233
</variablelist>
1234
1235
<para>The opcode given is not one that has been registered.</para>
1236
1237
1238
<para><function>NoAuthentication</function></para>
1239
1240
<variablelist>
1241
<varlistentry>
1242
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1243
<listitem>
1244
<para>
1245
<function>ConnectionSetup</function>,
1246
<function>ProtocolSetup</function>
1247
</para>
1248
</listitem>
1249
</varlistentry>
1250
<varlistentry>
1251
<term><emphasis remap='I'>severity</emphasis>:</term>
1252
<listitem>
1253
<para>
1254
<function>ConnectionSetup</function> \(->
1255
<function>FatalToConnection</function>
1256
<function>ProtocolSetup</function> \(->
1257
<function>FatalToProtocol</function>
1258
</para>
1259
</listitem>
1260
</varlistentry>
1261
<varlistentry>
1262
<term><emphasis remap='I'>values</emphasis>:</term>
1263
<listitem>
1264
<para>(none)</para>
1265
</listitem>
1266
</varlistentry>
1267
</variablelist>
1268
1269
<para>None of the authentication protocols offered are available.</para>
1270
1271
<para><function>NoVersion</function></para>
1272
1273
<variablelist>
1274
<varlistentry>
1275
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1276
<listitem>
1277
<para>
1278
<function>ConnectionSetup</function>,
1279
<function>ProtocolSetup</function>
1280
</para>
1281
</listitem>
1282
</varlistentry>
1283
<varlistentry>
1284
<term><emphasis remap='I'>severity</emphasis>:</term>
1285
<listitem>
1286
<para>
1287
<function>ConnectionSetup</function> \(->
1288
<function>FatalToConnection</function>
1289
<function>ProtocolSetup</function> \(->
1290
<function>FatalToProtocol</function>
1291
</para>
1292
</listitem>
1293
</varlistentry>
1294
<varlistentry>
1295
<term><emphasis remap='I'>values</emphasis>:</term>
1296
<listitem>
1297
<para>(none)</para>
1298
</listitem>
1299
</varlistentry>
1300
</variablelist>
1301
1302
<para>None of the protocol versions offered are available.</para>
1303
1304
<para><function>SetupFailed</function></para>
1305
1306
<variablelist>
1307
<varlistentry>
1308
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1309
<listitem>
1310
<para>
1311
<function>ConnectionSetup</function>,
1312
<function>ProtocolSetup</function>,
1313
<function>AuthenticationReply</function>
1314
</para>
1315
</listitem>
1316
</varlistentry>
1317
<varlistentry>
1318
<term><emphasis remap='I'>severity</emphasis>:</term>
1319
<listitem>
1320
<para>
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>
1328
</para>
1329
</listitem>
1330
</varlistentry>
1331
<varlistentry>
1332
<term><emphasis remap='I'>values</emphasis>:</term>
1333
<listitem>
1334
<para>STRING reason</para>
1335
</listitem>
1336
</varlistentry>
1337
</variablelist>
1338
1339
<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.
1345
</para>
1346
1347
<para><function>AuthenticationRejected</function></para>
1348
<variablelist>
1349
<varlistentry>
1350
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1351
<listitem>
1352
<para>
1353
<function>AuthenticationReply</function>,
1354
<function>AuthenticationRequired</function>,
1355
<function>AuthenticationNextPhase</function>
1356
</para>
1357
</listitem>
1358
</varlistentry>
1359
<varlistentry>
1360
<term><emphasis remap='I'>severity</emphasis>:</term>
1361
<listitem>
1362
<para><function>FatalToProtocol</function></para>
1363
</listitem>
1364
</varlistentry>
1365
<varlistentry>
1366
<term><emphasis remap='I'>values</emphasis>:</term>
1367
<listitem>
1368
<para>STRING reason</para>
1369
</listitem>
1370
</varlistentry>
1371
</variablelist>
1372
1373
<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.
1377
</para>
1378
1379
<para><function>AuthenticationFailed</function></para>
1380
<variablelist>
1381
<varlistentry>
1382
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1383
<listitem>
1384
<para>
1385
<function>AuthenticationReply</function>,
1386
<function>AuthenticationRequired</function>,
1387
<function>AuthenticationNextPhase</function>
1388
</para>
1389
</listitem>
1390
</varlistentry>
1391
<varlistentry>
1392
<term><emphasis remap='I'>severity</emphasis>:</term>
1393
<listitem>
1394
<para><function>FatalToProtocol</function></para>
1395
</listitem>
1396
</varlistentry>
1397
<varlistentry>
1398
<term><emphasis remap='I'>values</emphasis>:</term>
1399
<listitem>
1400
<para>STRING reason</para>
1401
</listitem>
1402
</varlistentry>
1403
</variablelist>
1404
1405
<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.
1414
</para>
1415
1416
<para><function>ProtocolDuplicate</function></para>
1417
<variablelist>
1418
<varlistentry>
1419
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1420
<listitem>
1421
<para><function>ProtocolSetup</function></para>
1422
</listitem>
1423
</varlistentry>
1424
<varlistentry>
1425
<term><emphasis remap='I'>severity</emphasis>:</term>
1426
<listitem>
1427
<para><function>FatalToProtocol</function> (but see note)</para>
1428
</listitem>
1429
</varlistentry>
1430
<varlistentry>
1431
<term><emphasis remap='I'>values</emphasis>:</term>
1432
<listitem>
1433
<para>STRING protocol name</para>
1434
</listitem>
1435
</varlistentry>
1436
</variablelist>
1437
1438
<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.
1442
</para>
1443
1444
<para><function>MajorOpcodeDuplicate</function></para>
1445
<variablelist>
1446
<varlistentry>
1447
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1448
<listitem>
1449
<para><function>ProtocolSetup</function></para>
1450
</listitem>
1451
</varlistentry>
1452
<varlistentry>
1453
<term><emphasis remap='I'>severity</emphasis>:</term>
1454
<listitem>
1455
<para><function>FatalToProtocol</function> (but see note)</para>
1456
</listitem>
1457
</varlistentry>
1458
<varlistentry>
1459
<term><emphasis remap='I'>values</emphasis>:</term>
1460
<listitem>
1461
<para>CARD8 opcode</para>
1462
</listitem>
1463
</varlistentry>
1464
</variablelist>
1465
1466
<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.
1471
</para>
1472
1473
<para><function>UnknownProtocol</function></para>
1474
<variablelist>
1475
<varlistentry>
1476
<term><emphasis remap='I'>offending-minor-opcode</emphasis>:</term>
1477
<listitem>
1478
<para><function>ProtocolSetup</function></para>
1479
</listitem>
1480
</varlistentry>
1481
<varlistentry>
1482
<term><emphasis remap='I'>severity</emphasis>:</term>
1483
<listitem>
1484
<para><function>FatalToProtocol</function></para>
1485
</listitem>
1486
</varlistentry>
1487
<varlistentry>
1488
<term><emphasis remap='I'>values</emphasis>:</term>
1489
<listitem>
1490
<para>STRING protocol name</para>
1491
</listitem>
1492
</varlistentry>
1493
</variablelist>
1494
1495
<para>The protocol specified is not supported.</para>
1496
1497
</sect1>
1498
</chapter>
1499
1500
<chapter id="state_diagrams">
1501
<title>State Diagrams</title>
1502
1503
<para>
1504
Here are the state diagrams for the party that initiates the connection:
1505
</para>
1506
1507
<literallayout>
1508
<emphasis remap='C'>start</emphasis>:
1509
connect to other end, send <function>ByteOrder</function> <function>ConnectionSetup</function> -> <emphasis remap='C'>conn_wait</emphasis>
1510
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>
1516
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>
1520
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>
1526
</literallayout>
1527
1528
<para>
1529
Here are top-level state transitions for the party
1530
that accepts connections.
1531
</para>
1532
1533
<literallayout>
1534
<emphasis remap='C'>listener</emphasis>:
1535
accept connection -> <emphasis remap='C'>init_wait</emphasis>
1536
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>
1540
1541
<emphasis remap='C'>auth_ask</emphasis>:
1542
send <function>ByteOrder</function> <function>ConnectionReply</function>
1543
-> <emphasis remap='C'>stasis</emphasis>
1544
1545
send <function>AuthenticationRequired</function> -> <emphasis remap='C'>auth_wait</emphasis>
1546
1547
send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1548
1549
<emphasis remap='C'>auth_wait</emphasis>:
1550
receive <function>AuthenticationReply</function> -> <emphasis remap='C'>auth_check</emphasis>
1551
1552
receive <other>, send <function>Error</function> -> <emphasis remap='C'>quit</emphasis>
1553
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>
1558
</literallayout>
1559
1560
<para>
1561
Here are the top-level state transitions for all parties after the initial
1562
connection establishment subprotocol.
1563
</para>
1564
1565
<note>
1566
<para>
1567
Note: this is not quite the truth for branches out from stasis, in
1568
that multiple conversations can be interleaved on the connection.
1569
</para>
1570
</note>
1571
1572
<literallayout>
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>
1581
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>
1587
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>
1592
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>
1598
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>
1603
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>
1607
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>
1611
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>
1616
1617
<emphasis remap='C'>ping_wait</emphasis>:
1618
receive <function>PingReply</function> -> <emphasis remap='C'>stasis</emphasis>
1619
1620
<emphasis remap='C'>quit</emphasis>:
1621
-> close connection
1622
</literallayout>
1623
1624
<para>
1625
Here are the state transitions for shutting down the connection:
1626
</para>
1627
1628
<literallayout>
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>
1632
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>
1638
</literallayout>
1639
</chapter>
1640
<chapter id="protocol_encoding">
1641
<title>Protocol Encoding</title>
1642
1643
<para>
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.
1649
</para>
1650
1651
<para>
1652
This document describes major version 1, minor version 0
1653
of the ICE protocol.
1654
</para>
1655
1656
<para>
1657
LISTof<type> indicates some number of repetitions of
1658
<type>, with no
1659
additional padding. The number of repetitions must be specified elsewhere
1660
in the message.
1661
</para>
1662
1663
<sect1 id="primitives">
1664
<title>Primitives</title>
1665
1666
<informaltable pgwide='1' frame='none'>
1667
<tgroup cols='3' align='center'>
1668
<colspec colname='c1'/>
1669
<colspec colname='c2'/>
1670
<colspec colname='c3'/>
1671
<thead>
1672
<row>
1673
<entry align='left'>Type Name</entry>
1674
<entry align='left'>Length (bytes)</entry>
1675
<entry align='left'>Description</entry>
1676
</row>
1677
</thead>
1678
<tbody>
1679
<row>
1680
<entry align='left'>CARD8</entry>
1681
<entry align='left'>1</entry>
1682
<entry align='left'>8-bit unsigned integer</entry>
1683
</row>
1684
<row>
1685
<entry align='left'>CARD16</entry>
1686
<entry align='left'>2</entry>
1687
<entry align='left'>16-bit unsigned integer</entry>
1688
</row>
1689
<row>
1690
<entry align='left'>CARD32</entry>
1691
<entry align='left'>4</entry>
1692
<entry align='left'>32-bit unsigned integer</entry>
1693
</row>
1694
<row>
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>
1699
</row>
1700
</tbody>
1701
</tgroup>
1702
</informaltable>
1703
1704
</sect1>
1705
1706
<sect1 id="enumerations">
1707
<title>Enumerations</title>
1708
1709
1710
<informaltable pgwide='1' frame='none'>
1711
<tgroup cols='3' align='center'>
1712
<colspec colname='c1'/>
1713
<colspec colname='c2'/>
1714
<colspec colname='c3'/>
1715
<thead>
1716
<row>
1717
<entry align='left'>Type Name</entry>
1718
<entry align='left'>Value</entry>
1719
<entry align='left'>Description</entry>
1720
</row>
1721
</thead>
1722
<tbody>
1723
<row>
1724
<entry align='left'>BOOL</entry>
1725
<entry align='left'>0</entry>
1726
<entry align='left'>False</entry>
1727
</row>
1728
<row>
1729
<entry align='left'></entry>
1730
<entry align='left'>1</entry>
1731
<entry align='left'>True</entry>
1732
</row>
1733
</tbody>
1734
</tgroup>
1735
</informaltable>
1736
1737
</sect1>
1738
1739
<sect1 id="compound_types">
1740
<title>Compound Types</title>
1741
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'/>
1748
<thead>
1749
<row>
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>
1754
</row>
1755
</thead>
1756
<tbody>
1757
<row>
1758
<entry align='left'>VERSION</entry>
1759
<entry align='left'></entry>
1760
<entry align='left'></entry>
1761
<entry align='left'></entry>
1762
</row>
1763
<row>
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>
1768
</row>
1769
<row>
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>
1774
</row>
1775
<row>
1776
<entry align='left'>STRING</entry>
1777
<entry align='left'></entry>
1778
<entry align='left'></entry>
1779
<entry align='left'></entry>
1780
</row>
1781
<row>
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>
1786
</row>
1787
<row>
1788
<entry align='left'></entry>
1789
<entry align='left'>n</entry>
1790
<entry align='left'>LISTofLPCE</entry>
1791
<entry align='left'>string</entry>
1792
</row>
1793
<row>
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>
1798
</row>
1799
</tbody>
1800
</tgroup>
1801
</informaltable>
1802
1803
</sect1>
1804
1805
<sect1 id="ice_minor_opcodes">
1806
<title>ICE Minor opcodes</title>
1807
1808
<informaltable pgwide='0' frame='none'>
1809
<tgroup cols='2' align='center'>
1810
<colspec colname='c1'/>
1811
<colspec colname='c2'/>
1812
<thead>
1813
<row>
1814
<entry align='left'>Message Name</entry>
1815
<entry align='right'>Encoding</entry>
1816
</row>
1817
</thead>
1818
<tbody>
1819
<row>
1820
<entry align='left'>Error</entry>
1821
<entry align='right'>0</entry>
1822
</row>
1823
<row>
1824
<entry align='left'>ByteOrder</entry>
1825
<entry align='right'>1</entry>
1826
</row>
1827
<row>
1828
<entry align='left'>ConnectionSetup</entry>
1829
<entry align='right'>2</entry>
1830
</row>
1831
<row>
1832
<entry align='left'>AuthenticationRequired</entry>
1833
<entry align='right'>3</entry>
1834
</row>
1835
<row>
1836
<entry align='left'>AuthenticationReply</entry>
1837
<entry align='right'>4</entry>
1838
</row>
1839
<row>
1840
<entry align='left'>AuthenticationNextPhase</entry>
1841
<entry align='right'>5</entry>
1842
</row>
1843
<row>
1844
<entry align='left'>ConnectionReply</entry>
1845
<entry align='right'>6</entry>
1846
</row>
1847
<row>
1848
<entry align='left'>ProtocolSetup</entry>
1849
<entry align='right'>7</entry>
1850
</row>
1851
<row>
1852
<entry align='left'>ProtocolReply</entry>
1853
<entry align='right'>8</entry>
1854
</row>
1855
<row>
1856
<entry align='left'>Ping</entry>
1857
<entry align='right'>9</entry>
1858
</row>
1859
<row>
1860
<entry align='left'>PingReply</entry>
1861
<entry align='right'>10</entry>
1862
</row>
1863
<row>
1864
<entry align='left'>WantToClose</entry>
1865
<entry align='right'>11</entry>
1866
</row>
1867
<row>
1868
<entry align='left'>NoClose</entry>
1869
<entry align='right'>12</entry>
1870
</row>
1871
</tbody>
1872
</tgroup>
1873
</informaltable>
1874
1875
</sect1>
1876
1877
<sect1 id="message_encoding">
1878
<title>Message Encoding</title>
1879
1880
<literallayout class="monospaced">
1881
<function>Error</function>
1882
1 CARD8 major-opcode
1883
1 0 Error
1884
2 CARD16 class
1885
4 (n+p)/8+1 length
1886
1 CARD8 offending-minor-opcode
1887
1 severity:
1888
0 CanContinue
1889
1 FatalToProtocol
1890
2 FatalToConnection
1891
2 unused
1892
4 CARD32 sequence number of erroneous message
1893
n <varies> value(s)
1894
p pad, p = pad(n,8)
1895
</literallayout>
1896
1897
1898
<literallayout class="monospaced">
1899
<function>ByteOrder</function>
1900
1 0 ICE
1901
1 1 ByteOrder
1902
1 byte-order:
1903
0 LSBfirst
1904
1 MSBfirst
1905
1 unused
1906
4 0 length
1907
</literallayout>
1908
1909
<literallayout class="monospaced">
1910
<function>ConnectionSetup</function>
1911
1 0 ICE
1912
1 2 ConnectionSetup
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
1917
7 unused
1918
i STRING vendor
1919
j STRING release
1920
k LISTofSTRING authentication-protocol-names
1921
m LISTofVERSION version-list
1922
p unused, p = pad(i+j+k+m,8)
1923
</literallayout>
1924
1925
<literallayout class="monospaced">
1926
<function>AuthenticationRequired</function>
1927
1 0 ICE
1928
1 3 AuthenticationRequired
1929
1 CARD8 authentication-protocol-index
1930
1 unused
1931
4 (n+p)/8+1 length
1932
2 n length of authentication data
1933
6 unused
1934
n <varies> data
1935
p unused, p = pad(n,8)
1936
</literallayout>
1937
1938
<literallayout class="monospaced">
1939
<function>AuthenticationReply</function>
1940
1 0 ICE
1941
1 4 AuthenticationReply
1942
2 unused
1943
4 (n+p)/8+1 length
1944
2 n length of authentication data
1945
6 unused
1946
n <varies> data
1947
p unused, p = pad(n,8)
1948
</literallayout>
1949
1950
<literallayout class="monospaced">
1951
<function>AuthenticationNextPhase</function>
1952
1 0 ICE
1953
1 5 AuthenticationNextPhase
1954
2 unused
1955
4 (n+p)/8+1 length
1956
2 n length of authentication data
1957
6 unused
1958
n <varies> data
1959
p unused, p = pad(n,8)
1960
</literallayout>
1961
1962
<literallayout class="monospaced">
1963
<function>ConnectionReply</function>
1964
1 0 ICE
1965
1 6 ConnectionReply
1966
1 CARD8 version-index
1967
1 unused
1968
4 (i+j+p)/8 length
1969
i STRING vendor
1970
j STRING release
1971
p unused, p = pad(i+j,8)
1972
</literallayout>
1973
1974
<literallayout class="monospaced">
1975
<function>ProtocolSetup</function>
1976
1 0 ICE
1977
1 7 ProtocolSetup
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
1983
6 unused
1984
i STRING protocol-name
1985
j STRING vendor
1986
k STRING release
1987
m LISTofSTRING authentication-protocol-names
1988
n LISTofVERSION version-list
1989
p unused, p = pad(i+j+k+m+n,8)
1990
</literallayout>
1991
1992
<literallayout class="monospaced">
1993
<function>ProtocolReply</function>
1994
1 0 ICE
1995
1 8 ProtocolReply
1996
1 CARD8 version-index
1997
1 CARD8 major-opcode
1998
4 (i+j+p)/8 length
1999
i STRING vendor
2000
j STRING release
2001
p unused, p = pad(i+j, 8)
2002
</literallayout>
2003
2004
<literallayout class="monospaced">
2005
<function>Ping</function>
2006
1 0 ICE
2007
1 9 Ping
2008
2 0 unused
2009
4 0 length
2010
</literallayout>
2011
2012
<literallayout class="monospaced">
2013
<function>PingReply</function>
2014
1 0 ICE
2015
1 10 PingReply
2016
2 0 unused
2017
4 0 length
2018
</literallayout>
2019
2020
<literallayout class="monospaced">
2021
<function>WantToClose</function>
2022
1 0 ICE
2023
1 11 WantToClose
2024
2 0 unused
2025
4 0 length
2026
</literallayout>
2027
2028
<literallayout class="monospaced">
2029
<function>NoClose</function>
2030
1 0 ICE
2031
1 12 NoClose
2032
2 0 unused
2033
4 0 length
2034
</literallayout>
2035
2036
</sect1>
2037
2038
<sect1 id="error_class_encoding">
2039
<title>Error Class Encoding</title>
2040
2041
<para>
2042
Generic errors have classes in the range 0x8000-0xFFFF, and
2043
subprotocol-specific errors are in the range 0x0000-0x7FFF.
2044
</para>
2045
2046
<sect2 id="generic_error_class_encoding">
2047
<title>Generic Error Class Encoding</title>
2048
2049
<informaltable pgwide='0' frame='none'>
2050
<tgroup cols='2' align='center'>
2051
<colspec colname='c1'/>
2052
<colspec colname='c2'/>
2053
<thead>
2054
<row>
2055
<entry align='left'>Class</entry>
2056
<entry align='center'>Encoding</entry>
2057
</row>
2058
</thead>
2059
<tbody>
2060
<row>
2061
<entry align='left'>BadMinor</entry>
2062
<entry align='right'>0x8000</entry>
2063
</row>
2064
<row>
2065
<entry align='left'>BadState</entry>
2066
<entry align='right'>0x8001</entry>
2067
</row>
2068
<row>
2069
<entry align='left'>BadLength</entry>
2070
<entry align='right'>0x8002</entry>
2071
</row>
2072
<row>
2073
<entry align='left'>BadValue</entry>
2074
<entry align='right'>0x8003</entry>
2075
</row>
2076
</tbody>
2077
</tgroup>
2078
</informaltable>
2079
2080
</sect2>
2081
<sect2 id="ice_specific_error_class_encoding">
2082
<title>ICE-specific Error Class Encoding</title>
2083
2084
<informaltable pgwide='0' frame='none'>
2085
<tgroup cols='2' align='center'>
2086
<colspec colname='c1'/>
2087
<colspec colname='c2'/>
2088
<thead>
2089
<row>
2090
<entry align='left'>Class</entry>
2091
<entry align='center'>Encoding</entry>
2092
</row>
2093
</thead>
2094
<tbody>
2095
<row>
2096
<entry align='left'>BadMajor</entry>
2097
<entry align='right'>0</entry>
2098
</row>
2099
<row>
2100
<entry align='left'>NoAuthentication</entry>
2101
<entry align='right'>1</entry>
2102
</row>
2103
<row>
2104
<entry align='left'>NoVersion</entry>
2105
<entry align='right'>2</entry>
2106
</row>
2107
<row>
2108
<entry align='left'>SetupFailed</entry>
2109
<entry align='right'>3</entry>
2110
</row>
2111
<row>
2112
<entry align='left'>AuthenticationRejected</entry>
2113
<entry align='right'>4</entry>
2114
</row>
2115
<row>
2116
<entry align='left'>AuthenticationFailed</entry>
2117
<entry align='right'>5</entry>
2118
</row>
2119
<row>
2120
<entry align='left'>ProtocolDuplicate</entry>
2121
<entry align='right'>6</entry>
2122
</row>
2123
<row>
2124
<entry align='left'>MajorOpcodeDuplicate</entry>
2125
<entry align='right'>7</entry>
2126
</row>
2127
<row>
2128
<entry align='left'>UnknownProtocol</entry>
2129
<entry align='right'>8</entry>
2130
</row>
2131
</tbody>
2132
</tgroup>
2133
</informaltable>
2134
2135
</sect2>
2136
</sect1>
2137
</chapter>
2138
2139
<appendix id="modification_history">
2140
2141
<title>Modification History</title>
2142
2143
<sect1 id="release_6_to_release_6_1">
2144
<title>Release 6 to Release 6.1</title>
2145
<para>
2146
Release 6.1 added the ICE X rendezvous protocol (Appendix B) and
2147
updated the document version to 1.1.
2148
</para>
2149
</sect1>
2150
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>
2154
</sect1>
2155
2156
</appendix>
2157
2158
<appendix id="ice_x_rendezvous_protocol">
2159
<title>ICE X Rendezvous Protocol</title>
2160
2161
<sect1 id="introduction">
2162
<title>Introduction</title>
2163
<para>
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.
2169
</para>
2170
</sect1>
2171
2172
<sect1 id="overview_of_ice_x_rendezvous">
2173
<title>Overview of ICE X Rendezvous</title>
2174
2175
<para>
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>
2183
event identifies
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.
2188
</para>
2189
</sect1>
2190
2191
<sect1 id="registering_known_protocols">
2192
<title>Registering Known Protocols</title>
2193
2194
<para>
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
2202
specified in an ICE
2203
<function>ProtocolSetup</function>
2204
message.
2205
</para>
2206
2207
<para>
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.
2217
</para>
2218
</sect1>
2219
2220
<sect1 id="initiating_the_rendezvoud">
2221
<title>Initiating the Rendezvous</title>
2222
2223
<para>
2224
To initiate the rendezvous a client acting as an ICE answering
2225
party sends an X
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.
2232
</para>
2233
2234
<para>
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.
2240
</para>
2241
2242
<para>
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:
2246
</para>
2247
2248
<informaltable pgwide='0' frame='none'>
2249
<tgroup cols='2' align='center'>
2250
<colspec colname='c1'/>
2251
<colspec colname='c2'/>
2252
<thead>
2253
<row>
2254
<entry align='left'>Field</entry>
2255
<entry align='left'>Value</entry>
2256
</row>
2257
</thead>
2258
<tbody>
2259
<row>
2260
<entry align='left'>type</entry>
2261
<entry align='left'>XA_STRING</entry>
2262
</row>
2263
<row>
2264
<entry align='left'>format</entry>
2265
<entry align='left'>8</entry>
2266
</row>
2267
<row>
2268
<entry align='left'>value</entry>
2269
<entry align='left'>comma-separated list of ICE network IDs</entry>
2270
</row>
2271
</tbody>
2272
</tgroup>
2273
</informaltable>
2274
2275
2276
2277
<para>
2278
Once the ICE answering party has established this text property on one
2279
of its windows, it initiates the rendezvous by sending an
2280
ICE_PROTOCOLS
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.
2286
</para>
2287
2288
<informaltable pgwide='0' frame='none'>
2289
<tgroup cols='2' align='center'>
2290
<colspec colname='c1'/>
2291
<colspec colname='c2'/>
2292
<thead>
2293
<row>
2294
<entry align='left'>Field</entry>
2295
<entry align='left'>Value</entry>
2296
</row>
2297
</thead>
2298
<tbody>
2299
<row>
2300
<entry align='left'>message_type</entry>
2301
<entry align='left'>Atom = "ICE_PROTOCOLS"</entry>
2302
</row>
2303
<row>
2304
<entry align='left'>format</entry>
2305
<entry align='left'>32</entry>
2306
</row>
2307
<row>
2308
<entry align='left'>data.l[0]</entry>
2309
<entry align='left'>Atom identifying the ICE subprotocol to speak</entry>
2310
</row>
2311
<row>
2312
<entry align='left'>data.l[1]</entry>
2313
<entry align='left'>Timestamp</entry>
2314
</row>
2315
<row>
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>
2319
</row>
2320
<row>
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>
2324
</row>
2325
<row>
2326
<entry align='left'>data.l[4]</entry>
2327
<entry align='left'>Reserved. Must be 0.</entry>
2328
</row>
2329
</tbody>
2330
</tgroup>
2331
</informaltable>
2332
2333
2334
<para>
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.
2339
</para>
2340
2341
<para>
2342
When an ICE originating party receives a
2343
<function>ClientMessage</function>
2344
event of type
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].
2350
</para>
2351
2352
<para>
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:
2358
</para>
2359
2360
<informaltable pgwide='0' frame='none'>
2361
<tgroup cols='2' align='center'>
2362
<colspec colname='c1'/>
2363
<colspec colname='c2'/>
2364
<thead>
2365
<row>
2366
<entry align='left'>Field</entry>
2367
<entry align='left'>Value</entry>
2368
</row>
2369
</thead>
2370
<tbody>
2371
<row>
2372
<entry align='left'>message_type</entry>
2373
<entry align='left'>Atom = "ICE_INITIATE_FAILED"</entry>
2374
</row>
2375
<row>
2376
<entry align='left'>format</entry>
2377
<entry align='left'>32</entry>
2378
</row>
2379
<row>
2380
<entry align='left'>data.l[0]</entry>
2381
<entry align='left'>Atom identifying the ICE subprotocol requested</entry>
2382
</row>
2383
<row>
2384
<entry align='left'>data.l[1]</entry>
2385
<entry align='left'>Timestamp</entry>
2386
</row>
2387
<row>
2388
<entry align='left'>data.l[2]</entry>
2389
<entry align='left'><para>Initiating party's window ID
2390
(holding ICE_PROTOCOLS)</para></entry>
2391
</row>
2392
<row>
2393
<entry align='left'>data.l[3]</entry>
2394
<entry align='left'>int: reason for failure</entry>
2395
</row>
2396
<row>
2397
<entry align='left'>data.l[4]</entry>
2398
<entry align='left'>Reserved, must be 0</entry>
2399
</row>
2400
</tbody>
2401
</tgroup>
2402
</informaltable>
2403
2404
2405
<para>
2406
The values of data.l[0] and data.l[1] are copied directly from the
2407
client message event the client received.
2408
</para>
2409
2410
<para>
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.
2415
</para>
2416
2417
<para>Data.l[3] has one of the following values:</para>
2418
2419
<!-- .ne 21 -->
2420
2421
<informaltable pgwide='0' frame='none'>
2422
<tgroup cols='3' align='center'>
2423
<colspec colname='c1'/>
2424
<colspec colname='c2'/>
2425
<colspec colname='c3'/>
2426
<thead>
2427
<row>
2428
<entry align='left'>Value</entry>
2429
<entry align='left'>Encoding</entry>
2430
<entry align='left'>Description</entry>
2431
</row>
2432
</thead>
2433
<tbody>
2434
<row>
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.
2444
</entry>
2445
</row>
2446
<row>
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>
2454
otherwise
2455
<function>OpenFailed</function>
2456
will be returned.</entry>
2457
</row>
2458
<row>
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>
2464
</row>
2465
<row>
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>
2471
</row>
2472
<row>
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>
2482
</row>
2483
</tbody>
2484
</tgroup>
2485
</informaltable>
2486
2487
2488
<note>
2489
<para>
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.
2499
</para>
2500
2501
<para>
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.
2519
</para>
2520
2521
<para>
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>
2531
events of type
2532
ICE_PROTOCOLS specifying ICE_INITIATE_<emphasis remap='I'>pname</emphasis>
2533
for ICE subprotocol <emphasis remap='I'>pname</emphasis>.
2534
</para>
2535
</note>
2536
</sect1>
2537
2538
<sect1 id="ice_subprotocol_versioning">
2539
<title>ICE Subprotocol Versioning</title>
2540
2541
<para>
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>
2546
event. Because
2547
of this, ICE subprotocol versioning is handled within the ICE protocol
2548
setup phase.</para>
2549
<note remap='NT'>
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.
2557
</para>
2558
2559
<para>
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.
2566
</para>
2567
2568
<para>
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
2582
negotiation.
2583
</para>
2584
2585
<para>
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.
2589
</para>
2590
</note>
2591
</sect1>
2592
</appendix>
2593
</book>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1