pyramid_nacl_session
API Reference¶
-
class
pyramid_nacl_session.
EncryptedSerializer
(secret, serializer=None)¶ Encrypt session state using PyNaCl.
Parameters: - secret (bytes) – a 32-byte random secret for encrypting/decrypting the pickled session state.
- serializer – An object with two methods:
loads
anddumps
. Theloads
method should accept bytes and return a Python object. Thedumps
method should accept a Python object and return bytes. AValueError
should be raised for malformed inputs. Default:None
, which will usepyramid.session.PickleSerializer
.
-
pyramid_nacl_session.
EncryptedCookieSessionFactory
(secret, cookie_name='session', max_age=None, path='/', domain=None, secure=False, httponly=False, timeout=1200, reissue_time=0, set_on_exception=True, serializer=None, samesite='Lax')¶ Configure a session factory which will provide encrypted cookie-based sessions. The return value of this function is a session factory which may be used with the
pyramid.config.Configurator.set_session_factory()
method.The session factory returned by this function will create sessions which are limited to storing fewer than 4000 bytes of data (as the payload must fit into a single cookie).
Parameters:
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. It should be unique within the set of secret values provided to Pyramid for its various subsystems (see Admonishment Against Secret-Sharing). cookie_name
- The name of the cookie used for sessioning. Default:
'session'
. max_age
- The maximum age of the cookie used for sessioning (in seconds).
Default:
None
(browser scope). path
- The path used for the session cookie. Default:
'/'
. domain
- The domain used for the session cookie. Default:
None
(no domain). secure
- The ‘secure’ flag of the session cookie. Default:
False
. httponly
- Hide the cookie from Javascript by setting the ‘HttpOnly’ flag of the
session cookie. Default:
False
. samesite
- The ‘samesite’ option of the session cookie. Set the value to
None
to turn off the samesite option. Default:'Lax'
. timeout
- A number of seconds of inactivity before a session times out. If
None
then the cookie never expires. This lifetime only applies to the value within the cookie. Meaning that if the cookie expires due to a lowermax_age
, then this setting has no effect. Default:1200
. reissue_time
- The number of seconds that must pass before the cookie is automatically
reissued as the result of accessing the session. The
duration is measured as the number of seconds since the last session
cookie was issued and ‘now’. If this value is
0
, a new cookie will be reissued on every request accessing the session. IfNone
then the cookie’s lifetime will never be extended. A good rule of thumb: if you want auto-expired cookies based on inactivity: set thetimeout
value to 1200 (20 mins) and set thereissue_time
value to perhaps a tenth of thetimeout
value (120 or 2 mins). It’s nonsensical to set thetimeout
value lower than thereissue_time
value, as the ticket will never be reissued. However, such a configuration is not explicitly prevented. Default:0
. set_on_exception
- If
True
, set a session cookie even if an exception occurs while rendering a view. Default:True
. serializer
- An object with two methods:
loads
anddumps
. Theloads
method should accept bytes and return a Python object. Thedumps
method should accept a Python object and return bytes. AValueError
should be raised for malformed inputs. If a serializer is not passed, thepyramid.session.PickleSerializer
serializer will be used.
-
pyramid_nacl_session.
generate_secret
(as_hex=True)¶ Generate a random, 32-byte secret.
Parameters: as_hex (boolean) – If true, convert the secret to hex. Return type: bytes Returns: the secret (perhaps converted to hex).
-
pyramid_nacl_session.
session_factory_from_settings
(settings)¶ Return a Pyramid session factory using PyNaCl session settings supplied from a Paste configuration file.