rfc2109.txt

来自「RFC 的详细文档！」· 文本 代码 · 共 1,180 行 · 第 1/3 页

Network Working Group                                         D. Kristol
Request for Comments: 2109        Bell Laboratories, Lucent Technologies
Category: Standards Track                                    L. Montulli
                                                 Netscape Communications
                                                           February 1997


                    HTTP State Management Mechanism

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

1.  ABSTRACT

   This document specifies a way to create a stateful session with HTTP
   requests and responses.  It describes two new headers, Cookie and
   Set-Cookie, which carry state information between participating
   origin servers and user agents.  The method described here differs
   from Netscape's Cookie proposal, but it can interoperate with
   HTTP/1.0 user agents that use Netscape's method.  (See the HISTORICAL
   section.)

2.  TERMINOLOGY

   The terms user agent, client, server, proxy, and origin server have
   the same meaning as in the HTTP/1.0 specification.

   Fully-qualified host name (FQHN) means either the fully-qualified
   domain name (FQDN) of a host (i.e., a completely specified domain
   name ending in a top-level domain such as .com or .uk), or the
   numeric Internet Protocol (IP) address of a host.  The fully
   qualified domain name is preferred; use of numeric IP addresses is
   strongly discouraged.

   The terms request-host and request-URI refer to the values the client
   would send to the server as, respectively, the host (but not port)
   and abs_path portions of the absoluteURI (http_URL) of the HTTP
   request line.  Note that request-host must be a FQHN.








Kristol & Montulli          Standards Track                     [Page 1]

RFC 2109            HTTP State Management Mechanism        February 1997


   Hosts names can be specified either as an IP address or a FQHN
   string.  Sometimes we compare one host name with another.  Host A's
   name domain-matches host B's if

   * both host names are IP addresses and their host name strings match
     exactly; or

   * both host names are FQDN strings and their host name strings match
     exactly; or

   * A is a FQDN string and has the form NB, where N is a non-empty name
     string, B has the form .B', and B' is a FQDN string.  (So, x.y.com
     domain-matches .y.com but not y.com.)

   Note that domain-match is not a commutative operation: a.b.c.com
   domain-matches .c.com, but not the reverse.

   Because it was used in Netscape's original implementation of state
   management, we will use the term cookie to refer to the state
   information that passes between an origin server and user agent, and
   that gets stored by the user agent.

3.  STATE AND SESSIONS

   This document describes a way to create stateful sessions with HTTP
   requests and responses.  Currently, HTTP servers respond to each
   client request without relating that request to previous or
   subsequent requests; the technique allows clients and servers that
   wish to exchange state information to place HTTP requests and
   responses within a larger context, which we term a "session".  This
   context might be used to create, for example, a "shopping cart", in
   which user selections can be aggregated before purchase, or a
   magazine browsing system, in which a user's previous reading affects
   which offerings are presented.

   There are, of course, many different potential contexts and thus many
   different potential types of session.  The designers' paradigm for
   sessions created by the exchange of cookies has these key attributes:

      1.  Each session has a beginning and an end.

      2.  Each session is relatively short-lived.

      3.  Either the user agent or the origin server may terminate a
          session.

      4.  The session is implicit in the exchange of state information.




Kristol & Montulli          Standards Track                     [Page 2]

RFC 2109            HTTP State Management Mechanism        February 1997


4.  OUTLINE

   We outline here a way for an origin server to send state information
   to the user agent, and for the user agent to return the state
   information to the origin server.  The goal is to have a minimal
   impact on HTTP and user agents.  Only origin servers that need to
   maintain sessions would suffer any significant impact, and that
   impact can largely be confined to Common Gateway Interface (CGI)
   programs, unless the server provides more sophisticated state
   management support.  (See Implementation Considerations, below.)

4.1  Syntax:  General

   The two state management headers, Set-Cookie and Cookie, have common
   syntactic properties involving attribute-value pairs.  The following
   grammar uses the notation, and tokens DIGIT (decimal digits) and
   token (informally, a sequence of non-special, non-white space
   characters) from the HTTP/1.1 specification [RFC 2068] to describe
   their syntax.

   av-pairs        =       av-pair *(";" av-pair)
   av-pair         =       attr ["=" value]        ; optional value
   attr            =       token
   value           =       word
   word            =       token | quoted-string

   Attributes (names) (attr) are case-insensitive.  White space is
   permitted between tokens.  Note that while the above syntax
   description shows value as optional, most attrs require them.

   NOTE: The syntax above allows whitespace between the attribute and
   the = sign.

4.2  Origin Server Role

4.2.1  General

   The origin server initiates a session, if it so desires.  (Note that
   "session" here does not refer to a persistent network connection but
   to a logical session created from HTTP requests and responses.  The
   presence or absence of a persistent connection should have no effect
   on the use of cookie-derived sessions).  To initiate a session, the
   origin server returns an extra response header to the client, Set-
   Cookie.  (The details follow later.)

   A user agent returns a Cookie request header (see below) to the
   origin server if it chooses to continue a session.  The origin server
   may ignore it or use it to determine the current state of the



Kristol & Montulli          Standards Track                     [Page 3]

RFC 2109            HTTP State Management Mechanism        February 1997


   session.  It may send back to the client a Set-Cookie response header
   with the same or different information, or it may send no Set-Cookie
   header at all.  The origin server effectively ends a session by
   sending the client a Set-Cookie header with Max-Age=0.

   Servers may return a Set-Cookie response headers with any response.
   User agents should send Cookie request headers, subject to other
   rules detailed below, with every request.

   An origin server may include multiple Set-Cookie headers in a
   response.  Note that an intervening gateway could fold multiple such
   headers into a single header.

4.2.2  Set-Cookie Syntax

   The syntax for the Set-Cookie response header is

   set-cookie      =       "Set-Cookie:" cookies
   cookies         =       1#cookie
   cookie          =       NAME "=" VALUE *(";" cookie-av)
   NAME            =       attr
   VALUE           =       value
   cookie-av       =       "Comment" "=" value
                   |       "Domain" "=" value
                   |       "Max-Age" "=" value
                   |       "Path" "=" value
                   |       "Secure"
                   |       "Version" "=" 1*DIGIT

   Informally, the Set-Cookie response header comprises the token Set-
   Cookie:, followed by a comma-separated list of one or more cookies.
   Each cookie begins with a NAME=VALUE pair, followed by zero or more
   semi-colon-separated attribute-value pairs.  The syntax for
   attribute-value pairs was shown earlier.  The specific attributes and
   the semantics of their values follows.  The NAME=VALUE attribute-
   value pair must come first in each cookie.  The others, if present,
   can occur in any order.  If an attribute appears more than once in a
   cookie, the behavior is undefined.

   NAME=VALUE
      Required.  The name of the state information ("cookie") is NAME,
      and its value is VALUE.  NAMEs that begin with $ are reserved for
      other uses and must not be used by applications.








Kristol & Montulli          Standards Track                     [Page 4]

RFC 2109            HTTP State Management Mechanism        February 1997


      The VALUE is opaque to the user agent and may be anything the
      origin server chooses to send, possibly in a server-selected
      printable ASCII encoding.  "Opaque" implies that the content is of
      interest and relevance only to the origin server.  The content
      may, in fact, be readable by anyone that examines the Set-Cookie
      header.

   Comment=comment
      Optional.  Because cookies can contain private information about a
      user, the Cookie attribute allows an origin server to document its
      intended use of a cookie.  The user can inspect the information to
      decide whether to initiate or continue a session with this cookie.

   Domain=domain
      Optional.  The Domain attribute specifies the domain for which the
      cookie is valid.  An explicitly specified domain must always start
      with a dot.

   Max-Age=delta-seconds
      Optional.  The Max-Age attribute defines the lifetime of the
      cookie, in seconds.  The delta-seconds value is a decimal non-
      negative integer.  After delta-seconds seconds elapse, the client
      should discard the cookie.  A value of zero means the cookie
      should be discarded immediately.

   Path=path
      Optional.  The Path attribute specifies the subset of URLs to
      which this cookie applies.

   Secure
      Optional.  The Secure attribute (with no value) directs the user
      agent to use only (unspecified) secure means to contact the origin
      server whenever it sends back this cookie.

      The user agent (possibly under the user's control) may determine
      what level of security it considers appropriate for "secure"
      cookies.  The Secure attribute should be considered security
      advice from the server to the user agent, indicating that it is in
      the session's interest to protect the cookie contents.

   Version=version
      Required.  The Version attribute, a decimal integer, identifies to
      which version of the state management specification the cookie
      conforms.  For this specification, Version=1 applies.







Kristol & Montulli          Standards Track                     [Page 5]

RFC 2109            HTTP State Management Mechanism        February 1997


4.2.3  Controlling Caching

   An origin server must be cognizant of the effect of possible caching
   of both the returned resource and the Set-Cookie header.  Caching
   "public" documents is desirable.  For example, if the origin server
   wants to use a public document such as a "front door" page as a
   sentinel to indicate the beginning of a session for which a Set-
   Cookie response header must be generated, the page should be stored
   in caches "pre-expired" so that the origin server will see further
   requests.  "Private documents", for example those that contain
   information strictly private to a session, should not be cached in
   shared caches.

   If the cookie is intended for use by a single user, the Set-cookie
   header should not be cached.  A Set-cookie header that is intended to
   be shared by multiple users may be cached.

   The origin server should send the following additional HTTP/1.1
   response headers, depending on circumstances:

   * To suppress caching of the Set-Cookie header: Cache-control: no-
     cache="set-cookie".

   and one of the following:

   * To suppress caching of a private document in shared caches: Cache-
     control: private.

   * To allow caching of a document and require that it be validated
     before returning it to the client: Cache-control: must-revalidate.

   * To allow caching of a document, but to require that proxy caches
     (not user agent caches) validate it before returning it to the
     client: Cache-control: proxy-revalidate.

   * To allow caching of a document and request that it be validated
     before returning it to the client (by "pre-expiring" it):
     Cache-control: max-age=0.  Not all caches will revalidate the
     document in every case.

   HTTP/1.1 servers must send Expires: old-date (where old-date is a
   date long in the past) on responses containing Set-Cookie response
   headers unless they know for certain (by out of band means) that
   there are no downsteam HTTP/1.0 proxies.  HTTP/1.1 servers may send
   other Cache-Control directives that permit caching by HTTP/1.1
   proxies in addition to the Expires: old-date directive; the Cache-
   Control directive will override the Expires: old-date for HTTP/1.1
   proxies.



Kristol & Montulli          Standards Track                     [Page 6]

RFC 2109            HTTP State Management Mechanism        February 1997


4.3  User Agent Role

4.3.1  Interpreting Set-Cookie

   The user agent keeps separate track of state information that arrives
   via Set-Cookie response headers from each origin server (as
   distinguished by name or IP address and port).  The user agent
   applies these defaults for optional attributes that are missing:

   VersionDefaults to "old cookie" behavior as originally specified by
          Netscape.  See the HISTORICAL section.

   Domain Defaults to the request-host.  (Note that there is no dot at
          the beginning of request-host.)

   Max-AgeThe default behavior is to discard the cookie when the user
          agent exits.

   Path   Defaults to the path of the request URL that generated the
          Set-Cookie response, up to, but not including, the
          right-most /.

   Secure If absent, the user agent may send the cookie over an
          insecure channel.

4.3.2  Rejecting Cookies

   To prevent possible security or privacy violations, a user agent
   rejects a cookie (shall not store its information) if any of the
   following is true:

   * The value for the Path attribute is not a prefix of the request-
     URI.

   * The value for the Domain attribute contains no embedded dots or
     does not start with a dot.

   * The value for the request-host does not domain-match the Domain
     attribute.

   * The request-host is a FQDN (not IP address) and has the form HD,
     where D is the value of the Domain attribute, and H is a string
     that contains one or more dots.

   Examples:

   * A Set-Cookie from request-host y.x.foo.com for Domain=.foo.com
     would be rejected, because H is y.x and contains a dot.



Kristol & Montulli          Standards Track                     [Page 7]