-
Notifications
You must be signed in to change notification settings - Fork 3
Expand file tree
/
Copy pathrfc3507.txt
More file actions
2747 lines (1827 loc) · 96.5 KB
/
rfc3507.txt
File metadata and controls
2747 lines (1827 loc) · 96.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group J. Elson
Request for Comments: 3507 A. Cerpa
Category: Informational UCLA
April 2003
Internet Content Adaptation Protocol (ICAP)
Status of this Memo
This memo provides information for the Internet community. It does
not specify an Internet standard of any kind. Distribution of this
memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved.
IESG Note
The Open Pluggable Services (OPES) working group has been chartered
to produce a standards track protocol specification for a protocol
intended to perform the same of functions as ICAP. However, since
ICAP is already in widespread use the IESG believes it is appropriate
to document existing usage by publishing the ICAP specification as an
informational document. The IESG also notes that ICAP was developed
before the publication of RFC 3238 and therefore does not address the
architectural and policy issues described in that document.
Abstract
ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
providing simple object-based content vectoring for HTTP services.
ICAP is, in essence, a lightweight protocol for executing a "remote
procedure call" on HTTP messages. It allows ICAP clients to pass
HTTP messages to ICAP servers for some sort of transformation or
other processing ("adaptation"). The server executes its
transformation service on messages and sends back responses to the
client, usually with modified messages. Typically, the adapted
messages are either HTTP requests or HTTP responses.
Elson & Cerpa Informational [Page 1]
RFC 3507 ICAP April 2003
Table of Contents
1. Introduction............................................3
2. Terminology.............................................5
3. ICAP Overall Operation..................................8
3.1 Request Modification..............................8
3.2 Response Modification............................10
4. Protocol Semantics.....................................11
4.1 General Operation................................11
4.2 ICAP URIs........................................11
4.3 ICAP Headers.....................................12
4.3.1 Headers Common to Requests and
Responses................................12
4.3.2 Request Headers..........................13
4.3.3 Response Headers.........................14
4.3.4 ICAP-Related Headers in HTTP
Messages.................................15
4.4 ICAP Bodies: Encapsulation of HTTP
Messages.........................................16
4.4.1 Expected Encapsulated Sections...........16
4.4.2 Encapsulated HTTP Headers................18
4.5 Message Preview..................................18
4.6 "204 No Content" Responses outside of
Previews.........................................22
4.7 ISTag Response Header............................22
4.8 Request Modification Mode........................23
4.8.1 Request..................................23
4.8.2 Response.................................24
4.8.3 Examples.................................24
4.9 Response Modification Mode.......................27
4.9.1 Request..................................27
4.9.2 Response.................................27
4.9.3 Examples.................................28
4.10 OPTIONS Method...................................29
4.10.1 OPTIONS request..........................29
4.10.2 OPTIONS response.........................30
4.10.3 OPTIONS examples.........................33
5. Caching................................................33
6. Implementation Notes...................................34
6.1 Vectoring Points.................................34
6.2 Application Level Errors.........................35
6.3 Use of Chunked Transfer-Encoding.................37
6.4 Distinct URIs for Distinct Services..............37
7. Security Considerations................................37
7.1 Authentication...................................37
7.2 Encryption.......................................38
7.3 Service Validation...............................38
8. Motivations and Design Alternatives....................39
Elson & Cerpa Informational [Page 2]
RFC 3507 ICAP April 2003
8.1 To Be HTTP, or Not to Be.........................39
8.2 Mandatory Use of Chunking........................39
8.3 Use of the null-body directive in the
Encapsulated header..............................40
9. References.............................................40
10. Contributors...........................................41
Appendix A BNF Grammar for ICAP Messages..................45
Authors' Addresses..........................................48
Full Copyright Statement....................................49
1. Introduction
As the Internet grows, so does the need for scalable Internet
services. Popular web servers are asked to deliver content to
hundreds of millions of users connected at ever-increasing
bandwidths. The model of centralized, monolithic servers that are
responsible for all aspects of every client's request seems to be
reaching the end of its useful life.
To keep up with the growth in the number of clients, there has been a
move towards architectures that scale better through the use of
replication, distribution, and caching. On the content provider
side, replication and load-balancing techniques allow the burden of
client requests to be spread out over a myriad of servers. Content
providers have also begun to deploy geographically diverse content
distribution networks that bring origin-servers closer to the "edge"
of the network where clients are attached. These networks of
distributed origin-servers or "surrogates" allow the content provider
to distribute their content whilst retaining control over the
integrity of that content. The distributed nature of this type of
deployment and the proximity of a given surrogate to the end-user
enables the content provider to offer additional services to a user
which might be based, for example, on geography where this would have
been difficult with a single, centralized service.
ICAP, the Internet Content Adaption Protocol, is a protocol aimed at
providing simple object-based content vectoring for HTTP services.
ICAP is, in essence, a lightweight protocol for executing a "remote
procedure call" on HTTP messages. It allows ICAP clients to pass
HTTP messages to ICAP servers for some sort of transformation or
other processing ("adaptation"). The server executes its
transformation service on messages and sends back responses to the
client, usually with modified messages. The adapted messages may be
either HTTP requests or HTTP responses. Though transformations may
be possible on other non-HTTP content, they are beyond the scope of
this document.
Elson & Cerpa Informational [Page 3]
RFC 3507 ICAP April 2003
This type of Remote Procedure Call (RPC) is useful in a number of
ways. For example:
o Simple transformations of content can be performed near the edge
of the network instead of requiring an updated copy of an object
from an origin server. For example, a content provider might want
to provide a popular web page with a different advertisement every
time the page is viewed. Currently, content providers implement
this policy by marking such pages as non-cachable and tracking
user cookies. This imposes additional load on the origin server
and the network. In our architecture, the page could be cached
once near the edges of the network. These edge caches can then
use an ICAP call to a nearby ad-insertion server every time the
page is served to a client.
Other such transformations by edge servers are possible, either
with cooperation from the content provider (as in a content
distribution network), or as a value-added service provided by a
client's network provider (as in a surrogate). Examples of these
kinds of transformations are translation of web pages to different
human languages or to different formats that are appropriate for
special physical devices (e.g., PDA-based or cell-phone-based
browsers).
o Surrogates or origin servers can avoid performing expensive
operations by shipping the work off to other servers instead.
This helps distribute load across multiple machines. For example,
consider a user attempting to download an executable program via a
surrogate (e.g., a caching proxy). The surrogate, acting as an
ICAP client, can ask an external server to check the executable
for viruses before accepting it into its cache.
o Firewalls or surrogates can act as ICAP clients and send outgoing
requests to a service that checks to make sure the URI in the
request is allowed (for example, in a system that allows parental
control of web content viewed by children). In this case, it is a
*request* that is being adapted, not an object returned by a
response.
In all of these examples, ICAP is helping to reduce or distribute the
load on origin servers, surrogates, or the network itself. In some
cases, ICAP facilitates transformations near the edge of the network,
allowing greater cachability of the underlying content. In other
examples, devices such as origin servers or surrogates are able to
reduce their load by distributing expensive operations onto other
machines. In all cases, ICAP has also created a standard interface
for content adaptation to allow greater flexibility in content
distribution or the addition of value added services in surrogates.
Elson & Cerpa Informational [Page 4]
RFC 3507 ICAP April 2003
There are two major components in our architecture:
1. Transaction semantics -- "How do I ask for adaptation?"
2. Control of policy -- "When am I supposed to ask for adaptation,
what kind of adaptation do I ask for, and from where?"
Currently, ICAP defines only the transaction semantics. For example,
this document specifies how to send an HTTP message from an ICAP
client to an ICAP server, specify the URI of the ICAP resource
requested along with other resource-specific parameters, and receive
the adapted message.
Although a necessary building-block, this wire-protocol defined by
ICAP is of limited use without the second part: an accompanying
application framework in which it operates. The more difficult
policy issue is beyond the scope of the current ICAP protocol, but is
planned in future work.
In initial implementations, we expect that implementation-specific
manual configuration will be used to define policy. This includes
the rules for recognizing messages that require adaptation, the URIs
of available adaptation resources, and so on. For ICAP clients and
servers to interoperate, the exact method used to define policy need
not be consistent across implementations, as long as the policy
itself is consistent.
IMPORTANT:
Note that at this time, in the absence of a policy-framework, it
is strongly RECOMMENDED that transformations SHOULD only be
performed on messages with the explicit consent of either the
content-provider or the user (or both). Deployment of
transformation services without the consent of either leads to, at
best, unpredictable results. For more discussion of these issues,
see Section 7.
Once the full extent of the typical policy decisions are more fully
understood through experience with these initial implementations,
later follow-ons to this architecture may define an additional policy
control protocol. This future protocol may allow a standard policy
definition interface complementary to the ICAP transaction interface
defined here.
2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in BCP 14, RFC 2119 [2].
Elson & Cerpa Informational [Page 5]
RFC 3507 ICAP April 2003
The special terminology used in this document is defined below. The
majority of these terms are taken as-is from HTTP/1.1 [4] and are
reproduced here for reference. A thorough understanding of HTTP/1.1
is assumed on the part of the reader.
connection:
A transport layer virtual circuit established between two programs
for the purpose of communication.
message:
The basic unit of HTTP communication, consisting of a structured
sequence of octets matching the syntax defined in Section 4 of
HTTP/1.1 [4] and transmitted via the connection.
request:
An HTTP request message, as defined in Section 5 of HTTP/1.1 [4].
response:
An HTTP response message, as defined in Section 6 of HTTP/1.1 [4].
resource:
A network data object or service that can be identified by a URI,
as defined in Section 3.2 of HTTP/1.1 [4]. Resources may be
available in multiple representations (e.g., multiple languages,
data formats, size, resolutions) or vary in other ways.
client:
A program that establishes connections for the purpose of sending
requests.
server:
An application program that accepts connections in order to
service requests by sending back responses. Any given program may
be capable of being both a client and a server; our use of these
terms refers only to the role being performed by the program for a
particular connection, rather than to the program's capabilities
in general. Likewise, any server may act as an origin server,
surrogate, gateway, or tunnel, switching behavior based on the
nature of each request.
origin server:
The server on which a given resource resides or is to be created.
Elson & Cerpa Informational [Page 6]
RFC 3507 ICAP April 2003
proxy:
An intermediary program which acts as both a server and a client
for the purpose of making requests on behalf of other clients.
Requests are serviced internally or by passing them on, with
possible translation, to other servers. A proxy MUST implement
both the client and server requirements of this specification.
cache:
A program's local store of response messages and the subsystem
that controls its message storage, retrieval, and deletion. A
cache stores cachable responses in order to reduce the response
time and network bandwidth consumption on future, equivalent
requests. Any client or server may include a cache, though a
cache cannot be used by a server that is acting as a tunnel.
cachable:
A response is cachable if a cache is allowed to store a copy of
the response message for use in answering subsequent requests.
The rules for determining the cachability of HTTP responses are
defined in Section 13 of [4]. Even if a resource is cachable,
there may be additional constraints on whether a cache can use the
cached copy for a particular request.
surrogate:
A gateway co-located with an origin server, or at a different
point in the network, delegated the authority to operate on behalf
of, and typically working in close co-operation with, one or more
origin servers. Responses are typically delivered from an
internal cache. Surrogates may derive cache entries from the
origin server or from another of the origin server's delegates.
In some cases a surrogate may tunnel such requests.
Where close co-operation between origin servers and surrogates
exists, this enables modifications of some protocol requirements,
including the Cache-Control directives in [4]. Such modifications
have yet to be fully specified.
Devices commonly known as "reverse proxies" and "(origin) server
accelerators" are both more properly defined as surrogates.
New definitions:
ICAP resource:
Similar to an HTTP resource as described above, but the URI refers
to an ICAP service that performs adaptations of HTTP messages.
Elson & Cerpa Informational [Page 7]
RFC 3507 ICAP April 2003
ICAP server:
Similar to an HTTP server as described above, except that the
application services ICAP requests.
ICAP client:
A program that establishes connections to ICAP servers for the
purpose of sending requests. An ICAP client is often, but not
always, a surrogate acting on behalf of a user.
3. ICAP Overall Operation
Before describing ICAP's semantics in detail, we will first give a
general overview of the protocol's major functions and expected uses.
As described earlier, ICAP focuses on modification of HTTP requests
(Section 3.1), and modification of HTTP responses (Section 3.2).
3.1 Request Modification
In "request modification" (reqmod) mode, an ICAP client sends an HTTP
request to an ICAP server. The ICAP server may then:
1) Send back a modified version of the request. The ICAP client may
then perform the modified request by contacting an origin server;
or, pipeline the modified request to another ICAP server for
further modification.
2) Send back an HTTP response to the request. This is used to
provide information useful to the user in case of an error (e.g.,
"you sent a request to view a page you are not allowed to see").
3) Return an error.
ICAP clients MUST be able to handle all three types of responses.
However, in line with the guidance provided for HTTP surrogates in
Section 13.8 of [4], ICAP client implementors do have flexibility in
handling errors. If the ICAP server returns an error, the ICAP
client may (for example) return the error to the user, execute the
unadapted request as it arrived from the client, or re-try the
adaptation again.
We will illustrate this method with an example application: content
filtering. Consider a surrogate that receives a request from a
client for a web page on an origin server. The surrogate, acting as
an ICAP client, sends the client's request to an ICAP server that
performs URI-based content filtering. If access to the requested URI
is allowed, the request is returned to the ICAP client unmodified.
However, if the ICAP server chooses to disallow access to the
requested resources, it may either:
Elson & Cerpa Informational [Page 8]
RFC 3507 ICAP April 2003
1) Modify the request so that it points to a page containing an error
message instead of the original URI.
2) Return an encapsulated HTTP response that indicates an HTTP error.
This method can be used for a variety of other applications; for
example, anonymization, modification of the Accept: headers to handle
special device requirements, and so forth.
Typical data flow:
origin-server
| /|\
| |
5 | | 4
| |
\|/ | 2
ICAP-client --------------> ICAP-resource
(surrogate) <-------------- on ICAP-server
| /|\ 3
| |
6 | | 1
| |
\|/ |
client
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
2. The surrogate sends the request to the ICAP server.
3. The ICAP server executes the ICAP resource's service on the
request and sends the possibly modified request, or a response to
the request back to the ICAP client.
If Step 3 returned a request:
4. The surrogate sends the request, possibly different from original
client request, to the origin server.
5. The origin server responds to request.
6. The surrogate sends the reply (from either the ICAP server or the
origin server) to the client.
Elson & Cerpa Informational [Page 9]
RFC 3507 ICAP April 2003
3.2 Response Modification
In the "response modification" (respmod) mode, an ICAP client sends
an HTTP response to an ICAP server. (The response sent by the ICAP
client typically has been generated by an origin server.) The ICAP
server may then:
1) Send back a modified version of the response.
2) Return an error.
The response modification method is intended for post-processing
performed on an HTTP response before it is delivered to a client.
Examples include formatting HTML for display on special devices,
human language translation, virus checking, and so forth.
Typical data flow:
origin-server
| /|\
| |
3 | | 2
| |
\|/ | 4
ICAP-client --------------> ICAP-resource
(surrogate) <-------------- on ICAP-server
| /|\ 5
| |
6 | | 1
| |
\|/ |
client
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
2. The surrogate sends the request to the origin server.
3. The origin server responds to request.
4. The ICAP-capable surrogate sends the origin server's reply to the
ICAP server.
5. The ICAP server executes the ICAP resource's service on the origin
server's reply and sends the possibly modified reply back to the
ICAP client.
Elson & Cerpa Informational [Page 10]
RFC 3507 ICAP April 2003
6. The surrogate sends the reply, possibly modified from the original
origin server's reply, to the client.
4. Protocol Semantics
4.1 General Operation
ICAP is a request/response protocol similar in semantics and usage to
HTTP/1.1 [4]. Despite the similarity, ICAP is not HTTP, nor is it an
application protocol that runs over HTTP. This means, for example,
that ICAP messages can not be forwarded by HTTP surrogates. Our
reasons for not building directly on top of HTTP are discussed in
Section 8.1.
ICAP uses TCP/IP as a transport protocol. The default port is 1344,
but other ports may be used. The TCP flow is initiated by the ICAP
client to a passively listening ICAP server.
ICAP messages consist of requests from client to server and responses
from server to client. Requests and responses use the generic
message format of RFC 2822 [3] -- that is, a start-line (either a
request line or a status line), a number of header fields (also known
as "headers"), an empty line (i.e., a line with nothing preceding the
CRLF) indicating the end of the header fields, and a message-body.
The header lines of an ICAP message specify the ICAP resource being
requested as well as other meta-data such as cache control
information. The message body of an ICAP request contains the
(encapsulated) HTTP messages that are being modified.
As in HTTP/1.1, a single transport connection MAY (perhaps even
SHOULD) be re-used for multiple request/response pairs. The rules
for doing so in ICAP are the same as described in Section 8.1.2.2 of
[4]. Specifically, requests are matched up with responses by
allowing only one outstanding request on a transport connection at a
time. Multiple parallel connections MAY be used as in HTTP.
4.2 ICAP URIs
All ICAP requests specify the ICAP resource being requested from the
server using an ICAP URI. This MUST be an absolute URI that
specifies both the complete hostname and the path of the resource
being requested. For definitive information on URL syntax and
semantics, see "Uniform Resource Identifiers (URI): Generic Syntax
and Semantics," RFC 2396 [1], Section 3. The URI structure defined
by ICAP is roughly:
Elson & Cerpa Informational [Page 11]
RFC 3507 ICAP April 2003
ICAP_URI = Scheme ":" Net_Path [ "?" Query ]
Scheme = "icap"
Net_Path = "//" Authority [ Abs_Path ]
Authority = [ userinfo "@" ] host [ ":" port ]
ICAP adds the new scheme "icap" to the ones defined in RFC 2396. If
the port is empty or not given, port 1344 is assumed. An example
ICAP URI line might look like this:
icap://icap.example.net:2000/services/icap-service-1
An ICAP server MUST be able to recognize all of its hosts names,
including any aliases, local variations, and numeric IP addresses of
its interfaces.
Any arguments that an ICAP client wishes to pass to an ICAP service
to modify the nature of the service MAY be passed as part of the
ICAP-URI, using the standard "?"-encoding of attribute-value pairs
used in HTTP. For example:
icap://icap.net/service?mode=translate&lang=french
4.3 ICAP Headers
The following sections define the valid headers for ICAP messages.
Section 4.3.1 describes headers common to both requests and
responses. Request-specific and response-specific headers are
described in Sections 4.3.2 and 4.3.3, respectively.
User-defined header extensions are allowed. In compliance with the
precedent established by the Internet mail format [3] and later
adopted by HTTP [4], all user-defined headers MUST follow the "X-"
naming convention ("X-Extension-Header: Foo"). ICAP implementations
MAY ignore any "X-" headers without loss of compliance with the
protocol as defined in this document.
Each header field consists of a name followed by a colon (":") and
the field value. Field names are case-insensitive. ICAP follows the
rules describe in section 4.2 of [4].
4.3.1 Headers Common to Requests and Responses
The headers of all ICAP messages MAY include the following
directives, defined in ICAP the same as they are in HTTP:
Elson & Cerpa Informational [Page 12]
RFC 3507 ICAP April 2003
Cache-Control
Connection
Date
Expires
Pragma
Trailer
Upgrade
Note in particular that the "Transfer-Encoding" option is not
allowed. The special transfer-encoding requirements of ICAP bodies
are described in Section 4.4.
The Upgrade header MAY be used to negotiate Transport-Layer Security
on an ICAP connection, exactly as described for HTTP/1.1 in [4].
The ICAP-specific headers defined are:
Encapsulated (See Section 4.4)
4.3.2 Request Headers
Similar to HTTP, ICAP requests MUST start with a request line that
contains a method, the complete URI of the ICAP resource being
requested, and an ICAP version string. The current version number of
ICAP is "1.0".
This version of ICAP defines three methods:
REQMOD - for Request Modification (Section 4.8)
RESPMOD - for Response Modification (Section 4.9)
OPTIONS - to learn about configuration (Section 4.10)
The OPTIONS method MUST be implemented by all ICAP servers. All
other methods are optional and MAY be implemented.
User-defined extension methods are allowed. Before attempting to use
an extension method, an ICAP client SHOULD use the OPTIONS method to
query the ICAP server's list of supported methods; see Section 4.10.
(If an ICAP server receives a request for an unknown method, it MUST
give a 501 error response as described in the next section.)
Given the URI rules described in Section 4.2, a well-formed ICAP
request line looks like the following example:
RESPMOD icap://icap.example.net/translate?mode=french ICAP/1.0
Elson & Cerpa Informational [Page 13]
RFC 3507 ICAP April 2003
A number of request-specific headers are allowed in ICAP requests,
following the same semantics as the corresponding HTTP request
headers (Section 5.3 of [4]). These are:
Authorization
Allow (see Section 4.6)
From (see Section 14.22 of [4])
Host (REQUIRED in ICAP as it is in HTTP/1.1)
Referer (see Section 14.36 of [4])
User-Agent
In addition to HTTP-like headers, there are also request headers
unique to ICAP defined:
Preview (see Section 4.5)
4.3.3 Response Headers
ICAP responses MUST start with an ICAP status line, similar in form
to that used by HTTP, including the ICAP version and a status code.
For example:
ICAP/1.0 200 OK
Semantics of ICAP status codes in ICAP match the status codes defined
by HTTP (Section 6.1.1 and 10 of [4]), except where otherwise
indicated in this document; n.b. 100 (Section 4.5) and 204 (Section
4.6).
ICAP error codes that differ from their HTTP counterparts are:
100 - Continue after ICAP Preview (Section 4.5).
204 - No modifications needed (Section 4.6).
400 - Bad request.
404 - ICAP Service not found.
405 - Method not allowed for service (e.g., RESPMOD requested for
service that supports only REQMOD).
408 - Request timeout. ICAP server gave up waiting for a request
from an ICAP client.
500 - Server error. Error on the ICAP server, such as "out of disk
space".
Elson & Cerpa Informational [Page 14]
RFC 3507 ICAP April 2003
501 - Method not implemented. This response is illegal for an
OPTIONS request since implementation of OPTIONS is mandatory.
502 - Bad Gateway. This is an ICAP proxy and proxying produced an
error.
503 - Service overloaded. The ICAP server has exceeded a maximum
connection limit associated with this service; the ICAP client
should not exceed this limit in the future.
505 - ICAP version not supported by server.
As in HTTP, the 4xx class of error codes indicate client errors, and
the 5xx class indicate server errors.
ICAP's response-header fields allow the server to pass additional
information in the response that cannot be placed in the ICAP's
status line.
A response-specific header is allowed in ICAP requests, following the
same semantics as the corresponding HTTP response headers (Section
6.2 of [4]). This is:
Server (see Section 14.38 of [4])
In addition to HTTP-like headers, there is also a response header
unique to ICAP defined:
ISTag (see Section 4.7)
4.3.4 ICAP-Related Headers in HTTP Messages
When an ICAP-enabled HTTP surrogate makes an HTTP request to an
origin server, it is often useful to advise the origin server of the
surrogate's ICAP capabilities. Origin servers can use this
information to modify its response accordingly. For example, an
origin server may choose not to insert an advertisement into a page
if it knows that a downstream ICAP server can insert the ad instead.
Although this ICAP specification can not mandate how HTTP is used in
communication between HTTP clients and servers, we do suggest a
convention: such headers (if used) SHOULD start with "X-ICAP". HTTP
clients with ICAP services SHOULD minimally include an "X-ICAP-
Version: 1.0" header along with their application-specific headers.
Elson & Cerpa Informational [Page 15]
RFC 3507 ICAP April 2003
4.4 ICAP Bodies: Encapsulation of HTTP Messages
The ICAP encapsulation model is a lightweight means of packaging any
number of HTTP message sections into an encapsulating ICAP message-
body, in order to allow the vectoring of requests, responses, and
request/response pairs to an ICAP server.
This is accomplished by concatenating interesting message parts
(encapsulatED sections) into a single ICAP message-body (the
encapsulatING message). The encapsulated sections may be the headers
or bodies of HTTP messages.
Encapsulated bodies MUST be transferred using the "chunked"
transfer-coding described in Section 3.6.1 of [4]. However,
encapsulated headers MUST NOT be chunked. In other words, an ICAP
message-body switches from being non-chunked to chunked as the body
passes from the encapsulated header to encapsulated body section.
(See Examples in Sections 4.8.3 and 4.9.3.). The motivation behind
this decision is described in Section 8.2.
4.4.1 The "Encapsulated" Header
The offset of each encapsulated section's start relative to the start
of the encapsulating message's body is noted using the "Encapsulated"
header. This header MUST be included in every ICAP message. For
example, the header
Encapsulated: req-hdr=0, res-hdr=45, res-body=100
indicates a message that encapsulates a group of request headers, a
group of response headers, and then a response body. Each of these
is included at the byte-offsets listed. The byte-offsets are in
decimal notation for consistency with HTTP's Content-Length header.
The special entity "null-body" indicates there is no encapsulated
body in the ICAP message.
The syntax of an Encapsulated header is:
encapsulated_header: "Encapsulated: " encapsulated_list
encapsulated_list: encapsulated_entity |
encapsulated_entity ", " encapsulated_list
encapsulated_entity: reqhdr | reshdr | reqbody | resbody | optbody
reqhdr = "req-hdr" "=" (decimal integer)
reshdr = "res-hdr" "=" (decimal integer)
reqbody = { "req-body" | "null-body" } "=" (decimal integer)
resbody = { "res-body" | "null-body" } "=" (decimal integer)
optbody = { "opt-body" | "null-body" } "=" (decimal integer)
Elson & Cerpa Informational [Page 16]
RFC 3507 ICAP April 2003
There are semantic restrictions on Encapsulated headers beyond the
syntactic restrictions. The order in which the encapsulated parts
appear in the encapsulating message-body MUST be the same as the
order in which the parts are named in the Encapsulated header. In
other words, the offsets listed in the Encapsulated line MUST be
monotonically increasing. In addition, the legal forms of the
Encapsulated header depend on the method being used (REQMOD, RESPMOD,
or OPTIONS). Specifically:
REQMOD request encapsulated_list: [reqhdr] reqbody
REQMOD response encapsulated_list: {[reqhdr] reqbody} |
{[reshdr] resbody}
RESPMOD request encapsulated_list: [reqhdr] [reshdr] resbody
RESPMOD response encapsulated_list: [reshdr] resbody
OPTIONS response encapsulated_list: optbody
In the above grammar, note that encapsulated headers are always
optional. At most one body per encapsulated message is allowed. If
no encapsulated body is presented, the "null-body" header is used
instead; this is useful because it indicates the length of the header
section.
Examples of legal Encapsulated headers:
/* REQMOD request: This encapsulated HTTP request's headers start
* at offset 0; the HTTP request body (e.g., in a POST) starts
* at 412. */
Encapsulated: req-hdr=0, req-body=412
/* REQMOD request: Similar to the above, but no request body is
* present (e.g., a GET). We use the null-body directive instead.
* In both this case and the previous one, we can tell from the
* Encapsulated header that the request headers were 412 bytes
* long. */
Encapsulated: req-hdr=0, null-body=412
/* REQMOD response: ICAP server returned a modified request,
* with body */
Encapsulated: req-hdr=0, req-body=512
/* RESPMOD request: Request headers at 0, response headers at 822,
* response body at 1655. Note that no request body is allowed in
* RESPMOD requests. */
Encapsulated: req-hdr=0, res-hdr=822, res-body=1655
/* RESPMOD or REQMOD response: header and body returned */
Encapsulated: res-hdr=0, res-body=749
Elson & Cerpa Informational [Page 17]
RFC 3507 ICAP April 2003
/* OPTIONS response when there IS an options body */
Encapsulated: opt-body=0
/* OPTIONS response when there IS NOT an options body */
Encapsulated: null-body=0
4.4.2 Encapsulated HTTP Headers
By default, ICAP messages may encapsulate HTTP message headers and
entity bodies. HTTP headers MUST start with the request-line or
status-line for requests and responses, respectively, followed by
interesting HTTP headers.
The encapsulated headers MUST be terminated by a blank line, in order
to make them human readable, and in order to terminate line-by-line
HTTP parsers.
HTTP/1.1 makes a distinction between end-to-end headers and hop-by-
hop headers (see Section 13.5.1 of [4]). End-to-end headers are
meaningful to the ultimate recipient of a message, whereas hop-by-hop
headers are meaningful only for a single transport-layer connection.
Hop-by-hop headers include Connection, Keep-Alive, and so forth. All
end-to-end HTTP headers SHOULD be encapsulated, and all hop-by-hop
headers MUST NOT be encapsulated.
Despite the above restrictions on encapsulation, the hop-by-hop
Proxy-Authenticate and Proxy-Authorization headers MUST be forwarded
to the ICAP server in the ICAP header section (not the encapsulated
message). This allows propagation of client credentials that might
have been sent to the ICAP client in cases where the ICAP client is
also an HTTP surrogate. Note that this does not contradict HTTP/1.1,
which explicitly states "A proxy MAY relay the credentials from the
client request to the next proxy if that is the mechanism by which
the proxies cooperatively authenticate a given request." (Section
14.34).
The Via header of an encapsulated message SHOULD be modified by an
ICAP server as if the encapsulated message were traveling through an
HTTP surrogate. The Via header added by an ICAP server MUST specify
protocol as ICAP/1.0.
4.5 Message Preview