mention that session signature checks max age

add expiration to cookie security docs
closes pallets#2422

Author: davidism

docs/config.rst

@@ -167,9 +167,12 @@ The following configuration values are used internally by Flask:
 
 .. py:data:: PERMANENT_SESSION_LIFETIME
 
-    If ``session.permanent`` is true, the cookie's max age will be set to this
-    number of seconds. Can either be a :class:`datetime.timedelta` or an
-    ``int``.
+    If ``session.permanent`` is true, the cookie's expiration will be set this
+    number of seconds in the future. Can either be a
+    :class:`datetime.timedelta` or an ``int``.
+
+    Flask's default cookie implementation validates that the cryptographic
+    signature is not older than this value.
 
     Default: ``timedelta(days=31)`` (``2678400`` seconds)
 

docs/security.rst

@@ -206,7 +206,36 @@ They can be set on other cookies too.
 
    response.set_cookie('username', 'flask', secure=True, httponly=True)
 
-- https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Secure_and_HttpOnly_cookies
+Specifying ``Expires`` or ``Max-Age`` options, will remove the cookie after
+the given time, or the current time plus the age, respectively. If neither
+option is set, the cookie will be removed when the browser is closed. ::
+
+    # cookie expires after 10 minutes
+    response.set_cookie('snakes', '3', max_age=600)
+
+For the session cookie, if ``session.permanent`` is set, then
+:data:`SESSION_COOKIE_LIFETIME` is used to set the expiration. Flask's default
+cookie implementation validates that the cryptographic signature is not older
+than this value. Lowering this value may help mitigate replay attacks, where
+intercepted cookies can be sent at a later time.
+
+    app.config.update(
+        PERMANENT_SESSION_LIFETIME=600
+    )
+
+    @app.route('/login', methods=['POST'])
+    def login():
+        ...
+        session.clear()
+        session['user_id'] = user.id
+        session.permanent = True
+        ...
+
+Use :class:`TimedSerializer` to sign and validate other cookie values (or any
+values that need secure signatures).
+
+- https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies
+- https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie
 
 HTTP Public Key Pinning (HPKP)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~