Internet-Draft M. Stecher Expires: October, 2003 webwasher AG Category: Informational J. Merrick Network Appliance A. Beck M. Hofmann Lucent Technologies April, 2003 ICAP Extensions draft-stecher-icap-subid-00.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire in October, 2003. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract The Internet Content Adaptation Protocol (ICAP) [1] provides simple, object-based content vectoring for HTTP services. User-defined header extensions are widely used by many ICAP client and server implementations. Some implementations have also introduced new ICAP methods. This document describes and defines a number of ICAP extensions to ensure ongoing interoperability between the implementations. Stecher, et. al. Expires October, 2003 [Page 1] Internet-Draft ICAP Extensions April 2003 Table of Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 3 3 User-defined ICAP request header extensions . . . . . . . . 4 3.1 X-Client-IP . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 X-Server-IP . . . . . . . . . . . . . . . . . . . . . . . . 5 3.3 X-Subscriber-ID . . . . . . . . . . . . . . . . . . . . . . 5 3.4 X-Authenticated-User . . . . . . . . . . . . . . . . . . . . 5 3.5 X-Authenticated-Groups . . . . . . . . . . . . . . . . . . . 6 3.6 ICAP request example . . . . . . . . . . . . . . . . . . . . 7 4 User-defined ICAP response header extensions . . . . . . . . 7 4.1 X-ICAP-Profile . . . . . . . . . . . . . . . . . . . . . . . 7 4.2 X-Attribute . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 X-Attribute-Cacheability . . . . . . . . . . . . . . . . . . 8 4.4 X-Attribute-Prefix . . . . . . . . . . . . . . . . . . . . . 9 4.5 X-Infection-Found . . . . . . . . . . . . . . . . . . . . . 9 4.6 X-Violations-Found . . . . . . . . . . . . . . . . . . . . . 10 4.7 X-Virus-ID . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.8 X-Response-Info . . . . . . . . . . . . . . . . . . . . . . 12 4.9 X-Response-Desc . . . . . . . . . . . . . . . . . . . . . . 12 4.10 ICAP response examples . . . . . . . . . . . . . . . . . . . 12 5 OPTIONS response extensions . . . . . . . . . . . . . . . . 14 5.1 X-Include . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.2 Attribute-List response body . . . . . . . . . . . . . . . . 14 5.3 Example of an OPTIONS response . . . . . . . . . . . . . . . 15 6 The LOG method . . . . . . . . . . . . . . . . . . . . . . . 16 6.1 LOG request . . . . . . . . . . . . . . . . . . . . . . . . 16 6.1.1 Request-Date . . . . . . . . . . . . . . . . . . . . . . . . 17 6.1.2 Object-Length . . . . . . . . . . . . . . . . . . . . . . . 17 6.1.3 Requested-URI . . . . . . . . . . . . . . . . . . . . . . . 17 6.1.4 LOG-[service-ID] and X-LOG-[service-ID] . . . . . . . . . . 18 6.2 Request body . . . . . . . . . . . . . . . . . . . . . . . . 18 6.3 LOG response . . . . . . . . . . . . . . . . . . . . . . . . 18 7 Security Considerations . . . . . . . . . . . . . . . . . . 18 8 References . . . . . . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 19 Contributors . . . . . . . . . . . . . . . . . . . . . . . . 20 Full Copyright Statement . . . . . . . . . . . . . . . . . . 20 Stecher, et. al. Expires October, 2003 [Page 2] Internet-Draft ICAP Extensions April 2003 1 Introduction The Internet Content Adaptation Protocol (ICAP) [1] provides simple, object-based content vectoring for HTTP services. An ICAP request or response typically includes an encapsulated HTTP message. Some ICAP services, however, require more information than what is contained in the encapsulated HTTP message. For example, some services require information about the identity of the source of the encapsulated HTTP message. This document specifies user-defined header extensions which allow an ICAP client and/or server to include certain meta information in ICAP requests or responses. In compliance with the precedent established by the Internet mail format [2] and later adopted by HTTP [5], the user-defined headers follow the "X-" naming convention. ICAP implementations MAY ignore these "X-" headers without loss of compliance with the protocol as defined in [1]. Each header field consists of a name followed by a colon (":") and the field value. Field names are case-insensitive. ICAP follows the rules as described in section 4.2 of [5]. In compliance with section 4.3 of the ICAP specification [1] user-defined header extensions are allowed. Section 4.3.2 of the ICAP protocol [1] also allows the adding of user-defined extension methods. Section 6 of this document defines a new method that has been introduced. 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 of [1]. 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 RFC 2119 [3]. This grammar of the syntax definitions given in this document is specified in terms of the augmented Backus-Naur Form (BNF) similar to that used by the HTTP/1.1 specification (See Section 2.1 of [5]). Implementers will need to be familiar with the notation in order to understand this specification. Many header values (where noted) have exactly the same grammar and semantics as in HTTP/1.1. We do not reproduce this grammar here. Stecher, et. al. Expires October, 2003 [Page 3] Internet-Draft ICAP Extensions April 2003 3 User-defined ICAP request header extensions This section describes the format and the usage of some specific user-defined ICAP header extensions that MAY be used in REQMOD and RESPMOD requests, namely X-Client-IP X-Server-IP X-Subscriber-ID X-Authenticated-User X-Authenticated-Groups All of these headers provide meta information about the source of the encapsulated HTTP message. Such information might be required by ICAP services, which modify Web pages based on a user profile or a set of user parameters. Other examples include user-specific content filtering services and all types of subscription-based services. As the ICAP server typically communicates with the ICAP client rather than the source of encapsulated HTTP messages, it cannot extract the identity of the source of the HTTP messages from the underlying transport session. Furthermore, ICAP itself does not define a mechanism for the exchange of such information between ICAP client and ICAP server. For these reasons, this section specifies user-defined request header extensions for ICAP, which allow the ICAP client to include meta information about the source of the encapsulated HTTP message. If the meta information for some header is not available, the header field MUST be omitted. See section 5.1 about the X-Include header to request the headers defined in this section. 3.1 X-Client-IP The value of the X-Client-IP header field is the IP source address of the encapsulated HTTP request. The IP address MUST be a dotted-decimal IPv4 address or an IPv6 hex address. For ICAP messages in request modification mode (REQMOD), the X-Client-IP header field MUST contain the IP source address of the encapsulated HTTP request. For ICAP messages in response modification mode (RESPMOD), the X-Client-IP header field MUST contain the IP source address of the client issuing the HTTP request (that resulted in the encapsulated HTTP response). Note that this is the IP source address of the corresponding HTTP request and not the IP source address of the encapsulated HTTP response. Stecher, et. al. Expires October, 2003 [Page 4] Internet-Draft ICAP Extensions April 2003 An ICAP client MUST NOT include the X-Client-IP header if it is not aware of the source IP address of the client issuing the HTTP request. 3.2 X-Server-IP The value of the X-Server-IP header field is the IP destination address of the encapsulated HTTP request. It specifies the HTTP destination host and not the IP address of any intermediate proxy server. The IP address MUST be a dotted-decimal IPv4 address or an IPv6 hex address. 3.3 X-Subscriber-ID This header contains a unique subscriber ID of the user who issued the HTTP request. This MAY be an e-mail address but the exact format of the subscriber ID is not specified by ICAP or this document. The ICAP client MUST NOT include an X-Subscriber-ID header in the outgoing ICAP message if it is not aware of the subscriber ID of the client issuing the HTTP request. 3.4 X-Authenticated-User If the user who issued the HTTP request has been authenticated and the ICAP client knows the authenticated user name, the ICAP client can assemble an Auth-User-URI and send a base-64 encoded version of it as a value of the X-Authenticated-User header. The syntax of the Auth-User-URI is Syntax: X-Authenticated-User-Header = "X-Authenticated-User: " base64-encoded-Auth-User-URI Auth-User-URI = Auth-Scheme "://" Auth-User-Path By now Auth-Scheme is known as one of these values and can be extended by additional authentication schemes in the future: Auth-Scheme = "WinNT" | "LDAP" | "Radius" | "Local" The Auth-Scheme name MUST be treated as case insensitive. The Auth-User-Path depends on the authentication scheme: Auth-User-Path = Auth-User-Path-WinNT | Auth-User-Path-LDAP | Auth-User-Path-Radius | Auth-User-Path-Local Auth-User-Path-WinNT = domain-name "/" user-name Auth-User-Path-LDAP = LDAP-server "/" distinguished-name ;syntax described in [6] Stecher, et. al. Expires October, 2003 [Page 5] Internet-Draft ICAP Extensions April 2003 Auth-User-Path-Radius = Radius-server "/" user-name Auth-User-Path-Local = user-name domain-name = token user-name = token LDAP-server = host-name | ip-address Radius-server = host-name | ip-address Examples (in plain text, not yet base-64 encoded): WinNT://mycompany.com/mike.smith LDAP://192.168.12.100/o=mycompany, ou=engineering, cn=mike.smith Radius://192.168.12.101/mike.smith Local://mike.smith 3.5 X-Authenticated-Groups If the user who issued the HTTP request has been authenticated and the user belongs to some groups and the ICAP client knows these groups, the ICAP client can assemble an Auth-Group-URI-List and send a base-64 encoded version of it as a value of the X-Authenticated-Groups header. A linefeed character (0x0A) separates groups in the list. (Commas cannot be used as separator because they are ambiguous for some authentication schemes like LDAP). The syntax of the Auth-Group-URI-List is Syntax: X-Authenticated-Groups-Header = "X-Authenticated-Groups: " base64-encoded-Auth-Group-URI-List Auth-Group-URI-List = Auth-Group-URI *( LF Auth-Group-URI ) Auth-Group-URI = Auth-Scheme "://" Auth-Group-Path The Auth-Group-Path depends on the authentication scheme Auth-Group-Path = Auth-Group-Path-WinNT | Auth-Group-Path-LDAP | Auth-Group-Path-Local Auth-Group-Path-WinNT = domain-name "/" group-name Auth-Group-Path-LDAP = LDAP-server "/" distinguished-name Auth-Group-Path-Local = group-name group-name = token Examples (in plain text, not yet base-64 encoded): WinNT://mycompany.com/marketing[LF]WinNT://mycompany.com/sales LDAP://192.168.12.100/o=mycompany, ou=engineering Local://sales[LF]WinNT://mycompany.com/sales Stecher, et. al. Expires October, 2003 [Page 6] Internet-Draft ICAP Extensions April 2003 3.6 ICAP request example This is an example of a REQMOD ICAP request that includes all of the headers described above: REQMOD icap://icap-server.net/server?arg=87 ICAP/1.0 Host: icap-server.net Encapsulated: req-hdr=0, null-body=170 X-Client-IP: 192.168.3.67 X-Server-IP: 123.45.67.89 X-Subscriber-ID: mike.smith@mycompany.com X-Authenticated-User: TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wYW55LCBvdT 1lbmdpbmVlcmluZywgY249bWlrZS5zbWl0aA== X-Authenticated-Groups: TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wYW55LCBvdT1lbmdpbmVlcmluZw== [CRLF] GET / HTTP/1.1 Host: www.origin-server.com Accept: text/html, text/plain Accept-Encoding: compress Cookie: ff39fk3jur@4ii0e02i If-None-Match: "xyzzy", "r2d2xxxx" [CRLF] The authenticated user name and group name is the base-64 encoded version of the LDAP samples above. Please note again that the request could also be a RESPMOD request and that this example assumes that there has been an X-Include response header in the service's OPTIONS response that requested all of these headers (see section 5.1). 4 User-defined ICAP response header extensions This section describes the format and the usage of some specific user-defined ICAP header extensions that MAY be used in REQMOD and RESPMOD responses, namely X-ICAP-Profile X-Attribute X-Attribute-Cacheability X-Attribute-Prefix 4.1 X-ICAP-Profile The request headers described in section 3 are often used by the ICAP service to determine a user profile that has to be applied. The name of this profile MAY be returned to the ICAP client with the X-ICAP-Profile header. Its main purpose is logging of the profile by the ICAP client. Stecher, et. al. Expires October, 2003 [Page 7] Internet-Draft ICAP Extensions April 2003 4.2 X-Attribute Some ICAP services do some kind of content classification; a typical example is an Internet Access Control module that does URL blocking by categorization of URLs in REQMOD requests. The X-Attribute header SHOULD be used to return a list of attributes to the ICAP client. The list has comma-separated values of either 64-bit unsigned integers or ASCII character strings. If the ICAP server returned a list of values in the OPTIONS response body, the X-Attribute header's value list MUST contain only those values. The X-Attribute header MUST be omitted if the content cannot be classified. Syntax: X-Attribute-Header = "X-Attribute: " 1#Attribute Attribute = uint64 | token uint64 = 0..18446744073709551615 Example: X-Attribute: sport, online-sales 4.3 X-Attribute-Cacheability This header specifies for which client(s) the attributes returned with the X-Attribute header MAY be reused. (Whether the attribute is cacheable or not, and for how long, is the role of the Cache-Control and Expires headers, see section 4.3.1 of [1]). The X-Attribute-Cacheability header can specify that the X-Attribute response is valid for all clients or only valid for one user or one user group. If the X-Attribute-Cacheability header is omitted, the X-Attribute response is valid for all clients. Syntax: X-Attribute-Cacheability-Header = "X-Attribute-Cacheability: " Cache-All | Cache-User | Cache-Group Cache-All = "all" Cache-User = "user=" base64-encoded-Auth-User-URI Cache-Group = "group=" base64-encoded-Auth-Group-URI-List The user or group name is usually a value from the X-Authenticated-User/-Groups request headers. Example: X-Attribute-Cacheability: group=TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb 21wYW55LCBvdT1lbmdpbmVlcmluZw== Stecher, et. al. Expires October, 2003 [Page 8] Internet-Draft ICAP Extensions April 2003 4.4 X-Attribute-Prefix An ICAP service MAY want to tell its client that the attribute returned in the X-Attribute header applies not only to the URL in the original request, but also to every URL that contains a certain prefix. In these cases, the ICAP server MAY use the X-Attribute-Prefix header to tell the client how many characters of the original URL's path (not the host name) are significant. Example: A URL categorization service is looking at the following requested HTTP URL: http://www.espn.com/football/latest-scores.html and determines that its X-Attribute response is not only valid for this specific HTML page but for all URLs that start with http://www.espn.com/football/ for example http://www.espn.com/football/logo.gif http://www.espn.com/football/germany/bundesliga.html So the ICAP server has to use the length of the string "/football/" and reply with the header X-Attribute-Prefix: 10 To indicate that the X-Attribute response is valid for all URLs of the host in the current request, the response MUST be X-Attribute-Prefix: 1 (the length of the URL path "/"). A value less than 1 MUST NOT be used. If the Attribute-Prefix header is omitted, it is assumed that the attribute returned in the Attribute header applies to just the URL in the original request. 4.5 X-Infection-Found A virus scanning or another threat prevention ICAP service MAY use this header to inform the ICAP client about the threats that have been found in the ICAP message body of the request. The value of the X-Infection-Found header is a semicolon-separated parameter list with exactly three parameters in a given order. Stecher, et. al. Expires October, 2003 [Page 9] Internet-Draft ICAP Extensions April 2003 Syntax: X-Infection-Found-Header = "X-Infection-Found: Type=" TypeID "; Resolution=" ResolutionID "; Threat=" ThreadDescription ";" TypeID = 0 | 1 | 2 ResolutionID = 0 | 1 | 2 ThreadDescription = TEXT The TypeID can currently be one of the following three values: zero for virus infections, one for mail policy violations (e.g. illegal file attachment name) or two for container violations (e.g. a zip file that takes too long to decompress). Note that neither the ICAP protocol [1] nor this document defines how e-mails are vectored via ICAP to a callout server. The TypeID=1 case is still mentioned here to be compatible with other virus scanner deployments and to be complete if a future version of ICAP or extensions will define e-mail encapsulation. The ResolutionID can currently be one of the following three values: zero for a file that was not repaired, one if the returned file in the RESPMOD response is the repaired version of the infected file that was encapsulated in the request or two if the original file should be blocked or rejected due to container or mail policy violations. Note that an ICAP server SHOULD NOT return an infected file in a RESPMOD response and rely on correct interpretation of ResolutionID=2 by the ICAP client to block the original data. ResolutionID zero and two are typically used with an ICAP response that encapsulates an error message. The ThreatDescription is a human-readable description of the threat, for example the virus name or the policy violation description. It MAY contain spaces, SHOULD NOT be quoted and MUST NOT contain semicolons because it is terminated by the final semicolon of the header definition. Example: X-Infection-Found: Type=0; Resolution=1; Threat=EICAR Test String; The ICAP request contained data that is infected by the EICAR test string; the file has been repaired (e.g. the eicar.com file has been removed from an archive and the remaining archive is sent back in the response). 4.6 X-Violations-Found This header provides a detailed description of all the policy violations (e.g. found viruses) that occurred while handling the request. The X-Violations-Found header has a multi-line value starting with the number of reported violations on the first line and four additional lines per violation. Stecher, et. al. Expires October, 2003 [Page 10] Internet-Draft ICAP Extensions April 2003 Syntax: X-Violations-Found-Header = "X-Violations-Found:" count 1*( CR LF Filename CR LF ThreadDescription CR LF ProblemID CR LF ResolutionID ) count = 1*DIGIT Filename = TEXT ThreadDescription = TEXT ProblemID = 1*DIGIT ResolutionID = 0 | 1 | 2 The Filename MAY describe a single file within an archive that has been vectored to the ICAP server. The ThreatDescription is a human readable description of the threat, for example the virus name or the policy violation description. It MAY contain spaces and SHOULD NOT be quoted. ProblemID is an integer identifier of the policy violation, for example a virus ID. The ResoltionID can currently be one of the following three values: zero for a file that was not repaired, one if the violation has been repaired or two if the violating part has been removed (usually used if a file has been removed from a container). Example: X-Violations-Found: 2 test.zip/dir1/eicar.com EICAR Test String 11101 2 test.zip/dir2/eicar.com EICAR Test String 11101 2 4.7 X-Virus-ID This header is a shorter alternative to the X-Infection-Found header. On a single line it can contain any virus or threat description. The ICAP client MAY log this information. Syntax: X-Virus-ID-Header = "X-Virus-ID:" OneLineUSTEXT OneLineUSText = 1*( ) Example: X-Virus-ID: EICAR Test String Stecher, et. al. Expires October, 2003 [Page 11] Internet-Draft ICAP Extensions April 2003 4.8 X-Response-Info The value of this header is a one word description of the action that the ICAP service applied on the content. Syntax: X-Response-Info-Header = "X-Response-Info:" token Example: X-Response-Info: Blocked 4.9 X-Response-Desc The value of this header is a one line description about the action that the ICAP service applied on the content. Syntax: X-Response-Desc-Header = "X-Response-Desc:" OneLineUSText Example: X-Response-Desc: URL category policy envoked 4.10 ICAP response examples This is an example of a REQMOD ICAP response that includes all of the headers described above (it is a possible response of the request example of section 3.6): ICAP/1.0 200 OK ISTAG: "001-000-000006" Encapsulated: req-hdr=0, null-body=170 Cache-Control: max-age=3600 X-ICAP-Profile: default X-Attribute: humor X-Attribute-Cacheability: user=TERBUDovLzE5Mi4xNjguMTIuMTAwL289bXljb21wY W55LCBvdT1lbmdpbmVlcmluZywgY249bWlrZS5zbWl0aA== X-Attribute-Prefix: 1 [CRLF] GET / HTTP/1.1 Accept: text/html, text/plain Accept-Encoding: compress Cookie: ff39fk3jur@4ii0e02i Host: www.origin-server.com If-None-Match: "xyzzy", "r2d2xxxx" [CRLF] Stecher, et. al. Expires October, 2003 [Page 12] Internet-Draft ICAP Extensions April 2003 This is an example of a RESPMOD ICAP response from an ICAP virus scanner that detected a virus in the data that the HTTP server sent: ICAP/1.0 200 OK ISTAG: "001-000-000006" Encapsulated: res-hdr=0, res-body=72 X-Infection-Found: Type=0; Resolution=0; Threat=EICAR Test String; X-Violations-Found: 2 test.zip/dir1/eicar.com EICAR Test String 11101 0 test.zip/dir2/eicar.com EICAR Test String 11101 0 X-Virus-ID: EICAR Test String [CRLF] HTTP/1.1 403 Forbidden Content-Type: text/html Content-Length: 101 [CRLF] 65 The file download has been blocked due to a detected virus infection. 0 [CRLF] Stecher, et. al. Expires October, 2003 [Page 13] Internet-Draft ICAP Extensions April 2003 5 OPTIONS response extensions 5.1 X-Include There are known ICAP clients that follow the X-Client-IP specification of [2] and always include this header; other ICAP client implementations only add the headers listed in section 3 if the ICAP server requested these headers with the X-Include header of its OPTIONS response. With this implementation the client can save time and resources to collect the meta information if it is not needed and personal information is only sent upon request. To ensure maximum interoperability, an ICAP server SHOULD be prepared to run with any ICAP client. Therefore the ICAP server MUST advertise those headers of section 3 in which it is interested, within the X-Include header of the OPTIONS response. An ICAP client SHOULD only send those headers that are returned in the X-Include OPTIONS response header, unless it knows that the ICAP service does not support an X-Include header although it needs the header of section 3. The value of the X-Include header is a comma-separated list of any ICAP header extension field names that the ICAP server wants the client to add to the requests if the information is available and the header is supported. Although this document only knows the headers listed in section 3, the value list may be extended by other (user-defined) headers. An ICAP server MUST NOT include any of the standard headers defined in [1] into the value list. An ICAP client MUST ignore those header names it does not know. Syntax X-Include-Header = "X-Include: " 1#Header-Field Header-Field = token 5.2 Attribute-List response body Section 4.10.2 of [1] describes the syntax of an optional body of the ICAP response to an OPTIONS request but that document does not introduce any response body. This document introduces the Attribute-List response body for responses to OPTIONS requests. This body lists all possible values of the X-Attribute header. An ICAP client MAY use this list to pre-allocate structures rather than a dynamic resource allocation during processing of the X-Attribute header values, but an ICAP client SHOULD NOT rely on the existence of this response body attribute list. If an ICAP server sends an Attribute-List response body it MUST NOT use any other attributes in the X-Attribute response. Stecher, et. al. Expires October, 2003 [Page 14] Internet-Draft ICAP Extensions April 2003 In order to add the response body, the ICAP server has to exchange the "null-body=0" value of the Encapsulated header with an "opt-body=0" value and add the Opt-Body-Type header with the value "Attribute-List". The chunk-encoded body then contains a list of attributes that can be used in X-Attribute headers (see section 4.2). The attribute list needs to be separated by CRLF and MAY include additional spaces for formatting reasons which MUST be ignored by the ICAP client. The first line of the list MUST be the string "X-ICAP-Attribute-[service-ID]" where [service-ID] is the value of the Service-ID header field. The last line of the list MUST contain the character ";" plus an additional CRLF sequence. In the example in section 5.3 this ends up being an empty line because of the additional CRLF that belongs to the chunked encoding. 5.3 Example of an OPTIONS response ICAP/1.0 200 OK Date: Fri, 31 Jan 2003 12:00:00 GMT ISTAG: "5BDEEEA9-12E4-2" Encapsulated: opt-body=0 Opt-Body-Type: Attribute-List Max-Connections: 100 Methods: REQMOD Options-TTL: 3600 Service: XYZ Technology URL Blocking Software 5.0 Service-ID: XYZTech X-Include: X-Client-IP, X-Authenticated-User [CRLF] 38 X-ICAP-Attribute-XYZTech sex gambling jobs ; 0 [CRLF] Stecher, et. al. Expires October, 2003 [Page 15] Internet-Draft ICAP Extensions April 2003 6 The LOG method A new ICAP method is introduced, called LOG. It can be used to notify the ICAP service about the end of an HTTP transaction. It can be useful in the following two cases: - if the ICAP server wants to log information about the modified request, but all of the information needed (such as the size of the object returned from the origin server) is not available at the time the REQMOD request is made, or - if the ICAP server wants to be notified and log information when a previously-cached REQMOD response is reused by an ICAP client. The LOG method is an optional additional method for REQMOD services; it is meant to complement the REQMOD request. An ICAP client MUST send a LOG request only if a REQMOD request was sent or if it was able to use a cached REQMOD response. That means that a LOG request always has a corresponding REQMOD request. The ICAP protocol allows the addition of user-defined methods (see section 4.3.2 of [1]). Section 4.10.2 of [1] defines the Methods response header of the OPTIONS request as a list of methods, but section 6.4 of [1] discourages a service with one URI to support multiple methods. Therefore ICAP server implementations SHOULD define a distinct service for LOG and allow the REQMOD and LOG services to communicate internally. Defining a distinct LOG service ensures maximum interoperability because it can only be configured at ICAP clients supporting LOG and all other ICAP clients will not see the LOG method in the OPTIONS response. But even for distinct services an ICAP server MUST send the same X-Include header in the OPTIONS responses for the REQMOD and the corresponding LOG service. 6.1 LOG request The first request line follows the normal ICAP request specification (4.3.2 of [1]). The LOG request MUST include a number of required headers, namely: Host (required by 4.3.2 of [1]) Request-Date (new ICAP header defined below in 6.1.1) Object-Length (new ICAP header defined below in 6.1.2) Requested-URI (new ICAP header defined below in 6.1.3) In addition, the LOG request MUST include these headers if they are added to REQMOD requests: X-Client-IP X-Server-IP X-Authenticated-User X-Authenticated-Groups Stecher, et. al. Expires October, 2003 [Page 16] Internet-Draft ICAP Extensions April 2003 And these headers MUST be added if they were present in the REQMOD response: LOG-[service-ID] (new ICAP header defined below in 6.1.4) 6.1.1 Request-Date This represents the date and time of the original REQMOD request that is now being logged. It does NOT represent the date and time the log request is being sent to the ICAP server. Syntax: Request-Date-Header = "Request-Date: " rfc1123-date ; see [4] and 3.3.1 of [5] Example: Request-Date: Sun, 16 Feb 2003 23:33:55 GMT 6.1.2 Object-Length This represents the size of the object downloaded from the origin server (maybe modified by RESPMOD services), represented as an unsigned 8-byte integer. When a Content-Length header is used in the origin server's response, Object-Length will be the same as the content length. If chunked encoding or TCP close was used to transfer the body from the origin server, Object-Length will contain the number of bytes read from the server. Syntax: Object-Length-Header = "Object-Length: " uint64 Example: Object-Length: 12345678 6.1.3 Requested-URI This represents the URI specified in the original client's request. Syntax: Requested-URI-Header = "Requested-URI: " URI Example: Requested-URI: http://www.origin-server.com/origin-resource Stecher, et. al. Expires October, 2003 [Page 17] Internet-Draft ICAP Extensions April 2003 6.1.4 LOG-[service-ID] and X-LOG-[service-ID] The REQMOD response MAY contain an X-LOG-[service-ID] header. [service-ID] needs to be replaced with the service-ID value that has been advertised in the OPTIONS response. The value of the X-LOG-[service-ID] header can be of any type. If the ICAP client finds an X-LOG-[service-ID] header in the REQMOD response it MUST add a LOG-[service-ID] header with the same value to the LOG request and it MUST omit this header otherwise. Adding extension headers to REQMOD requires the X- prefixed form while LOG-[service-ID] has been introduced as a standard header for the LOG method, so the inconsistency in the two header names is mainly due to historic reasons. In order to remain backward compatible an ICAP client supporting LOG SHOULD also look for a LOG-[service-ID] header in the REQMOD response (without the X- prefix). Regardless of whether LOG-[service-ID] or X-LOG-[service-ID] has been used in REQMOD, the header in the LOG request MUST be LOG-[service-ID] (without X- prefix). 6.2 Request body No body for a LOG request is defined in this document. Future extensions MAY add a body; therefore, the LOG request MUST also include the always required encapsulated header, indicating that no body is following, by specifying: Encapsulated: null-body=0 6.3 LOG response There is no LOG response defined. This method is not a request/response message but a notification that is sent by the ICAP client to the server. The ICAP server MUST NOT send a response upon a LOG request. 7 Security considerations Users of ICAP should take note that ICAP messages (including the user-defined extension headers proposed in this document) are not encrypted for transit by default. In the absence of some other form of encryption at the link or network layers, eavesdroppers may be able to record the unencrypted transactions between ICAP clients and ICAP servers, including the information contained in the user-defined header extensions proposed in this document. Stecher, et. al. Expires October, 2003 [Page 18] Internet-Draft ICAP Extensions April 2003 8 References [1] J. Elson, A. Cerpa: "ICAP - the Internet Content Adaptation Protocol", Request for Comments 3507, April 2003. [2] Crocker, D., "Standard for the format of ARPA Internet text messages", Request for Comments 822, August 1982. [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [4] Braden, R., "Requirements for Internet hosts - application and support", STD 3, RFC 1123, October 1989. [5] Fielding, R., et. al., "Hypertext Transfer Protocol -- HTTP/1.1", Request for Comments 2616, June 1999. [6] Kille, S., and M. Wahl, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names", RFC 2253, December 1997. Authors' Addresses Martin Stecher martin.stecher@webwasher.com webwasher AG Vattmannstr. 3 33100 Paderborn Germany Jeffrey Merrick Jeffrey.Merrick@netapp.com Network Appliance, Inc. 495 East Java Drive Sunnyvale, CA 94089 USA Andre Beck abeck@bell-labs.com Markus Hofmann hofmann@bell-labs.com Bell Labs Research Lucent Technologies 101 Crawfords Corner Rd. Holmdel, NJ 07733 USA Stecher, et. al. Expires October, 2003 [Page 19] Internet-Draft ICAP Extensions April 2003 Contributors Best thanks to all who helped in compiling and creating this draft, including the following contributors: Darrell Long Blue Coat Systems, Inc. Rui Ataide Symantec Corporation Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Stecher, et. al. Expires October, 2003 [Page 20]