idnits 2.17.1 draft-stecher-icap-subid-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 2 instances of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. == There are 1 instance of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: 'CRLF' on line 677 ** Obsolete normative reference: RFC 822 (ref. '2') (Obsoleted by RFC 2822) ** Obsolete normative reference: RFC 2616 (ref. '5') (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2253 (ref. '6') (Obsoleted by RFC 4510, RFC 4514) Summary: 7 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft M. Stecher 3 Expires: October, 2003 webwasher AG 4 Category: Informational J. Merrick 5 Network Appliance 6 A. Beck 7 M. Hofmann 8 Lucent Technologies 10 April, 2003 12 ICAP Extensions 13 draft-stecher-icap-subid-00.txt 15 Status of this Memo 16 This document is an Internet-Draft and is in full conformance with 17 all provisions of Section 10 of RFC2026. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire in October, 2003. 37 Copyright Notice 38 Copyright (C) The Internet Society (2003). All Rights Reserved. 40 Abstract 41 The Internet Content Adaptation Protocol (ICAP) [1] provides simple, 42 object-based content vectoring for HTTP services. User-defined header 43 extensions are widely used by many ICAP client and server 44 implementations. 45 Some implementations have also introduced new ICAP methods. 46 This document describes and defines a number of ICAP extensions to 47 ensure ongoing interoperability between the implementations. 49 Table of Contents 51 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 52 2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 53 3 User-defined ICAP request header extensions . . . . . . . . 4 54 3.1 X-Client-IP . . . . . . . . . . . . . . . . . . . . . . . . 4 55 3.2 X-Server-IP . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3.3 X-Subscriber-ID . . . . . . . . . . . . . . . . . . . . . . 5 57 3.4 X-Authenticated-User . . . . . . . . . . . . . . . . . . . . 5 58 3.5 X-Authenticated-Groups . . . . . . . . . . . . . . . . . . . 6 59 3.6 ICAP request example . . . . . . . . . . . . . . . . . . . . 7 60 4 User-defined ICAP response header extensions . . . . . . . . 7 61 4.1 X-ICAP-Profile . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.2 X-Attribute . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.3 X-Attribute-Cacheability . . . . . . . . . . . . . . . . . . 8 64 4.4 X-Attribute-Prefix . . . . . . . . . . . . . . . . . . . . . 9 65 4.5 X-Infection-Found . . . . . . . . . . . . . . . . . . . . . 9 66 4.6 X-Violations-Found . . . . . . . . . . . . . . . . . . . . . 10 67 4.7 X-Virus-ID . . . . . . . . . . . . . . . . . . . . . . . . . 11 68 4.8 X-Response-Info . . . . . . . . . . . . . . . . . . . . . . 12 69 4.9 X-Response-Desc . . . . . . . . . . . . . . . . . . . . . . 12 70 4.10 ICAP response examples . . . . . . . . . . . . . . . . . . . 12 71 5 OPTIONS response extensions . . . . . . . . . . . . . . . . 14 72 5.1 X-Include . . . . . . . . . . . . . . . . . . . . . . . . . 14 73 5.2 Attribute-List response body . . . . . . . . . . . . . . . . 14 74 5.3 Example of an OPTIONS response . . . . . . . . . . . . . . . 15 75 6 The LOG method . . . . . . . . . . . . . . . . . . . . . . . 16 76 6.1 LOG request . . . . . . . . . . . . . . . . . . . . . . . . 16 77 6.1.1 Request-Date . . . . . . . . . . . . . . . . . . . . . . . . 17 78 6.1.2 Object-Length . . . . . . . . . . . . . . . . . . . . . . . 17 79 6.1.3 Requested-URI . . . . . . . . . . . . . . . . . . . . . . . 17 80 6.1.4 LOG-[service-ID] and X-LOG-[service-ID] . . . . . . . . . . 18 81 6.2 Request body . . . . . . . . . . . . . . . . . . . . . . . . 18 82 6.3 LOG response . . . . . . . . . . . . . . . . . . . . . . . . 18 83 7 Security Considerations . . . . . . . . . . . . . . . . . . 18 84 8 References . . . . . . . . . . . . . . . . . . . . . . . . . 19 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 19 86 Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 87 Full Copyright Statement . . . . . . . . . . . . . . . . . . 20 89 1 Introduction 91 The Internet Content Adaptation Protocol (ICAP) [1] provides simple, 92 object-based content vectoring for HTTP services. An ICAP request or 93 response typically includes an encapsulated HTTP message. Some ICAP 94 services, however, require more information than what is contained in 95 the encapsulated HTTP message. For example, some services require 96 information about the identity of the source of the encapsulated HTTP 97 message. This document specifies user-defined header extensions which 98 allow an ICAP client and/or server to include certain meta information 99 in ICAP requests or responses. 101 In compliance with the precedent established by the Internet mail format 102 [2] and later adopted by HTTP [5], the user-defined headers follow the 103 "X-" naming convention. ICAP implementations MAY ignore these "X-" 104 headers without loss of compliance with the protocol as defined in [1]. 106 Each header field consists of a name followed by a colon (":") and the 107 field value. Field names are case-insensitive. ICAP follows the rules 108 as described in section 4.2 of [5]. 110 In compliance with section 4.3 of the ICAP specification [1] 111 user-defined header extensions are allowed. 113 Section 4.3.2 of the ICAP protocol [1] also allows the adding of 114 user-defined extension methods. Section 6 of this document defines a new 115 method that has been introduced. 116 Before attempting to use an extension method, an ICAP client SHOULD use 117 the OPTIONS method to query the ICAP server's list of supported methods; 118 see Section 4.10 of [1]. 120 2 Terminology 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in RFC 2119 [3]. 126 This grammar of the syntax definitions given in this document is 127 specified in terms of the augmented Backus-Naur Form (BNF) similar to 128 that used by the HTTP/1.1 specification (See Section 2.1 of [5]). 129 Implementers will need to be familiar with the notation in order to 130 understand this specification. 132 Many header values (where noted) have exactly the same grammar and 133 semantics as in HTTP/1.1. We do not reproduce this grammar here. 135 3 User-defined ICAP request header extensions 137 This section describes the format and the usage of some specific 138 user-defined ICAP header extensions that MAY be used in REQMOD and 139 RESPMOD requests, namely 141 X-Client-IP 142 X-Server-IP 143 X-Subscriber-ID 144 X-Authenticated-User 145 X-Authenticated-Groups 147 All of these headers provide meta information about the source of the 148 encapsulated HTTP message. Such information might be required by ICAP 149 services, which modify Web pages based on a user profile or a set of 150 user parameters. Other examples include user-specific content filtering 151 services and all types of subscription-based services. 153 As the ICAP server typically communicates with the ICAP client rather 154 than the source of encapsulated HTTP messages, it cannot extract the 155 identity of the source of the HTTP messages from the underlying 156 transport session. Furthermore, ICAP itself does not define a mechanism 157 for the exchange of such information between ICAP client and ICAP 158 server. 160 For these reasons, this section specifies user-defined request header 161 extensions for ICAP, which allow the ICAP client to include meta 162 information about the source of the encapsulated HTTP message. 164 If the meta information for some header is not available, the header 165 field MUST be omitted. See section 5.1 about the X-Include header to 166 request the headers defined in this section. 168 3.1 X-Client-IP 170 The value of the X-Client-IP header field is the IP source address of 171 the encapsulated HTTP request. The IP address MUST be a dotted-decimal 172 IPv4 address or an IPv6 hex address. 174 For ICAP messages in request modification mode (REQMOD), the X-Client-IP 175 header field MUST contain the IP source address of the encapsulated HTTP 176 request. 178 For ICAP messages in response modification mode (RESPMOD), the 179 X-Client-IP header field MUST contain the IP source address of the 180 client issuing the HTTP request (that resulted in the encapsulated HTTP 181 response). Note that this is the IP source address of the corresponding 182 HTTP request and not the IP source address of the encapsulated HTTP 183 response. 185 An ICAP client MUST NOT include the X-Client-IP header if it is not 186 aware of the source IP address of the client issuing the HTTP request. 188 3.2 X-Server-IP 190 The value of the X-Server-IP header field is the IP destination address 191 of the encapsulated HTTP request. It specifies the HTTP destination host 192 and not the IP address of any intermediate proxy server. 193 The IP address MUST be a dotted-decimal IPv4 address or an IPv6 hex 194 address. 196 3.3 X-Subscriber-ID 198 This header contains a unique subscriber ID of the user who issued the 199 HTTP request. This MAY be an e-mail address but the exact format of the 200 subscriber ID is not specified by ICAP or this document. 202 The ICAP client MUST NOT include an X-Subscriber-ID header in the 203 outgoing ICAP message if it is not aware of the subscriber ID of the 204 client issuing the HTTP request. 206 3.4 X-Authenticated-User 208 If the user who issued the HTTP request has been authenticated and the 209 ICAP client knows the authenticated user name, the ICAP client can 210 assemble an Auth-User-URI and send a base-64 encoded version of it as a 211 value of the X-Authenticated-User header. The syntax of the 212 Auth-User-URI is 214 Syntax: 215 X-Authenticated-User-Header = "X-Authenticated-User: " 216 base64-encoded-Auth-User-URI 217 Auth-User-URI = Auth-Scheme "://" Auth-User-Path 219 By now Auth-Scheme is known as one of these values and can be extended 220 by additional authentication schemes in the future: 222 Auth-Scheme = "WinNT" | "LDAP" | "Radius" | "Local" 223 The Auth-Scheme name MUST be treated as case insensitive. 225 The Auth-User-Path depends on the authentication scheme: 227 Auth-User-Path = Auth-User-Path-WinNT | Auth-User-Path-LDAP | 228 Auth-User-Path-Radius | Auth-User-Path-Local 229 Auth-User-Path-WinNT = domain-name "/" user-name 230 Auth-User-Path-LDAP = LDAP-server "/" distinguished-name 231 ;syntax described in [6] 233 Auth-User-Path-Radius = Radius-server "/" user-name 234 Auth-User-Path-Local = user-name 235 domain-name = token 236 user-name = token 237 LDAP-server = host-name | ip-address 238 Radius-server = host-name | ip-address 240 Examples (in plain text, not yet base-64 encoded): 242 WinNT://mycompany.com/mike.smith 243 LDAP://192.168.12.100/o=mycompany, ou=engineering, cn=mike.smith 244 Radius://192.168.12.101/mike.smith 245 Local://mike.smith 247 3.5 X-Authenticated-Groups 249 If the user who issued the HTTP request has been authenticated and the 250 user belongs to some groups and the ICAP client knows these groups, the 251 ICAP client can assemble an Auth-Group-URI-List and send a base-64 252 encoded version of it as a value of the X-Authenticated-Groups header. 253 A linefeed character (0x0A) separates groups in the list. (Commas cannot 254 be used as separator because they are ambiguous for some authentication 255 schemes like LDAP). 256 The syntax of the Auth-Group-URI-List is 258 Syntax: 259 X-Authenticated-Groups-Header = "X-Authenticated-Groups: " 260 base64-encoded-Auth-Group-URI-List 261 Auth-Group-URI-List = Auth-Group-URI *( LF Auth-Group-URI ) 262 Auth-Group-URI = Auth-Scheme "://" Auth-Group-Path 264 The Auth-Group-Path depends on the authentication scheme 266 Auth-Group-Path = Auth-Group-Path-WinNT | Auth-Group-Path-LDAP | 267 Auth-Group-Path-Local 269 Auth-Group-Path-WinNT = domain-name "/" group-name 270 Auth-Group-Path-LDAP = LDAP-server "/" distinguished-name 271 Auth-Group-Path-Local = group-name 272 group-name = token 274 Examples (in plain text, not yet base-64 encoded): 276 WinNT://mycompany.com/marketing[LF]WinNT://mycompany.com/sales 277 LDAP://192.168.12.100/o=mycompany, ou=engineering 278 Local://sales[LF]WinNT://mycompany.com/sales 280 3.6 ICAP request example 282 This is an example of a REQMOD ICAP request that includes all of the 283 headers described above: 285 REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0 286 Host: icap-server.net 287 Encapsulated: req-hdr=0, null-body=170 288 X-Client-IP: 192.168.3.67 289 X-Server-IP: 123.45.67.89 290 X-Subscriber-ID: mike.smith@mycompany.com 291 X-Authenticated-User: TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wYW55LCBvdT 292 1lbmdpbmVlcmluZywgY249bWlrZS5zbWl0aA== 293 X-Authenticated-Groups: 294 TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wYW55LCBvdT1lbmdpbmVlcmluZw== 295 [CRLF] 296 GET / HTTP/1.1 297 Host: www.origin-server.com 298 Accept: text/html, text/plain 299 Accept-Encoding: compress 300 Cookie: ff39fk3jur@4ii0e02i 301 If-None-Match: "xyzzy", "r2d2xxxx" 302 [CRLF] 304 The authenticated user name and group name is the base-64 encoded 305 version of the LDAP samples above. 306 Please note again that the request could also be a RESPMOD request and 307 that this example assumes that there has been an X-Include response 308 header in the service's OPTIONS response that requested all of these 309 headers (see section 5.1). 311 4 User-defined ICAP response header extensions 313 This section describes the format and the usage of some specific 314 user-defined ICAP header extensions that MAY be used in REQMOD and 315 RESPMOD responses, namely 317 X-ICAP-Profile 318 X-Attribute 319 X-Attribute-Cacheability 320 X-Attribute-Prefix 322 4.1 X-ICAP-Profile 324 The request headers described in section 3 are often used by the ICAP 325 service to determine a user profile that has to be applied. The name of 326 this profile MAY be returned to the ICAP client with the X-ICAP-Profile 327 header. Its main purpose is logging of the profile by the ICAP client. 329 4.2 X-Attribute 331 Some ICAP services do some kind of content classification; a typical 332 example is an Internet Access Control module that does URL blocking by 333 categorization of URLs in REQMOD requests. 334 The X-Attribute header SHOULD be used to return a list of attributes to 335 the ICAP client. The list has comma-separated values of either 64-bit 336 unsigned integers or ASCII character strings. 338 If the ICAP server returned a list of values in the OPTIONS response 339 body, the X-Attribute header's value list MUST contain only those 340 values. 341 The X-Attribute header MUST be omitted if the content cannot be 342 classified. 344 Syntax: 345 X-Attribute-Header = "X-Attribute: " 1#Attribute 346 Attribute = uint64 | token 347 uint64 = 0..18446744073709551615 349 Example: 350 X-Attribute: sport, online-sales 352 4.3 X-Attribute-Cacheability 354 This header specifies for which client(s) the attributes returned with 355 the X-Attribute header MAY be reused. (Whether the attribute is 356 cacheable or not, and for how long, is the role of the Cache-Control and 357 Expires headers, see section 4.3.1 of [1]). 358 The X-Attribute-Cacheability header can specify that the X-Attribute 359 response is valid for all clients or only valid for one user or one user 360 group. 361 If the X-Attribute-Cacheability header is omitted, the X-Attribute 362 response is valid for all clients. 364 Syntax: 365 X-Attribute-Cacheability-Header = "X-Attribute-Cacheability: " 366 Cache-All | Cache-User | Cache-Group 367 Cache-All = "all" 368 Cache-User = "user=" base64-encoded-Auth-User-URI 369 Cache-Group = "group=" base64-encoded-Auth-Group-URI-List 371 The user or group name is usually a value from the 372 X-Authenticated-User/-Groups request headers. 374 Example: 375 X-Attribute-Cacheability: group=TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb 376 21wYW55LCBvdT1lbmdpbmVlcmluZw== 378 4.4 X-Attribute-Prefix 380 An ICAP service MAY want to tell its client that the attribute returned 381 in the X-Attribute header applies not only to the URL in the original 382 request, but also to every URL that contains a certain prefix. In these 383 cases, the ICAP server MAY use the X-Attribute-Prefix header to tell the 384 client how many characters of the original URL's path (not the host 385 name) are significant. 387 Example: 388 A URL categorization service is looking at the following requested HTTP 389 URL: 390 http://www.espn.com/football/latest-scores.html 391 and determines that its X-Attribute response is not only valid for this 392 specific HTML page but for all URLs that start with 393 http://www.espn.com/football/ 394 for example 395 http://www.espn.com/football/logo.gif 396 http://www.espn.com/football/germany/bundesliga.html 398 So the ICAP server has to use the length of the string "/football/" and 399 reply with the header 400 X-Attribute-Prefix: 10 402 To indicate that the X-Attribute response is valid for all URLs of the 403 host in the current request, the response MUST be 404 X-Attribute-Prefix: 1 405 (the length of the URL path "/"). 407 A value less than 1 MUST NOT be used. 409 If the Attribute-Prefix header is omitted, it is assumed that the 410 attribute returned in the Attribute header applies to just the URL in 411 the original request. 413 4.5 X-Infection-Found 415 A virus scanning or another threat prevention ICAP service MAY use this 416 header to inform the ICAP client about the threats that have been found 417 in the ICAP message body of the request. 419 The value of the X-Infection-Found header is a semicolon-separated 420 parameter list with exactly three parameters in a given order. 422 Syntax: 423 X-Infection-Found-Header = "X-Infection-Found: Type=" TypeID 424 "; Resolution=" ResolutionID 425 "; Threat=" ThreadDescription ";" 426 TypeID = 0 | 1 | 2 427 ResolutionID = 0 | 1 | 2 428 ThreadDescription = TEXT 430 The TypeID can currently be one of the following three values: zero for 431 virus infections, one for mail policy violations (e.g. illegal file 432 attachment name) or two for container violations (e.g. a zip file that 433 takes too long to decompress). 434 Note that neither the ICAP protocol [1] nor this document defines how 435 e-mails are vectored via ICAP to a callout server. The TypeID=1 case is 436 still mentioned here to be compatible with other virus scanner 437 deployments and to be complete if a future version of ICAP or extensions 438 will define e-mail encapsulation. 440 The ResolutionID can currently be one of the following three values: 441 zero for a file that was not repaired, one if the returned file in the 442 RESPMOD response is the repaired version of the infected file that was 443 encapsulated in the request or two if the original file should be 444 blocked or rejected due to container or mail policy violations. 445 Note that an ICAP server SHOULD NOT return an infected file in a RESPMOD 446 response and rely on correct interpretation of ResolutionID=2 by the 447 ICAP client to block the original data. ResolutionID zero and two are 448 typically used with an ICAP response that encapsulates an error message. 450 The ThreatDescription is a human-readable description of the threat, for 451 example the virus name or the policy violation description. It MAY 452 contain spaces, SHOULD NOT be quoted and MUST NOT contain semicolons 453 because it is terminated by the final semicolon of the header 454 definition. 456 Example: 457 X-Infection-Found: Type=0; Resolution=1; Threat=EICAR Test String; 458 The ICAP request contained data that is infected by the EICAR test 459 string; the file has been repaired (e.g. the eicar.com file has been 460 removed from an archive and the remaining archive is sent back in the 461 response). 463 4.6 X-Violations-Found 465 This header provides a detailed description of all the policy violations 466 (e.g. found viruses) that occurred while handling the request. 467 The X-Violations-Found header has a multi-line value starting with the 468 number of reported violations on the first line and four additional 469 lines per violation. 471 Syntax: 472 X-Violations-Found-Header = "X-Violations-Found:" count 1*( CR LF 473 Filename CR LF ThreadDescription CR LF ProblemID CR LF ResolutionID ) 474 count = 1*DIGIT 475 Filename = TEXT 476 ThreadDescription = TEXT 477 ProblemID = 1*DIGIT 478 ResolutionID = 0 | 1 | 2 480 The Filename MAY describe a single file within an archive that has been 481 vectored to the ICAP server. 483 The ThreatDescription is a human readable description of the threat, for 484 example the virus name or the policy violation description. It MAY 485 contain spaces and SHOULD NOT be quoted. 487 ProblemID is an integer identifier of the policy violation, for example 488 a virus ID. 490 The ResoltionID can currently be one of the following three values: zero 491 for a file that was not repaired, one if the violation has been repaired 492 or two if the violating part has been removed (usually used if a file 493 has been removed from a container). 495 Example: 496 X-Violations-Found: 2 497 test.zip/dir1/eicar.com 498 EICAR Test String 499 11101 500 2 501 test.zip/dir2/eicar.com 502 EICAR Test String 503 11101 504 2 506 4.7 X-Virus-ID 508 This header is a shorter alternative to the X-Infection-Found header. On 509 a single line it can contain any virus or threat description. The ICAP 510 client MAY log this information. 512 Syntax: 513 X-Virus-ID-Header = "X-Virus-ID:" OneLineUSTEXT 514 OneLineUSText = 1*( ) 516 Example: 517 X-Virus-ID: EICAR Test String 519 4.8 X-Response-Info 521 The value of this header is a one word description of the action that 522 the ICAP service applied on the content. 524 Syntax: 525 X-Response-Info-Header = "X-Response-Info:" token 527 Example: 528 X-Response-Info: Blocked 530 4.9 X-Response-Desc 532 The value of this header is a one line description about the action 533 that the ICAP service applied on the content. 535 Syntax: 536 X-Response-Desc-Header = "X-Response-Desc:" OneLineUSText 538 Example: 539 X-Response-Desc: URL category policy envoked 541 4.10 ICAP response examples 543 This is an example of a REQMOD ICAP response that includes all of the 544 headers described above (it is a possible response of the request 545 example of section 3.6): 547 ICAP/1.0 200 OK 548 ISTAG: "001-000-000006" 549 Encapsulated: req-hdr=0, null-body=170 550 Cache-Control: max-age=3600 551 X-ICAP-Profile: default 552 X-Attribute: humor 553 X-Attribute-Cacheability: user=TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wY 554 W55LCBvdT1lbmdpbmVlcmluZywgY249bWlrZS5zbWl0aA== 555 X-Attribute-Prefix: 1 556 [CRLF] 557 GET / HTTP/1.1 558 Accept: text/html, text/plain 559 Accept-Encoding: compress 560 Cookie: ff39fk3jur@4ii0e02i 561 Host: www.origin-server.com 562 If-None-Match: "xyzzy", "r2d2xxxx" 563 [CRLF] 564 This is an example of a RESPMOD ICAP response from an ICAP virus scanner 565 that detected a virus in the data that the HTTP server sent: 567 ICAP/1.0 200 OK 568 ISTAG: "001-000-000006" 569 Encapsulated: res-hdr=0, res-body=72 570 X-Infection-Found: Type=0; Resolution=0; Threat=EICAR Test String; 571 X-Violations-Found: 2 572 test.zip/dir1/eicar.com 573 EICAR Test String 574 11101 575 0 576 test.zip/dir2/eicar.com 577 EICAR Test String 578 11101 579 0 580 X-Virus-ID: EICAR Test String 581 [CRLF] 582 HTTP/1.1 403 Forbidden 583 Content-Type: text/html 584 Content-Length: 101 585 [CRLF] 586 65 587 588 The file download has been blocked due to a detected virus infection. 589 590 0 591 [CRLF] 592 5 OPTIONS response extensions 594 5.1 X-Include 596 There are known ICAP clients that follow the X-Client-IP specification 597 of [2] and always include this header; other ICAP client implementations 598 only add the headers listed in section 3 if the ICAP server requested 599 these headers with the X-Include header of its OPTIONS response. 600 With this implementation the client can save time and resources to 601 collect the meta information if it is not needed and personal 602 information is only sent upon request. 603 To ensure maximum interoperability, an ICAP server SHOULD be prepared to 604 run with any ICAP client. Therefore the ICAP server MUST advertise those 605 headers of section 3 in which it is interested, within the X-Include 606 header of the OPTIONS response. 607 An ICAP client SHOULD only send those headers that are returned in the 608 X-Include OPTIONS response header, unless it knows that the ICAP service 609 does not support an X-Include header although it needs the header of 610 section 3. 612 The value of the X-Include header is a comma-separated list of any ICAP 613 header extension field names that the ICAP server wants the client to 614 add to the requests if the information is available and the header is 615 supported. Although this document only knows the headers listed in 616 section 3, the value list may be extended by other (user-defined) 617 headers. 618 An ICAP server MUST NOT include any of the standard headers defined in 619 [1] into the value list. An ICAP client MUST ignore those header names 620 it does not know. 622 Syntax 623 X-Include-Header = "X-Include: " 1#Header-Field 624 Header-Field = token 626 5.2 Attribute-List response body 628 Section 4.10.2 of [1] describes the syntax of an optional body of the 629 ICAP response to an OPTIONS request but that document does not introduce 630 any response body. 631 This document introduces the Attribute-List response body for responses 632 to OPTIONS requests. This body lists all possible values of the 633 X-Attribute header. An ICAP client MAY use this list to pre-allocate 634 structures rather than a dynamic resource allocation during processing 635 of the X-Attribute header values, but an ICAP client SHOULD NOT rely on 636 the existence of this response body attribute list. 637 If an ICAP server sends an Attribute-List response body it MUST NOT use 638 any other attributes in the X-Attribute response. 640 In order to add the response body, the ICAP server has to exchange the 641 "null-body=0" value of the Encapsulated header with an "opt-body=0" 642 value and add the Opt-Body-Type header with the value "Attribute-List". 644 The chunk-encoded body then contains a list of attributes that can be 645 used in X-Attribute headers (see section 4.2). The attribute list needs 646 to be separated by CRLF and MAY include additional spaces for formatting 647 reasons which MUST be ignored by the ICAP client. 648 The first line of the list MUST be the string 649 "X-ICAP-Attribute-[service-ID]" where [service-ID] is the value of the 650 Service-ID header field. The last line of the list MUST contain the 651 character ";" plus an additional CRLF sequence. In the example in 652 section 5.3 this ends up being an empty line because of the additional 653 CRLF that belongs to the chunked encoding. 655 5.3 Example of an OPTIONS response 657 ICAP/1.0 200 OK 658 Date: Fri, 31 Jan 2003 12:00:00 GMT 659 ISTAG: "5BDEEEA9-12E4-2" 660 Encapsulated: opt-body=0 661 Opt-Body-Type: Attribute-List 662 Max-Connections: 100 663 Methods: REQMOD 664 Options-TTL: 3600 665 Service: XYZ Technology URL Blocking Software 5.0 666 Service-ID: XYZTech 667 X-Include: X-Client-IP, X-Authenticated-User 668 [CRLF] 669 38 670 X-ICAP-Attribute-XYZTech 671 sex 672 gambling 673 jobs 674 ; 676 0 677 [CRLF] 678 6 The LOG method 680 A new ICAP method is introduced, called LOG. It can be used to notify 681 the ICAP service about the end of an HTTP transaction. It can be useful 682 in the following two cases: 683 - if the ICAP server wants to log information about the modified 684 request, but all of the information needed (such as the size of the 685 object returned from the origin server) is not available at the time the 686 REQMOD request is made, or 687 - if the ICAP server wants to be notified and log information when a 688 previously-cached REQMOD response is reused by an ICAP client. 690 The LOG method is an optional additional method for REQMOD services; it 691 is meant to complement the REQMOD request. An ICAP client MUST send a 692 LOG request only if a REQMOD request was sent or if it was able to use a 693 cached REQMOD response. That means that a LOG request always has a 694 corresponding REQMOD request. 696 The ICAP protocol allows the addition of user-defined methods (see 697 section 4.3.2 of [1]). Section 4.10.2 of [1] defines the Methods 698 response header of the OPTIONS request as a list of methods, but section 699 6.4 of [1] discourages a service with one URI to support multiple 700 methods. 701 Therefore ICAP server implementations SHOULD define a distinct service 702 for LOG and allow the REQMOD and LOG services to communicate internally. 703 Defining a distinct LOG service ensures maximum interoperability because 704 it can only be configured at ICAP clients supporting LOG and all other 705 ICAP clients will not see the LOG method in the OPTIONS response. 707 But even for distinct services an ICAP server MUST send the same 708 X-Include header in the OPTIONS responses for the REQMOD and the 709 corresponding LOG service. 711 6.1 LOG request 713 The first request line follows the normal ICAP request specification 714 (4.3.2 of [1]). 715 The LOG request MUST include a number of required headers, namely: 716 Host (required by 4.3.2 of [1]) 717 Request-Date (new ICAP header defined below in 6.1.1) 718 Object-Length (new ICAP header defined below in 6.1.2) 719 Requested-URI (new ICAP header defined below in 6.1.3) 721 In addition, the LOG request MUST include these headers if they are 722 added to REQMOD requests: 723 X-Client-IP 724 X-Server-IP 725 X-Authenticated-User 726 X-Authenticated-Groups 728 And these headers MUST be added if they were present in the REQMOD 729 response: 730 LOG-[service-ID] (new ICAP header defined below in 6.1.4) 732 6.1.1 Request-Date 734 This represents the date and time of the original REQMOD request that is 735 now being logged. It does NOT represent the date and time the log 736 request is being sent to the ICAP server. 738 Syntax: 739 Request-Date-Header = "Request-Date: " rfc1123-date 740 ; see [4] and 3.3.1 of [5] 742 Example: 743 Request-Date: Sun, 16 Feb 2003 23:33:55 GMT 745 6.1.2 Object-Length 747 This represents the size of the object downloaded from the origin server 748 (maybe modified by RESPMOD services), represented as an unsigned 8-byte 749 integer. When a Content-Length header is used in the origin server's 750 response, Object-Length will be the same as the content length. If 751 chunked encoding or TCP close was used to transfer the body from the 752 origin server, Object-Length will contain the number of bytes read from 753 the server. 755 Syntax: 756 Object-Length-Header = "Object-Length: " uint64 758 Example: 759 Object-Length: 12345678 761 6.1.3 Requested-URI 763 This represents the URI specified in the original client's request. 765 Syntax: 766 Requested-URI-Header = "Requested-URI: " URI 768 Example: 769 Requested-URI: http://www.origin-server.com/origin-resource 771 6.1.4 LOG-[service-ID] and X-LOG-[service-ID] 773 The REQMOD response MAY contain an X-LOG-[service-ID] header. 774 [service-ID] needs to be replaced with the service-ID value that has 775 been advertised in the OPTIONS response. The value of the 776 X-LOG-[service-ID] header can be of any type. 777 If the ICAP client finds an X-LOG-[service-ID] header in the REQMOD 778 response it MUST add a LOG-[service-ID] header with the same value to 779 the LOG request and it MUST omit this header otherwise. 780 Adding extension headers to REQMOD requires the X- prefixed form while 781 LOG-[service-ID] has been introduced as a standard header for the LOG 782 method, so the inconsistency in the two header names is mainly due to 783 historic reasons. 784 In order to remain backward compatible an ICAP client supporting LOG 785 SHOULD also look for a LOG-[service-ID] header in the REQMOD response 786 (without the X- prefix). Regardless of whether LOG-[service-ID] or 787 X-LOG-[service-ID] has been used in REQMOD, the header in the LOG 788 request MUST be LOG-[service-ID] (without X- prefix). 790 6.2 Request body 792 No body for a LOG request is defined in this document. Future extensions 793 MAY add a body; therefore, the LOG request MUST also include the always 794 required encapsulated header, indicating that no body is following, by 795 specifying: 796 Encapsulated: null-body=0 798 6.3 LOG response 800 There is no LOG response defined. This method is not a request/response 801 message but a notification that is sent by the ICAP client to the 802 server. 803 The ICAP server MUST NOT send a response upon a LOG request. 805 7 Security considerations 807 Users of ICAP should take note that ICAP messages (including the 808 user-defined extension headers proposed in this document) are not 809 encrypted for transit by default. In the absence of some other form of 810 encryption at the link or network layers, eavesdroppers may be able to 811 record the unencrypted transactions between ICAP clients and ICAP 812 servers, including the information contained in the user-defined header 813 extensions proposed in this document. 815 8 References 817 [1] J. Elson, A. Cerpa: "ICAP - the Internet Content Adaptation 818 Protocol", Request for Comments 3507, April 2003. 820 [2] Crocker, D., "Standard for the format of ARPA Internet text 821 messages", Request for Comments 822, August 1982. 823 [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement 824 Levels", RFC 2119, March 1997. 826 [4] Braden, R., "Requirements for Internet hosts - application and 827 support", STD 3, RFC 1123, October 1989. 829 [5] Fielding, R., et. al., "Hypertext Transfer Protocol -- 830 HTTP/1.1", Request for Comments 2616, June 1999. 832 [6] Kille, S., and M. Wahl, "Lightweight Directory Access Protocol 833 (v3): UTF-8 String Representation of Distinguished Names", RFC 834 2253, December 1997. 836 Authors' Addresses 838 Martin Stecher martin.stecher@webwasher.com 839 webwasher AG 840 Vattmannstr. 3 841 33100 Paderborn 842 Germany 844 Jeffrey Merrick Jeffrey.Merrick@netapp.com 845 Network Appliance, Inc. 846 495 East Java Drive 847 Sunnyvale, CA 94089 848 USA 850 Andre Beck abeck@bell-labs.com 851 Markus Hofmann hofmann@bell-labs.com 852 Bell Labs Research 853 Lucent Technologies 854 101 Crawfords Corner Rd. 855 Holmdel, NJ 07733 856 USA 858 Contributors 859 Best thanks to all who helped in compiling and creating this draft, 860 including the following contributors: 862 Darrell Long 863 Blue Coat Systems, Inc. 865 Rui Ataide 866 Symantec Corporation 868 Full Copyright Statement 869 Copyright (C) The Internet Society (2003). All Rights Reserved. 871 This document and translations of it may be copied and furnished to 872 others, and derivative works that comment on or otherwise explain it 873 or assist in its implementation may be prepared, copied, published 874 and distributed, in whole or in part, without restriction of any 875 kind, provided that the above copyright notice and this paragraph are 876 included on all such copies and derivative works. However, this 877 document itself may not be modified in any way, such as by removing 878 the copyright notice or references to the Internet Society or other 879 Internet organizations, except as needed for the purpose of 880 developing Internet standards in which case the procedures for 881 copyrights defined in the Internet Standards process must be 882 followed, or as required to translate it into languages other than 883 English. 885 The limited permissions granted above are perpetual and will not be 886 revoked by the Internet Society or its successors or assigns. 888 This document and the information contained herein is provided on an 889 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 890 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 891 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 892 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 893 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 895 Acknowledgement 897 Funding for the RFC Editor function is currently provided by the 898 Internet Society.