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 "partitioned": "Partitioned",
277 }
278
279 _reserved_defaults = dict.fromkeys(_reserved, "")
280
281 _flags = {'secure', 'httponly', 'partitioned'}
282
283 def __init__(self):
284 # Set defaults
285 self._key = self._value = self._coded_value = None
286
287 # Set default attributes
288 dict.update(self, self._reserved_defaults)
289
290 @property
291 def key(self):
292 return self._key
293
294 @property
295 def value(self):
296 return self._value
297
298 @property
299 def coded_value(self):
300 return self._coded_value
301
302 def __setitem__(self, K, V):
303 K = K.lower()
304 if not K in self._reserved:
305 raise CookieError("Invalid attribute %r" % (K,))
306 if _has_control_character(K, V):
307 raise CookieError(f"Control characters are not allowed in cookies {K!r} {V!r}")
308 dict.__setitem__(self, K, V)
309
310 def setdefault(self, key, val=None):
311 key = key.lower()
312 if key not in self._reserved:
313 raise CookieError("Invalid attribute %r" % (key,))
314 if _has_control_character(key, val):
315 raise CookieError("Control characters are not allowed in cookies %r %r" % (key, val,))
316 return dict.setdefault(self, key, val)
317
318 def __eq__(self, morsel):
319 if not isinstance(morsel, Morsel):
320 return NotImplemented
321 return (dict.__eq__(self, morsel) and
322 self._value == morsel._value and
323 self._key == morsel._key and
324 self._coded_value == morsel._coded_value)
325
326 __ne__ = object.__ne__
327
328 def copy(self):
329 morsel = Morsel()
330 dict.update(morsel, self)
331 morsel.__dict__.update(self.__dict__)
332 return morsel
333
334 def update(self, values):
335 data = {}
336 for key, val in dict(values).items():
337 key = key.lower()
338 if key not in self._reserved:
339 raise CookieError("Invalid attribute %r" % (key,))
340 if _has_control_character(key, val):
341 raise CookieError("Control characters are not allowed in "
342 f"cookies {key!r} {val!r}")
343 data[key] = val
344 dict.update(self, data)
345
346 def __ior__(self, values):
347 self.update(values)
348 return self
349
350 def isReservedKey(self, K):
351 return K.lower() in self._reserved
352
353 def set(self, key, val, coded_val):
354 if key.lower() in self._reserved:
355 raise CookieError('Attempt to set a reserved key %r' % (key,))
356 if not _is_legal_key(key):
357 raise CookieError('Illegal key %r' % (key,))
358 if _has_control_character(key, val, coded_val):
359 raise CookieError(
360 "Control characters are not allowed in cookies %r %r %r" % (key, val, coded_val,))
361
362 # It's a good key, so save it.
363 self._key = key
364 self._value = val
365 self._coded_value = coded_val
366
367 def __getstate__(self):
368 return {
369 'key': self._key,
370 'value': self._value,
371 'coded_value': self._coded_value,
372 }
373
374 def __setstate__(self, state):
375 key = state['key']
376 value = state['value']
377 coded_value = state['coded_value']
378 if _has_control_character(key, value, coded_value):
379 raise CookieError("Control characters are not allowed in cookies "
380 f"{key!r} {value!r} {coded_value!r}")
381 self._key = key
382 self._value = value
383 self._coded_value = coded_value
384
385 def output(self, attrs=None, header="Set-Cookie:"):
386 return "%s %s" % (header, self.OutputString(attrs))
387
388 __str__ = output
389
390 def __repr__(self):
391 return '<%s: %s>' % (self.__class__.__name__, self.OutputString())
392
393 def js_output(self, attrs=None):
394 import base64
395 # Print javascript
396 output_string = self.OutputString(attrs)
397 if _has_control_character(output_string):
398 raise CookieError("Control characters are not allowed in cookies")
399 # Base64-encode value to avoid template
400 # injection in cookie values.
401 output_encoded = base64.b64encode(output_string.encode('utf-8')).decode("ascii")
402 return """
403 <script type="text/javascript">
404 <!-- begin hiding
405 document.cookie = atob(\"%s\");
406 // end hiding -->
407 </script>
408 """ % (output_encoded,)
409
410 def OutputString(self, attrs=None):
411 # Build up our result
412 #
413 result = []
414 append = result.append
415
416 # First, the key=value pair
417 append("%s=%s" % (self.key, self.coded_value))
418
419 # Now add any defined attributes
420 if attrs is None:
421 attrs = self._reserved
422 items = sorted(self.items())
423 for key, value in items:
424 if value == "":
425 continue
426 if key not in attrs:
427 continue
428 if key == "expires" and isinstance(value, int):
429 append("%s=%s" % (self._reserved[key], _getdate(value)))
430 elif key == "max-age" and isinstance(value, int):
431 append("%s=%d" % (self._reserved[key], value))
432 elif key == "comment" and isinstance(value, str):
433 append("%s=%s" % (self._reserved[key], _quote(value)))
434 elif key in self._flags:
435 if value:
436 append(str(self._reserved[key]))
437 else:
438 append("%s=%s" % (self._reserved[key], value))
439
440 # Return the result
441 return _semispacejoin(result)
442
443 __class_getitem__ = classmethod(types.GenericAlias)
444
445
446 #
447 # Pattern for finding cookie
448 #
449 # This used to be strict parsing based on the RFC2109 and RFC2068
450 # specifications. I have since discovered that MSIE 3.0x doesn't
451 # follow the character rules outlined in those specs. As a
452 # result, the parsing rules here are less strict.
453 #
454
455 _LegalKeyChars = r"\w\d!#%&'~_`><@,:/\$\*\+\-\.\^\|\)\(\?\}\{\="
456 _LegalValueChars = _LegalKeyChars + r'\[\]'
457 _CookiePattern = re.compile(r"""
458 \s* # Optional whitespace at start of cookie
459 (?P<key> # Start of group 'key'
460 [""" + _LegalKeyChars + r"""]+? # Any word of at least one letter
461 ) # End of group 'key'
462 ( # Optional group: there may not be a value.
463 \s*=\s* # Equal Sign
464 (?P<val> # Start of group 'val'
465 "(?:[^\\"]|\\.)*" # Any double-quoted string
466 | # or
467 # Special case for "expires" attr
468 (\w{3,6}day|\w{3}),\s # Day of the week or abbreviated day
469 [\w\d\s-]{9,11}\s[\d:]{8}\sGMT # Date and time in specific format
470 | # or
471 [""" + _LegalValueChars + r"""]* # Any word or empty string
472 ) # End of group 'val'
473 )? # End of optional value group
474 \s* # Any number of spaces.
475 (\s+|;|$) # Ending either at space, semicolon, or EOS.
476 """, re.ASCII | re.VERBOSE) # re.ASCII may be removed if safe.
477
478
479 # At long last, here is the cookie class. Using this class is almost just like
480 # using a dictionary. See this module's docstring for example usage.
481 #
482 class BaseCookie(dict):
483 """A container class for a set of Morsels."""
484
485 def value_decode(self, val):
486 """real_value, coded_value = value_decode(STRING)
487 Called prior to setting a cookie's value from the network
488 representation. The VALUE is the value read from HTTP
489 header.
490 Override this function to modify the behavior of cookies.
491 """
492 return val, val
493
494 def value_encode(self, val):
495 """real_value, coded_value = value_encode(VALUE)
496 Called prior to setting a cookie's value from the dictionary
497 representation. The VALUE is the value being assigned.
498 Override this function to modify the behavior of cookies.
499 """
500 strval = str(val)
501 return strval, strval
502
503 def __init__(self, input=None):
504 if input:
505 self.load(input)
506
507 def __set(self, key, real_value, coded_value):
508 """Private method for setting a cookie's value"""
509 M = self.get(key, Morsel())
510 M.set(key, real_value, coded_value)
511 dict.__setitem__(self, key, M)
512
513 def __setitem__(self, key, value):
514 """Dictionary style assignment."""
515 if isinstance(value, Morsel):
516 # allow assignment of constructed Morsels (e.g. for pickling)
517 dict.__setitem__(self, key, value)
518 else:
519 rval, cval = self.value_encode(value)
520 self.__set(key, rval, cval)
521
522 def output(self, attrs=None, header="Set-Cookie:", sep="\015\012"):
523 """Return a string suitable for HTTP."""
524 result = []
525 items = sorted(self.items())
526 for key, value in items:
527 value_output = value.output(attrs, header)
528 if _has_control_character(value_output):
529 raise CookieError("Control characters are not allowed in cookies")
530 result.append(value_output)
531 return sep.join(result)
532
533 __str__ = output
534
535 def __repr__(self):
536 l = []
537 items = sorted(self.items())
538 for key, value in items:
539 l.append('%s=%s' % (key, repr(value.value)))
540 return '<%s: %s>' % (self.__class__.__name__, _spacejoin(l))
541
542 def js_output(self, attrs=None):
543 """Return a string suitable for JavaScript."""
544 result = []
545 items = sorted(self.items())
546 for key, value in items:
547 result.append(value.js_output(attrs))
548 return _nulljoin(result)
549
550 def load(self, rawdata):
551 """Load cookies from a string (presumably HTTP_COOKIE) or
552 from a dictionary. Loading cookies from a dictionary 'd'
553 is equivalent to calling:
554 map(Cookie.__setitem__, d.keys(), d.values())
555 """
556 if isinstance(rawdata, str):
557 self.__parse_string(rawdata)
558 else:
559 # self.update() wouldn't call our custom __setitem__
560 for key, value in rawdata.items():
561 self[key] = value
562 return
563
564 def __parse_string(self, str, patt=_CookiePattern):
565 i = 0 # Our starting point
566 n = len(str) # Length of string
567 parsed_items = [] # Parsed (type, key, value) triples
568 morsel_seen = False # A key=value pair was previously encountered
569
570 TYPE_ATTRIBUTE = 1
571 TYPE_KEYVALUE = 2
572
573 # We first parse the whole cookie string and reject it if it's
574 # syntactically invalid (this helps avoid some classes of injection
575 # attacks).
576 while 0 <= i < n:
577 # Start looking for a cookie
578 match = patt.match(str, i)
579 if not match:
580 # No more cookies
581 break
582
583 key, value = match.group("key"), match.group("val")
584 i = match.end(0)
585
586 if key[0] == "$":
587 if not morsel_seen:
588 # We ignore attributes which pertain to the cookie
589 # mechanism as a whole, such as "$Version".
590 # See RFC 2965. (Does anyone care?)
591 continue
592 parsed_items.append((TYPE_ATTRIBUTE, key[1:], value))
593 elif key.lower() in Morsel._reserved:
594 if not morsel_seen:
595 # Invalid cookie string
596 return
597 if value is None:
598 if key.lower() in Morsel._flags:
599 parsed_items.append((TYPE_ATTRIBUTE, key, True))
600 else:
601 # Invalid cookie string
602 return
603 else:
604 parsed_items.append((TYPE_ATTRIBUTE, key, _unquote(value)))
605 elif value is not None:
606 parsed_items.append((TYPE_KEYVALUE, key, self.value_decode(value)))
607 morsel_seen = True
608 else:
609 # Invalid cookie string
610 return
611
612 # The cookie string is valid, apply it.
613 M = None # current morsel
614 for tp, key, value in parsed_items:
615 if tp == TYPE_ATTRIBUTE:
616 assert M is not None
617 M[key] = value
618 else:
619 assert tp == TYPE_KEYVALUE
620 rval, cval = value
621 self.__set(key, rval, cval)
622 M = self[key]
623
624
625 class SimpleCookie(BaseCookie):
626 """
627 SimpleCookie supports strings as cookie values. When setting
628 the value using the dictionary assignment notation, SimpleCookie
629 calls the builtin str() to convert the value to a string. Values
630 received from HTTP are kept as strings.
631 """
632 def value_decode(self, val):
633 return _unquote(val), val
634
635 def value_encode(self, val):
636 strval = str(val)
637 return strval, _quote(strval)