05.Tornado Cookies

Cookie 是很多网站为了辨别用户的身份而储存在用户本地终端（Client Side）的数据，定义于 RFC2109。

5.1RequestHandler.cookies

self.request.cookies 的别名。

5.2RequestHandler.get_cookie(name: str, default: Optional[str] = None) -> Optional[str]

返回具有给定名称的请求cookie的值。

如果指定的cookie不存在，则返回默认值。

此方法仅返回请求中存在的Cookie。它看不到此处理程序中set_cookie设置的传出cookie。

5.3RequestHandler.set_cookie(name: str, value: Union[str, bytes], domain: Optional[str] = None, expires: Optional[Union[float, Tuple, datetime]] = None, path: str = '/', expires_days: Optional[float] = None, *, max_age: Optional[int] = None, httponly: bool = False, secure: bool = False, samesite: Optional[str] = None, **kwargs: Any) -> None

使用给定的选项设置传出cookie名称/值。

新设置的cookie不会立即通过get_cookie显示；他们直到下一次请求才出现。

大多数参数都直接传递给http.cookies。

expires可以是time.time返回的数字时间戳、time.gmtime返回的时间元组或datetime.datetime对象。expires_days是为了方便设置从今天开始的到期时间（如果都设置了，则使用expires）。

自6.3版本起弃用：关键字参数目前不区分大小写。在Tornado 7.0中，这将被更改为只接受小写参数。

5.4RequestHandler.clear_cookie(name: str, **kwargs: Any) -> None

删除具有给定名称的cookie。

此方法接受与set_cookie相同的参数，除了expires和max_age。清除cookie需要与设置时相同的域和路径参数。在某些情况下，还需要匹配相同的站点和安全参数。

与set_cookie类似，只有在发出以下请求后才能看到此方法的效果。

5.5RequestHandler.clear_all_cookies(**kwargs: Any) -> None

尝试删除用户随此请求发送的所有Cookie。

有关关键字参数的更多信息，请参阅clear_cookie。由于cookie协议的限制，无法在服务器端确定哪些值是域、路径、samesite或安全参数所必需的，只有在设置cookie时始终对这些参数使用相同的值，这种方法才能成功。

与set_cookie类似，只有在发出以下请求后才能看到此方法的效果。

在版本3.2中更改：添加了路径和域参数。

在版本6.3中更改：现在接受set_cookie所做的所有关键字参数。

自6.3版本以来已弃用：管理Cookie的规则越来越复杂，使得clear_all_cookies方法无法可靠工作，因为我们对Cookie的所有了解都是它们的名称。应用程序通常应该一次使用一个clear_cookie。

5.6RequestHandler.get_signed_cookie(name: str, value: Optional[str] = None, max_age_days: float = 31, min_version: Optional[int] = None) -> Optional[bytes]

如果给定的签名cookie有效，则返回该cookie，否则返回None。

解码后的cookie值以字节字符串的形式返回（与get_cookie不同）。

与get_cookie类似，此方法仅返回请求中存在的cookie。它看不到此处理程序中由set_signed_cookie设置的传出cookie。

在版本3.2.1中更改：

添加了min_version参数。推出cookie版本2；默认情况下接受版本1和2。

在版本6.3中更改：从get_secure_cookie重命名为get_signed_cookie，以避免与cookie属性和前缀中“安全”的其他用法混淆。旧名字仍然是别名。

5.7RequestHandler.set_signed_cookie(name: str, value: Union[str, bytes], expires_days: Optional[float] = 30, version: Optional[int] = None, **kwargs: Any) -> None

对cookie进行签名和时间戳，使其无法伪造。

您必须在应用程序中指定cookie_secret设置才能使用此方法。它应该是一个长的随机字节序列，用作签名的HMAC密钥。

要使用此方法读取cookie集，请使用get_signed_cookie（）。

请注意，expires_days参数设置了浏览器中cookie的生存期，但与get_signed_cookie的max_age_days参数无关。值“无”将生存期限制为当前浏览器会话。

安全Cookie可能包含任意字节值，而不仅仅是unicode字符串（与常规Cookie不同）

与set_cookie类似，只有在发出以下请求后才能看到此方法的效果。

在版本3.2.1中更改：添加了版本参数。引入cookie版本2并将其设置为默认值。

在版本6.3中更改：从set_secure_cookie重命名为set_signed_cookie，以避免与cookie属性和前缀中“安全”的其他用法混淆。旧名字仍然是别名。

5.8 Cookies 安全机制

在实际应用中，Cookie 经常用于保存 Session 信息。如：

import tornado.web 
session_id = 1 
class MainHandler(tornado.web.RequestHandler): 
    def get(self): 
        global session_id
        if not self.get_cookie("session"): 
            self.set_cookie("session",str( session_id)) 
            session_id = session_id + 1 
            self.write("Your session got a new session!") 
        else: 
            self.write("Your session was set!")

本例中用 get_cookie()函数判断 Cookie 名“session”是否存在，如果不存在则为其赋予新的session_id。

因为 Cookie 总是被保存在客户端，所以如何保证其不被篡改是服务器端程序必须解决的问题。Tornado 提供了为 Cookie 信息加密的机制，使得客户端无法随意解析和修改 Cookie 的键值。如：

import tornado.web
import asyncio

session_id = 1

class MainHandler(tornado.web.RequestHandler):
    def get(self):
        global session_id
        if not self.get_signed_cookie("session"):
            self.set_signed_cookie("session",str( session_id))
            session_id = session_id + 1
            self.write("Your session got a new session!")
        else:
            self.write("Your session was set!")

def make_app():
    return tornado.web.Application([
        (r"/", MainHandler),
    ], cookie_secret="SECRET_DONT_LEAK")

async def main():
    app = make_app()
    app.listen(8888)
    shutdown_event = asyncio.Event()
    await shutdown_event.wait()

if __name__ == "__main__":
    asyncio.run(main())

本例网站只提供了一个根目录页面，解析其关键点如下。

1. 在 tornado.web.Application 对象初始化时赋予 cookie_secret 参数，该参数值是一个字符串，用于保存本网站 Cookie 加密时的密钥。
2. 在需要读取 Cookie 的地方用 RequestHandler.get_signed_cookie 替换原来的 RequestHandler.get_cookie 调用。
3. 在需要写入 Cookie 的地方用 RequestHandler.set_signed_cookie 替换原来的 RequestHandler.set_cookie 调用。

这样，开发者就无须担心 Cookie 的伪造问题了。

5.9用户身份认证

在 Tornado 的 RequestHandler 类中有一个 current_user 属性用于保存当前请求的用户名。RequestHandler.current_user 的默认值是 None，在 get()、post()等处理函数中可以随时读取该属性以获得当前的用户名。RequestHandler.current_user 是一个只读属性，所以开发者需要重载RequestHandler.get_current_user()函数以设置该属性值。

如：通过使用 RequestHandler.current_user 属性及 RequestHandler.get_current_user() 方法来实现的用户身份控制。

import tornado.web
import tornado.ioloop
import uuid # UUID 生成库

dict_sessions = {} # 保存所有登录的 Session

class BaseHandler(tornado.web.RequestHandler): # 公共基类
    def get_current_user(self): # 写入 current_user 的函数
        if self.get_secure_cookie("session_id") is None:
            return None
        session_id = self.get_secure_cookie("session_id").decode("utf-8")
        return dict_sessions.get(session_id)

class MainHandler(BaseHandler):
    @tornado.web.authenticated # 需要身份认证才能访问的处理器
    def get(self):
        name = tornado.escape.xhtml_escape(self.current_user)
        self.write("Hello, " + name)

class LoginHandler(BaseHandler):
    def get(self): # 登录页面
        self.write('<html><body><form action="/login" method="post">'
                'Name: <input type="text" name="name">'
                '<input type="submit" value="Sign in">'
                '</form></body></html>')

    def post(self):  # 验证是否允许登录
        if len(self.get_argument("name")) < 3:
            self.redirect("/login")
            return
        session_id = str(uuid.uuid1())
        dict_sessions[session_id] = self.get_argument("name")
        self.set_secure_cookie("session_id", session_id)
        self.redirect("/")

application = tornado.web.Application(
    [  # URL 映射定义
         (r"/", MainHandler),
         (r"/login", LoginHandler),
    ],
    cookie_secret="SECRET_DONT_LEAK",  # Cookie 加密密钥
    login_url="/login")  # 定义登录页面

def main():
    application.listen(8888)
    tornado.ioloop.IOLoop.current().start()  # 挂起监听

if __name__ == "__main__":
    main()

上面的例子是一个完整的身份认证编程框架，对其代码解析如下：

1. 用全局字典 dict_sessions 保存已经登录的用户信息，为简单起见，本例只用其保存“会话 ID：用户名”的键/值对。
2. 定义公共基类 BaseHandler，该类继承自 tornado.web.RequestHandler，用于定义本网站所有处理器的公共属性和行为。重载它的 get_current_user()函数，其在开发者访问 RequestHandler.current_user 属性时自动被 Tornado 调用。该函数首先用get_secure_cookie()获得本次访问的会话 ID，然后用会话 ID 从 dict_sessions 中获得用户名并返回。
3. MainHander 类是一个要求用户经过身份认证才能访问的处理器实例。该处理器中的处理函数 get()使用了装饰器 tornado.web.authenticated，具有该装饰器的处理函数在执行之前根据 current_user 是否已经被赋值来判断用户的身份认证情况。如果已经被赋值则可以进行正常逻辑，否则自动重定向到网站的登录页面。
4. LoginHandler 类是登录页面处理器，其 get()函数用于渲染登录页面，post()函数用于验证是否允许用户登录。本例中只要用户输入的用户名大于等于 3 个字节即允许用户登录。
5. 在 tornado.web.Application 的初始化函数中通过 login_url 参数给出网站的登录页面地址。该地址被用于 tornado.web.authenticated 装饰器在发现用户尚未验证时重定向到一个 URL。
6. Tornado 使用 bytes 类型保存 cookie 值，因此在用 get_secure_cookie()读取 cookie 后需要用 decode() 函数将其转换为 string 类型再使用。

注：加入身份认证的所有页面处理器需要继承自 BaseHandler 类，而不是直接继承原来的 tornado.web.RequestHandler 类。

商用的用户身份认证还要完善更多的内容，比如加入密码验证机制、管理登录超时、将用户信息保存到数据库等，这些内容留给读者自己实践。

5.10防止跨站攻击

跨站请求伪造（Cross-Site Request Forgery，CSRF）是一种对网站的恶意利用。通过 CSRF，攻击者可以冒用用户的身份，在用户不知情的情况下执行恶意操作。

5.10.1CSRF 攻击原理

上图展示了 CSRF 的基本原理，其中 Site1 是存在 CSRF 漏洞的网站，而 Site2 是存在攻击行为的恶意网站。

1. 用户首先访问了存在 CSRF 漏洞的网站 Sites1，成功登录并获取到了 Cookie。此后，所有该用户对 Site1 的访问均会携带 Site1 的 Cookie，因此被 Site1 认为是有效操作。
2. 此时用户又访问了带有攻击行为的站点 Site2，而 Site2 的返回页面中带有一个访问 Site1进行恶意操作的连接，但被伪装成了合法内容。比如超链接看上去是一个抽奖信息，实际上却是向 Site1 站点提交提款请求的信息。
3. 用户一旦点击恶意链接，就在不知情的情况下向 Site1 站点发送了请求。因为之前用户在 Site1 进行过登录且尚未退出，所以 Site1 在收到用户的请求和附带的 Cookie 时将认为该请求是用户发出的正常请求。此时，恶意站点的目的已经达到。

5.10.2用 Tornado 防范 CSRF 攻击

为了防范 CSRF 攻击，要求每个请求包括一个参数值作为令牌来匹配存储在 Cookie 中的对应值。

Tornado 应用可以通过一个 Cookie 头和一个隐藏的 HTML 表单元素向页面提供令牌。这样，当一个合法页面的表单被提交时，它将包括表单值和已存储的 Cookie。如果两者匹配，则 Tornado 应用认定请求有效。

开启 Tornado 的 CSRF 防范功能需要两个步骤：

1. 在实例化 tornado.web.Application 时传入 xsrf_cookies=True 参数，即：
2. application = tornado.web.Application(
   [
   (r'/', MainHandler),
   (r'/purchase', PurchaseHandler),
   ],
   cookie_secret = "DONT_LEAK_SECRET",
   xsrf_cookies = True)
3. 或者
4. settings = {
   "cookie_secret": "DONT_LEAK_SECRET",
   "xsrf_cookies": True
   }
   
   application = tornado.web.Application(
   [
   (r'/', MainHandler),
   (r'/login', LoginHandler),
   ], **settings)
5. 当 tornado.web.Application 需要初始化的参数过多时，可以像本例一样通过 setting 字典的形式传入命名参数。
6. 在每个具有 HTML 表单的模板文件中，为所有表单添加 xsrf_form_html()函数标签。
7. <form action="/login" method="post">
   {% module xsrf_form_html() %}
   <input type="text" name="message"/>
   <input type="submit" value="Post"/>
   </form>
8. 这里的{% module xsrf_form_html() %}起到了为表单添加隐藏元素以防止跨站请求的作用。Tornado 的安全 Cookies 支持和 XSRF 防范框架减轻了应用开发者的很多负担。没有它们，开发者需要思考很多防范的细节措施，因此 Tornado 内建的安全功能也非常有用。