Table of Contents | Previous | Next | Index

## Appendix C
Netscape Cookies

A 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 server-side JavaScript using the `client` object, when using client-cookie maintenance.

For information about using cookies in server-side JavaScript, see the Server-Side JavaScript 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 semicolon, 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" on page 677. 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" on page 677. 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 `royalairways.com` matches hostnames `anvil.royalairways.com` and `ship.crate.royalairways.com`. Only hosts within the specified domain can set a cookie for a domain. In addition, domain names must use at least two or three 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. 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.

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 12:01:24

Copyright (c) 1999 Netscape Communications Corporation