netlib Cookies

Cookies evolved so state could be maintained in the otherwise stateless http protocol. They were introduced in version 1.0 of Netscape Navigator and are implemented by extending http headers which are a part of the http protocol 1.0 and higher. As of the first free source release, netlib supports the original cookie specification. None of Netscape's (or Mozilla's as of the first free source release) browsers are RFC 2109 compliant.

When an http response is parsed by netlib via a call to net_parse_http_mime_headers(), if a "Set-Cookie:" header is found, NET_SetCookieStringFromHttp() is called. NET_SetCookieStringFromHttp() calls the private net_IntSetCookieString() function after making the cookie expiration time relative to the GMT as reported by the server date. This is done to compensate for client systems that don't have any concept of timezone (i.e. dos systems that don't have the TZ environment variable set). net_IntSetCookieString() parses the cookie attributes out of the Set-Cookie header and copies them into a net_CookieStruct (defined in ns/lib/libnet/mkaccess.c), which is added to the netlib cookie list in memory.

As of the first free source release, when javascript cookie is set, NET_SetCookieString() is called which simply wraps a net_IntSetCookieString() call. Javascript cookie setting code should be modified to call NET_SetCookieStringFromHttp() so it can have the same expiration time protection.

Client Request

When the http headers are being constructed for an http url request (GET, POST, or otherwise) via a call to net_build_http_request(), the NET_GetCookie() function is called to determine whether or not a cookie, or cookies, should be sent along with the http request. NET_GetCookie() has the current url string passed into it. NET_GetCookie() searches the netlib cookie list for any cookies that should be sent along in the http request. If it finds a cookie, or cookies, based on the criteria outlined in the original cookie specification it allocates a string as a char* and returns it to the calling net_build_http_request() for inclusion in the http headers.

Every http request prompts a call to NET_GetCookie(). If cookies are disabled, NET_GetCookie() will never return anything.

Foreign Cookies

The original cookie specification allows cookies from servers other than the one your main document resides on to be set. These cookies are refered to as foreign cookies. Netscape client's 4.x and higher allow users to configure they're clients to not accept foreign cookies. If the client has been configured not to accept foreign cookies, net_IntSetCookieString() compares the host of the document currently being viewed (the url most recently accessed in the session history database) with the one in the url that is setting the cookie; if they don't match, the cookie is not set.

Cookie Persistance

Each profile has a cookies text file that resides in the root profile directory. This file contains formatted ascii text and contains all the cookies that haven't expired. The file is written out everytime a cookie changes (is added or modified) in the netlib cookie list (the file is only written out at the end of the session in Navigator 3.x and lower). Cookies are read from the file and parsed into net_CookieStructs then added to the netlib cookie list during netlib initialization which occurs only once, at the beginning of a session.

As of the first free source release cookies are only removed from the netlib cookie list (expired) when a call to NET_DisplayCookieInfoAsHTML() (about:cookies), or NET_RemoveAllCookies() is made. However, cookies that have expired are never sent and are not written to disk.

Javascript Cookie Filters

As of the first free source release cookies can be filtered via javascript functions. There is no ui for this feature. In order to filter cookies via javascript, two things need to be done: the line, user_pref("network.cookie.filterName", "cookieFilterFunctionName");, must appear in the user's pref file, and a javascript file defining the cookieFilterFunction (the function can have any name, it must match the name in the pref file) must be created in the same directory as the cookies text file. The javascript cookie determine whether a cookie should be accepted, rejected, or confirmed by the user, based on any of the information provided in the javascript cookie object (see netlib javascript cookie object description below).

If the user's configuration is set to:

"Accept all cookies" - the javascript cookie filter function is executed if it exists (i.e. the two criteria above are met).
"Only accept cookies that get sent back to the originating server" - (i.e. don't accept foreign cookies) the javascript cookie filter function is ignored only if a foreign cookie is encountered, otherwise it is executed if it exists.
"Disable Cookies" - the javascript cookie filter function is ignored.
"Warn me before accepting a cookie" - the javascript cookie filter function is executed if it exists and overrides the warning preference.

Here's a sample cookies.js file. This file can be used to filter cookies if you place it in the same directory as your cookies text file and add the user_pref line described above. You can then edit the values in the arrays to determine how you want your cookies accepted, rejected, or confirmed.

netlib Javascript Cookie Object

The netlib javascript cookie object has the following properties.

Red - read only
Blue - read/write

Name Type Description

path string path the cookie applies to

domain string domain the cookie applies to

name string name of the cookie

value string value of the cookie

expires string date the cookie expires

url string url setting the cookie

isSecure boolean the cookie is sent over secure connections only

isDomain boolean the cookie has a domain attribute

prompt boolean user has configured prefs to throw cookie confirm dialog

preference int the user's cookie acceptance value

accept() method allows the cookie to be set

reject() method causes the cookie not to be set

ask() method prompt a netlib confirmation dialog
(happens during netlib set cookie execution)

confirm() method prompt a javascript confirmation dialog
(happens during javascript function execution)

Judson Valeski, 1998