1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
|
<HTML>
<HEAD>
<TITLE>Client Side State - HTTP Cookies</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff" LINK="#0000ff" VLINK="#ff0000" ALINK="#ff0000" TEXT="#000000" >
<CENTER>
<!-- BANNER:s3 -->
<A HREF="/maps/banners/documentation_s3.map"><IMG SRC="/images/banners/documentation_s3.gif" ALT="Documentation" BORDER=0 WIDTH=612 HEIGHT=50 ISMAP USEMAP="#banner_nav"></A>
<MAP NAME="banner_nav">
<AREA SHAPE=RECT COORDS="62,11,91,40" HREF="/">
<AREA SHAPE=RECT COORDS="153,41,221,50" HREF="/">
<AREA SHAPE=RECT COORDS="298,8,374,34" HREF="/support/index.html">
<AREA SHAPE=RECT COORDS="381,15,586,43" HREF="http://help.netscape.com/browse/index.html">
<AREA SHAPE=default NOHREF>
</MAP>
<!-- BANNER:s3 -->
<H2>
<FONT SIZE=+3>P</FONT>ERSISTENT
<FONT SIZE=+3>C</FONT>LIENT
<FONT SIZE=+3>S</FONT>TATE<BR>
<FONT SIZE=+3>HTTP C</FONT>OOKIES
</H2>
<H3>Preliminary Specification - Use with caution</H3>
</CENTER>
<HR SIZE=4>
<CENTER>
<H3>
<FONT SIZE=+2>I</FONT>NTRODUCTION
</H3>
</CENTER>
Cookies are a general mechanism which server side connections (such as
CGI scripts) can use to both store and retrieve information on the
client side of the connection. The addition of a simple, persistent,
client-side state significantly extends the capabilities of Web-based
client/server applications.<P>
<CENTER>
<H3>
<FONT SIZE=+2>O</FONT>VERVIEW
</H3>
</CENTER>
A server, when returning an HTTP object to a client, may also send a
piece of state information which the client will store. Included in that
state object is a description of the range of URLs for which that state 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. The state object is called
a <B>cookie</B>, for no compelling reason. <P>
This simple mechanism provides a powerful new tool which enables a host
of new types of applications to be written for web-based environments.
Shopping applications can now store information about the currently
selected items, for fee services can send back registration information
and free the client from retyping a user-id on next connection,
sites can store per-user preferences on the client, and have the client supply
those preferences every time that site is connected to.
<CENTER>
<H3>
<FONT SIZE=+2>S</FONT>PECIFICATION
</H3>
</CENTER>
A cookie is introduced to the client by including a <B>Set-Cookie</B>
header as part of an HTTP response, typically this will be generated
by a CGI script.
<H3>Syntax of the Set-Cookie HTTP Response Header</H3>
This is the format a CGI script would use to add to the HTTP headers
a new piece of data which is to be stored by the client for later retrieval.
<PRE>
Set-Cookie: <I>NAME</I>=<I>VALUE</I>; expires=<I>DATE</I>;
path=<I>PATH</I>; domain=<I>DOMAIN_NAME</I>; secure
</PRE>
<DL>
<DT> <I>NAME</I>=<I>VALUE</I><DD>
This string is a sequence of characters excluding semi-colon, comma and white
space. If there is a need to place such data in the name or value, some
encoding method such as URL style %XX encoding is recommended, though no
encoding is defined or required. <P> This is the only required attribute
on the <B>Set-Cookie</B> header. <P>
<DT><B>expires</B>=<I>DATE</I>
<DD>
The <B>expires</B> attribute 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. <P>
The date string is formatted as:
<BLOCKQUOTE> <TT>Wdy, DD-Mon-YYYY HH:MM:SS GMT</TT></BLOCKQUOTE>
This is based on
<A TARGET="_top" HREF="http://ds.internic.net/rfc/rfc822.txt">RFC 822</A>,
<A TARGET="_top" HREF="http://ds.internic.net/rfc/rfc850.txt">RFC 850</A>,
<A TARGET="_top" HREF="http://www.w3.org/hypertext/WWW/Protocols/rfc1036/rfc1036.html#z6">
RFC 1036</A>, and
<A TARGET="_top" HREF="http://ds1.internic.net/rfc/rfc1123.txt">
RFC 1123</A>,
with the variations that the only legal time zone is <B>GMT</B> and
the separators between the elements of the date must be dashes.
<P>
<B>expires</B> is an optional attribute. If not specified, the cookie will
expire when the user's session ends. <P>
<B>Note:</B> There is a bug in Netscape Navigator version 1.1 and earlier.
Only cookies whose <B>path</B> attribute is set explicitly to "/" will
be properly saved between sessions if they have an <B>expires</B>
attribute.<P>
<DT> <B>domain</B>=<I>DOMAIN_NAME</I>
<DD>
When searching the cookie list for valid cookies, a comparison of the
<B>domain</B>
attributes of the cookie is made with the Internet domain name of the
host from which the URL will be fetched. If there is a tail match,
then the cookie will go through <B>path</B> matching to see if it
should be sent. "Tail matching" means that <B>domain</B> attribute
is matched against the tail of the fully qualified domain name of
the host. A <B>domain</B> attribute of "acme.com" would match
host names "anvil.acme.com" as well as "shipping.crate.acme.com". <P>
Only hosts within the specified domain
can set a cookie for a domain and domains must have at least two (2)
or three (3) periods in them to prevent domains of the form:
".com", ".edu", and "va.us". Any domain that fails within
one of the seven special top level domains listed below only require
two periods. Any other domain requires at least three. The
seven special top level domains are: "COM", "EDU", "NET", "ORG",
"GOV", "MIL", and "INT".
<P>
The default value of <B>domain</B> is the host name of the server
which generated the cookie response. <P>
<DT> <B>path</B>=<I>PATH</I>
<DD>
The <B>path</B> attribute is used to specify the subset of URLs in a
domain for
which the cookie is valid. If a cookie has already passed <B>domain</B>
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. The path "/foo"
would match "/foobar" and "/foo/bar.html". The path "/" is the most
general path. <P>
If the <B>path</B> is not specified, it as assumed to be the same path
as the document being described by the header which contains the cookie.
<P>
<DT> <B>secure</B>
<DD>
If a cookie is marked <B>secure</B>, it will only be transmitted if the
communications channel with the host is a secure one. Currently
this means that secure cookies will only be sent to HTTPS (HTTP over SSL)
servers. <P>
If <B>secure</B> is not specified, a cookie is considered safe to be sent
in the clear over unsecured channels.
</DL>
<H3>Syntax of the Cookie HTTP Request Header</H3>
When requesting a URL from an HTTP server, the browser will match
the URL against all cookies and if any of them match, a line
containing the name/value pairs of all matching cookies will
be included in the HTTP request. Here is the format of that line:
<PRE>
Cookie: <I>NAME1=OPAQUE_STRING1</I>; <I>NAME2=OPAQUE_STRING2 ...</I>
</PRE>
<H3>Additional Notes</H3>
<UL>
<LI>Multiple <B>Set-Cookie</B> headers can be issued in a single server
response.
<p>
<LI>Instances of the same path and name will overwrite each other, with the
latest instance taking precedence. Instances of the same path but
different names will add additional mappings.
<p>
<LI>Setting the path to a higher-level value does not override other more
specific path mappings. If there are multiple matches for a given cookie
name, but with separate paths, all the matching cookies will be sent.
(See examples below.)
<p>
<LI>The
expires header lets the client know when it is safe to purge the mapping
but the client is not required to do so. A client may also delete a
cookie before it's expiration date arrives if the number of cookies
exceeds its internal limits.
<p>
<LI>When sending cookies to a server, all cookies with a more specific
path mapping should be 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.
<p>
<LI>There are limitations on the number of cookies that a client
can store at any one time. This is a specification of the minimum
number of cookies that a client should be prepared to receive and
store.
<UL>
<LI>300 total cookies
<LI>4 kilobytes per cookie, where the name and the OPAQUE_STRING
combine to form the 4 kilobyte limit.
<LI>20 cookies per server or domain. (note that completely
specified hosts and domains are treated as separate entities
and have a 20 cookie limitation for each, not combined)
</UL>
Servers should not expect clients to be able to exceed these limits.
When the 300 cookie limit or the 20 cookie per server limit
is exceeded, clients should delete 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.
<P>
<LI>If a CGI script wishes to delete a cookie, it can do so by
returning a cookie with the same name, and an <B>expires</B> time
which is in the past. The path and name must match exactly
in order for the expiring cookie to replace the valid cookie.
This requirement makes it difficult for anyone but the originator
of a cookie to delete a cookie.
<P><LI>When caching HTTP, as a proxy server might do, the <B>Set-cookie</B>
response header should never be cached.
<P><LI>If a proxy server receives a response which
contains a <B>Set-cookie</B> header, it should propagate the <B>Set-cookie</B>
header to the client, regardless of whether the response was 304
(Not Modified) or 200 (OK).
<P>Similarly, if a client request contains a Cookie: header, it
should be forwarded through a proxy, even if the conditional
If-modified-since request is being made.
</UL>
<CENTER>
<H3>
<FONT SIZE=+2>E</FONT>XAMPLES
</H3>
</CENTER>
Here are some sample exchanges which are designed to illustrate the use
of cookies.
<H3>First Example transaction sequence:</H3>
<DL>
<dt>Client requests a document, and receives in the response:<dd>
<PRE>
Set-Cookie: CUSTOMER=WILE_E_COYOTE; path=/; expires=Wednesday, 09-Nov-99 23:12:40 GMT</PRE>
<dt>When client requests a URL in path "/" on this server, it sends:<DD>
<PRE>Cookie: CUSTOMER=WILE_E_COYOTE</PRE>
<dt>Client requests a document, and receives in the response:<dd>
<PRE>Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/</PRE>
<dt>When client requests a URL in path "/" on this server, it sends:<dd>
<PRE>Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001</PRE>
<dt>Client receives:<dd>
<PRE>Set-Cookie: SHIPPING=FEDEX; path=/foo</PRE>
<dt>When client requests a URL in path "/" on this server, it sends:<dd>
<PRE>Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001</PRE>
<dt>When client requests a URL in path "/foo" on this server, it sends:<dd>
<PRE>Cookie: CUSTOMER=WILE_E_COYOTE; PART_NUMBER=ROCKET_LAUNCHER_0001; SHIPPING=FEDEX</PRE>
</DL>
<H3>Second Example transaction sequence:</H3>
<DL>
<dt>Assume all mappings from above have been cleared.<p>
<dt>Client receives:<dd>
<PRE>Set-Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001; path=/</PRE>
<dt>When client requests a URL in path "/" on this server, it sends:<dd>
<PRE>Cookie: PART_NUMBER=ROCKET_LAUNCHER_0001</PRE>
<dt>Client receives:<dd>
<PRE>Set-Cookie: PART_NUMBER=RIDING_ROCKET_0023; path=/ammo</PRE>
<dt>When client requests a URL in path "/ammo" on this server, it sends:<dd>
<PRE>Cookie: PART_NUMBER=RIDING_ROCKET_0023; PART_NUMBER=ROCKET_LAUNCHER_0001</PRE>
<dd>NOTE: There are two name/value pairs named "PART_NUMBER" due to the
inheritance
of the "/" mapping in addition to the "/ammo" mapping.
</DL>
<HR SIZE=4>
<P>
<CENTER>
<!-- footer -->
<TABLE WIDTH=600 BORDER=0 CELLPADDING=0 CELLSPACING=0>
<TR>
<TD WIDTH=600 HEIGHT=8><HR SIZE=1 NOSHADE></TD></TR>
<TR><TD ALIGN=LEFT VALIGN=TOP><FONT FACE="sans-serif, Arial, Helvetica" SIZE=-2><A HREF="http://home.netscape.com/misc/nav_redir/help.html" TARGET="_top">Help</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/site_map.html" TARGET="_top">Site Map</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/howtoget.html" TARGET="_top">How to Get Netscape Products</A> | <A HREF="http://home.netscape.com/misc/nav_redir/ad.html" TARGET="_top">Advertise With Us</A> | <A HREF="http://home.netscape.com/misc/nav_redir/addsite.html" TARGET="_top">Add Site</A> | <A HREF="http://home.netscape.com/misc/nav_redir/custom_browser.html" TARGET="_top">Custom Browser Program</A></FONT></TD></TR>
<TR>
<TD WIDTH=600 HEIGHT=8 COLSPAN=0></TD>
</TR>
<TR>
<TD ALIGN=LEFT VALIGN=TOP>
<!-- Channels -->
<FONT FACE="sans-serif, Arial, Helvetica" SIZE=-2><A HREF="http://home.netscape.com/misc/nav_redir/channels/autos.html" TARGET="_top">Autos</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/business.html" TARGET="_top">Business</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/computers_internet.html" TARGET="_top">Computing & Internet</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/entertainment.html" TARGET="_top">Entertainment</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/kids_family.html" TARGET="_top">Family</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/games.html" TARGET="_top">Games</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/health.html" TARGET="_top">Health</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/lifestyles.html" TARGET="_top">Lifestyles</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/local.html" TARGET="_top">Local</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/netscape.html" TARGET="_top">Netscape</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/open_directory.html">Netscape Open Directory</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/news.html" TARGET="_top">News</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/personalize_finance.html" TARGET="_top">Personal Finance</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/real_estate.html" TARGET="_top">Real Estate</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/education.html" TARGET="_top">Research & Learn</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/shopping.html" TARGET="_top">Shopping</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/smallbiz.html" TARGET="_top">Small Business</A> | <A
HREF="http://home.netscape.com/misc/nav_redir/channels/sports.html" TARGET="_top">Sports</A> | <A HREF="http://home.netscape.com/misc/nav_redir/channels/travel.html" TARGET="_top">Travel</A></FONT></TD></TR>
</TABLE>
<TABLE WIDTH=600 BORDER=0 CELLPADDING=0 CELLSPACING=0>
<TR><TD WIDTH=600 HEIGHT=8 COLSPAN=0></TD></TR>
<TR>
<TD WIDTH=600 COLSPAN=5 VALIGN=TOP ALIGN=LEFT>
<FONT FACE="sans-serif, Arial, Helvetica" SIZE=-2>
© 1999 Netscape, All Rights Reserved. <A HREF="http://home.netscape.com/legal_notices/index.html">Legal & Privacy Notices</A><BR>This site powered by <A HREF="http://home.netscape.com/comprod/server_central/index.html" TARGET="_top">Netscape SuiteSpot servers</A>.</FONT></TD>
</TR>
</TABLE>
<!-- end footer -->
</CENTER>
<P>
</BODY>
</HTML>
|
