fix merge conflict

6 files changed, 50 insertions, 19 deletions

diff --git a/docs/api/session.rst b/docs/api/session.rst
index 31bc196ad..dde9d20e9 100644
--- a/docs/api/session.rst
+++ b/docs/api/session.rst
@@ -5,12 +5,16 @@
 
 .. automodule:: pyramid.session
 
-  .. autofunction:: UnencryptedCookieSessionFactoryConfig
-
   .. autofunction:: signed_serialize
 
   .. autofunction:: signed_deserialize
 
   .. autofunction:: check_csrf_token
 
+  .. autofunction:: SignedCookieSessionFactory
+
+  .. autofunction:: UnencryptedCookieSessionFactoryConfig
+
+  .. autofunction:: BaseCookieSessionFactory
+
 
diff --git a/docs/narr/security.rst b/docs/narr/security.rst
index 6517fedf8..e85ed823a 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:
+
+Admonishment 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/docs/narr/sessions.rst b/docs/narr/sessions.rst
index f33bc6132..fb5035373 100644
--- a/docs/narr/sessions.rst
+++ b/docs/narr/sessions.rst
@@ -43,24 +43,23 @@ limitations:
 It is digitally signed, however, and thus its data cannot easily be
 tampered with.
 
-You can configure this session factory in your :app:`Pyramid`
-application by using the ``session_factory`` argument to the
-:class:`~pyramid.config.Configurator` class:
+You can configure this session factory in your :app:`Pyramid` application
+by using the :meth:`pyramid.config.Configurator.set_session_factory`` method.
 
 .. code-block:: python
    :linenos:
 
-   from pyramid.session import UnencryptedCookieSessionFactoryConfig
-   my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
-   
+   from pyramid.session import SignedCookieSessionFactory
+   my_session_factory = SignedCookieSessionFactory('itsaseekreet')
+
    from pyramid.config import Configurator
-   config = Configurator(session_factory = my_session_factory)
+   config = Configurator()
+   config.set_session_factory(my_session_factory)
 
 .. warning:: 
 
-   Note the very long, very explicit name for
-   ``UnencryptedCookieSessionFactoryConfig``.  It's trying to tell you that
-   this implementation is, by default, *unencrypted*.  You should not use it
+   By default the :func:`~pyramid.session.SignedCookieSessionFactory`
+   implementation is *unencrypted*.  You should not use it
    when you keep sensitive information in the session object, as the
    information can be easily read by both users of your application and third
    parties who have access to your users' network traffic.  And if you use this
diff --git a/docs/quick_tour/package/hello_world/__init__.py b/docs/quick_tour/package/hello_world/__init__.py
index 6e66bf40a..4a4fbec30 100644
--- a/docs/quick_tour/package/hello_world/__init__.py
+++ b/docs/quick_tour/package/hello_world/__init__.py
@@ -1,7 +1,7 @@
 from pyramid.config import Configurator
 from pyramid_jinja2 import renderer_factory
 # Start Sphinx Include 1
-from pyramid.session import UnencryptedCookieSessionFactoryConfig
+from pyramid.session import SignedCookieSessionFactory
 # End Sphinx Include 1
 
 from hello_world.models import get_root
@@ -16,7 +16,7 @@ def main(global_config, **settings):
     settings.setdefault('jinja2.i18n.domain', 'hello_world')
 
     # Start Sphinx Include 2
-    my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
+    my_session_factory = SignedCookieSessionFactory('itsaseekreet')
     config = Configurator(root_factory=get_root, settings=settings,
                           session_factory=my_session_factory)
     # End Sphinx Include 2
diff --git a/docs/quick_tour/package/hello_world/init.py b/docs/quick_tour/package/hello_world/init.py
index 9d7ec43d8..5b5f6a118 100644
--- a/docs/quick_tour/package/hello_world/init.py
+++ b/docs/quick_tour/package/hello_world/init.py
@@ -1,7 +1,7 @@
 from pyramid.config import Configurator
 from pyramid_jinja2 import renderer_factory
 # Start Sphinx 1
-from pyramid.session import UnencryptedCookieSessionFactoryConfig
+from pyramid.session import SignedCookieSessionFactory
 # End Sphinx 1
 
 from hello_world.models import get_root
@@ -22,7 +22,7 @@ def main(global_config, **settings):
     # End Include
 
     # Start Sphinx Include 2
-    my_session_factory = UnencryptedCookieSessionFactoryConfig('itsaseekreet')
+    my_session_factory = SignedCookieSessionFactory('itsaseekreet')
     config = Configurator(session_factory=my_session_factory)
     # End Sphinx Include 2
 
diff --git a/docs/quick_tutorial/sessions/tutorial/__init__.py b/docs/quick_tutorial/sessions/tutorial/__init__.py
index ecf57bb32..9ddc2e1b1 100644
--- a/docs/quick_tutorial/sessions/tutorial/__init__.py
+++ b/docs/quick_tutorial/sessions/tutorial/__init__.py
@@ -1,9 +1,9 @@
 from pyramid.config import Configurator
-from pyramid.session import UnencryptedCookieSessionFactoryConfig
+from pyramid.session import SignedCookieSessionFactory
 
 
 def main(global_config, **settings):
-    my_session_factory = UnencryptedCookieSessionFactoryConfig(
+    my_session_factory = SignedCookieSessionFactory(
         'itsaseekreet')
     config = Configurator(settings=settings,
                           session_factory=my_session_factory)
@@ -11,4 +11,4 @@ def main(global_config, **settings):
     config.add_route('home', '/')
     config.add_route('hello', '/howdy')
     config.scan('.views')
-    return config.make_wsgi_app()
\ No newline at end of file
+    return config.make_wsgi_app()