Debian Codegraph @

rfc3507.html

raw
1 <pre>Network Working Group J. Elson
2 Request for Comments: 3507 A. Cerpa
3 Category: Informational UCLA
4 April 2003
5
6
7 <span class="h1">Internet Content Adaptation Protocol (ICAP)</span>
8
9 Status of this Memo
10
11 This memo provides information for the Internet community. It does
12 not specify an Internet standard of any kind. Distribution of this
13 memo is unlimited.
14
15 Copyright Notice
16
17 Copyright (C) The Internet Society (2003). All Rights Reserved.
18
19 IESG Note
20
21 The Open Pluggable Services (OPES) working group has been chartered
22 to produce a standards track protocol specification for a protocol
23 intended to perform the same of functions as ICAP. However, since
24 ICAP is already in widespread use the IESG believes it is appropriate
25 to document existing usage by publishing the ICAP specification as an
26 informational document. The IESG also notes that ICAP was developed
27 before the publication of <a href="./rfc3238">RFC 3238</a> and therefore does not address the
28 architectural and policy issues described in that document.
29
30 Abstract
31
32 ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
33 providing simple object-based content vectoring for HTTP services.
34 ICAP is, in essence, a lightweight protocol for executing a "remote
35 procedure call" on HTTP messages. It allows ICAP clients to pass
36 HTTP messages to ICAP servers for some sort of transformation or
37 other processing ("adaptation"). The server executes its
38 transformation service on messages and sends back responses to the
39 client, usually with modified messages. Typically, the adapted
40 messages are either HTTP requests or HTTP responses.
41
42
43
44
45
46
47
48
49
50
51
52 <span class="grey">Elson &amp; Cerpa Informational [Page 1]</span></pre>
53 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
54 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
55
56
57 Table of Contents
58
59 <a href="#section-1">1</a>. Introduction............................................<a href="#page-3">3</a>
60 <a href="#section-2">2</a>. Terminology.............................................<a href="#page-5">5</a>
61 <a href="#section-3">3</a>. ICAP Overall Operation..................................<a href="#page-8">8</a>
62 <a href="#section-3.1">3.1</a> Request Modification..............................<a href="#page-8">8</a>
63 <a href="#section-3.2">3.2</a> Response Modification............................<a href="#page-10">10</a>
64 <a href="#section-4">4</a>. Protocol Semantics.....................................<a href="#page-11">11</a>
65 <a href="#section-4.1">4.1</a> General Operation................................<a href="#page-11">11</a>
66 <a href="#section-4.2">4.2</a> ICAP URIs........................................<a href="#page-11">11</a>
67 <a href="#section-4.3">4.3</a> ICAP Headers.....................................<a href="#page-12">12</a>
68 4.3.1 Headers Common to Requests and
69 Responses................................<a href="#page-12">12</a>
70 <a href="#section-4.3.2">4.3.2</a> Request Headers..........................<a href="#page-13">13</a>
71 <a href="#section-4.3.3">4.3.3</a> Response Headers.........................<a href="#page-14">14</a>
72 4.3.4 ICAP-Related Headers in HTTP
73 Messages.................................<a href="#page-15">15</a>
74 4.4 ICAP Bodies: Encapsulation of HTTP
75 Messages.........................................<a href="#page-16">16</a>
76 <a href="#section-4.4.1">4.4.1</a> Expected Encapsulated Sections...........<a href="#page-16">16</a>
77 <a href="#section-4.4.2">4.4.2</a> Encapsulated HTTP Headers................<a href="#page-18">18</a>
78 <a href="#section-4.5">4.5</a> Message Preview..................................<a href="#page-18">18</a>
79 4.6 "204 No Content" Responses outside of
80 Previews.........................................<a href="#page-22">22</a>
81 <a href="#section-4.7">4.7</a> ISTag Response Header............................<a href="#page-22">22</a>
82 <a href="#section-4.8">4.8</a> Request Modification Mode........................<a href="#page-23">23</a>
83 <a href="#section-4.8.1">4.8.1</a> Request..................................<a href="#page-23">23</a>
84 <a href="#section-4.8.2">4.8.2</a> Response.................................<a href="#page-24">24</a>
85 <a href="#section-4.8.3">4.8.3</a> Examples.................................<a href="#page-24">24</a>
86 <a href="#section-4.9">4.9</a> Response Modification Mode.......................<a href="#page-27">27</a>
87 <a href="#section-4.9.1">4.9.1</a> Request..................................<a href="#page-27">27</a>
88 <a href="#section-4.9.2">4.9.2</a> Response.................................<a href="#page-27">27</a>
89 <a href="#section-4.9.3">4.9.3</a> Examples.................................<a href="#page-28">28</a>
90 <a href="#section-4.10">4.10</a> OPTIONS Method...................................<a href="#page-29">29</a>
91 <a href="#section-4.10.1">4.10.1</a> OPTIONS request..........................<a href="#page-29">29</a>
92 <a href="#section-4.10.2">4.10.2</a> OPTIONS response.........................<a href="#page-30">30</a>
93 <a href="#section-4.10.3">4.10.3</a> OPTIONS examples.........................<a href="#page-33">33</a>
94 <a href="#section-5">5</a>. Caching................................................<a href="#page-33">33</a>
95 <a href="#section-6">6</a>. Implementation Notes...................................<a href="#page-34">34</a>
96 <a href="#section-6.1">6.1</a> Vectoring Points.................................<a href="#page-34">34</a>
97 <a href="#section-6.2">6.2</a> Application Level Errors.........................<a href="#page-35">35</a>
98 <a href="#section-6.3">6.3</a> Use of Chunked Transfer-Encoding.................<a href="#page-37">37</a>
99 <a href="#section-6.4">6.4</a> Distinct URIs for Distinct Services..............<a href="#page-37">37</a>
100 <a href="#section-7">7</a>. Security Considerations................................<a href="#page-37">37</a>
101 <a href="#section-7.1">7.1</a> Authentication...................................<a href="#page-37">37</a>
102 <a href="#section-7.2">7.2</a> Encryption.......................................<a href="#page-38">38</a>
103 <a href="#section-7.3">7.3</a> Service Validation...............................<a href="#page-38">38</a>
104 <a href="#section-8">8</a>. Motivations and Design Alternatives....................<a href="#page-39">39</a>
105
106
107
108 <span class="grey">Elson &amp; Cerpa Informational [Page 2]</span></pre>
109 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
110 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
111
112
113 <a href="#section-8.1">8.1</a> To Be HTTP, or Not to Be.........................<a href="#page-39">39</a>
114 <a href="#section-8.2">8.2</a> Mandatory Use of Chunking........................<a href="#page-39">39</a>
115 8.3 Use of the null-body directive in the
116 Encapsulated header..............................<a href="#page-40">40</a>
117 <a href="#section-9">9</a>. References.............................................<a href="#page-40">40</a>
118 <a href="#section-10">10</a>. Contributors...........................................<a href="#page-41">41</a>
119 <a href="#appendix-A">Appendix A</a> BNF Grammar for ICAP Messages..................<a href="#page-45">45</a>
120 Authors' Addresses..........................................<a href="#page-48">48</a>
121 Full Copyright Statement....................................<a href="#page-49">49</a>
122
123 <span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
124
125 As the Internet grows, so does the need for scalable Internet
126 services. Popular web servers are asked to deliver content to
127 hundreds of millions of users connected at ever-increasing
128 bandwidths. The model of centralized, monolithic servers that are
129 responsible for all aspects of every client's request seems to be
130 reaching the end of its useful life.
131
132 To keep up with the growth in the number of clients, there has been a
133 move towards architectures that scale better through the use of
134 replication, distribution, and caching. On the content provider
135 side, replication and load-balancing techniques allow the burden of
136 client requests to be spread out over a myriad of servers. Content
137 providers have also begun to deploy geographically diverse content
138 distribution networks that bring origin-servers closer to the "edge"
139 of the network where clients are attached. These networks of
140 distributed origin-servers or "surrogates" allow the content provider
141 to distribute their content whilst retaining control over the
142 integrity of that content. The distributed nature of this type of
143 deployment and the proximity of a given surrogate to the end-user
144 enables the content provider to offer additional services to a user
145 which might be based, for example, on geography where this would have
146 been difficult with a single, centralized service.
147
148 ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
149 providing simple object-based content vectoring for HTTP services.
150 ICAP is, in essence, a lightweight protocol for executing a "remote
151 procedure call" on HTTP messages. It allows ICAP clients to pass
152 HTTP messages to ICAP servers for some sort of transformation or
153 other processing ("adaptation"). The server executes its
154 transformation service on messages and sends back responses to the
155 client, usually with modified messages. The adapted messages may be
156 either HTTP requests or HTTP responses. Though transformations may
157 be possible on other non-HTTP content, they are beyond the scope of
158 this document.
159
160
161
162
163
164 <span class="grey">Elson &amp; Cerpa Informational [Page 3]</span></pre>
165 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
166 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
167
168
169 This type of Remote Procedure Call (RPC) is useful in a number of
170 ways. For example:
171
172 o Simple transformations of content can be performed near the edge
173 of the network instead of requiring an updated copy of an object
174 from an origin server. For example, a content provider might want
175 to provide a popular web page with a different advertisement every
176 time the page is viewed. Currently, content providers implement
177 this policy by marking such pages as non-cachable and tracking
178 user cookies. This imposes additional load on the origin server
179 and the network. In our architecture, the page could be cached
180 once near the edges of the network. These edge caches can then
181 use an ICAP call to a nearby ad-insertion server every time the
182 page is served to a client.
183
184 Other such transformations by edge servers are possible, either
185 with cooperation from the content provider (as in a content
186 distribution network), or as a value-added service provided by a
187 client's network provider (as in a surrogate). Examples of these
188 kinds of transformations are translation of web pages to different
189 human languages or to different formats that are appropriate for
190 special physical devices (e.g., PDA-based or cell-phone-based
191 browsers).
192
193 o Surrogates or origin servers can avoid performing expensive
194 operations by shipping the work off to other servers instead.
195 This helps distribute load across multiple machines. For example,
196 consider a user attempting to download an executable program via a
197 surrogate (e.g., a caching proxy). The surrogate, acting as an
198 ICAP client, can ask an external server to check the executable
199 for viruses before accepting it into its cache.
200
201 o Firewalls or surrogates can act as ICAP clients and send outgoing
202 requests to a service that checks to make sure the URI in the
203 request is allowed (for example, in a system that allows parental
204 control of web content viewed by children). In this case, it is a
205 *request* that is being adapted, not an object returned by a
206 response.
207
208 In all of these examples, ICAP is helping to reduce or distribute the
209 load on origin servers, surrogates, or the network itself. In some
210 cases, ICAP facilitates transformations near the edge of the network,
211 allowing greater cachability of the underlying content. In other
212 examples, devices such as origin servers or surrogates are able to
213 reduce their load by distributing expensive operations onto other
214 machines. In all cases, ICAP has also created a standard interface
215 for content adaptation to allow greater flexibility in content
216 distribution or the addition of value added services in surrogates.
217
218
219
220 <span class="grey">Elson &amp; Cerpa Informational [Page 4]</span></pre>
221 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
222 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
223
224
225 There are two major components in our architecture:
226
227 1. Transaction semantics -- "How do I ask for adaptation?"
228
229 2. Control of policy -- "When am I supposed to ask for adaptation,
230 what kind of adaptation do I ask for, and from where?"
231
232 Currently, ICAP defines only the transaction semantics. For example,
233 this document specifies how to send an HTTP message from an ICAP
234 client to an ICAP server, specify the URI of the ICAP resource
235 requested along with other resource-specific parameters, and receive
236 the adapted message.
237
238 Although a necessary building-block, this wire-protocol defined by
239 ICAP is of limited use without the second part: an accompanying
240 application framework in which it operates. The more difficult
241 policy issue is beyond the scope of the current ICAP protocol, but is
242 planned in future work.
243
244 In initial implementations, we expect that implementation-specific
245 manual configuration will be used to define policy. This includes
246 the rules for recognizing messages that require adaptation, the URIs
247 of available adaptation resources, and so on. For ICAP clients and
248 servers to interoperate, the exact method used to define policy need
249 not be consistent across implementations, as long as the policy
250 itself is consistent.
251
252 IMPORTANT:
253 Note that at this time, in the absence of a policy-framework, it
254 is strongly RECOMMENDED that transformations SHOULD only be
255 performed on messages with the explicit consent of either the
256 content-provider or the user (or both). Deployment of
257 transformation services without the consent of either leads to, at
258 best, unpredictable results. For more discussion of these issues,
259 see <a href="#section-7">Section 7</a>.
260
261 Once the full extent of the typical policy decisions are more fully
262 understood through experience with these initial implementations,
263 later follow-ons to this architecture may define an additional policy
264 control protocol. This future protocol may allow a standard policy
265 definition interface complementary to the ICAP transaction interface
266 defined here.
267
268 <span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Terminology</span>
269
270 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
271 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
272 document are to be interpreted as described in <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a> [<a href="#ref-2" title="&quot;Key words for use in RFCs to Indicate Requirement Levels&quot;">2</a>].
273
274
275
276 <span class="grey">Elson &amp; Cerpa Informational [Page 5]</span></pre>
277 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
278 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
279
280
281 The special terminology used in this document is defined below. The
282 majority of these terms are taken as-is from HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>] and are
283 reproduced here for reference. A thorough understanding of HTTP/1.1
284 is assumed on the part of the reader.
285
286 connection:
287 A transport layer virtual circuit established between two programs
288 for the purpose of communication.
289
290 message:
291 The basic unit of HTTP communication, consisting of a structured
292 sequence of octets matching the syntax defined in <a href="#section-4">Section 4</a> of
293 HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>] and transmitted via the connection.
294
295 request:
296 An HTTP request message, as defined in <a href="#section-5">Section 5</a> of HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
297
298 response:
299 An HTTP response message, as defined in <a href="#section-6">Section 6</a> of HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
300
301 resource:
302 A network data object or service that can be identified by a URI,
303 as defined in <a href="#section-3.2">Section 3.2</a> of HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. Resources may be
304 available in multiple representations (e.g., multiple languages,
305 data formats, size, resolutions) or vary in other ways.
306
307 client:
308 A program that establishes connections for the purpose of sending
309 requests.
310
311 server:
312 An application program that accepts connections in order to
313 service requests by sending back responses. Any given program may
314 be capable of being both a client and a server; our use of these
315 terms refers only to the role being performed by the program for a
316 particular connection, rather than to the program's capabilities
317 in general. Likewise, any server may act as an origin server,
318 surrogate, gateway, or tunnel, switching behavior based on the
319 nature of each request.
320
321 origin server:
322 The server on which a given resource resides or is to be created.
323
324
325
326
327
328
329
330
331
332 <span class="grey">Elson &amp; Cerpa Informational [Page 6]</span></pre>
333 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
334 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
335
336
337 proxy:
338 An intermediary program which acts as both a server and a client
339 for the purpose of making requests on behalf of other clients.
340 Requests are serviced internally or by passing them on, with
341 possible translation, to other servers. A proxy MUST implement
342 both the client and server requirements of this specification.
343
344 cache:
345 A program's local store of response messages and the subsystem
346 that controls its message storage, retrieval, and deletion. A
347 cache stores cachable responses in order to reduce the response
348 time and network bandwidth consumption on future, equivalent
349 requests. Any client or server may include a cache, though a
350 cache cannot be used by a server that is acting as a tunnel.
351
352 cachable:
353 A response is cachable if a cache is allowed to store a copy of
354 the response message for use in answering subsequent requests.
355 The rules for determining the cachability of HTTP responses are
356 defined in Section 13 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. Even if a resource is cachable,
357 there may be additional constraints on whether a cache can use the
358 cached copy for a particular request.
359
360 surrogate:
361 A gateway co-located with an origin server, or at a different
362 point in the network, delegated the authority to operate on behalf
363 of, and typically working in close co-operation with, one or more
364 origin servers. Responses are typically delivered from an
365 internal cache. Surrogates may derive cache entries from the
366 origin server or from another of the origin server's delegates.
367 In some cases a surrogate may tunnel such requests.
368
369 Where close co-operation between origin servers and surrogates
370 exists, this enables modifications of some protocol requirements,
371 including the Cache-Control directives in [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. Such modifications
372 have yet to be fully specified.
373
374 Devices commonly known as "reverse proxies" and "(origin) server
375 accelerators" are both more properly defined as surrogates.
376
377 New definitions:
378
379 ICAP resource:
380 Similar to an HTTP resource as described above, but the URI refers
381 to an ICAP service that performs adaptations of HTTP messages.
382
383
384
385
386
387
388 <span class="grey">Elson &amp; Cerpa Informational [Page 7]</span></pre>
389 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
390 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
391
392
393 ICAP server:
394 Similar to an HTTP server as described above, except that the
395 application services ICAP requests.
396
397 ICAP client:
398 A program that establishes connections to ICAP servers for the
399 purpose of sending requests. An ICAP client is often, but not
400 always, a surrogate acting on behalf of a user.
401
402 <span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. ICAP Overall Operation</span>
403
404 Before describing ICAP's semantics in detail, we will first give a
405 general overview of the protocol's major functions and expected uses.
406 As described earlier, ICAP focuses on modification of HTTP requests
407 (<a href="#section-3.1">Section 3.1</a>), and modification of HTTP responses (<a href="#section-3.2">Section 3.2</a>).
408
409 <span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a> Request Modification</span>
410
411 In "request modification" (reqmod) mode, an ICAP client sends an HTTP
412 request to an ICAP server. The ICAP server may then:
413
414 1) Send back a modified version of the request. The ICAP client may
415 then perform the modified request by contacting an origin server;
416 or, pipeline the modified request to another ICAP server for
417 further modification.
418
419 2) Send back an HTTP response to the request. This is used to
420 provide information useful to the user in case of an error (e.g.,
421 "you sent a request to view a page you are not allowed to see").
422
423 3) Return an error.
424
425 ICAP clients MUST be able to handle all three types of responses.
426 However, in line with the guidance provided for HTTP surrogates in
427 Section 13.8 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>], ICAP client implementors do have flexibility in
428 handling errors. If the ICAP server returns an error, the ICAP
429 client may (for example) return the error to the user, execute the
430 unadapted request as it arrived from the client, or re-try the
431 adaptation again.
432
433 We will illustrate this method with an example application: content
434 filtering. Consider a surrogate that receives a request from a
435 client for a web page on an origin server. The surrogate, acting as
436 an ICAP client, sends the client's request to an ICAP server that
437 performs URI-based content filtering. If access to the requested URI
438 is allowed, the request is returned to the ICAP client unmodified.
439 However, if the ICAP server chooses to disallow access to the
440 requested resources, it may either:
441
442
443
444 <span class="grey">Elson &amp; Cerpa Informational [Page 8]</span></pre>
445 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
446 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
447
448
449 1) Modify the request so that it points to a page containing an error
450 message instead of the original URI.
451
452 2) Return an encapsulated HTTP response that indicates an HTTP error.
453
454 This method can be used for a variety of other applications; for
455 example, anonymization, modification of the Accept: headers to handle
456 special device requirements, and so forth.
457
458 Typical data flow:
459
460 origin-server
461 | /|\
462 | |
463 5 | | 4
464 | |
465 \|/ | 2
466 ICAP-client --------------&gt; ICAP-resource
467 (surrogate) &lt;-------------- on ICAP-server
468 | /|\ 3
469 | |
470 6 | | 1
471 | |
472 \|/ |
473 client
474
475 1. A client makes a request to a ICAP-capable surrogate (ICAP client)
476 for an object on an origin server.
477
478 2. The surrogate sends the request to the ICAP server.
479
480 3. The ICAP server executes the ICAP resource's service on the
481 request and sends the possibly modified request, or a response to
482 the request back to the ICAP client.
483
484 If Step 3 returned a request:
485
486 4. The surrogate sends the request, possibly different from original
487 client request, to the origin server.
488
489 5. The origin server responds to request.
490
491 6. The surrogate sends the reply (from either the ICAP server or the
492 origin server) to the client.
493
494
495
496
497
498
499
500 <span class="grey">Elson &amp; Cerpa Informational [Page 9]</span></pre>
501 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
502 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
503
504
505 <span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a> Response Modification</span>
506
507 In the "response modification" (respmod) mode, an ICAP client sends
508 an HTTP response to an ICAP server. (The response sent by the ICAP
509 client typically has been generated by an origin server.) The ICAP
510 server may then:
511
512 1) Send back a modified version of the response.
513
514 2) Return an error.
515
516 The response modification method is intended for post-processing
517 performed on an HTTP response before it is delivered to a client.
518 Examples include formatting HTML for display on special devices,
519 human language translation, virus checking, and so forth.
520
521 Typical data flow:
522
523 origin-server
524 | /|\
525 | |
526 3 | | 2
527 | |
528 \|/ | 4
529 ICAP-client --------------&gt; ICAP-resource
530 (surrogate) &lt;-------------- on ICAP-server
531 | /|\ 5
532 | |
533 6 | | 1
534 | |
535 \|/ |
536 client
537
538 1. A client makes a request to a ICAP-capable surrogate (ICAP client)
539 for an object on an origin server.
540
541 2. The surrogate sends the request to the origin server.
542
543 3. The origin server responds to request.
544
545 4. The ICAP-capable surrogate sends the origin server's reply to the
546 ICAP server.
547
548 5. The ICAP server executes the ICAP resource's service on the origin
549 server's reply and sends the possibly modified reply back to the
550 ICAP client.
551
552
553
554
555
556 <span class="grey">Elson &amp; Cerpa Informational [Page 10]</span></pre>
557 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
558 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
559
560
561 6. The surrogate sends the reply, possibly modified from the original
562 origin server's reply, to the client.
563
564 <span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Protocol Semantics</span>
565
566 <span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a> General Operation</span>
567
568 ICAP is a request/response protocol similar in semantics and usage to
569 HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. Despite the similarity, ICAP is not HTTP, nor is it an
570 application protocol that runs over HTTP. This means, for example,
571 that ICAP messages can not be forwarded by HTTP surrogates. Our
572 reasons for not building directly on top of HTTP are discussed in
573 <a href="#section-8.1">Section 8.1</a>.
574
575 ICAP uses TCP/IP as a transport protocol. The default port is 1344,
576 but other ports may be used. The TCP flow is initiated by the ICAP
577 client to a passively listening ICAP server.
578
579 ICAP messages consist of requests from client to server and responses
580 from server to client. Requests and responses use the generic
581 message format of <a href="./rfc2822">RFC 2822</a> [<a href="#ref-3" title="&quot;Internet Message Format&quot;">3</a>] -- that is, a start-line (either a
582 request line or a status line), a number of header fields (also known
583 as "headers"), an empty line (i.e., a line with nothing preceding the
584 CRLF) indicating the end of the header fields, and a message-body.
585
586 The header lines of an ICAP message specify the ICAP resource being
587 requested as well as other meta-data such as cache control
588 information. The message body of an ICAP request contains the
589 (encapsulated) HTTP messages that are being modified.
590
591 As in HTTP/1.1, a single transport connection MAY (perhaps even
592 SHOULD) be re-used for multiple request/response pairs. The rules
593 for doing so in ICAP are the same as described in Section 8.1.2.2 of
594 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. Specifically, requests are matched up with responses by
595 allowing only one outstanding request on a transport connection at a
596 time. Multiple parallel connections MAY be used as in HTTP.
597
598 <span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a> ICAP URIs</span>
599
600 All ICAP requests specify the ICAP resource being requested from the
601 server using an ICAP URI. This MUST be an absolute URI that
602 specifies both the complete hostname and the path of the resource
603 being requested. For definitive information on URL syntax and
604 semantics, see "Uniform Resource Identifiers (URI): Generic Syntax
605 and Semantics," <a href="./rfc2396">RFC 2396</a> [<a href="#ref-1" title="&quot;Uniform Resource Identifiers (URI): Generic Syntax and Semantics&quot;">1</a>], Section 3. The URI structure defined
606 by ICAP is roughly:
607
608
609
610
611
612 <span class="grey">Elson &amp; Cerpa Informational [Page 11]</span></pre>
613 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
614 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
615
616
617 ICAP_URI = Scheme ":" Net_Path [ "?" Query ]
618
619 Scheme = "icap"
620
621 Net_Path = "//" Authority [ Abs_Path ]
622
623 Authority = [ userinfo "@" ] host [ ":" port ]
624
625 ICAP adds the new scheme "icap" to the ones defined in <a href="./rfc2396">RFC 2396</a>. If
626 the port is empty or not given, port 1344 is assumed. An example
627 ICAP URI line might look like this:
628
629 icap://icap.example.net:2000/services/icap-service-1
630
631 An ICAP server MUST be able to recognize all of its hosts names,
632 including any aliases, local variations, and numeric IP addresses of
633 its interfaces.
634
635 Any arguments that an ICAP client wishes to pass to an ICAP service
636 to modify the nature of the service MAY be passed as part of the
637 ICAP-URI, using the standard "?"-encoding of attribute-value pairs
638 used in HTTP. For example:
639
640 icap://icap.net/service?mode=translate&amp;lang=french
641
642 <span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a> ICAP Headers</span>
643
644 The following sections define the valid headers for ICAP messages.
645 <a href="#section-4.3.1">Section 4.3.1</a> describes headers common to both requests and
646 responses. Request-specific and response-specific headers are
647 described in Sections <a href="#section-4.3.2">4.3.2</a> and <a href="#section-4.3.3">4.3.3</a>, respectively.
648
649 User-defined header extensions are allowed. In compliance with the
650 precedent established by the Internet mail format [<a href="#ref-3" title="&quot;Internet Message Format&quot;">3</a>] and later
651 adopted by HTTP [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>], all user-defined headers MUST follow the "X-"
652 naming convention ("X-Extension-Header: Foo"). ICAP implementations
653 MAY ignore any "X-" headers without loss of compliance with the
654 protocol as defined in this document.
655
656 Each header field consists of a name followed by a colon (":") and
657 the field value. Field names are case-insensitive. ICAP follows the
658 rules describe in section 4.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
659
660 <span class="h4"><a class="selflink" id="section-4.3.1" href="#section-4.3.1">4.3.1</a> Headers Common to Requests and Responses</span>
661
662 The headers of all ICAP messages MAY include the following
663 directives, defined in ICAP the same as they are in HTTP:
664
665
666
667
668 <span class="grey">Elson &amp; Cerpa Informational [Page 12]</span></pre>
669 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
670 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
671
672
673 Cache-Control
674 Connection
675 Date
676 Expires
677 Pragma
678 Trailer
679 Upgrade
680
681 Note in particular that the "Transfer-Encoding" option is not
682 allowed. The special transfer-encoding requirements of ICAP bodies
683 are described in <a href="#section-4.4">Section 4.4</a>.
684
685 The Upgrade header MAY be used to negotiate Transport-Layer Security
686 on an ICAP connection, exactly as described for HTTP/1.1 in [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
687
688 The ICAP-specific headers defined are:
689
690 Encapsulated (See <a href="#section-4.4">Section 4.4</a>)
691
692 <span class="h4"><a class="selflink" id="section-4.3.2" href="#section-4.3.2">4.3.2</a> Request Headers</span>
693
694 Similar to HTTP, ICAP requests MUST start with a request line that
695 contains a method, the complete URI of the ICAP resource being
696 requested, and an ICAP version string. The current version number of
697 ICAP is "1.0".
698
699 This version of ICAP defines three methods:
700
701 REQMOD - for Request Modification (<a href="#section-4.8">Section 4.8</a>)
702 RESPMOD - for Response Modification (<a href="#section-4.9">Section 4.9</a>)
703 OPTIONS - to learn about configuration (<a href="#section-4.10">Section 4.10</a>)
704
705 The OPTIONS method MUST be implemented by all ICAP servers. All
706 other methods are optional and MAY be implemented.
707
708 User-defined extension methods are allowed. Before attempting to use
709 an extension method, an ICAP client SHOULD use the OPTIONS method to
710 query the ICAP server's list of supported methods; see <a href="#section-4.10">Section 4.10</a>.
711 (If an ICAP server receives a request for an unknown method, it MUST
712 give a 501 error response as described in the next section.)
713
714 Given the URI rules described in <a href="#section-4.2">Section 4.2</a>, a well-formed ICAP
715 request line looks like the following example:
716
717 RESPMOD icap://icap.example.net/translate?mode=french ICAP/1.0
718
719
720
721
722
723
724 <span class="grey">Elson &amp; Cerpa Informational [Page 13]</span></pre>
725 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
726 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
727
728
729 A number of request-specific headers are allowed in ICAP requests,
730 following the same semantics as the corresponding HTTP request
731 headers (Section 5.3 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]). These are:
732
733 Authorization
734 Allow (see <a href="#section-4.6">Section 4.6</a>)
735 From (see Section 14.22 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>])
736 Host (REQUIRED in ICAP as it is in HTTP/1.1)
737 Referer (see Section 14.36 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>])
738 User-Agent
739
740 In addition to HTTP-like headers, there are also request headers
741 unique to ICAP defined:
742
743 Preview (see <a href="#section-4.5">Section 4.5</a>)
744
745 <span class="h4"><a class="selflink" id="section-4.3.3" href="#section-4.3.3">4.3.3</a> Response Headers</span>
746
747 ICAP responses MUST start with an ICAP status line, similar in form
748 to that used by HTTP, including the ICAP version and a status code.
749 For example:
750
751 ICAP/1.0 200 OK
752
753 Semantics of ICAP status codes in ICAP match the status codes defined
754 by HTTP (<a href="#section-6.1.1">Section 6.1.1</a> and 10 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]), except where otherwise
755 indicated in this document; n.b. 100 (<a href="#section-4.5">Section 4.5</a>) and 204 (<a href="#section-4.6">Section</a>
756 <a href="#section-4.6">4.6</a>).
757
758 ICAP error codes that differ from their HTTP counterparts are:
759
760 100 - Continue after ICAP Preview (<a href="#section-4.5">Section 4.5</a>).
761
762 204 - No modifications needed (<a href="#section-4.6">Section 4.6</a>).
763
764 400 - Bad request.
765
766 404 - ICAP Service not found.
767
768 405 - Method not allowed for service (e.g., RESPMOD requested for
769 service that supports only REQMOD).
770
771 408 - Request timeout. ICAP server gave up waiting for a request
772 from an ICAP client.
773
774 500 - Server error. Error on the ICAP server, such as "out of disk
775 space".
776
777
778
779
780 <span class="grey">Elson &amp; Cerpa Informational [Page 14]</span></pre>
781 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span>
782 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
783
784
785 501 - Method not implemented. This response is illegal for an
786 OPTIONS request since implementation of OPTIONS is mandatory.
787
788 502 - Bad Gateway. This is an ICAP proxy and proxying produced an
789 error.
790
791 503 - Service overloaded. The ICAP server has exceeded a maximum
792 connection limit associated with this service; the ICAP client
793 should not exceed this limit in the future.
794
795 505 - ICAP version not supported by server.
796
797 As in HTTP, the 4xx class of error codes indicate client errors, and
798 the 5xx class indicate server errors.
799
800 ICAP's response-header fields allow the server to pass additional
801 information in the response that cannot be placed in the ICAP's
802 status line.
803
804 A response-specific header is allowed in ICAP requests, following the
805 same semantics as the corresponding HTTP response headers (<a href="#section-6.2">Section</a>
806 <a href="#section-6.2">6.2</a> of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]). This is:
807
808 Server (see Section 14.38 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>])
809
810 In addition to HTTP-like headers, there is also a response header
811 unique to ICAP defined:
812
813 ISTag (see <a href="#section-4.7">Section 4.7</a>)
814
815 <span class="h4"><a class="selflink" id="section-4.3.4" href="#section-4.3.4">4.3.4</a> ICAP-Related Headers in HTTP Messages</span>
816
817 When an ICAP-enabled HTTP surrogate makes an HTTP request to an
818 origin server, it is often useful to advise the origin server of the
819 surrogate's ICAP capabilities. Origin servers can use this
820 information to modify its response accordingly. For example, an
821 origin server may choose not to insert an advertisement into a page
822 if it knows that a downstream ICAP server can insert the ad instead.
823
824 Although this ICAP specification can not mandate how HTTP is used in
825 communication between HTTP clients and servers, we do suggest a
826 convention: such headers (if used) SHOULD start with "X-ICAP". HTTP
827 clients with ICAP services SHOULD minimally include an "X-ICAP-
828 Version: 1.0" header along with their application-specific headers.
829
830
831
832
833
834
835
836 <span class="grey">Elson &amp; Cerpa Informational [Page 15]</span></pre>
837 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span>
838 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
839
840
841 <span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a> ICAP Bodies: Encapsulation of HTTP Messages</span>
842
843 The ICAP encapsulation model is a lightweight means of packaging any
844 number of HTTP message sections into an encapsulating ICAP message-
845 body, in order to allow the vectoring of requests, responses, and
846 request/response pairs to an ICAP server.
847
848 This is accomplished by concatenating interesting message parts
849 (encapsulatED sections) into a single ICAP message-body (the
850 encapsulatING message). The encapsulated sections may be the headers
851 or bodies of HTTP messages.
852
853 Encapsulated bodies MUST be transferred using the "chunked"
854 transfer-coding described in Section 3.6.1 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. However,
855 encapsulated headers MUST NOT be chunked. In other words, an ICAP
856 message-body switches from being non-chunked to chunked as the body
857 passes from the encapsulated header to encapsulated body section.
858 (See Examples in Sections <a href="#section-4.8.3">4.8.3</a> and <a href="#section-4.9.3">4.9.3</a>.). The motivation behind
859 this decision is described in <a href="#section-8.2">Section 8.2</a>.
860
861 <span class="h4"><a class="selflink" id="section-4.4.1" href="#section-4.4.1">4.4.1</a> The "Encapsulated" Header</span>
862
863 The offset of each encapsulated section's start relative to the start
864 of the encapsulating message's body is noted using the "Encapsulated"
865 header. This header MUST be included in every ICAP message. For
866 example, the header
867
868 Encapsulated: req-hdr=0, res-hdr=45, res-body=100
869
870 indicates a message that encapsulates a group of request headers, a
871 group of response headers, and then a response body. Each of these
872 is included at the byte-offsets listed. The byte-offsets are in
873 decimal notation for consistency with HTTP's Content-Length header.
874
875 The special entity "null-body" indicates there is no encapsulated
876 body in the ICAP message.
877
878 The syntax of an Encapsulated header is:
879
880 encapsulated_header: "Encapsulated: " encapsulated_list
881 encapsulated_list: encapsulated_entity |
882 encapsulated_entity ", " encapsulated_list
883 encapsulated_entity: reqhdr | reshdr | reqbody | resbody | optbody
884 reqhdr = "req-hdr" "=" (decimal integer)
885 reshdr = "res-hdr" "=" (decimal integer)
886 reqbody = { "req-body" | "null-body" } "=" (decimal integer)
887 resbody = { "res-body" | "null-body" } "=" (decimal integer)
888 optbody = { "opt-body" | "null-body" } "=" (decimal integer)
889
890
891
892 <span class="grey">Elson &amp; Cerpa Informational [Page 16]</span></pre>
893 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span>
894 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
895
896
897 There are semantic restrictions on Encapsulated headers beyond the
898 syntactic restrictions. The order in which the encapsulated parts
899 appear in the encapsulating message-body MUST be the same as the
900 order in which the parts are named in the Encapsulated header. In
901 other words, the offsets listed in the Encapsulated line MUST be
902 monotonically increasing. In addition, the legal forms of the
903 Encapsulated header depend on the method being used (REQMOD, RESPMOD,
904 or OPTIONS). Specifically:
905
906 REQMOD request encapsulated_list: [reqhdr] reqbody
907 REQMOD response encapsulated_list: {[reqhdr] reqbody} |
908 {[reshdr] resbody}
909 RESPMOD request encapsulated_list: [reqhdr] [reshdr] resbody
910 RESPMOD response encapsulated_list: [reshdr] resbody
911 OPTIONS response encapsulated_list: optbody
912
913 In the above grammar, note that encapsulated headers are always
914 optional. At most one body per encapsulated message is allowed. If
915 no encapsulated body is presented, the "null-body" header is used
916 instead; this is useful because it indicates the length of the header
917 section.
918
919 Examples of legal Encapsulated headers:
920
921 /* REQMOD request: This encapsulated HTTP request's headers start
922 * at offset 0; the HTTP request body (e.g., in a POST) starts
923 * at 412. */
924 Encapsulated: req-hdr=0, req-body=412
925
926 /* REQMOD request: Similar to the above, but no request body is
927 * present (e.g., a GET). We use the null-body directive instead.
928 * In both this case and the previous one, we can tell from the
929 * Encapsulated header that the request headers were 412 bytes
930 * long. */
931 Encapsulated: req-hdr=0, null-body=412
932
933 /* REQMOD response: ICAP server returned a modified request,
934 * with body */
935 Encapsulated: req-hdr=0, req-body=512
936
937 /* RESPMOD request: Request headers at 0, response headers at 822,
938 * response body at 1655. Note that no request body is allowed in
939 * RESPMOD requests. */
940 Encapsulated: req-hdr=0, res-hdr=822, res-body=1655
941
942 /* RESPMOD or REQMOD response: header and body returned */
943 Encapsulated: res-hdr=0, res-body=749
944
945
946
947
948 <span class="grey">Elson &amp; Cerpa Informational [Page 17]</span></pre>
949 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-18" ></span>
950 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
951
952
953 /* OPTIONS response when there IS an options body */
954 Encapsulated: opt-body=0
955
956 /* OPTIONS response when there IS NOT an options body */
957 Encapsulated: null-body=0
958
959 <span class="h4"><a class="selflink" id="section-4.4.2" href="#section-4.4.2">4.4.2</a> Encapsulated HTTP Headers</span>
960
961 By default, ICAP messages may encapsulate HTTP message headers and
962 entity bodies. HTTP headers MUST start with the request-line or
963 status-line for requests and responses, respectively, followed by
964 interesting HTTP headers.
965
966 The encapsulated headers MUST be terminated by a blank line, in order
967 to make them human readable, and in order to terminate line-by-line
968 HTTP parsers.
969
970 HTTP/1.1 makes a distinction between end-to-end headers and hop-by-
971 hop headers (see Section 13.5.1 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]). End-to-end headers are
972 meaningful to the ultimate recipient of a message, whereas hop-by-hop
973 headers are meaningful only for a single transport-layer connection.
974 Hop-by-hop headers include Connection, Keep-Alive, and so forth. All
975 end-to-end HTTP headers SHOULD be encapsulated, and all hop-by-hop
976 headers MUST NOT be encapsulated.
977
978 Despite the above restrictions on encapsulation, the hop-by-hop
979 Proxy-Authenticate and Proxy-Authorization headers MUST be forwarded
980 to the ICAP server in the ICAP header section (not the encapsulated
981 message). This allows propagation of client credentials that might
982 have been sent to the ICAP client in cases where the ICAP client is
983 also an HTTP surrogate. Note that this does not contradict HTTP/1.1,
984 which explicitly states "A proxy MAY relay the credentials from the
985 client request to the next proxy if that is the mechanism by which
986 the proxies cooperatively authenticate a given request." (<a href="#section-14.34">Section</a>
987 <a href="#section-14.34">14.34</a>).
988
989 The Via header of an encapsulated message SHOULD be modified by an
990 ICAP server as if the encapsulated message were traveling through an
991 HTTP surrogate. The Via header added by an ICAP server MUST specify
992 protocol as ICAP/1.0.
993
994 <span class="h3"><a class="selflink" id="section-4.5" href="#section-4.5">4.5</a> Message Preview</span>
995
996 ICAP REQMOD or RESPMOD requests sent by the ICAP client to the ICAP
997 server may include a "preview". This feature allows an ICAP server
998 to see the beginning of a transaction, then decide if it wants to
999
1000
1001
1002
1003
1004 <span class="grey">Elson &amp; Cerpa Informational [Page 18]</span></pre>
1005 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-19" ></span>
1006 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1007
1008
1009 opt-out of the transaction early instead of receiving the remainder
1010 of the request message. Previewing can yield significant performance
1011 improvements in a variety of situations, such as the following:
1012
1013 - Virus-checkers can certify a large fraction of files as "clean"
1014 just by looking at the file type, file name extension, and the
1015 first few bytes of the file. Only the remaining files need to be
1016 transmitted to the virus-checking ICAP server in their entirety.
1017
1018 - Content filters can use Preview to decide if an HTTP entity needs
1019 to be inspected (the HTTP file type alone is not enough in cases
1020 where "text" actually turns out to be graphics data). The magic
1021 numbers at the front of the file can identify a file as a JPEG or
1022 GIF.
1023
1024 - If an ICAP server wants to transcode all GIF87 files into GIF89
1025 files, then the GIF87 files could quickly be detected by looking
1026 at the first few body bytes of the file.
1027
1028 - If an ICAP server wants to force all cacheable files to expire in
1029 24 hours or less, then this could be implemented by selecting HTTP
1030 messages with expiries more than 24 hours in the future.
1031
1032 ICAP servers SHOULD use the OPTIONS method (see <a href="#section-4.10">Section 4.10</a>) to
1033 specify how many bytes of preview are needed for a particular ICAP
1034 application on a per-resource basis. Clients SHOULD be able to
1035 provide Previews of at least 4096 bytes. Clients furthermore SHOULD
1036 provide a Preview when using any ICAP resource that has indicated a
1037 Preview is useful. (This indication might be provided via the
1038 OPTIONS method, or some other "out-of-band" configuration.) Clients
1039 SHOULD NOT provide a larger Preview than a server has indicated it is
1040 willing to accept.
1041
1042 To effect a Preview, an ICAP client MUST add a "Preview:" header to
1043 its request headers indicating the length of the preview. The ICAP
1044 client then sends:
1045
1046 - all of the encapsulated header sections, and
1047
1048 - the beginning of the encapsulated body section, if any, up to the
1049 number of bytes advertised in the Preview (possibly 0).
1050
1051 After the Preview is sent, the client stops and waits for an
1052 intermediate response from the ICAP server before continuing. This
1053 mechanism is similar to the "100-Continue" feature found in HTTP,
1054 except that the stop-and-wait point can be within the message body.
1055 In contrast, HTTP requires that the point must be the boundary
1056 between the headers and body.
1057
1058
1059
1060 <span class="grey">Elson &amp; Cerpa Informational [Page 19]</span></pre>
1061 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-20" ></span>
1062 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1063
1064
1065 For example, to effect a Preview consisting of only encapsulated HTTP
1066 headers, the ICAP client would add the following header to the ICAP
1067 request:
1068
1069 Preview: 0
1070
1071 This indicates that the ICAP client will send only the encapsulated
1072 header sections to the ICAP server, then it will send a zero-length
1073 chunk and stop and wait for a "go ahead" to send more encapsulated
1074 body bytes to the ICAP server.
1075
1076 Similarly, the ICAP header:
1077
1078 Preview: 4096
1079
1080 Indicates that the ICAP client will attempt to send 4096 bytes of
1081 origin server data in the encapsulated body of the ICAP request to
1082 the ICAP server. It is important to note that the actual transfer
1083 may be less, because the ICAP client is acting like a surrogate and
1084 is not looking ahead to find the total length of the origin server
1085 response. The entire ICAP encapsulated header section(s) will be
1086 sent, followed by up to 4096 bytes of encapsulated HTTP body. The
1087 chunk body terminator "0\r\n\r\n" is always included in these
1088 transactions.
1089
1090 After sending the preview, the ICAP client will wait for a response
1091 from the ICAP server. The response MUST be one of the following:
1092
1093 - 204 No Content. The ICAP server does not want to (or can not)
1094 modify the ICAP client's request. The ICAP client MUST treat this
1095 the same as if it had sent the entire message to the ICAP server
1096 and an identical message was returned.
1097
1098 - ICAP reqmod or respmod response, depending what method was the
1099 original request. See <a href="#section-4.8.2">Section 4.8.2</a> and 4.9.2 for the format of
1100 reqmod and respmod responses.
1101
1102 - 100 Continue. If the entire encapsulated HTTP body did not fit
1103 in the preview, the ICAP client MUST send the remainder of its
1104 ICAP message, starting from the first chunk after the preview. If
1105 the entire message fit in the preview (detected by the "EOF"
1106 symbol explained below), then the ICAP server MUST NOT respond
1107 with 100 Continue.
1108
1109 When an ICAP client is performing a preview, it may not yet know how
1110 many bytes will ultimately be available in the arriving HTTP message
1111 that it is relaying to the HTTP server. Therefore, ICAP defines a
1112 way for ICAP clients to indicate "EOF" to ICAP servers if one
1113
1114
1115
1116 <span class="grey">Elson &amp; Cerpa Informational [Page 20]</span></pre>
1117 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-21" ></span>
1118 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1119
1120
1121 unexpectedly arrives during the preview process. This is a
1122 particularly useful optimization if a header-only HTTP response
1123 arrives at the ICAP client (i.e., zero bytes of body); only a single
1124 round trip will be needed for the complete ICAP server response.
1125
1126 We define an HTTP chunk-extension of "ieof" to indicate that an ICAP
1127 chunk is the last chunk (see [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]). The ICAP server MUST strip this
1128 chunk extension before passing the chunk data to an ICAP application
1129 process.
1130
1131 For example, consider an ICAP client that has just received HTTP
1132 response headers from an origin server and initiates an ICAP RESPMOD
1133 transaction to an ICAP server. It does not know yet how many body
1134 bytes will be arriving from the origin server because the server is
1135 not using the Content-Length header. The ICAP client informs the
1136 ICAP server that it will be sending a 1024-byte preview using a
1137 "Preview: 1024" request header. If the HTTP origin server then
1138 closes its connection to the ICAP client before sending any data
1139 (i.e., it provides a zero-byte body), the corresponding zero-byte
1140 preview for that zero-byte origin response would appear as follows:
1141
1142 \r\n
1143 0; ieof\r\n\r\n
1144
1145 If an ICAP server sees this preview, it knows from the presence of
1146 "ieof" that the client will not be sending any more chunk data. In
1147 this case, the server MUST respond with the modified response or a
1148 204 No Content message right away. It MUST NOT send a 100-Continue
1149 response in this case. (In contrast, if the origin response had been
1150 1 byte or larger, the "ieof" would not have appeared. In that case,
1151 an ICAP server MAY reply with 100-Continue, a modified response, or
1152 204 No Content.)
1153
1154 In another example, if the preview is 1024 bytes and the origin
1155 response is 1024 bytes in two chunks, then the encapsulation would
1156 appear as follows:
1157
1158 200\r\n
1159 &lt;512 bytes of data&gt;\r\n
1160 200\r\n
1161 &lt;512 bytes of data&gt;\r\n
1162 0; ieof\r\n\r\n
1163
1164 &lt;204 or modified response&gt; (100 Continue disallowed due to ieof)
1165
1166 If the preview is 1024 bytes and the origin response is 1025 bytes
1167 (and the ICAP server responds with 100-continue), then these chunks
1168 would appear on the wire:
1169
1170
1171
1172 <span class="grey">Elson &amp; Cerpa Informational [Page 21]</span></pre>
1173 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-22" ></span>
1174 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1175
1176
1177 200\r\n
1178 &lt;512 bytes of data&gt;\r\n
1179 200\r\n
1180 &lt;512 bytes of data&gt;\r\n
1181 0\r\n
1182
1183 &lt;100 Continue Message&gt;
1184
1185 1\r\n
1186 &lt;1 byte of data&gt;\r\n
1187 0\r\n\r\n &lt;no ieof because we are no longer in preview mode&gt;
1188
1189 Once the ICAP server receives the eof indicator, it finishes reading
1190 the current chunk stream.
1191
1192 Note that when offering a Preview, the ICAP client is committing to
1193 temporarily buffer the previewed portion of the message so that it
1194 can honor a "204 No Content" response. The remainder of the message
1195 is not necessarily buffered; it might be pipelined directly from
1196 another source to the ICAP server after a 100-Continue.
1197
1198 <span class="h3"><a class="selflink" id="section-4.6" href="#section-4.6">4.6</a> "204 No Content" Responses outside of Previews</span>
1199
1200 An ICAP client MAY choose to honor "204 No Content" responses for an
1201 entire message. This is the decision of the client because it
1202 imposes a burden on the client of buffering the entire message.
1203
1204 An ICAP client MAY include "Allow: 204" in its request headers,
1205 indicating that the server MAY reply to the message with a "204 No
1206 Content" response if the object does not need modification.
1207
1208 If an ICAP server receives a request that does not have "Allow: 204",
1209 it MUST NOT reply with a 204. In this case, an ICAP server MUST
1210 return the entire message back to the client, even though it is
1211 identical to the message it received.
1212
1213 The ONLY EXCEPTION to this rule is in the case of a message preview,
1214 as described in the previous section. If this is the case, an ICAP
1215 server can respond with a 204 No Content message in response to a
1216 message preview EVEN if the original request did not have the "Allow:
1217 204" header.
1218
1219 <span class="h3"><a class="selflink" id="section-4.7" href="#section-4.7">4.7</a> ISTag Response Header</span>
1220
1221 The ISTag ("ICAP Service Tag") response-header field provides a way
1222 for ICAP servers to send a service-specific "cookie" to ICAP clients
1223 that represents a service's current state. It is a 32-byte-maximum
1224 alphanumeric string of data (not including the null character) that
1225
1226
1227
1228 <span class="grey">Elson &amp; Cerpa Informational [Page 22]</span></pre>
1229 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-23" ></span>
1230 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1231
1232
1233 may, for example, be a representation of the software version or
1234 configuration of a service. An ISTag validates that previous ICAP
1235 server responses can still be considered fresh by an ICAP client that
1236 may be caching them. If a change on the ICAP server invalidates
1237 previous responses, the ICAP server can invalidate portions of the
1238 ICAP client's cache by changing its ISTag. The ISTag MUST be
1239 included in every ICAP response from an ICAP server.
1240
1241 For example, consider a virus-scanning ICAP service. The ISTag might
1242 be a combination of the virus scanner's software version and the
1243 release number of its virus signature database. When the database is
1244 updated, the ISTag can be changed to invalidate all previous
1245 responses that had been certified as "clean" and cached with the old
1246 ISTag.
1247
1248 ISTag is similar, but not identical, to the HTTP ETag. While an ETag
1249 is a validator for a particular entity (object), an ISTag validates
1250 all entities generated by a particular service (URI). A change in
1251 the ISTag invalidates all the other entities provided a service with
1252 the old ISTag, not just the entity whose response contained the
1253 updated ISTag.
1254
1255 The syntax of an ISTag is simply:
1256 ISTag = "ISTag: " quoted-string
1257
1258 In this document we use the quoted-string definition defined in
1259 section 2.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
1260
1261 For example:
1262 ISTag: "874900-1994-1c02798"
1263
1264 <span class="h3"><a class="selflink" id="section-4.8" href="#section-4.8">4.8</a> Request Modification Mode</span>
1265
1266 In this method, described in <a href="#section-3.1">Section 3.1</a>, an ICAP client sends an
1267 HTTP request to an ICAP server. The ICAP server returns a modified
1268 version of the request, an HTTP response, or (if the client indicates
1269 it supports 204 responses) an indication that no modification is
1270 required.
1271
1272 <span class="h4"><a class="selflink" id="section-4.8.1" href="#section-4.8.1">4.8.1</a> Request</span>
1273
1274 In REQMOD mode, the ICAP request MUST contain an encapsulated HTTP
1275 request. The headers and body (if any) MUST both be encapsulated,
1276 except that hop-by-hop headers are not encapsulated.
1277
1278
1279
1280
1281
1282
1283
1284 <span class="grey">Elson &amp; Cerpa Informational [Page 23]</span></pre>
1285 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-24" ></span>
1286 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1287
1288
1289 <span class="h4"><a class="selflink" id="section-4.8.2" href="#section-4.8.2">4.8.2</a> Response</span>
1290
1291 The response from the ICAP server back to the ICAP client may take
1292 one of four forms:
1293
1294 - An error indication,
1295
1296 - A 204 indicating that the ICAP client's request requires no
1297 adaptation (see <a href="#section-4.6">Section 4.6</a> for limitations of this response),
1298
1299 - An encapsulated, adapted version of the ICAP client's request, or
1300
1301 - An encapsulated HTTP error response. Note that Request
1302 Modification requests may only be satisfied with HTTP responses in
1303 cases when the HTTP response is an error (e.g., 403 Forbidden).
1304
1305 The first line of the response message MUST be a status line as
1306 described in <a href="#section-4.3.3">Section 4.3.3</a>. If the return code is a 2XX, the ICAP
1307 client SHOULD continue its normal execution of the request. If the
1308 ICAP client is a surrogate, this may include serving an object from
1309 its cache or forwarding the modified request to an origin server.
1310 Note it is valid for a 2XX ICAP response to contain an encapsulated
1311 HTTP error response, which in turn should be returned to the
1312 downstream client by the ICAP client.
1313
1314 For other return codes that indicate an error, the ICAP client MAY
1315 (for example) return the error to the downstream client or user,
1316 execute the unadapted request as it arrived from the client, or re-
1317 try the adaptation again.
1318
1319 The modified request headers, if any, MUST be returned to the ICAP
1320 client using appropriate encapsulation as described in <a href="#section-4.4">Section 4.4</a>.
1321
1322 <span class="h4"><a class="selflink" id="section-4.8.3" href="#section-4.8.3">4.8.3</a> Examples</span>
1323
1324 Consider the following example, in which a surrogate receives a
1325 simple GET request from a client. The surrogate, acting as an ICAP
1326 client, then forwards this request to an ICAP server for
1327 modification. The ICAP server modifies the request headers and sends
1328 them back to the ICAP client. Our hypothetical ICAP server will
1329 modify several headers and strip the cookie from the original
1330 request.
1331
1332 In all of our examples, we include the extra meta-data added to the
1333 message due to chunking the encapsulated message body (if any). We
1334 assume that end-of-line terminations, and blank lines, are two-byte
1335 "CRLF" sequences.
1336
1337
1338
1339
1340 <span class="grey">Elson &amp; Cerpa Informational [Page 24]</span></pre>
1341 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-25" ></span>
1342 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1343
1344
1345 ICAP Request Modification Example 1 - ICAP Request
1346 ----------------------------------------------------------------
1347 REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0
1348 Host: icap-server.net
1349 Encapsulated: req-hdr=0, null-body=170
1350
1351 GET / HTTP/1.1
1352 Host: www.origin-server.com
1353 Accept: text/html, text/plain
1354 Accept-Encoding: compress
1355 Cookie: ff39fk3jur@4ii0e02i
1356 If-None-Match: "xyzzy", "r2d2xxxx"
1357
1358 ----------------------------------------------------------------
1359 ICAP Request Modification Example 1 - ICAP Response
1360 ----------------------------------------------------------------
1361 ICAP/1.0 200 OK
1362 Date: Mon, 10 Jan 2000 09:55:21 GMT
1363 Server: ICAP-Server-Software/1.0
1364 Connection: close
1365 ISTag: "W3E4R7U9-L2E4-2"
1366 Encapsulated: req-hdr=0, null-body=231
1367
1368 GET /modified-path HTTP/1.1
1369 Host: www.origin-server.com
1370 Via: 1.0 icap-server.net (ICAP Example ReqMod Service 1.1)
1371 Accept: text/html, text/plain, image/gif
1372 Accept-Encoding: gzip, compress
1373 If-None-Match: "xyzzy", "r2d2xxxx"
1374
1375 ----------------------------------------------------------------
1376
1377 The second example is similar to the first, except that the request
1378 being modified in this case is a POST instead of a GET. Note that
1379 the encapsulated Content-Length argument has been modified to reflect
1380 the modified body of the POST message. The outer ICAP message does
1381 not need a Content-Length header because it uses chunking (not
1382 shown).
1383
1384 In this second example, the Encapsulated header shows the division
1385 between the forwarded header and forwarded body, for both the request
1386 and the response.
1387
1388 ICAP Request Modification Example 2 - ICAP Request
1389 ----------------------------------------------------------------
1390 REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0
1391 Host: icap-server.net
1392 Encapsulated: req-hdr=0, req-body=147
1393
1394
1395
1396 <span class="grey">Elson &amp; Cerpa Informational [Page 25]</span></pre>
1397 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-26" ></span>
1398 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1399
1400
1401 POST /origin-resource/form.pl HTTP/1.1
1402 Host: www.origin-server.com
1403 Accept: text/html, text/plain
1404 Accept-Encoding: compress
1405 Pragma: no-cache
1406
1407 1e
1408 I am posting this information.
1409 0
1410
1411 ----------------------------------------------------------------
1412 ICAP Request Modification Example 2 - ICAP Response
1413 ----------------------------------------------------------------
1414 ICAP/1.0 200 OK
1415 Date: Mon, 10 Jan 2000 09:55:21 GMT
1416 Server: ICAP-Server-Software/1.0
1417 Connection: close
1418 ISTag: "W3E4R7U9-L2E4-2"
1419 Encapsulated: req-hdr=0, req-body=244
1420
1421 POST /origin-resource/form.pl HTTP/1.1
1422 Host: www.origin-server.com
1423 Via: 1.0 icap-server.net (ICAP Example ReqMod Service 1.1)
1424 Accept: text/html, text/plain, image/gif
1425 Accept-Encoding: gzip, compress
1426 Pragma: no-cache
1427 Content-Length: 45
1428
1429 2d
1430 I am posting this information. ICAP powered!
1431 0
1432
1433 ----------------------------------------------------------------
1434 Finally, this third example shows an ICAP server returning an error
1435 response when it receives a Request Modification request.
1436
1437 ICAP Request Modification Example 3 - ICAP Request
1438 ----------------------------------------------------------------
1439 REQMOD icap://icap-server.net/content-filter ICAP/1.0
1440 Host: icap-server.net
1441 Encapsulated: req-hdr=0, null-body=119
1442
1443 GET /naughty-content HTTP/1.1
1444 Host: www.naughty-site.com
1445 Accept: text/html, text/plain
1446 Accept-Encoding: compress
1447
1448 ----------------------------------------------------------------
1449
1450
1451
1452 <span class="grey">Elson &amp; Cerpa Informational [Page 26]</span></pre>
1453 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-27" ></span>
1454 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1455
1456
1457 ICAP Request Modification Example 3 - ICAP Response
1458 ----------------------------------------------------------------
1459 ICAP/1.0 200 OK
1460 Date: Mon, 10 Jan 2000 09:55:21 GMT
1461 Server: ICAP-Server-Software/1.0
1462 Connection: close
1463 ISTag: "W3E4R7U9-L2E4-2"
1464 Encapsulated: res-hdr=0, res-body=213
1465
1466 HTTP/1.1 403 Forbidden
1467 Date: Wed, 08 Nov 2000 16:02:10 GMT
1468 Server: Apache/1.3.12 (Unix)
1469 Last-Modified: Thu, 02 Nov 2000 13:51:37 GMT
1470 ETag: "63600-1989-3a017169"
1471 Content-Length: 58
1472 Content-Type: text/html
1473
1474 3a
1475 Sorry, you are not allowed to access that naughty content.
1476 0
1477
1478 ----------------------------------------------------------------
1479
1480 <span class="h3"><a class="selflink" id="section-4.9" href="#section-4.9">4.9</a> Response Modification Mode</span>
1481
1482 In this method, described in <a href="#section-3.2">Section 3.2</a>, an ICAP client sends an
1483 origin server's HTTP response to an ICAP server, and (if available)
1484 the original client request that caused that response. Similar to
1485 Request Modification method, the response from the ICAP server can be
1486 an adapted HTTP response, an error, or a 204 response code indicating
1487 that no adaptation is required.
1488
1489 <span class="h4"><a class="selflink" id="section-4.9.1" href="#section-4.9.1">4.9.1</a> Request</span>
1490
1491 Using encapsulation described in <a href="#section-4.4">Section 4.4</a>, the header and body of
1492 the HTTP response to be modified MUST be included in the ICAP body.
1493 If available, the header of the original client request SHOULD also
1494 be included. As with the other method, the hop-by-hop headers of the
1495 encapsulated messages MUST NOT be forwarded. The Encapsulated header
1496 MUST indicate the byte-offsets of the beginning of each of these four
1497 parts.
1498
1499 <span class="h4"><a class="selflink" id="section-4.9.2" href="#section-4.9.2">4.9.2</a> Response</span>
1500
1501 The response from the ICAP server looks just like a reply in the
1502 Request Modification method (<a href="#section-4.8">Section 4.8</a>); that is,
1503
1504 - An error indication,
1505
1506
1507
1508 <span class="grey">Elson &amp; Cerpa Informational [Page 27]</span></pre>
1509 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-28" ></span>
1510 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1511
1512
1513 - An encapsulated and potentially modified HTTP response header and
1514 response body, or
1515
1516 - An HTTP response 204 indicating that the ICAP client's request
1517 requires no adaptation.
1518
1519 The first line of the response message MUST be a status line as
1520 described in <a href="#section-4.3.3">Section 4.3.3</a>. If the return code is a 2XX, the ICAP
1521 client SHOULD continue its normal execution of the response. The
1522 ICAP client MAY re-examine the headers in the response's message
1523 headers in order to make further decisions about the response (e.g.,
1524 its cachability).
1525
1526 For other return codes that indicate an error, the ICAP client SHOULD
1527 NOT return these directly to downstream client, since these errors
1528 only make sense in the ICAP client/server transaction.
1529
1530 The modified response headers, if any, MUST be returned to the ICAP
1531 client using appropriate encapsulation as described in <a href="#section-4.4">Section 4.4</a>.
1532
1533 <span class="h4"><a class="selflink" id="section-4.9.3" href="#section-4.9.3">4.9.3</a> Examples</span>
1534
1535 In Example 4, an ICAP client is requesting modification of an entity
1536 that was returned as a result of a client GET. The original client
1537 GET was to an origin server at "www.origin-server.com"; the ICAP
1538 server is at "icap.example.org".
1539
1540 ICAP Response Modification Example 4 - ICAP Request
1541 ----------------------------------------------------------------
1542 RESPMOD icap://icap.example.org/satisf ICAP/1.0
1543 Host: icap.example.org
1544 Encapsulated: req-hdr=0, res-hdr=137, res-body=296
1545
1546 GET /origin-resource HTTP/1.1
1547 Host: www.origin-server.com
1548 Accept: text/html, text/plain, image/gif
1549 Accept-Encoding: gzip, compress
1550
1551 HTTP/1.1 200 OK
1552 Date: Mon, 10 Jan 2000 09:52:22 GMT
1553 Server: Apache/1.3.6 (Unix)
1554 ETag: "63840-1ab7-378d415b"
1555 Content-Type: text/html
1556 Content-Length: 51
1557
1558
1559
1560
1561
1562
1563
1564 <span class="grey">Elson &amp; Cerpa Informational [Page 28]</span></pre>
1565 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-29" ></span>
1566 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1567
1568
1569 33
1570 This is data that was returned by an origin server.
1571 0
1572
1573 ----------------------------------------------------------------
1574
1575 ICAP Response Modification Example 4 - ICAP Response
1576 ----------------------------------------------------------------
1577 ICAP/1.0 200 OK
1578 Date: Mon, 10 Jan 2000 09:55:21 GMT
1579 Server: ICAP-Server-Software/1.0
1580 Connection: close
1581 ISTag: "W3E4R7U9-L2E4-2"
1582 Encapsulated: res-hdr=0, res-body=222
1583
1584 HTTP/1.1 200 OK
1585 Date: Mon, 10 Jan 2000 09:55:21 GMT
1586 Via: 1.0 icap.example.org (ICAP Example RespMod Service 1.1)
1587 Server: Apache/1.3.6 (Unix)
1588 ETag: "63840-1ab7-378d415b"
1589 Content-Type: text/html
1590 Content-Length: 92
1591
1592 5c
1593 This is data that was returned by an origin server, but with
1594 value added by an ICAP server.
1595 0
1596
1597 ----------------------------------------------------------------
1598
1599 <span class="h3"><a class="selflink" id="section-4.10" href="#section-4.10">4.10</a> OPTIONS Method</span>
1600
1601 The ICAP "OPTIONS" method is used by the ICAP client to retrieve
1602 configuration information from the ICAP server. In this method, the
1603 ICAP client sends a request addressed to a specific ICAP resource and
1604 receives back a response with options that are specific to the
1605 service named by the URI. All OPTIONS requests MAY also return
1606 options that are global to the server (i.e., apply to all services).
1607
1608 <span class="h4"><a class="selflink" id="section-4.10.1" href="#section-4.10.1">4.10.1</a> OPTIONS Request</span>
1609
1610 The OPTIONS method consists of a request-line, as described in
1611 <a href="#section-4.3.2">Section 4.3.2</a>, such as the following example:
1612
1613 OPTIONS icap://icap.server.net/sample-service ICAP/1.0 User-Agent:
1614 ICAP-client-XYZ/1.001
1615
1616
1617
1618
1619
1620 <span class="grey">Elson &amp; Cerpa Informational [Page 29]</span></pre>
1621 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-30" ></span>
1622 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1623
1624
1625 Other headers are also allowed as described in <a href="#section-4.3.1">Section 4.3.1</a> and
1626 <a href="#section-4.3.2">Section 4.3.2</a> (for example, Host).
1627
1628 <span class="h4"><a class="selflink" id="section-4.10.2" href="#section-4.10.2">4.10.2</a> OPTIONS Response</span>
1629
1630 The OPTIONS response consists of a status line as described in
1631 <a href="#section-4.3.3">section 4.3.3</a> followed by a series of header field names-value pairs
1632 optionally followed by an opt-body. Multiple values in the value
1633 field MUST be separated by commas. If an opt-body is present in the
1634 OPTIONS response, the Opt-body-type header describes the format of
1635 the opt-body.
1636
1637 The OPTIONS headers supported in this version of the protocol are:
1638
1639 -- Methods:
1640
1641 The method that is supported by this service. This header MUST be
1642 included in the OPTIONS response. The OPTIONS method MUST NOT be
1643 in the Methods' list since it MUST be supported by all the ICAP
1644 server implementations. Each service should have a distinct URI
1645 and support only one method in addition to OPTIONS (see <a href="#section-6.4">Section</a>
1646 <a href="#section-6.4">6.4</a>).
1647
1648 For example:
1649 Methods: RESPMOD
1650
1651 -- Service:
1652
1653 A text description of the vendor and product name. This header
1654 MAY be included in the OPTIONS response.
1655
1656 For example:
1657 Service: XYZ Technology Server 1.0
1658
1659 -- ISTag:
1660
1661 See <a href="#section-4.7">section 4.7</a> for details. This header MUST be included in the
1662 OPTIONS response.
1663
1664 For example:
1665 ISTag: "5BDEEEA9-12E4-2"
1666
1667 -- Encapsulated:
1668
1669 This header MUST be included in the OPTIONS response; see <a href="#section-4.4">Section</a>
1670 <a href="#section-4.4">4.4</a>.
1671
1672
1673
1674
1675
1676 <span class="grey">Elson &amp; Cerpa Informational [Page 30]</span></pre>
1677 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-31" ></span>
1678 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1679
1680
1681 For example:
1682 Encapsulated: opt-body=0
1683
1684 -- Opt-body-type:
1685
1686 A token identifying the format of the opt-body. (Valid opt-body
1687 types are not defined by ICAP.) This header MUST be included in
1688 the OPTIONS response ONLY if an opt-body type is present.
1689
1690 For example:
1691 Opt-body-type: XML-Policy-Table-1.0
1692
1693 -- Max-Connections:
1694
1695 The maximum number of ICAP connections the server is able to
1696 support. This header MAY be included in the OPTIONS response.
1697
1698 For example:
1699 Max-Connections: 1500
1700
1701 -- Options-TTL:
1702
1703 The time (in seconds) for which this OPTIONS response is valid.
1704 If none is specified, the OPTIONS response does not expire. This
1705 header MAY be included in the OPTIONS response. The ICAP client
1706 MAY reissue an OPTIONS request once the Options-TTL expires.
1707
1708 For example:
1709 Options-TTL: 3600
1710
1711 -- Date:
1712
1713 The server's clock, specified as an <a href="./rfc1123">RFC 1123</a> compliant date/time
1714 string. This header MAY be included in the OPTIONS response.
1715
1716 For example:
1717 Date: Fri, 15 Jun 2001 04:33:55 GMT
1718
1719 -- Service-ID:
1720
1721 A short label identifying the ICAP service. It MAY be used in
1722 attribute header names. This header MAY be included in the
1723 OPTIONS response.
1724
1725 For example:
1726 Service-ID: xyztech
1727
1728
1729
1730
1731
1732 <span class="grey">Elson &amp; Cerpa Informational [Page 31]</span></pre>
1733 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-32" ></span>
1734 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1735
1736
1737 -- Allow:
1738
1739 A directive declaring a list of optional ICAP features that this
1740 server has implemented. This header MAY be included in the
1741 OPTIONS response. In this document we define the value "204" to
1742 indicate that the ICAP server supports a 204 response.
1743
1744 For example:
1745 Allow: 204
1746
1747 -- Preview:
1748
1749 The number of bytes to be sent by the ICAP client during a
1750 preview. This header MAY be included in the OPTIONS response.
1751
1752 For example:
1753 Preview: 1024
1754
1755 -- Transfer-Preview:
1756
1757 A list of file extensions that should be previewed to the ICAP
1758 server before sending them in their entirety. This header MAY be
1759 included in the OPTIONS response. Multiple file extensions values
1760 should be separated by commas. The wildcard value "*" specifies
1761 the default behavior for all the file extensions not specified in
1762 any other Transfer-* header (see below).
1763
1764 For example:
1765 Transfer-Preview: *
1766
1767 -- Transfer-Ignore:
1768
1769 A list of file extensions that should NOT be sent to the ICAP
1770 server. This header MAY be included in the OPTIONS response.
1771 Multiple file extensions should be separated by commas.
1772
1773 For example:
1774 Transfer-Ignore: html
1775
1776 -- Transfer-Complete:
1777
1778 A list of file extensions that should be sent in their entirety
1779 (without preview) to the ICAP server. This header MAY be included
1780 in the OPTIONS response. Multiple file extensions values should
1781 be separated by commas.
1782
1783 For example:
1784 Transfer-Complete: asp, bat, exe, com, ole
1785
1786
1787
1788 <span class="grey">Elson &amp; Cerpa Informational [Page 32]</span></pre>
1789 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-33" ></span>
1790 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1791
1792
1793 Note: If any of Transfer-* are sent, exactly one of them MUST contain
1794 the wildcard value "*" to specify the default. If no Transfer-* are
1795 sent, all responses will be sent in their entirety (without Preview).
1796
1797 <span class="h4"><a class="selflink" id="section-4.10.3" href="#section-4.10.3">4.10.3</a> OPTIONS Examples</span>
1798
1799 In example 5, an ICAP Client sends an OPTIONS Request to an ICAP
1800 Service named icap.server.net/sample-service in order to get
1801 configuration information for the service provided.
1802
1803 ICAP OPTIONS Example 5 - ICAP OPTIONS Request
1804 ----------------------------------------------------------------
1805 OPTIONS icap://icap.server.net/sample-service ICAP/1.0
1806 Host: icap.server.net
1807 User-Agent: BazookaDotCom-ICAP-Client-Library/2.3
1808
1809 ----------------------------------------------------------------
1810
1811 ICAP OPTIONS Example 5 - ICAP OPTIONS Response
1812 ----------------------------------------------------------------
1813 ICAP/1.0 200 OK
1814 Date: Mon, 10 Jan 2000 09:55:21 GMT
1815 Methods: RESPMOD
1816 Service: FOO Tech Server 1.0
1817 ISTag: "W3E4R7U9-L2E4-2"
1818 Encapsulated: null-body=0
1819 Max-Connections: 1000
1820 Options-TTL: 7200
1821 Allow: 204
1822 Preview: 2048
1823 Transfer-Complete: asp, bat, exe, com
1824 Transfer-Ignore: html
1825 Transfer-Preview: *
1826
1827 ----------------------------------------------------------------
1828
1829 <span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Caching</span>
1830
1831 ICAP servers' responses MAY be cached by ICAP clients, just as any
1832 other surrogate might cache HTTP responses. Similar to HTTP, ICAP
1833 clients MAY always store a successful response (see sections <a href="#section-4.8.2">4.8.2</a>
1834 and 4.9.2) as a cache entry, and MAY return it without validation if
1835 it is fresh. ICAP servers use the caching directives described in
1836 HTTP/1.1 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>].
1837
1838 In Request Modification mode, the ICAP server MAY include caching
1839 directives in the ICAP header section of the ICAP response (NOT in
1840 the encapsulated HTTP request of the ICAP message body). In Response
1841
1842
1843
1844 <span class="grey">Elson &amp; Cerpa Informational [Page 33]</span></pre>
1845 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-34" ></span>
1846 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1847
1848
1849 Modification mode, the ICAP server MAY add or modify the HTTP caching
1850 directives located in the encapsulated HTTP response (NOT in the ICAP
1851 header section). Consequently, the ICAP client SHOULD look for
1852 caching directives in the ICAP headers in case of REQMOD, and in the
1853 encapsulated HTTP response in case of RESPMOD.
1854
1855 In cases where an ICAP server returns a modified version of an object
1856 created by an origin server, such as in Response Modification mode,
1857 the expiration of the ICAP-modified object MUST NOT be longer than
1858 that of the origin object. In other words, ICAP servers MUST NOT
1859 extend the lifetime of origin server objects, but MAY shorten it.
1860
1861 In cases where the ICAP server is the authoritative source of an ICAP
1862 response, such as in Request Modification mode, the ICAP server is
1863 not restricted in its expiration policy.
1864
1865 Note that the ISTag response-header may also be used to providing
1866 caching hints to clients; see <a href="#section-4.7">Section 4.7</a>.
1867
1868 <span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. Implementation Notes</span>
1869
1870 <span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a> Vectoring Points</span>
1871
1872 The definition of the ICAP protocol itself only describes two
1873 different adaptation channels: modification (and satisfaction) of
1874 requests, and modifications of replies. However, an ICAP client
1875 implementation is likely to actually distinguish among four different
1876 classes of adaptation:
1877
1878 1. Adaptation of client requests. This is adaptation done every
1879 time a request arrives from a client. This is adaptation done
1880 when a request is "on its way into the cache". Factors such as
1881 the state of the objects currently cached will determine whether
1882 or not this request actually gets forwarded to an origin server
1883 (instead of, say, getting served off the cache's disk). An
1884 example of this type of adaptation would be special access
1885 control or authentication services that must be performed on a
1886 per-client basis.
1887
1888 2. Adaptation of requests on their way to an origin server.
1889 Although this type of adaptation is also an adaptation of
1890 requests similar to (1), it describes requests that are "on their
1891 way out of the cache"; i.e., if a request actually requires that
1892 an origin server be contacted. These adaptation requests are not
1893 necessarily specific to particular clients. An example would be
1894 addition of "Accept:" headers for special devices; these
1895 adaptations can potentially apply to many clients.
1896
1897
1898
1899
1900 <span class="grey">Elson &amp; Cerpa Informational [Page 34]</span></pre>
1901 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-35" ></span>
1902 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1903
1904
1905 3. Adaptations of responses coming from an origin server. This is
1906 the adaptation of an object "on its way into the cache". In
1907 other words, this is adaptation that a surrogate might want to
1908 perform on an object before caching it. The adapted object may
1909 subsequently served to many clients. An example of this type of
1910 adaptation is virus checking: a surrogate will want to check an
1911 incoming origin reply for viruses once, before allowing it into
1912 the cache -- not every time the cached object is served to a
1913 client.
1914
1915 Adaptation of responses coming from the surrogate, heading back
1916 to the client. Although this type of adaptation, like (3), is
1917 the adaptation of a response, it is client-specific. Client
1918 reply adaptation is adaptation that is required every time an
1919 object is served to a client, even if all the replies come from
1920 the same cached object off of disk. Ad insertion is a common
1921 form of this kind of adaptation; e.g., if a popular (cached)
1922 object that rarely changes needs a different ad inserted into it
1923 every time it is served off disk to a client. Note that the
1924 relationship between adaptations of type (3) and (4) is analogous
1925 to the relationship between types (2) and (1).
1926
1927 Although the distinction among these four adaptation points is
1928 critical for ICAP client implementations, the distinction is not
1929 significant for the ICAP protocol itself. From the point of view of
1930 an ICAP server, a request is a request -- the ICAP server doesn't
1931 care what policy led the ICAP client to generate the request. We
1932 therefore did not make these four channels explicit in ICAP for
1933 simplicity.
1934
1935 <span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a> Application Level Errors</span>
1936
1937 <a href="#section-4">Section 4</a> described "on the wire" protocol errors that MUST be
1938 standardized across implementations to ensure interoperability. In
1939 this section, we describe errors that are communicated between ICAP
1940 software and the clients and servers on which they are implemented.
1941 Although such errors are implementation dependent and do not
1942 necessarily need to be standardized because they are "within the
1943 box", they are presented here as advice to future implementors based
1944 on past implementation experience.
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956 <span class="grey">Elson &amp; Cerpa Informational [Page 35]</span></pre>
1957 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-36" ></span>
1958 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
1959
1960
1961 Error name Value
1962 ====================================================
1963 ICAP_CANT_CONNECT 1000
1964 ICAP_SERVER_RESPONSE_CLOSE 1001
1965 ICAP_SERVER_RESPONSE_RESET 1002
1966 ICAP_SERVER_UNKNOWN_CODE 1003
1967 ICAP_SERVER_UNEXPECTED_CLOSE_204 1004
1968 ICAP_SERVER_UNEXPECTED_CLOSE 1005
1969
1970 1000 ICAP_CANT_CONNECT:
1971 "Cannot connect to ICAP server".
1972
1973 The ICAP server is not connected on the socket. Maybe the ICAP
1974 server is dead or it is not connected on the socket.
1975
1976 1001 ICAP_SERVER_RESPONSE_CLOSE:
1977 "ICAP Server closed connection while reading response".
1978
1979 The ICAP server TCP-shutdowns the connection before the ICAP
1980 client can send all the body data.
1981
1982 1002 ICAP_SERVER_RESPONSE_RESET:
1983 "ICAP Server reset connection while reading response".
1984
1985 The ICAP server TCP-reset the connection before the ICAP client
1986 can send all the body data.
1987
1988 1003 ICAP_SERVER_UNKNOWN_CODE:
1989 "ICAP Server sent unknown response code".
1990
1991 An unknown ICAP response code (see <a href="#section-4">Section 4</a>.x) was received by
1992 the ICAP client.
1993
1994 1004 ICAP_SERVER_UNEXPECTED_CLOSE_204:
1995 "ICAP Server closed connection on 204 without 'Connection: close'
1996 header".
1997
1998 An ICAP server MUST send the "Connection: close" header if
1999 intends to close after the current transaction.
2000
2001 1005 ICAP_SERVER_UNEXPECTED_CLOSE:
2002 "ICAP Server closed connection as ICAP client wrote body
2003 preview".
2004
2005
2006
2007
2008
2009
2010
2011
2012 <span class="grey">Elson &amp; Cerpa Informational [Page 36]</span></pre>
2013 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-37" ></span>
2014 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2015
2016
2017 <span class="h3"><a class="selflink" id="section-6.3" href="#section-6.3">6.3</a> Use of Chunked Transfer-Encoding</span>
2018
2019 For simplicity, ICAP messages MUST use the "chunked" transfer-
2020 encoding within the encapsulated body section as defined in HTTP/1.1
2021 [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]. This requires that ICAP client implementations convert incoming
2022 objects "on the fly" to chunked from whatever transfer-encoding on
2023 which they arrive. However, the transformation is simple:
2024
2025 - For objects arriving using "Content-Length" headers, one big chunk
2026 can be created of the same size as indicated in the Content-Length
2027 header.
2028
2029 - For objects arriving using a TCP close to signal the end of the
2030 object, each incoming group of bytes read from the OS can be
2031 converted into a chunk (by writing the length of the bytes read,
2032 followed by the bytes themselves)
2033
2034 - For objects arriving using chunked encoding, they can be
2035 retransmitted as is (without re-chunking).
2036
2037 <span class="h3"><a class="selflink" id="section-6.4" href="#section-6.4">6.4</a> Distinct URIs for Distinct Services</span>
2038
2039 ICAP servers SHOULD assign unique URIs to each service they provide,
2040 even if such services might theoretically be differentiated based on
2041 their method. In other words, a REQMOD and RESPMOD service should
2042 never have the same URI, even if they do something that is
2043 conceptually the same.
2044
2045 This situation in ICAP is similar to that found in HTTP where it
2046 might, in theory, be possible to perform a GET or a POST to the same
2047 URI and expect two different results. This kind of overloading of
2048 URIs only causes confusion and should be avoided.
2049
2050 <span class="h2"><a class="selflink" id="section-7" href="#section-7">7</a>. Security Considerations</span>
2051
2052 <span class="h3"><a class="selflink" id="section-7.1" href="#section-7.1">7.1</a> Authentication</span>
2053
2054 Authentication in ICAP is very similar to proxy authentication in
2055 HTTP as specified in <a href="./rfc2617">RFC 2617</a>. Specifically, the following rules
2056 apply:
2057
2058 - WWW-Authenticate challenges and responses are for end-to-end
2059 authentication between a client (user) and an origin server. As
2060 any proxy, ICAP clients and ICAP servers MUST forward these
2061 headers without modification.
2062
2063
2064
2065
2066
2067
2068 <span class="grey">Elson &amp; Cerpa Informational [Page 37]</span></pre>
2069 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-38" ></span>
2070 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2071
2072
2073 - If authentication is required between an ICAP client and ICAP
2074 server, hop-by-hop Proxy Authentication as described in <a href="./rfc2617">RFC 2617</a>
2075 MUST be used.
2076
2077 There are potential applications where a user (as opposed to ICAP
2078 client) might have rights to access an ICAP service. In this version
2079 of the protocol, we assume that ICAP clients and ICAP servers are
2080 under the same administrative domain, and contained in a single trust
2081 domain. Therefore, in these cases, we assume that it is sufficient
2082 for users to authenticate themselves to the ICAP client (which is a
2083 surrogate from the point of view from the user). This type of
2084 authentication will also be Proxy Authentication as described in <a href="./rfc2617">RFC</a>
2085 <a href="./rfc2617">2617</a>.
2086
2087 This standard explicitly excludes any method for a user to
2088 authenticate directly to an ICAP server; the ICAP client MUST be
2089 involved as described above.
2090
2091 <span class="h3"><a class="selflink" id="section-7.2" href="#section-7.2">7.2</a> Encryption</span>
2092
2093 Users of ICAP should note well that ICAP messages are not encrypted
2094 for transit by default. In the absence of some other form of
2095 encryption at the link or network layers, eavesdroppers may be able
2096 to record the unencrypted transactions between ICAP clients and
2097 servers. As described in <a href="#section-4.3.1">Section 4.3.1</a>, the Upgrade header MAY be
2098 used to negotiate transport-layer security for an ICAP connection
2099 [<a href="#ref-5" title="&quot;Upgrading to TLS Within HTTP/1.1&quot;">5</a>].
2100
2101 Note also that end-to-end encryption between a client and origin
2102 server is likely to preclude the use of value-added services by
2103 intermediaries such as surrogates. An ICAP server that is unable to
2104 decrypt a client's messages will, of course, be unable to perform any
2105 transformations on it.
2106
2107 <span class="h3"><a class="selflink" id="section-7.3" href="#section-7.3">7.3</a> Service Validation</span>
2108
2109 Normal HTTP surrogates, when operating correctly, should not affect
2110 the end-to-end semantics of messages that pass through them. This
2111 forms a well-defined criterion to validate that a surrogate is
2112 working correctly: a message should look the same before the
2113 surrogate as it does after the surrogate.
2114
2115 In contrast, ICAP is meant to cause changes in the semantics of
2116 messages on their way from origin servers to users. The criteria for
2117 a correctly operating surrogate are no longer as easy to define.
2118 This will make validation of ICAP services significantly more
2119 difficult. Incorrect adaptations may lead to security
2120 vulnerabilities that were not present in the unadapted content.
2121
2122
2123
2124 <span class="grey">Elson &amp; Cerpa Informational [Page 38]</span></pre>
2125 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-39" ></span>
2126 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2127
2128
2129 <span class="h2"><a class="selflink" id="section-8" href="#section-8">8</a>. Motivations and Design Alternatives</span>
2130
2131 This section describes some of our design decisions in more detail,
2132 and describes the ideas and motivations behind them. This section
2133 does not define protocol requirements, but hopefully sheds light on
2134 the requirements defined in previous sections. Nothing in this
2135 section carries the "force of law" or is part of the formal protocol
2136 specification.
2137
2138 In general, our guiding principle was to make ICAP the simplest
2139 possible protocol that would do the job, and no simpler. Some
2140 features were rejected where alternative (non-protocol-based)
2141 solutions could be found. In addition, we have intentionally left a
2142 number of issues at the discretion of the implementor, where we
2143 believe that doing so does not compromise interoperability.
2144
2145 <span class="h3"><a class="selflink" id="section-8.1" href="#section-8.1">8.1</a> To Be HTTP, or Not To Be</span>
2146
2147 ICAP was initially designed as an application-layer protocol built to
2148 run on top of HTTP. This was desirable for a number of reasons.
2149 HTTP is well-understood in the community and has enjoyed significant
2150 investments in software infrastructure (clients, servers, parsers,
2151 etc.). Our initial designs focused on leveraging that existing work;
2152 we hoped that it would be possible to implement ICAP services simply,
2153 using CGI scripts run by existing web servers.
2154
2155 However, the devil (as always) proved to be in the details. Certain
2156 features that we considered important were impossible to implement
2157 with HTTP. For example, ICAP clients can stop and wait for a "100
2158 Continue" message in the midst of a message-body; HTTP clients may
2159 only wait between the header and body. In addition, certain
2160 transformations of HTTP messages by surrogates are legal (and
2161 harmless for HTTP), but caused problems with ICAP's "header-in-
2162 header" encapsulation and other features.
2163
2164 Ultimately, we decided that the tangle of workarounds required to fit
2165 ICAP into HTTP was more complex and confusing than moving away from
2166 HTTP and defining a new (but similar) protocol.
2167
2168 <span class="h3"><a class="selflink" id="section-8.2" href="#section-8.2">8.2</a> Mandatory Use of Chunking</span>
2169
2170 Chunking is mandatory in ICAP encapsulated bodies for three reasons.
2171 First, efficiency is important, and the chunked encoding allows both
2172 the client and server to keep the transport-layer connection open for
2173 later reuse. Second, ICAP servers (and their developers) should be
2174 encouraged to produce "incremental" responses where possible, to
2175 reduce the latency perceived by users. Chunked encoding is the only
2176 way to support this type of implementation. Finally, by
2177
2178
2179
2180 <span class="grey">Elson &amp; Cerpa Informational [Page 39]</span></pre>
2181 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-40" ></span>
2182 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2183
2184
2185 standardizing on a single encapsulation mechanism, we avoid the
2186 complexity that would be required in client and server software to
2187 support multiple mechanisms. This simplifies ICAP, particularly in
2188 the "body preview" feature described in <a href="#section-4.5">Section 4.5</a>.
2189
2190 While chunking of encapsulated bodies is mandatory, encapsulated
2191 headers are not chunked. There are two reasons for this decision.
2192 First, in cases where a chunked HTTP message body is being
2193 encapsulated in an ICAP message, the ICAP client (HTTP server) can
2194 copy it directly from the HTTP client to the ICAP server without un-
2195 chunking and then re-chunking it. Second, many header-parser
2196 implementations have difficulty dealing with headers that come in
2197 multiple chunks. Earlier drafts of this document mandated that a
2198 chunk boundary not come within a header. For clarity, chunking of
2199 encapsulated headers has simply been disallowed.
2200
2201 <span class="h3"><a class="selflink" id="section-8.3" href="#section-8.3">8.3</a> Use of the null-body directive in the Encapsulated header</span>
2202
2203 There is a disadvantage to not using the chunked transfer-encoding
2204 for encapsulated header part of an ICAP message. Specifically,
2205 parsers do not know in advance how much header data is coming (e.g.,
2206 for buffer allocation). ICAP does not allow chunking in the header
2207 part for reasons described in <a href="#section-8.2">Section 8.2</a>. To compensate, the
2208 "null-body" directive allows the final header's length to be
2209 determined, despite it not being chunked.
2210
2211 <span class="h2"><a class="selflink" id="section-9" href="#section-9">9</a>. References</span>
2212
2213 [<a id="ref-1">1</a>] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource
2214 Identifiers (URI): Generic Syntax and Semantics", <a href="./rfc2396">RFC 2396</a>,
2215 August 1998.
2216
2217 [<a id="ref-2">2</a>] Bradner, S., "Key words for use in RFCs to Indicate Requirement
2218 Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>, March 1997.
2219
2220 [<a id="ref-3">3</a>] Resnick, P., "Internet Message Format", <a href="./rfc2822">RFC 2822</a>, April 2001.
2221
2222 [<a id="ref-4">4</a>] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L.,
2223 Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
2224 HTTP/1.1", <a href="./rfc2616">RFC 2616</a>, June 1999.
2225
2226 [<a id="ref-5">5</a>] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1",
2227 <a href="./rfc2817">RFC 2817</a>, May 2000.
2228
2229
2230
2231
2232
2233
2234
2235
2236 <span class="grey">Elson &amp; Cerpa Informational [Page 40]</span></pre>
2237 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-41" ></span>
2238 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2239
2240
2241 <span class="h2"><a class="selflink" id="section-10" href="#section-10">10</a>. Contributors</span>
2242
2243 ICAP is based on an original idea by John Martin and Peter Danzig.
2244 Many individuals and organizations have contributed to the
2245 development of ICAP, including the following contributors (past and
2246 present):
2247
2248 Lee Duggs
2249 Network Appliance, Inc.
2250 495 East Java Dr.
2251 Sunnyvale, CA 94089 USA
2252
2253 Phone: (408) 822-6000
2254 EMail: [email protected]
2255
2256 Paul Eastham
2257 Network Appliance, Inc.
2258 495 East Java Dr.
2259 Sunnyvale, CA 94089 USA
2260
2261 Phone: (408) 822-6000
2262 EMail: [email protected]
2263
2264 Debbie Futcher
2265 Network Appliance, Inc.
2266 495 East Java Dr.
2267 Sunnyvale, CA 94089 USA
2268
2269 Phone: (408) 822-6000
2270 EMail: [email protected]
2271
2272 Don Gillies
2273 Network Appliance, Inc.
2274 495 East Java Dr.
2275 Sunnyvale, CA 94089 USA
2276
2277 Phone: (408) 822-6000
2278 EMail: [email protected]
2279
2280 Steven La
2281 Network Appliance, Inc.
2282 495 East Java Dr.
2283 Sunnyvale, CA 94089 USA
2284
2285 Phone: (408) 822-6000
2286 EMail: [email protected]
2287
2288
2289
2290
2291
2292 <span class="grey">Elson &amp; Cerpa Informational [Page 41]</span></pre>
2293 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-42" ></span>
2294 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2295
2296
2297 John Martin
2298 Network Appliance, Inc.
2299 495 East Java Dr.
2300 Sunnyvale, CA 94089 USA
2301
2302 Phone: (408) 822-6000
2303 EMail: [email protected]
2304
2305 Jeff Merrick
2306 Network Appliance, Inc.
2307 495 East Java Dr.
2308 Sunnyvale, CA 94089 USA
2309
2310 Phone: (408) 822-6000
2311 EMail: [email protected]
2312
2313 John Schuster
2314 Network Appliance, Inc.
2315 495 East Java Dr.
2316 Sunnyvale, CA 94089 USA
2317
2318 Phone: (408) 822-6000
2319 EMail: [email protected]
2320
2321 Edward Sharp
2322 Network Appliance, Inc.
2323 495 East Java Dr.
2324 Sunnyvale, CA 94089 USA
2325
2326 Phone: (408) 822-6000
2327 EMail: [email protected]
2328
2329 Peter Danzig
2330 Akamai Technologies
2331 1400 Fashion Island Blvd
2332 San Mateo, CA 94404 USA
2333
2334 Phone: (650) 372-5757
2335 EMail: [email protected]
2336
2337 Mark Nottingham
2338 Akamai Technologies
2339 1400 Fashion Island Blvd
2340 San Mateo, CA 94404 USA
2341
2342 Phone: (650) 372-5757
2343 EMail: [email protected]
2344
2345
2346
2347
2348 <span class="grey">Elson &amp; Cerpa Informational [Page 42]</span></pre>
2349 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-43" ></span>
2350 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2351
2352
2353 Nitin Sharma
2354 Akamai Technologies
2355 1400 Fashion Island Blvd
2356 San Mateo, CA 94404 USA
2357
2358 Phone: (650) 372-5757
2359 EMail: [email protected]
2360
2361 Hilarie Orman
2362 Novell, Inc.
2363 122 East 1700 South
2364 Provo, UT 84606 USA
2365
2366 Phone: (801) 861-7021
2367 EMail: [email protected]
2368
2369 Craig Blitz
2370 Novell, Inc.
2371 122 East 1700 South
2372 Provo, UT 84606 USA
2373
2374 Phone: (801) 861-7021
2375 EMail: [email protected]
2376
2377 Gary Tomlinson
2378 Novell, Inc.
2379 122 East 1700 South
2380 Provo, UT 84606 USA
2381
2382 Phone: (801) 861-7021
2383 EMail: [email protected]
2384
2385 Andre Beck
2386 Bell Laboratories / Lucent Technologies
2387 101 Crawfords Corner Road
2388 Holmdel, New Jersey 07733-3030
2389
2390 Phone: (732) 332-5983
2391 EMail: [email protected]
2392
2393 Markus Hofmann
2394 Bell Laboratories / Lucent Technologies
2395 101 Crawfords Corner Road
2396 Holmdel, New Jersey 07733-3030
2397
2398 Phone: (732) 332-5983
2399 EMail: [email protected]
2400
2401
2402
2403
2404 <span class="grey">Elson &amp; Cerpa Informational [Page 43]</span></pre>
2405 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-44" ></span>
2406 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2407
2408
2409 David Bryant
2410 CacheFlow, Inc.
2411 650 Almanor Avenue
2412 Sunnyvale, California 94086
2413
2414 Phone: (888) 462-3568
2415 EMail: [email protected]
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460 <span class="grey">Elson &amp; Cerpa Informational [Page 44]</span></pre>
2461 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-45" ></span>
2462 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2463
2464
2465 Appendix A BNF Grammar for ICAP Messages
2466
2467 This grammar is specified in terms of the augmented Backus-Naur Form
2468 (BNF) similar to that used by the HTTP/1.1 specification (See <a href="#section-2.1">Section</a>
2469 <a href="#section-2.1">2.1</a> of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]). Implementors will need to be familiar with the notation
2470 in order to understand this specification.
2471
2472 Many header values (where noted) have exactly the same grammar and
2473 semantics as in HTTP/1.1. We do not reproduce those grammars here.
2474
2475 ICAP-Version = "ICAP/1.0"
2476
2477 ICAP-Message = Request | Response
2478
2479 Request = Request-Line
2480 *(Request-Header CRLF)
2481 CRLF
2482 [ Request-Body ]
2483
2484 Request-Line = Method SP ICAP_URI SP ICAP-Version CRLF
2485
2486 Method = "REQMOD" ; <a href="#section-4.8">Section 4.8</a>
2487 | "RESPMOD" ; <a href="#section-4.9">Section 4.9</a>
2488 | "OPTIONS" ; <a href="#section-4.10">Section 4.10</a>
2489 | Extension-Method ; <a href="#section-4.3.2">Section 4.3.2</a>
2490
2491 Extension-Method = token
2492
2493 ICAP_URI = Scheme ":" Net_Path [ "?" Query ] ; <a href="#section-4.2">Section 4.2</a>
2494
2495 Scheme = "icap"
2496
2497 Net_Path = "//" Authority [ Abs_Path ]
2498
2499 Authority = [ userinfo "@" ] host [ ":" port ]
2500
2501
2502 Request-Header = Request-Fields ":" [ Generic-Field-Value ]
2503
2504 Request-Fields = Request-Field-Name
2505 | Common-Field-Name
2506
2507 ; Header fields specific to requests
2508 Request-Field-Name = "Authorization" ; <a href="#section-4.3.2">Section 4.3.2</a>
2509 | "Allow" ; <a href="#section-4.3.2">Section 4.3.2</a>
2510 | "From" ; <a href="#section-4.3.2">Section 4.3.2</a>
2511 | "Host" ; <a href="#section-4.3.2">Section 4.3.2</a>
2512 | "Referer" ; <a href="#section-4.3.2">Section 4.3.2</a>
2513
2514
2515
2516 <span class="grey">Elson &amp; Cerpa Informational [Page 45]</span></pre>
2517 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-46" ></span>
2518 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2519
2520
2521 | "User-Agent" ; <a href="#section-4.3.2">Section 4.3.2</a>
2522 | "Preview" ; <a href="#section-4.5">Section 4.5</a>
2523
2524 ; Header fields common to both requests and responses
2525 Common-Field-Name = "Cache-Control" ; <a href="#section-4.3.1">Section 4.3.1</a>
2526 | "Connection" ; <a href="#section-4.3.1">Section 4.3.1</a>
2527 | "Date" ; <a href="#section-4.3.1">Section 4.3.1</a>
2528 | "Expires" ; <a href="#section-4.3.1">Section 4.3.1</a>
2529 | "Pragma" ; <a href="#section-4.3.1">Section 4.3.1</a>
2530 | "Trailer" ; <a href="#section-4.3.1">Section 4.3.1</a>
2531 | "Upgrade" ; <a href="#section-4.3.1">Section 4.3.1</a>
2532 | "Encapsulated" ; <a href="#section-4.4">Section 4.4</a>
2533 | Extension-Field-Name ; <a href="#section-4.3">Section 4.3</a>
2534
2535 Extension-Field-Name = "X-" token
2536
2537 Generic-Field-Value = *( Generic-Field-Content | LWS )
2538 Generic-Field-Content = &lt;the OCTETs making up the field-value
2539 and consisting of either *TEXT or
2540 combinations of token, separators,
2541 and quoted-string&gt;
2542
2543 Request-Body = *OCTET ; See Sections <a href="#section-4.4">4.4</a> and <a href="#section-4.5">4.5</a> for semantics
2544
2545 Response = Status-Line
2546 *(Response-Header CRLF)
2547 CRLF
2548 [ Response-Body ]
2549
2550 Status-Line = ICAP-Version SP Status-Code SP Reason-Phrase CRLF
2551
2552 Status-Code = "100" ; <a href="#section-4.5">Section 4.5</a>
2553 | "101" ; Section 10.1.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2554 | "200" ; Section 10.2.1 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2555 | "201" ; Section 10.2.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2556 | "202" ; Section 10.2.3 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2557 | "203" ; Section 10.2.4 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2558 | "204" ; <a href="#section-4.6">Section 4.6</a>
2559 | "205" ; Section 10.2.6 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2560 | "206" ; Section 10.2.7 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2561 | "300" ; Section 10.3.1 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2562 | "301" ; Section 10.3.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2563 | "302" ; Section 10.3.3 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2564 | "303" ; Section 10.3.4 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2565 | "304" ; Section 10.3.5 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2566 | "305" ; Section 10.3.6 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2567 | "306" ; Section 10.3.7 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2568 | "307" ; Section 10.3.8 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2569
2570
2571
2572 <span class="grey">Elson &amp; Cerpa Informational [Page 46]</span></pre>
2573 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-47" ></span>
2574 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2575
2576
2577 | "400" ; <a href="#section-4.3.3">Section 4.3.3</a>
2578 | "401" ; Section 10.4.2 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2579 | "402" ; Section 10.4.3 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2580 | "403" ; Section 10.4.4 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2581 | "404" ; <a href="#section-4.3.3">Section 4.3.3</a>
2582 | "405" ; <a href="#section-4.3.3">Section 4.3.3</a>
2583 | "406" ; Section 10.4.7 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2584 | "407" ; Section 10.4.8 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2585 | "408" ; <a href="#section-4.3.3">Section 4.3.3</a>
2586 | "409" ; Section 10.4.10 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2587 | "410" ; Section 10.4.11 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2588 | "411" ; Section 10.4.12 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2589 | "412" ; Section 10.4.13 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2590 | "413" ; Section 10.4.14 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2591 | "414" ; Section 10.4.15 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2592 | "415" ; Section 10.4.16 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2593 | "416" ; Section 10.4.17 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2594 | "417" ; Section 10.4.18 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2595 | "500" ; <a href="#section-4.3.3">Section 4.3.3</a>
2596 | "501" ; <a href="#section-4.3.3">Section 4.3.3</a>
2597 | "502" ; <a href="#section-4.3.3">Section 4.3.3</a>
2598 | "503" ; <a href="#section-4.3.3">Section 4.3.3</a>
2599 | "504" ; Section 10.5.5 of [<a href="#ref-4" title="&quot;Hypertext Transfer Protocol -- HTTP/1.1&quot;">4</a>]
2600 | "505" ; <a href="#section-4.3.3">Section 4.3.3</a>
2601 | Extension-Code
2602
2603 Extension-Code = 3DIGIT
2604
2605 Reason-Phrase = *&lt;TEXT, excluding CR, LF&gt;
2606
2607 Response-Header = Response-Fields ":" [ Generic-Field-Value ]
2608
2609 Response-Fields = Response-Field-Name
2610 | Common-Field-Name
2611
2612 Response-Field-Name = "Server" ; <a href="#section-4.3.3">Section 4.3.3</a>
2613 | "ISTag" ; <a href="#section-4.7">Section 4.7</a>
2614
2615 Response-Body = *OCTET ; See Sections <a href="#section-4.4">4.4</a> and <a href="#section-4.5">4.5</a> for semantics
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628 <span class="grey">Elson &amp; Cerpa Informational [Page 47]</span></pre>
2629 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-48" ></span>
2630 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2631
2632
2633 Authors' Addresses
2634
2635 Jeremy Elson
2636 University of California Los Angeles
2637 Department of Computer Science
2638 3440 Boelter Hall
2639 Los Angeles CA 90095
2640
2641 Phone: (310) 206-3925
2642 EMail: [email protected]
2643
2644
2645 Alberto Cerpa
2646 University of California Los Angeles
2647 Department of Computer Science
2648 3440 Boelter Hall
2649 Los Angeles CA 90095
2650
2651 Phone: (310) 206-3925
2652 EMail: [email protected]
2653
2654
2655 ICAP discussion currently takes place at
2656 [email protected].
2657 For more information, see
2658 <a href="http://groups.yahoo.com/group/icap-discussions/">http://groups.yahoo.com/group/icap-discussions/</a>.
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684 <span class="grey">Elson &amp; Cerpa Informational [Page 48]</span></pre>
2685 <hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-49" ></span>
2686 <span class="grey"><a href="./rfc3507">RFC 3507</a> ICAP April 2003</span>
2687
2688
2689 Full Copyright Statement
2690
2691 Copyright (C) The Internet Society (2003). All Rights Reserved.
2692
2693 This document and translations of it may be copied and furnished to
2694 others, and derivative works that comment on or otherwise explain it
2695 or assist in its implementation may be prepared, copied, published
2696 and distributed, in whole or in part, without restriction of any
2697 kind, provided that the above copyright notice and this paragraph are
2698 included on all such copies and derivative works. However, this
2699 document itself may not be modified in any way, such as by removing
2700 the copyright notice or references to the Internet Society or other
2701 Internet organizations, except as needed for the purpose of
2702 developing Internet standards in which case the procedures for
2703 copyrights defined in the Internet Standards process must be
2704 followed, or as required to translate it into languages other than
2705 English.
2706
2707 The limited permissions granted above are perpetual and will not be
2708 revoked by the Internet Society or its successors or assigns.
2709
2710 This document and the information contained herein is provided on an
2711 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
2712 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
2713 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
2714 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
2715 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
2716
2717 Acknowledgement
2718
2719 Funding for the RFC Editor function is currently provided by the
2720 Internet Society.
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740 Elson &amp; Cerpa Informational [Page 49]
2741 </pre>