[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00

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*( <any CHAR except CTLs> )

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
<html><body>
The file download has been blocked due to a detected virus infection.
</body></html>
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]

Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/