1import collections 2 3import base64 4import binascii 5import hashlib 6import hmac 7import json 8from datetime import ( 9 date, 10 datetime, 11 timedelta, 12 ) 13import re 14import string 15import time 16import warnings 17 18from webob.compat import ( 19 PY3, 20 text_type, 21 bytes_, 22 text_, 23 native_, 24 string_types, 25 ) 26 27from webob.util import strings_differ 28 29__all__ = ['Cookie', 'CookieProfile', 'SignedCookieProfile', 'SignedSerializer', 30 'JSONSerializer', 'Base64Serializer', 'make_cookie'] 31 32_marker = object() 33 34class RequestCookies(collections.MutableMapping): 35 36 _cache_key = 'webob._parsed_cookies' 37 38 def __init__(self, environ): 39 self._environ = environ 40 41 @property 42 def _cache(self): 43 env = self._environ 44 header = env.get('HTTP_COOKIE', '') 45 cache, cache_header = env.get(self._cache_key, ({}, None)) 46 if cache_header == header: 47 return cache 48 d = lambda b: b.decode('utf8') 49 cache = dict((d(k), d(v)) for k,v in parse_cookie(header)) 50 env[self._cache_key] = (cache, header) 51 return cache 52 53 def _mutate_header(self, name, value): 54 header = self._environ.get('HTTP_COOKIE') 55 had_header = header is not None 56 header = header or '' 57 if PY3: # pragma: no cover 58 header = header.encode('latin-1') 59 bytes_name = bytes_(name, 'ascii') 60 if value is None: 61 replacement = None 62 else: 63 bytes_val = _value_quote(bytes_(value, 'utf-8')) 64 replacement = bytes_name + b'=' + bytes_val 65 matches = _rx_cookie.finditer(header) 66 found = False 67 for match in matches: 68 start, end = match.span() 69 match_name = match.group(1) 70 if match_name == bytes_name: 71 found = True 72 if replacement is None: # remove value 73 header = header[:start].rstrip(b' ;') + header[end:] 74 else: # replace value 75 header = header[:start] + replacement + header[end:] 76 break 77 else: 78 if replacement is not None: 79 if header: 80 header += b'; ' + replacement 81 else: 82 header = replacement 83 84 if header: 85 self._environ['HTTP_COOKIE'] = native_(header, 'latin-1') 86 elif had_header: 87 self._environ['HTTP_COOKIE'] = '' 88 89 return found 90 91 def _valid_cookie_name(self, name): 92 if not isinstance(name, string_types): 93 raise TypeError(name, 'cookie name must be a string') 94 if not isinstance(name, text_type): 95 name = text_(name, 'utf-8') 96 try: 97 bytes_cookie_name = bytes_(name, 'ascii') 98 except UnicodeEncodeError: 99 raise TypeError('cookie name must be encodable to ascii') 100 if not _valid_cookie_name(bytes_cookie_name): 101 raise TypeError('cookie name must be valid according to RFC 6265') 102 return name 103 104 def __setitem__(self, name, value): 105 name = self._valid_cookie_name(name) 106 if not isinstance(value, string_types): 107 raise ValueError(value, 'cookie value must be a string') 108 if not isinstance(value, text_type): 109 try: 110 value = text_(value, 'utf-8') 111 except UnicodeDecodeError: 112 raise ValueError( 113 value, 'cookie value must be utf-8 binary or unicode') 114 self._mutate_header(name, value) 115 116 def __getitem__(self, name): 117 return self._cache[name] 118 119 def get(self, name, default=None): 120 return self._cache.get(name, default) 121 122 def __delitem__(self, name): 123 name = self._valid_cookie_name(name) 124 found = self._mutate_header(name, None) 125 if not found: 126 raise KeyError(name) 127 128 def keys(self): 129 return self._cache.keys() 130 131 def values(self): 132 return self._cache.values() 133 134 def items(self): 135 return self._cache.items() 136 137 if not PY3: 138 def iterkeys(self): 139 return self._cache.iterkeys() 140 141 def itervalues(self): 142 return self._cache.itervalues() 143 144 def iteritems(self): 145 return self._cache.iteritems() 146 147 def __contains__(self, name): 148 return name in self._cache 149 150 def __iter__(self): 151 return self._cache.__iter__() 152 153 def __len__(self): 154 return len(self._cache) 155 156 def clear(self): 157 self._environ['HTTP_COOKIE'] = '' 158 159 def __repr__(self): 160 return '<RequestCookies (dict-like) with values %r>' % (self._cache,) 161 162 163class Cookie(dict): 164 def __init__(self, input=None): 165 if input: 166 self.load(input) 167 168 def load(self, data): 169 morsel = {} 170 for key, val in _parse_cookie(data): 171 if key.lower() in _c_keys: 172 morsel[key] = val 173 else: 174 morsel = self.add(key, val) 175 176 def add(self, key, val): 177 if not isinstance(key, bytes): 178 key = key.encode('ascii', 'replace') 179 if not _valid_cookie_name(key): 180 return {} 181 r = Morsel(key, val) 182 dict.__setitem__(self, key, r) 183 return r 184 __setitem__ = add 185 186 def serialize(self, full=True): 187 return '; '.join(m.serialize(full) for m in self.values()) 188 189 def values(self): 190 return [m for _, m in sorted(self.items())] 191 192 __str__ = serialize 193 194 def __repr__(self): 195 return '<%s: [%s]>' % (self.__class__.__name__, 196 ', '.join(map(repr, self.values()))) 197 198 199def _parse_cookie(data): 200 if PY3: # pragma: no cover 201 data = data.encode('latin-1') 202 for key, val in _rx_cookie.findall(data): 203 yield key, _unquote(val) 204 205def parse_cookie(data): 206 """ 207 Parse cookies ignoring anything except names and values 208 """ 209 return ((k,v) for k,v in _parse_cookie(data) if _valid_cookie_name(k)) 210 211 212def cookie_property(key, serialize=lambda v: v): 213 def fset(self, v): 214 self[key] = serialize(v) 215 return property(lambda self: self[key], fset) 216 217def serialize_max_age(v): 218 if isinstance(v, timedelta): 219 v = str(v.seconds + v.days*24*60*60) 220 elif isinstance(v, int): 221 v = str(v) 222 return bytes_(v) 223 224def serialize_cookie_date(v): 225 if v is None: 226 return None 227 elif isinstance(v, bytes): 228 return v 229 elif isinstance(v, text_type): 230 return v.encode('ascii') 231 elif isinstance(v, int): 232 v = timedelta(seconds=v) 233 if isinstance(v, timedelta): 234 v = datetime.utcnow() + v 235 if isinstance(v, (datetime, date)): 236 v = v.timetuple() 237 r = time.strftime('%%s, %d-%%s-%Y %H:%M:%S GMT', v) 238 return bytes_(r % (weekdays[v[6]], months[v[1]]), 'ascii') 239 240class Morsel(dict): 241 __slots__ = ('name', 'value') 242 def __init__(self, name, value): 243 self.name = bytes_(name, encoding='ascii') 244 self.value = bytes_(value, encoding='ascii') 245 assert _valid_cookie_name(self.name) 246 self.update(dict.fromkeys(_c_keys, None)) 247 248 path = cookie_property(b'path') 249 domain = cookie_property(b'domain') 250 comment = cookie_property(b'comment') 251 expires = cookie_property(b'expires', serialize_cookie_date) 252 max_age = cookie_property(b'max-age', serialize_max_age) 253 httponly = cookie_property(b'httponly', bool) 254 secure = cookie_property(b'secure', bool) 255 256 def __setitem__(self, k, v): 257 k = bytes_(k.lower(), 'ascii') 258 if k in _c_keys: 259 dict.__setitem__(self, k, v) 260 261 def serialize(self, full=True): 262 result = [] 263 add = result.append 264 add(self.name + b'=' + _value_quote(self.value)) 265 if full: 266 for k in _c_valkeys: 267 v = self[k] 268 if v: 269 info = _c_renames[k] 270 name = info['name'] 271 quoter = info['quoter'] 272 add(name + b'=' + quoter(v)) 273 expires = self[b'expires'] 274 if expires: 275 add(b'expires=' + expires) 276 if self.secure: 277 add(b'secure') 278 if self.httponly: 279 add(b'HttpOnly') 280 return native_(b'; '.join(result), 'ascii') 281 282 __str__ = serialize 283 284 def __repr__(self): 285 return '<%s: %s=%r>' % (self.__class__.__name__, 286 native_(self.name), 287 native_(self.value) 288 ) 289 290# 291# parsing 292# 293 294 295_re_quoted = r'"(?:\\"|.)*?"' # any doublequoted string 296_legal_special_chars = "~!@#$%^&*()_+=-`.?|:/(){}<>'" 297_re_legal_char = r"[\w\d%s]" % re.escape(_legal_special_chars) 298_re_expires_val = r"\w{3},\s[\w\d-]{9,11}\s[\d:]{8}\sGMT" 299_re_cookie_str_key = r"(%s+?)" % _re_legal_char 300_re_cookie_str_equal = r"\s*=\s*" 301_re_unquoted_val = r"(?:%s|\\(?:[0-3][0-7][0-7]|.))*" % _re_legal_char 302_re_cookie_str_val = r"(%s|%s|%s)" % (_re_quoted, _re_expires_val, 303 _re_unquoted_val) 304_re_cookie_str = _re_cookie_str_key + _re_cookie_str_equal + _re_cookie_str_val 305 306_rx_cookie = re.compile(bytes_(_re_cookie_str, 'ascii')) 307_rx_unquote = re.compile(bytes_(r'\\([0-3][0-7][0-7]|.)', 'ascii')) 308 309_bchr = (lambda i: bytes([i])) if PY3 else chr 310_ch_unquote_map = dict((bytes_('%03o' % i), _bchr(i)) 311 for i in range(256) 312) 313_ch_unquote_map.update((v, v) for v in list(_ch_unquote_map.values())) 314 315_b_dollar_sign = ord('$') if PY3 else '$' 316_b_quote_mark = ord('"') if PY3 else '"' 317 318def _unquote(v): 319 #assert isinstance(v, bytes) 320 if v and v[0] == v[-1] == _b_quote_mark: 321 v = v[1:-1] 322 return _rx_unquote.sub(_ch_unquote, v) 323 324def _ch_unquote(m): 325 return _ch_unquote_map[m.group(1)] 326 327 328# 329# serializing 330# 331 332# these chars can be in cookie value see 333# http://tools.ietf.org/html/rfc6265#section-4.1.1 and 334# https://github.com/Pylons/webob/pull/104#issuecomment-28044314 335# 336# ! (0x21), "#$%&'()*+" (0x25-0x2B), "-./0123456789:" (0x2D-0x3A), 337# "<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[" (0x3C-0x5B), 338# "]^_`abcdefghijklmnopqrstuvwxyz{|}~" (0x5D-0x7E) 339 340_allowed_special_chars = "!#$%&'()*+-./:<=>?@[]^_`{|}~" 341_allowed_cookie_chars = (string.ascii_letters + string.digits + 342 _allowed_special_chars) 343_allowed_cookie_bytes = bytes_(_allowed_cookie_chars) 344 345# these are the characters accepted in cookie *names* 346# From http://tools.ietf.org/html/rfc2616#section-2.2: 347# token = 1*<any CHAR except CTLs or separators> 348# separators = "(" | ")" | "<" | ">" | "@" 349# | "," | ";" | ":" | "\" | <"> 350# | "/" | "[" | "]" | "?" | "=" 351# | "{" | "}" | SP | HT 352# 353# CTL = <any US-ASCII control character 354# (octets 0 - 31) and DEL (127)> 355# 356_valid_token_chars = string.ascii_letters + string.digits + "!#$%&'*+-.^_`|~" 357_valid_token_bytes = bytes_(_valid_token_chars) 358 359# this is a map used to escape the values 360 361_escape_noop_chars = _allowed_cookie_chars + ' ' 362_escape_map = dict((chr(i), '\\%03o' % i) for i in range(256)) 363_escape_map.update(zip(_escape_noop_chars, _escape_noop_chars)) 364if PY3: # pragma: no cover 365 # convert to {int -> bytes} 366 _escape_map = dict( 367 (ord(k), bytes_(v, 'ascii')) for k, v in _escape_map.items() 368 ) 369_escape_char = _escape_map.__getitem__ 370 371weekdays = ('Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun') 372months = (None, 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 373 'Oct', 'Nov', 'Dec') 374 375 376# This is temporary, until we can remove this from _value_quote 377_should_raise = None 378 379def __warn_or_raise(text, warn_class, to_raise, raise_reason): 380 if _should_raise: 381 raise to_raise(raise_reason) 382 383 else: 384 warnings.warn(text, warn_class, stacklevel=2) 385 386 387def _value_quote(v): 388 # This looks scary, but is simple. We remove all valid characters from the 389 # string, if we end up with leftovers (string is longer than 0, we have 390 # invalid characters in our value) 391 392 leftovers = v.translate(None, _allowed_cookie_bytes) 393 if leftovers: 394 __warn_or_raise( 395 "Cookie value contains invalid bytes: (%s). Future versions " 396 "will raise ValueError upon encountering invalid bytes." % 397 (leftovers,), 398 RuntimeWarning, ValueError, 'Invalid characters in cookie value' 399 ) 400 #raise ValueError('Invalid characters in cookie value') 401 return b'"' + b''.join(map(_escape_char, v)) + b'"' 402 403 return v 404 405def _valid_cookie_name(key): 406 return isinstance(key, bytes) and not ( 407 key.translate(None, _valid_token_bytes) 408 # Not explicitly required by RFC6265, may consider removing later: 409 or key[0] == _b_dollar_sign 410 or key.lower() in _c_keys 411 ) 412 413def _path_quote(v): 414 return b''.join(map(_escape_char, v)) 415 416_domain_quote = _path_quote 417_max_age_quote = _path_quote 418 419_c_renames = { 420 b"path" : {'name':b"Path", 'quoter':_path_quote}, 421 b"comment" : {'name':b"Comment", 'quoter':_value_quote}, 422 b"domain" : {'name':b"Domain", 'quoter':_domain_quote}, 423 b"max-age" : {'name':b"Max-Age", 'quoter':_max_age_quote}, 424 } 425_c_valkeys = sorted(_c_renames) 426_c_keys = set(_c_renames) 427_c_keys.update([b'expires', b'secure', b'httponly']) 428 429 430def make_cookie(name, value, max_age=None, path='/', domain=None, 431 secure=False, httponly=False, comment=None): 432 """ Generate a cookie value. If ``value`` is None, generate a cookie value 433 with an expiration date in the past""" 434 435 # We are deleting the cookie, override max_age and expires 436 if value is None: 437 value = b'' 438 # Note that the max-age value of zero is technically contraspec; 439 # RFC6265 says that max-age cannot be zero. However, all browsers 440 # appear to support this to mean "delete immediately". 441 # http://www.timwilson.id.au/news-three-critical-problems-with-rfc6265.html 442 max_age = 0 443 expires = 'Wed, 31-Dec-97 23:59:59 GMT' 444 445 # Convert max_age to seconds 446 elif isinstance(max_age, timedelta): 447 max_age = (max_age.days * 60 * 60 * 24) + max_age.seconds 448 expires = max_age 449 else: 450 expires = max_age 451 452 morsel = Morsel(name, value) 453 454 if domain is not None: 455 morsel.domain = bytes_(domain) 456 if path is not None: 457 morsel.path = bytes_(path) 458 if httponly: 459 morsel.httponly = True 460 if secure: 461 morsel.secure = True 462 if max_age is not None: 463 morsel.max_age = max_age 464 if expires is not None: 465 morsel.expires = expires 466 if comment is not None: 467 morsel.comment = bytes_(comment) 468 return morsel.serialize() 469 470class JSONSerializer(object): 471 """ A serializer which uses `json.dumps`` and ``json.loads``""" 472 def dumps(self, appstruct): 473 return bytes_(json.dumps(appstruct), encoding='utf-8') 474 475 def loads(self, bstruct): 476 # NB: json.loads raises ValueError if no json object can be decoded 477 # so we don't have to do it explicitly here. 478 return json.loads(text_(bstruct, encoding='utf-8')) 479 480class Base64Serializer(object): 481 """ A serializer which uses base64 to encode/decode data""" 482 483 def __init__(self, serializer=None): 484 if serializer is None: 485 serializer = JSONSerializer() 486 487 self.serializer = serializer 488 489 def dumps(self, appstruct): 490 """ 491 Given an ``appstruct``, serialize and sign the data. 492 493 Returns a bytestring. 494 """ 495 cstruct = self.serializer.dumps(appstruct) # will be bytes 496 return base64.urlsafe_b64encode(cstruct) 497 498 def loads(self, bstruct): 499 """ 500 Given a ``bstruct`` (a bytestring), verify the signature and then 501 deserialize and return the deserialized value. 502 503 A ``ValueError`` will be raised if the signature fails to validate. 504 """ 505 try: 506 cstruct = base64.urlsafe_b64decode(bytes_(bstruct)) 507 except (binascii.Error, TypeError) as e: 508 raise ValueError('Badly formed base64 data: %s' % e) 509 510 return self.serializer.loads(cstruct) 511 512class SignedSerializer(object): 513 """ 514 A helper to cryptographically sign arbitrary content using HMAC. 515 516 The serializer accepts arbitrary functions for performing the actual 517 serialization and deserialization. 518 519 ``secret`` 520 A string which is used to sign the cookie. The secret should be at 521 least as long as the block size of the selected hash algorithm. For 522 ``sha512`` this would mean a 128 bit (64 character) secret. 523 524 ``salt`` 525 A namespace to avoid collisions between different uses of a shared 526 secret. 527 528 ``hashalg`` 529 The HMAC digest algorithm to use for signing. The algorithm must be 530 supported by the :mod:`hashlib` library. Default: ``'sha512'``. 531 532 ``serializer`` 533 An object with two methods: `loads`` and ``dumps``. The ``loads`` method 534 should accept bytes and return a Python object. The ``dumps`` method 535 should accept a Python object and return bytes. A ``ValueError`` should 536 be raised for malformed inputs. Default: ``None`, which will use a 537 derivation of :func:`json.dumps` and ``json.loads``. 538 539 """ 540 541 def __init__(self, 542 secret, 543 salt, 544 hashalg='sha512', 545 serializer=None, 546 ): 547 self.salt = salt 548 self.secret = secret 549 self.hashalg = hashalg 550 551 try: 552 # bwcompat with webob <= 1.3.1, leave latin-1 as the default 553 self.salted_secret = bytes_(salt or '') + bytes_(secret) 554 except UnicodeEncodeError: 555 self.salted_secret = ( 556 bytes_(salt or '', 'utf-8') + bytes_(secret, 'utf-8')) 557 558 self.digestmod = lambda string=b'': hashlib.new(self.hashalg, string) 559 self.digest_size = self.digestmod().digest_size 560 561 if serializer is None: 562 serializer = JSONSerializer() 563 564 self.serializer = serializer 565 566 def dumps(self, appstruct): 567 """ 568 Given an ``appstruct``, serialize and sign the data. 569 570 Returns a bytestring. 571 """ 572 cstruct = self.serializer.dumps(appstruct) # will be bytes 573 sig = hmac.new(self.salted_secret, cstruct, self.digestmod).digest() 574 return base64.urlsafe_b64encode(sig + cstruct).rstrip(b'=') 575 576 def loads(self, bstruct): 577 """ 578 Given a ``bstruct`` (a bytestring), verify the signature and then 579 deserialize and return the deserialized value. 580 581 A ``ValueError`` will be raised if the signature fails to validate. 582 """ 583 try: 584 b64padding = b'=' * (-len(bstruct) % 4) 585 fstruct = base64.urlsafe_b64decode(bytes_(bstruct) + b64padding) 586 except (binascii.Error, TypeError) as e: 587 raise ValueError('Badly formed base64 data: %s' % e) 588 589 cstruct = fstruct[self.digest_size:] 590 expected_sig = fstruct[:self.digest_size] 591 592 sig = hmac.new( 593 self.salted_secret, bytes_(cstruct), self.digestmod).digest() 594 595 if strings_differ(sig, expected_sig): 596 raise ValueError('Invalid signature') 597 598 return self.serializer.loads(cstruct) 599 600 601_default = object() 602 603class CookieProfile(object): 604 """ 605 A helper class that helps bring some sanity to the insanity that is cookie 606 handling. 607 608 The helper is capable of generating multiple cookies if necessary to 609 support subdomains and parent domains. 610 611 ``cookie_name`` 612 The name of the cookie used for sessioning. Default: ``'session'``. 613 614 ``max_age`` 615 The maximum age of the cookie used for sessioning (in seconds). 616 Default: ``None`` (browser scope). 617 618 ``secure`` 619 The 'secure' flag of the session cookie. Default: ``False``. 620 621 ``httponly`` 622 Hide the cookie from Javascript by setting the 'HttpOnly' flag of the 623 session cookie. Default: ``False``. 624 625 ``path`` 626 The path used for the session cookie. Default: ``'/'``. 627 628 ``domains`` 629 The domain(s) used for the session cookie. Default: ``None`` (no domain). 630 Can be passed an iterable containing multiple domains, this will set 631 multiple cookies one for each domain. 632 633 ``serializer`` 634 An object with two methods: ``loads`` and ``dumps``. The ``loads`` method 635 should accept a bytestring and return a Python object. The ``dumps`` 636 method should accept a Python object and return bytes. A ``ValueError`` 637 should be raised for malformed inputs. Default: ``None``, which will use 638 a derivation of :func:`json.dumps` and :func:`json.loads`. 639 640 """ 641 642 def __init__(self, 643 cookie_name, 644 secure=False, 645 max_age=None, 646 httponly=None, 647 path='/', 648 domains=None, 649 serializer=None 650 ): 651 self.cookie_name = cookie_name 652 self.secure = secure 653 self.max_age = max_age 654 self.httponly = httponly 655 self.path = path 656 self.domains = domains 657 658 if serializer is None: 659 serializer = Base64Serializer() 660 661 self.serializer = serializer 662 self.request = None 663 664 def __call__(self, request): 665 """ Bind a request to a copy of this instance and return it""" 666 667 return self.bind(request) 668 669 def bind(self, request): 670 """ Bind a request to a copy of this instance and return it""" 671 672 selfish = CookieProfile( 673 self.cookie_name, 674 self.secure, 675 self.max_age, 676 self.httponly, 677 self.path, 678 self.domains, 679 self.serializer, 680 ) 681 selfish.request = request 682 return selfish 683 684 def get_value(self): 685 """ Looks for a cookie by name in the currently bound request, and 686 returns its value. If the cookie profile is not bound to a request, 687 this method will raise a :exc:`ValueError`. 688 689 Looks for the cookie in the cookies jar, and if it can find it it will 690 attempt to deserialize it. Returns ``None`` if there is no cookie or 691 if the value in the cookie cannot be successfully deserialized. 692 """ 693 694 if not self.request: 695 raise ValueError('No request bound to cookie profile') 696 697 cookie = self.request.cookies.get(self.cookie_name) 698 699 if cookie is not None: 700 try: 701 return self.serializer.loads(bytes_(cookie)) 702 except ValueError: 703 return None 704 705 def set_cookies(self, response, value, domains=_default, max_age=_default, 706 path=_default, secure=_default, httponly=_default): 707 """ Set the cookies on a response.""" 708 cookies = self.get_headers( 709 value, 710 domains=domains, 711 max_age=max_age, 712 path=path, 713 secure=secure, 714 httponly=httponly 715 ) 716 response.headerlist.extend(cookies) 717 return response 718 719 def get_headers(self, value, domains=_default, max_age=_default, 720 path=_default, secure=_default, httponly=_default): 721 """ Retrieve raw headers for setting cookies. 722 723 Returns a list of headers that should be set for the cookies to 724 be correctly tracked. 725 """ 726 if value is None: 727 max_age = 0 728 bstruct = None 729 else: 730 bstruct = self.serializer.dumps(value) 731 732 return self._get_cookies( 733 bstruct, 734 domains=domains, 735 max_age=max_age, 736 path=path, 737 secure=secure, 738 httponly=httponly 739 ) 740 741 def _get_cookies(self, value, domains, max_age, path, secure, httponly): 742 """Internal function 743 744 This returns a list of cookies that are valid HTTP Headers. 745 746 :environ: The request environment 747 :value: The value to store in the cookie 748 :domains: The domains, overrides any set in the CookieProfile 749 :max_age: The max_age, overrides any set in the CookieProfile 750 :path: The path, overrides any set in the CookieProfile 751 :secure: Set this cookie to secure, overrides any set in CookieProfile 752 :httponly: Set this cookie to HttpOnly, overrides any set in CookieProfile 753 754 """ 755 756 # If the user doesn't provide values, grab the defaults 757 if domains is _default: 758 domains = self.domains 759 760 if max_age is _default: 761 max_age = self.max_age 762 763 if path is _default: 764 path = self.path 765 766 if secure is _default: 767 secure = self.secure 768 769 if httponly is _default: 770 httponly = self.httponly 771 772 # Length selected based upon http://browsercookielimits.x64.me 773 if value is not None and len(value) > 4093: 774 raise ValueError( 775 'Cookie value is too long to store (%s bytes)' % 776 len(value) 777 ) 778 779 cookies = [] 780 781 if not domains: 782 cookievalue = make_cookie( 783 self.cookie_name, 784 value, 785 path=path, 786 max_age=max_age, 787 httponly=httponly, 788 secure=secure 789 ) 790 cookies.append(('Set-Cookie', cookievalue)) 791 792 else: 793 for domain in domains: 794 cookievalue = make_cookie( 795 self.cookie_name, 796 value, 797 path=path, 798 domain=domain, 799 max_age=max_age, 800 httponly=httponly, 801 secure=secure, 802 ) 803 cookies.append(('Set-Cookie', cookievalue)) 804 805 return cookies 806 807 808class SignedCookieProfile(CookieProfile): 809 """ 810 A helper for generating cookies that are signed to prevent tampering. 811 812 By default this will create a single cookie, given a value it will 813 serialize it, then use HMAC to cryptographically sign the data. Finally 814 the result is base64-encoded for transport. This way a remote user can 815 not tamper with the value without uncovering the secret/salt used. 816 817 ``secret`` 818 A string which is used to sign the cookie. The secret should be at 819 least as long as the block size of the selected hash algorithm. For 820 ``sha512`` this would mean a 128 bit (64 character) secret. 821 822 ``salt`` 823 A namespace to avoid collisions between different uses of a shared 824 secret. 825 826 ``hashalg`` 827 The HMAC digest algorithm to use for signing. The algorithm must be 828 supported by the :mod:`hashlib` library. Default: ``'sha512'``. 829 830 ``cookie_name`` 831 The name of the cookie used for sessioning. Default: ``'session'``. 832 833 ``max_age`` 834 The maximum age of the cookie used for sessioning (in seconds). 835 Default: ``None`` (browser scope). 836 837 ``secure`` 838 The 'secure' flag of the session cookie. Default: ``False``. 839 840 ``httponly`` 841 Hide the cookie from Javascript by setting the 'HttpOnly' flag of the 842 session cookie. Default: ``False``. 843 844 ``path`` 845 The path used for the session cookie. Default: ``'/'``. 846 847 ``domains`` 848 The domain(s) used for the session cookie. Default: ``None`` (no domain). 849 Can be passed an iterable containing multiple domains, this will set 850 multiple cookies one for each domain. 851 852 ``serializer`` 853 An object with two methods: `loads`` and ``dumps``. The ``loads`` method 854 should accept bytes and return a Python object. The ``dumps`` method 855 should accept a Python object and return bytes. A ``ValueError`` should 856 be raised for malformed inputs. Default: ``None`, which will use a 857 derivation of :func:`json.dumps` and ``json.loads``. 858 """ 859 def __init__(self, 860 secret, 861 salt, 862 cookie_name, 863 secure=False, 864 max_age=None, 865 httponly=False, 866 path="/", 867 domains=None, 868 hashalg='sha512', 869 serializer=None, 870 ): 871 self.secret = secret 872 self.salt = salt 873 self.hashalg = hashalg 874 self.original_serializer = serializer 875 876 signed_serializer = SignedSerializer( 877 secret, 878 salt, 879 hashalg, 880 serializer=self.original_serializer, 881 ) 882 CookieProfile.__init__( 883 self, 884 cookie_name, 885 secure=secure, 886 max_age=max_age, 887 httponly=httponly, 888 path=path, 889 domains=domains, 890 serializer=signed_serializer, 891 ) 892 893 def bind(self, request): 894 """ Bind a request to a copy of this instance and return it""" 895 896 selfish = SignedCookieProfile( 897 self.secret, 898 self.salt, 899 self.cookie_name, 900 self.secure, 901 self.max_age, 902 self.httponly, 903 self.path, 904 self.domains, 905 self.hashalg, 906 self.original_serializer, 907 ) 908 selfish.request = request 909 return selfish 910 911