add admonishment against secret sharing

3 files changed, 37 insertions, 3 deletions

diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 6517fedf8..9884bb1dc 100644
--- a/docs/narr/security.rst
+++ b/docs/narr/security.rst
@@ -669,3 +669,31 @@ following interface:
 After you do so, you can pass an instance of such a class into the
 :class:`~pyramid.config.Configurator.set_authorization_policy` method at
 configuration time to use it.
+
+.. _admonishment_against_secret_sharing:
+
+Admomishment Against Secret-Sharing
+-----------------------------------
+
+A "secret" is required by various components of Pyramid.  For example, the
+:term:`authentication policy` below uses a secret value ``seekrit``::
+
+  authn_policy = AuthTktAuthenticationPolicy('seekrit', hashalg='sha512')
+
+A :term:`session factory` also requires a secret::
+
+  my_session_factory = SignedCookieSessionFactory('itsaseekreet')
+
+It is tempting to use the same secret for multiple Pyramid subsystems.  For
+example, you might be tempted to use the value ``seekrit`` as the secret for
+both the authentication policy and the session factory defined above.  This is
+a bad idea, because in both cases, these secrets are used to sign the payload
+of the data.
+
+If you use the same secret for two different parts of your application for
+signing purposes, it may allow an attacker to get his chosen plaintext signed,
+which would allow the attacker to control the content of the payload.  Re-using
+a secret across two different subsystems might drop the security of signing to
+zero. Keys should not be re-used across different contexts where an attacker
+has the possibility of providing a chosen plaintext.
+
diff --git a/pyramid/authentication.py b/pyramid/authentication.py
index 454ebd4b2..3c4077073 100644
--- a/pyramid/authentication.py
+++ b/pyramid/authentication.py
@@ -424,7 +424,9 @@ class AuthTktAuthenticationPolicy(CallbackAuthenticationPolicy):
 
     ``secret``
 
-       The secret (a string) used for auth_tkt cookie signing.
+       The secret (a string) used for auth_tkt cookie signing.  This value
+       should be unique across all values provided to Pyramid for various
+       subsystem secrets (see :ref:`admonishment_against_secret_sharing`).
        Required.
 
     ``callback``
diff --git a/pyramid/session.py b/pyramid/session.py
index 60a5f7a63..f14783adb 100644
--- a/pyramid/session.py
+++ b/pyramid/session.py
@@ -487,7 +487,9 @@ def SignedCookieSessionFactory(
     ``secret``
       A string which is used to sign the cookie. The secret should be at
       least as long as the block size of the selected hash algorithm. For
-      ``sha512`` this would mean a 128 bit (64 character) secret.
+      ``sha512`` this would mean a 128 bit (64 character) secret.  It should
+      be unique within the set of secret values provided to Pyramid for
+      its various subsystems (see :ref:`admonishment_against_secret_sharing`).
 
     ``hashalg``
       The HMAC digest algorithm to use for signing. The algorithm must be
@@ -496,7 +498,9 @@ def SignedCookieSessionFactory(
     ``salt``
       A namespace to avoid collisions between different uses of a shared
       secret. Reusing a secret for different parts of an application is
-      strongly discouraged. Default: ``'pyramid.session.'``.
+      strongly discouraged, see (see
+      :ref:`admonishment_against_secret_sharing`). Default:
+      ``'pyramid.session.'``.
 
     ``cookie_name``
       The name of the cookie used for sessioning. Default: ``'session'``.