Debian Codegraph @

Lib/http/cookies.py

raw
1 ####
2 # Copyright 2000 by Timothy O'Malley <[email protected]>
3 #
4 # All Rights Reserved
5 #
6 # Permission to use, copy, modify, and distribute this software
7 # and its documentation for any purpose and without fee is hereby
8 # granted, provided that the above copyright notice appear in all
9 # copies and that both that copyright notice and this permission
10 # notice appear in supporting documentation, and that the name of
11 # Timothy O'Malley not be used in advertising or publicity
12 # pertaining to distribution of the software without specific, written
13 # prior permission.
14 #
15 # Timothy O'Malley DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
16 # SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
17 # AND FITNESS, IN NO EVENT SHALL Timothy O'Malley BE LIABLE FOR
18 # ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
19 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
20 # WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
21 # ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
22 # PERFORMANCE OF THIS SOFTWARE.
23 #
24 ####
25 #
26 # Id: Cookie.py,v 2.29 2000/08/23 05:28:49 timo Exp
27 # by Timothy O'Malley <[email protected]>
28 #
29 # Cookie.py is a Python module for the handling of HTTP
30 # cookies as a Python dictionary. See RFC 2109 for more
31 # information on cookies.
32 #
33 # The original idea to treat Cookies as a dictionary came from
34 # Dave Mitchell ([email protected]) in 1995, when he released the
35 # first version of nscookie.py.
36 #
37 ####
38
39 r"""
40 Here's a sample session to show how to use this module.
41 At the moment, this is the only documentation.
42
43 The Basics
44 ----------
45
46 Importing is easy...
47
48 >>> from http import cookies
49
50 Most of the time you start by creating a cookie.
51
52 >>> C = cookies.SimpleCookie()
53
54 Once you've created your Cookie, you can add values just as if it were
55 a dictionary.
56
57 >>> C = cookies.SimpleCookie()
58 >>> C["fig"] = "newton"
59 >>> C["sugar"] = "wafer"
60 >>> C.output()
61 'Set-Cookie: fig=newton\r\nSet-Cookie: sugar=wafer'
62
63 Notice that the printable representation of a Cookie is the
64 appropriate format for a Set-Cookie: header. This is the
65 default behavior. You can change the header and printed
66 attributes by using the .output() function
67
68 >>> C = cookies.SimpleCookie()
69 >>> C["rocky"] = "road"
70 >>> C["rocky"]["path"] = "/cookie"
71 >>> print(C.output(header="Cookie:"))
72 Cookie: rocky=road; Path=/cookie
73 >>> print(C.output(attrs=[], header="Cookie:"))
74 Cookie: rocky=road
75
76 The load() method of a Cookie extracts cookies from a string. In a
77 CGI script, you would use this method to extract the cookies from the
78 HTTP_COOKIE environment variable.
79
80 >>> C = cookies.SimpleCookie()
81 >>> C.load("chips=ahoy; vienna=finger")
82 >>> C.output()
83 'Set-Cookie: chips=ahoy\r\nSet-Cookie: vienna=finger'
84
85 The load() method is darn-tootin smart about identifying cookies
86 within a string. Escaped quotation marks, nested semicolons, and other
87 such trickeries do not confuse it.
88
89 >>> C = cookies.SimpleCookie()
90 >>> C.load('keebler="E=everybody; L=\\"Loves\\"; fudge=;";')
91 >>> print(C)
92 Set-Cookie: keebler="E=everybody; L=\"Loves\"; fudge=;"
93
94 Each element of the Cookie also supports all of the RFC 2109
95 Cookie attributes. Here's an example which sets the Path
96 attribute.
97
98 >>> C = cookies.SimpleCookie()
99 >>> C["oreo"] = "doublestuff"
100 >>> C["oreo"]["path"] = "/"
101 >>> print(C)
102 Set-Cookie: oreo=doublestuff; Path=/
103
104 Each dictionary element has a 'value' attribute, which gives you
105 back the value associated with the key.
106
107 >>> C = cookies.SimpleCookie()
108 >>> C["twix"] = "none for you"
109 >>> C["twix"].value
110 'none for you'
111
112 The SimpleCookie expects that all values should be standard strings.
113 Just to be sure, SimpleCookie invokes the str() builtin to convert
114 the value to a string, when the values are set dictionary-style.
115
116 >>> C = cookies.SimpleCookie()
117 >>> C["number"] = 7
118 >>> C["string"] = "seven"
119 >>> C["number"].value
120 '7'
121 >>> C["string"].value
122 'seven'
123 >>> C.output()
124 'Set-Cookie: number=7\r\nSet-Cookie: string=seven'
125
126 Finis.
127 """
128
129 #
130 # Import our required modules
131 #
132 import re
133 import string
134 import types
135
136 __all__ = ["CookieError", "BaseCookie", "SimpleCookie"]
137
138 _nulljoin = ''.join
139 _semispacejoin = '; '.join
140 _spacejoin = ' '.join
141
142 #
143 # Define an exception visible to External modules
144 #
145 class CookieError(Exception):
146 pass
147
148
149 # These quoting routines conform to the RFC2109 specification, which in
150 # turn references the character definitions from RFC2068. They provide
151 # a two-way quoting algorithm. Any non-text character is translated
152 # into a 4 character sequence: a forward-slash followed by the
153 # three-digit octal equivalent of the character. Any '\' or '"' is
154 # quoted with a preceding '\' slash.
155 # Because of the way browsers really handle cookies (as opposed to what
156 # the RFC says) we also encode "," and ";".
157 #
158 # These are taken from RFC2068 and RFC2109.
159 # _LegalChars is the list of chars which don't require "'s
160 # _Translator hash-table for fast quoting
161 #
162 _LegalChars = string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~:"
163 _UnescapedChars = _LegalChars + ' ()/<=>?@[]{}'
164
165 _Translator = {n: '\\%03o' % n
166 for n in set(range(256)) - set(map(ord, _UnescapedChars))}
167 _Translator.update({
168 ord('"'): '\\"',
169 ord('\\'): '\\\\',
170 })
171
172 _is_legal_key = re.compile('[%s]+' % re.escape(_LegalChars)).fullmatch
173 _control_character_re = re.compile(r'[\x00-\x1F\x7F]')
174
175
176 def _has_control_character(*val):
177 """Detects control characters within a value.
178 Supports any type, as header values can be any type.
179 """
180 return any(_control_character_re.search(str(v)) for v in val)
181
182
183 def _quote(str):
184 r"""Quote a string for use in a cookie header.
185
186 If the string does not need to be double-quoted, then just return the
187 string. Otherwise, surround the string in doublequotes and quote
188 (with a \) special characters.
189 """
190 if str is None or _is_legal_key(str):
191 return str
192 else:
193 return '"' + str.translate(_Translator) + '"'
194
195
196 _unquote_sub = re.compile(r'\\(?:([0-3][0-7][0-7])|(.))').sub
197
198 def _unquote_replace(m):
199 if m[1]:
200 return chr(int(m[1], 8))
201 else:
202 return m[2]
203
204 def _unquote(str):
205 # If there aren't any doublequotes,
206 # then there can't be any special characters. See RFC 2109.
207 if str is None or len(str) < 2:
208 return str
209 if str[0] != '"' or str[-1] != '"':
210 return str
211
212 # We have to assume that we must decode this string.
213 # Down to work.
214
215 # Remove the "s
216 str = str[1:-1]
217
218 # Check for special sequences. Examples:
219 # \012 --> \n
220 # \" --> "
221 #
222 return _unquote_sub(_unquote_replace, str)
223
224 # The _getdate() routine is used to set the expiration time in the cookie's HTTP
225 # header. By default, _getdate() returns the current time in the appropriate
226 # "expires" format for a Set-Cookie header. The one optional argument is an
227 # offset from now, in seconds. For example, an offset of -3600 means "one hour
228 # ago". The offset may be a floating-point number.
229 #
230
231 _weekdayname = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
232
233 _monthname = [None,
234 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
235 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
236
237 def _getdate(future=0, weekdayname=_weekdayname, monthname=_monthname):
238 from time import gmtime, time
239 now = time()
240 year, month, day, hh, mm, ss, wd, y, z = gmtime(now + future)
241 return "%s, %02d %3s %4d %02d:%02d:%02d GMT" % \
242 (weekdayname[wd], day, monthname[month], year, hh, mm, ss)
243
244
245 class Morsel(dict):
246 """A class to hold ONE (key, value) pair.
247
248 In a cookie, each such pair may have several attributes, so this class is
249 used to keep the attributes associated with the appropriate key,value pair.
250 This class also includes a coded_value attribute, which is used to hold
251 the network representation of the value.
252 """
253 # RFC 2109 lists these attributes as reserved:
254 # path comment domain
255 # max-age secure version
256 #
257 # For historical reasons, these attributes are also reserved:
258 # expires
259 #
260 # This is an extension from Microsoft:
261 # httponly
262 #
263 # This dictionary provides a mapping from the lowercase
264 # variant on the left to the appropriate traditional
265 # formatting on the right.
266 _reserved = {
267 "expires" : "expires",
268 "path" : "Path",
269 "comment" : "Comment",
270 "domain" : "Domain",
271 "max-age" : "Max-Age",
272 "secure" : "Secure",
273 "httponly" : "HttpOnly",
274 "version" : "Version",
275 "samesite" : "SameSite",
276 }
277
278 _flags = {'secure', 'httponly'}
279
280 def __init__(self):
281 # Set defaults
282 self._key = self._value = self._coded_value = None
283
284 # Set default attributes
285 for key in self._reserved:
286 dict.__setitem__(self, key, "")
287
288 @property
289 def key(self):
290 return self._key
291
292 @property
293 def value(self):
294 return self._value
295
296 @property
297 def coded_value(self):
298 return self._coded_value
299
300 def __setitem__(self, K, V):
301 K = K.lower()
302 if not K in self._reserved:
303 raise CookieError("Invalid attribute %r" % (K,))
304 if _has_control_character(K, V):
305 raise CookieError(f"Control characters are not allowed in cookies {K!r} {V!r}")
306 dict.__setitem__(self, K, V)
307
308 def setdefault(self, key, val=None):
309 key = key.lower()
310 if key not in self._reserved:
311 raise CookieError("Invalid attribute %r" % (key,))
312 if _has_control_character(key, val):
313 raise CookieError("Control characters are not allowed in cookies %r %r" % (key, val,))
314 return dict.setdefault(self, key, val)
315
316 def __eq__(self, morsel):
317 if not isinstance(morsel, Morsel):
318 return NotImplemented
319 return (dict.__eq__(self, morsel) and
320 self._value == morsel._value and
321 self._key == morsel._key and
322 self._coded_value == morsel._coded_value)
323
324 __ne__ = object.__ne__
325
326 def copy(self):
327 morsel = Morsel()
328 dict.update(morsel, self)
329 morsel.__dict__.update(self.__dict__)
330 return morsel
331
332 def update(self, values):
333 data = {}
334 for key, val in dict(values).items():
335 key = key.lower()
336 if key not in self._reserved:
337 raise CookieError("Invalid attribute %r" % (key,))
338 if _has_control_character(key, val):
339 raise CookieError("Control characters are not allowed in "
340 f"cookies {key!r} {val!r}")
341 data[key] = val
342 dict.update(self, data)
343
344 def __ior__(self, values):
345 self.update(values)
346 return self
347
348 def isReservedKey(self, K):
349 return K.lower() in self._reserved
350
351 def set(self, key, val, coded_val):
352 if key.lower() in self._reserved:
353 raise CookieError('Attempt to set a reserved key %r' % (key,))
354 if not _is_legal_key(key):
355 raise CookieError('Illegal key %r' % (key,))
356 if _has_control_character(key, val, coded_val):
357 raise CookieError(
358 "Control characters are not allowed in cookies %r %r %r" % (key, val, coded_val,))
359
360 # It's a good key, so save it.
361 self._key = key
362 self._value = val
363 self._coded_value = coded_val
364
365 def __getstate__(self):
366 return {
367 'key': self._key,
368 'value': self._value,
369 'coded_value': self._coded_value,
370 }
371
372 def __setstate__(self, state):
373 key = state['key']
374 value = state['value']
375 coded_value = state['coded_value']
376 if _has_control_character(key, value, coded_value):
377 raise CookieError("Control characters are not allowed in cookies "
378 f"{key!r} {value!r} {coded_value!r}")
379 self._key = key
380 self._value = value
381 self._coded_value = coded_value
382
383 def output(self, attrs=None, header="Set-Cookie:"):
384 return "%s %s" % (header, self.OutputString(attrs))
385
386 __str__ = output
387
388 def __repr__(self):
389 return '<%s: %s>' % (self.__class__.__name__, self.OutputString())
390
391 def js_output(self, attrs=None):
392 import urllib.parse
393 # Print javascript
394 output_string = self.OutputString(attrs)
395 if _has_control_character(output_string):
396 raise CookieError("Control characters are not allowed in cookies")
397 # Base64-encode value to avoid template
398 # injection in cookie values.
399 output_encoded = urllib.parse.quote(output_string, safe='', encoding='utf-8')
400 return """
401 <script type="text/javascript">
402 <!-- begin hiding
403 document.cookie = decodeURIComponent(\"%s\");
404 // end hiding -->
405 </script>
406 """ % (output_encoded,)
407
408 def OutputString(self, attrs=None):
409 # Build up our result
410 #
411 result = []
412 append = result.append
413
414 # First, the key=value pair
415 append("%s=%s" % (self.key, self.coded_value))
416
417 # Now add any defined attributes
418 if attrs is None:
419 attrs = self._reserved
420 items = sorted(self.items())
421 for key, value in items:
422 if value == "":
423 continue
424 if key not in attrs:
425 continue
426 if key == "expires" and isinstance(value, int):
427 append("%s=%s" % (self._reserved[key], _getdate(value)))
428 elif key == "max-age" and isinstance(value, int):
429 append("%s=%d" % (self._reserved[key], value))
430 elif key == "comment" and isinstance(value, str):
431 append("%s=%s" % (self._reserved[key], _quote(value)))
432 elif key in self._flags:
433 if value:
434 append(str(self._reserved[key]))
435 else:
436 append("%s=%s" % (self._reserved[key], value))
437
438 # Return the result
439 return _semispacejoin(result)
440
441 __class_getitem__ = classmethod(types.GenericAlias)
442
443
444 #
445 # Pattern for finding cookie
446 #
447 # This used to be strict parsing based on the RFC2109 and RFC2068
448 # specifications. I have since discovered that MSIE 3.0x doesn't
449 # follow the character rules outlined in those specs. As a
450 # result, the parsing rules here are less strict.
451 #
452
453 _LegalKeyChars = r"\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\="
454 _LegalValueChars = _LegalKeyChars + r'\[\]'
455 _CookiePattern = re.compile(r"""
456 \s* # Optional whitespace at start of cookie
457 (?P<key> # Start of group 'key'
458 [""" + _LegalKeyChars + r"""]+? # Any word of at least one letter
459 ) # End of group 'key'
460 ( # Optional group: there may not be a value.
461 \s*=\s* # Equal Sign
462 (?P<val> # Start of group 'val'
463 "(?:[^\\"]|\\.)*" # Any double-quoted string
464 | # or
465 # Special case for "expires" attr
466 (\w{3,6}day|\w{3}),\s # Day of the week or abbreviated day
467 [\w\d\s-]{9,11}\s[\d:]{8}\sGMT # Date and time in specific format
468 | # or
469 [""" + _LegalValueChars + r"""]* # Any word or empty string
470 ) # End of group 'val'
471 )? # End of optional value group
472 \s* # Any number of spaces.
473 (\s+|;|$) # Ending either at space, semicolon, or EOS.
474 """, re.ASCII | re.VERBOSE) # re.ASCII may be removed if safe.
475
476
477 # At long last, here is the cookie class. Using this class is almost just like
478 # using a dictionary. See this module's docstring for example usage.
479 #
480 class BaseCookie(dict):
481 """A container class for a set of Morsels."""
482
483 def value_decode(self, val):
484 """real_value, coded_value = value_decode(STRING)
485 Called prior to setting a cookie's value from the network
486 representation. The VALUE is the value read from HTTP
487 header.
488 Override this function to modify the behavior of cookies.
489 """
490 return val, val
491
492 def value_encode(self, val):
493 """real_value, coded_value = value_encode(VALUE)
494 Called prior to setting a cookie's value from the dictionary
495 representation. The VALUE is the value being assigned.
496 Override this function to modify the behavior of cookies.
497 """
498 strval = str(val)
499 return strval, strval
500
501 def __init__(self, input=None):
502 if input:
503 self.load(input)
504
505 def __set(self, key, real_value, coded_value):
506 """Private method for setting a cookie's value"""
507 M = self.get(key, Morsel())
508 M.set(key, real_value, coded_value)
509 dict.__setitem__(self, key, M)
510
511 def __setitem__(self, key, value):
512 """Dictionary style assignment."""
513 if isinstance(value, Morsel):
514 # allow assignment of constructed Morsels (e.g. for pickling)
515 dict.__setitem__(self, key, value)
516 else:
517 rval, cval = self.value_encode(value)
518 self.__set(key, rval, cval)
519
520 def output(self, attrs=None, header="Set-Cookie:", sep="\015\012"):
521 """Return a string suitable for HTTP."""
522 result = []
523 items = sorted(self.items())
524 for key, value in items:
525 value_output = value.output(attrs, header)
526 if _has_control_character(value_output):
527 raise CookieError("Control characters are not allowed in cookies")
528 result.append(value_output)
529 return sep.join(result)
530
531 __str__ = output
532
533 def __repr__(self):
534 l = []
535 items = sorted(self.items())
536 for key, value in items:
537 l.append('%s=%s' % (key, repr(value.value)))
538 return '<%s: %s>' % (self.__class__.__name__, _spacejoin(l))
539
540 def js_output(self, attrs=None):
541 """Return a string suitable for JavaScript."""
542 result = []
543 items = sorted(self.items())
544 for key, value in items:
545 result.append(value.js_output(attrs))
546 return _nulljoin(result)
547
548 def load(self, rawdata):
549 """Load cookies from a string (presumably HTTP_COOKIE) or
550 from a dictionary. Loading cookies from a dictionary 'd'
551 is equivalent to calling:
552 map(Cookie.__setitem__, d.keys(), d.values())
553 """
554 if isinstance(rawdata, str):
555 self.__parse_string(rawdata)
556 else:
557 # self.update() wouldn't call our custom __setitem__
558 for key, value in rawdata.items():
559 self[key] = value
560 return
561
562 def __parse_string(self, str, patt=_CookiePattern):
563 i = 0 # Our starting point
564 n = len(str) # Length of string
565 parsed_items = [] # Parsed (type, key, value) triples
566 morsel_seen = False # A key=value pair was previously encountered
567
568 TYPE_ATTRIBUTE = 1
569 TYPE_KEYVALUE = 2
570
571 # We first parse the whole cookie string and reject it if it's
572 # syntactically invalid (this helps avoid some classes of injection
573 # attacks).
574 while 0 <= i < n:
575 # Start looking for a cookie
576 match = patt.match(str, i)
577 if not match:
578 # No more cookies
579 break
580
581 key, value = match.group("key"), match.group("val")
582 i = match.end(0)
583
584 if key[0] == "$":
585 if not morsel_seen:
586 # We ignore attributes which pertain to the cookie
587 # mechanism as a whole, such as "$Version".
588 # See RFC 2965. (Does anyone care?)
589 continue
590 parsed_items.append((TYPE_ATTRIBUTE, key[1:], value))
591 elif key.lower() in Morsel._reserved:
592 if not morsel_seen:
593 # Invalid cookie string
594 return
595 if value is None:
596 if key.lower() in Morsel._flags:
597 parsed_items.append((TYPE_ATTRIBUTE, key, True))
598 else:
599 # Invalid cookie string
600 return
601 else:
602 parsed_items.append((TYPE_ATTRIBUTE, key, _unquote(value)))
603 elif value is not None:
604 parsed_items.append((TYPE_KEYVALUE, key, self.value_decode(value)))
605 morsel_seen = True
606 else:
607 # Invalid cookie string
608 return
609
610 # The cookie string is valid, apply it.
611 M = None # current morsel
612 for tp, key, value in parsed_items:
613 if tp == TYPE_ATTRIBUTE:
614 assert M is not None
615 M[key] = value
616 else:
617 assert tp == TYPE_KEYVALUE
618 rval, cval = value
619 self.__set(key, rval, cval)
620 M = self[key]
621
622
623 class SimpleCookie(BaseCookie):
624 """
625 SimpleCookie supports strings as cookie values. When setting
626 the value using the dictionary assignment notation, SimpleCookie
627 calls the builtin str() to convert the value to a string. Values
628 received from HTTP are kept as strings.
629 """
630 def value_decode(self, val):
631 return _unquote(val), val
632
633 def value_encode(self, val):
634 strval = str(val)
635 return strval, _quote(strval)