Netscape cookies

cookie is a small piece of information stored on the client machine in the cookies.txt file. This appendix discusses the implementation of cookies in the Navigator client; it is not a formal specification or standard.

You can manipulate cookies

• Explicitly, with a CGI program.
• Programmatically, with client-side JavaScript using the cookie property of the document object.
• Transparently, with the LiveWire the client object, when using client-cookie maintenance.

For information about using cookies in LiveWire, see the LiveWire Developer's Guide.

This appendix describes the format of cookie information in the HTTP header, and discusses using CGI programs and JavaScript to manipulate cookies.

Syntax

A CGI program uses the following syntax to add cookie information to the HTTP header:

Set-Cookie:
   name=value
   [;EXPIRES=dateValue]
   [;DOMAIN=domainName]
   [;PATH=pathName]
   [;SECURE]

Parameters

name=value is a sequence of characters excluding semi-colon, comma and white space. To place restricted characters in the name or value, use an encoding method such as URL-style %XX encoding.

EXPIRES=dateValue specifies a date string that defines the valid life time of that cookie. Once the expiration date has been reached, the cookie will no longer be stored or given out. If you do not specify dateValue, the cookie expires when the user's session ends.

The date string is formatted as:

Wdy, DD-Mon-YY HH:MM:SS GMT

where Wdy is the day of the week (for example, Mon or Tues); DD is a two-digit representation of the day of the month; Mon is a three-letter abbreviation for the month (for example, Jan or Feb); YY is the last two digits of the year; HH:MM:SS are hours, minutes, and seconds, respectively.

DOMAIN=domainName specifies the domain attributes for a valid cookie. See "Determining a valid cookie". If you do not specify a value for domainName, Navigator uses the host name of the server which generated the cookie response.

PATH=pathName specifies the path attributes for a valid cookie. See "Determining a valid cookie". If you do not specify a value for pathName, Navigator uses the path of the document that created the cookie property (or the path of the document described by the HTTP header, for CGI programming).

SECURE specifies that the cookie is transmitted only if the communications channel with the host is a secure. Only HTTPS (HTTP over SSL) servers are currently secure. If SECURE is not specified, the cookie is considered sent over any channel.

Description

A server sends cookie information to the client in the HTTP header when the server responds to a request. Included in that information is a description of the range of URLs for which it is valid. Any future HTTP requests made by the client which fall in that range will include a transmittal of the current value of the state object from the client back to the server.

Many different application types can take advantage of cookies. For example, a shopping application can store information about the currently selected items for use in the current session or a future session, and other applications can store individual user preferences on the client machine.

Determining a valid cookie

When searching the cookie list for valid cookies, a comparison of the domain attributes of the cookie is made with the domain name of the host from which the URL is retrieved.

If the domain attribute matches the end of the fully qualified domain name of the host, then path matching is performed to determine if the cookie should be sent. For example, a domain attribute of "acme.com" would match host names "anvil.acme.com" as well as "shipping.crate.acme.com".

Only hosts within the specified domain can set a cookie for a domain. In addition, domain names must use at least two or periods. Any domain in the "COM", "EDU", "NET", "ORG", "GOV", "MIL", and "INT" categories requires only two periods; all other domains require at least three periods.

PATH=pathName specifies the URLs in a domain for which the cookie is valid. If a cookie has already passed domain matching, then the pathname component of the URL is compared with the path attribute, and if there is a match, the cookie is considered valid and is sent along with the URL request. For example, PATH=/foo matches "/foobar" and "/foo/bar.html". The path "/" is the most general path.

Syntax of the cookie HTTP request header

When requesting a URL from an HTTP server, the browser matches the URL against all existing cookies. When a cookie matches the URL request, a line containing the name/value pairs of all matching cookies is included in the HTTP request in the following format:

Cookie: NAME1=OPAQUE_STRING1; NAME2=OPAQUE_STRING2 ...

Saving cookies

A single server response can issue multiple Set-Cookie headers. Saving a cookie with the same PATH and NAME values as an existing cookie overwrites the existing cookie. Saving a cookie with the same PATH value but a different NAME value adds an additional cookie.

The EXPIRES value indicates when to purge the mapping. Navigator will also delete a cookie before its expiration date arrives if the number of cookies exceeds its internal limits.

A cookie with a higher-level PATH value does not override a more specific PATH value. If there are multiple matches with separate paths, all the matching cookies are sent, as shown in the examples below.

A CGI script can delete a cookie by returning a cookie with the same PATH and NAME values, and an EXPIRES value which is in the past. Because the PATH and NAME must match exactly, it is difficult for scripts other than the originator of a cookie to delete a cookie.

Specifications for the client

When sending cookies to a server, all cookies with a more specific path mapping are sent before cookies with less specific path mappings. For example, a cookie "name1=foo" with a path mapping of "/" should be sent after a cookie "name1=foo2" with a path mapping of "/bar" if they are both to be sent.

The Navigator can receive and store the following:

• 300 total cookies
• 4 kilobytes per cookie, where the name and the OPAQUE_STRING combine to form the 4 kilobyte limit.
• 20 cookies per server or domain. Completely specified hosts and domains are considered separate entities, and each has a 20 cookie limitation.

When the 300 cookie limit or the 20 cookie per server limit is exceeded, Navigator deletes the least recently used cookie. When a cookie larger than 4 kilobytes is encountered the cookie should be trimmed to fit, but the name should remain intact as long as it is less than 4 kilobytes.

Examples

The following examples illustrate the transaction sequence in typical CGI programs. For an example of using cookies with JavaScript, see "cookie".

Example 1

Client requests a document, and receives in the response:

Set-Cookie: CUSTOMER=WILE_E_COYOTE; path=/; expires=Wednesday,
   09-Nov-99 23:12:40 GMT

When client requests a URL in path "/" on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE

Client requests a document, and receives in the response:

Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/

When client requests a URL in path "/" on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001

Client receives:

Set-Cookie: SHIPPING=FEDEX; path=/foo

When client requests a URL in path "/" on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001

When client requests a URL in path "/foo" on this server, it sends:

Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001;
   SHIPPING=FEDEX

Example 2

This example assumes all mappings from Example 1 have been cleared.

Client receives:

Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/

When client requests a URL in path "/" on this server, it sends:

Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001

Client receives:

Set-Cookie: PART_NUMBER=RIDING_ROCKET_0023; path=/ammo

When client requests a URL in path "/ammo" on this server, it sends:

Cookie: PART_NUMBER=RIDING_ROCKET_0023;
   PART_NUMBER=ROCKET_LAUNCHER_0001

There are two name/value pairs named "PART_NUMBER" due to the inheritance of the "/" mapping in addition to the "/ammo" mapping.