Documentation for key versioning added

diff --git a/docs/guide/security.rst b/docs/guide/security.rst
index 793fb0500638a4122d0e2566612e0b18e75a393f..9de3abb56584870bd3635a8bff55b1f72e766719 100644 (file)
--- a/docs/guide/security.rst
+++ b/docs/guide/security.rst
@@ -74,6 +74,15 @@ passed separately so that you may e.g. have a cookie that is valid for 30 days
 for most purposes, but for certain sensitive actions (such as changing billing
 information) you use a smaller ``max_age_days`` when reading the cookie.
 
+Tornado also supports multiple signing keys to enable signing key
+rotation. ``cookie_secret`` then must be a dict with integer key versions
+as keys and the corresponding secrets as values. The currently used
+signing key must then be set as ``key_version`` application setting
+but all other keys in the dict are allowed for cookie signature validation,
+if the correct key version is set in the cookie.
+To implement cookie updates, the current signing key version can be
+queried via `~.RequestHandler.get_secure_cookie_key_version`.
+
 .. _user-authentication:
 
 User authentication

diff --git a/docs/releases/next.rst b/docs/releases/next.rst
index 8cf004d8a599c182bec0903124ff4a1d10c360ba..930a118f073541cda3ef275dfb943a9848c6612f 100644 (file)
--- a/docs/releases/next.rst
+++ b/docs/releases/next.rst
@@ -56,6 +56,9 @@ Backwards-compatibility notes
 * Passing ``secure=False`` or ``httponly=False`` to
   `.RequestHandler.set_cookie` now works as expected (previously only the
   presence of the argument was considered and its value was ignored).
+* Key versioning support for cookie signing. ``cookie_secret`` application
+  setting can now contain a dict of valid keys with version as key. The
+  current signing key then must be specified via ``key_version`` setting.
 
 `tornado.websocket`
 ~~~~~~~~~~~~~~~~~~~

diff --git a/docs/web.rst b/docs/web.rst
index 0845641c7302cff4dde3cbf3f08a004d597ca1c2..0e4987a9a501343baa6a7143b8183983723386eb 100644 (file)
--- a/docs/web.rst
+++ b/docs/web.rst
@@ -86,6 +86,7 @@
    .. automethod:: RequestHandler.clear_cookie
    .. automethod:: RequestHandler.clear_all_cookies
    .. automethod:: RequestHandler.get_secure_cookie
+   .. automethod:: RequestHandler.get_secure_cookie_key_version
    .. automethod:: RequestHandler.set_secure_cookie
    .. automethod:: RequestHandler.create_signed_value
    .. autodata:: MIN_SUPPORTED_SIGNED_VALUE_VERSION
@@ -177,6 +178,9 @@
 
          * ``cookie_secret``: Used by `RequestHandler.get_secure_cookie`
            and `.set_secure_cookie` to sign cookies.
+         * ``key_version``: Used by requestHandler `.set_secure_cookie`
+           to sign cookies with a specific key when ``cookie_secret``
+           is a key dictionary.
          * ``login_url``: The `authenticated` decorator will redirect
            to this url if the user is not logged in.  Can be further
            customized by overriding `RequestHandler.get_login_url`