cppcms::session_interface Class Reference

This class provides an access to an application for session management. More...

#include <cppcms/session_interface.h>

Inheritance diagram for cppcms::session_interface:

List of all members.

Public Types
enum	{ fixed, renew, browser }
Public Member Functions
bool	is_set (std::string const &key)
void	erase (std::string const &key)
void	clear ()
bool	is_exposed (std::string const &key)
void	expose (std::string const &key, bool val=true)
void	hide (std::string const &key)
std::string &	operator[] (std::string const &key)
void	set (std::string const &key, std::string const &v)
std::string	get (std::string const &key)
std::string	get (std::string const &key, std::string const &default_value)
template<typename T >
T	get (std::string const &key)
template<typename T >
void	set (std::string const &key, T const &value)
template<typename Serializable >
void	store_data (std::string const &key, Serializable const &object)
template<typename Serializable >
void	fetch_data (std::string const &key, Serializable &object)
int	age ()
void	age (int t)
void	default_age ()
int	expiration ()
void	expiration (int h)
void	default_expiration ()
void	on_server (bool srv)
bool	on_server ()
void	set_session_cookie (std::string const &data)
void	clear_session_cookie ()
std::string	get_session_cookie ()
bool	load ()
void	save ()
bool	is_blocking ()
void	reset_session ()
bool	validate_csrf_token (std::string const &str)
void	validate_request_origin ()
void	request_origin_validation_is_required (bool required)
std::string	get_csrf_token ()
std::string	get_csrf_token_cookie_name ()
Friends
class	http::response
class	http::request

---

Detailed Description

This class provides an access to an application for session management.

Usually it is accessed via application::session member function.

Note, when the application is asynchronous, the sessions should be loaded manually as fetching information from session may be not so cheap

Generally, session data is represented as a map of key-value strings that can be read and written. All changes in session should be done before headers are written to the output (before requesting an output stream from http::response object)

Each of the values in session may be also exposed to client as cookie. For example if you want to disclose "foo" session key to the client side (Java Script) and session cookie is cppcms_session=S231abc23c34ca242352a then a cookie with name cppcms_session_foo will be created caring the value of this key.

Notes:

• Be careful with values you pass, cookies can carry quite a limited range of strings so it is your responsibility to make sure that these values are actually legal.
• Of course the client side can alter these cookies but this would not have an effect on the actual values fetched using session object. But still remember you should not relay on cookies values on server side for obvious security reasons.

---

Member Enumeration Documentation

anonymous enum

This enum defines the way session timeout is managed

Enumerator:

fixed	Once the session is created it will expire in age() second from the moment it created.
renew	Once the session expires in age() seconds of inactivity, once user sends an HTTP request again it is renewed
browser	The session is kept as long as browser keeps it (does not get closed). In addition the "renew" expiration policy is valid. So if user does not close his browser but is not active, it will expire in age() seconds.

---

Member Function Documentation

int cppcms::session_interface::age

(

)

Get the maximal age of the session in seconds

void cppcms::session_interface::age

(

int

t

)

Set the maximal age of the session in seconds

void cppcms::session_interface::clear

(

)

Remove all keys from the session and delete the session at all. (i.e. empty session is automatically deleted)

void cppcms::session_interface::clear_session_cookie

(

)

Remove the cookie of the current session

This function should be used only by user implementations of session storage

void cppcms::session_interface::default_age

(

)

Reset the maximal age of the session to default (session.timeout settings value or 24 hours if not set)

void cppcms::session_interface::default_expiration

(

)

Reset the expiration policy to the default (session.expire settings value or browser if not set)

void cppcms::session_interface::erase

(

std::string const &

key

)

Erase specific key from the session

int cppcms::session_interface::expiration

(

)

Get the expiration policy of the session: renew, fixed or browser

void cppcms::session_interface::expiration

(

int

h

)

Set the expiration policy of the session: renew, fixed or browser

void cppcms::session_interface::expose	(	std::string const &	key,
		bool	val = true
	)

Set exposition of the key to client side, if val is true the value will be exposed, otherwise hidden and cookie will be deleted.

template<typename Serializable >

void cppcms::session_interface::fetch_data	(	std::string const &	key,
		Serializable &	object
	)		[inline]

Fetch an object under key from the session deserializing it.

The serialization is done using cppcms::serialization_traits

Throws cppcms_error if the key is not set, may throw archive_error if deserialization fails (assuming that serialization uses cppcms::archive.

std::string cppcms::session_interface::get

(

std::string const &

key

)

Get a value for a session key. If it is not set, throws cppcms_error. It is good idea to call is_set before you call this function.

std::string cppcms::session_interface::get	(	std::string const &	key,
		std::string const &	default_value
	)

Get a value for a session key. If it is not set, returns default_value

template<typename T >

T cppcms::session_interface::get

(

std::string const &

key

)

[inline]

Get convert the value that is set for a key key to type T using std::iostream. For example you can read a number using int n=session().get<int>("number").

• it throws cppcms_error if a key key not set/
• it throws std::bad_cast of the conversion using std::iostream fails

Note: the conversion is locale independent (uses C locale)

std::string cppcms::session_interface::get_csrf_token

(

)

Get CSRF token that is stored in the session that can be used for validation of the request origin

std::string cppcms::session_interface::get_csrf_token_cookie_name

(

)

Get the cooke name that holds CSRF token. Note it can be used only if security.csrf.exposed is set to true (which is not by default)

std::string cppcms::session_interface::get_session_cookie

(

)

Get the value of the cookie that represents session on the client

This function should be used only by user implementations of session storage

void cppcms::session_interface::hide

(

std::string const &

key

)

Disable exposition of a key. Same as expose(key,false);

bool cppcms::session_interface::is_blocking

(

)

Returns true if the underlying session back-end uses blocking API so it is unsuitable to be called from asynchronous event loop. This can be used to decide how to load session for specific connection.

If the API is blocking you probably should load and save session from thread pool rather then from event loop when using asynchronous applications.

bool cppcms::session_interface::is_exposed

(

std::string const &

key

)

Returns true if specific key is exposed to client via cookies

bool cppcms::session_interface::is_set

(

std::string const &

key

)

Check if a key is set (assigned some value to it) in the session

bool cppcms::session_interface::load

(

)

Load the session, should be called one when dealing with sessions on asynchronous API where sessions are not loaded by default. This function returns true if any data was loaded.

void cppcms::session_interface::on_server

(

bool

srv

)

Set store on server side option for session. If srv is true then the session will be always stored on server side and not in cookies only (required "server" or "both" type storage in session.location setting

Rationale: client side storage using encrypted or signed cookies is very efficient, however it lacks of one important security feature: there is no other way to control their expiration but using timeout. So user may just revert the cookie to the old state to get back in time and restore its own session.

So it is recommended to use server side storage in such critical cases, like soling captcha or playing a game where you can't return to previous status when storing the data in the session object.

bool cppcms::session_interface::on_server

(

)

Get on_server session property

std::string& cppcms::session_interface::operator[]

(

std::string const &

key

)

Get the reference to a value for a key. Note if key is not exist, empty string is created in session object and reference to it returned (similarly to std::map's operator[])

void cppcms::session_interface::request_origin_validation_is_required

(

bool

required

)

Set CSRF validation mode.

If required is true then validate_request_origin() would throw request_forgery_error if the CSRF token is not valid.

Setting it to false would prevent from validate_request_origin() to do any checks.

Note:

The default is defined in the configuration property security.csrf.automatic. If its value is not set the default is true

It is useful when some parts of the application do not require CSRF validation regardless the status of sepecifc session owner

void cppcms::session_interface::reset_session

(

)

When using session id based session - force generation of new session id to prevent session fixation attacks

void cppcms::session_interface::save

(

)

Save the session data, generally should not be called as it is saved automatically. However when writing asynchronous application and using custom slow storage devices like SQL it may be useful to control when and how save() is called.

void cppcms::session_interface::set	(	std::string const &	key,
		std::string const &	v
	)

Set value v for a session key key

template<typename T >

void cppcms::session_interface::set	(	std::string const &	key,
		T const &	value
	)		[inline]

Assign a value of type T to key converting it to string using std::iostream. For example session().set("num",100); Note: the conversion is locale independent (uses C locale)

void cppcms::session_interface::set_session_cookie

(

std::string const &

data

)

Set the cookie that represents the current session (the value of the cookie)

This function should be used only by user implementations of session storage

template<typename Serializable >

void cppcms::session_interface::store_data	(	std::string const &	key,
		Serializable const &	object
	)		[inline]

Serialize an object and store it under a key.

The serialization is done using cppcms::serialization_traits

bool cppcms::session_interface::validate_csrf_token

(

std::string const &

str

)

Check that the CSRF token is the same as in the session object, it does not do any checks, whether CSRF enabled or the request method is correct. It should be used for custom request handling (like custom content types for RESTful services.

Returns true if the token is valid, otherwise returns false

void cppcms::session_interface::validate_request_origin

(

)

Check that there is no Cross Site Request Forgery Attempt.

If CSRF checks enabled it validates that there is a valid CSRF token is submitted via POST request or via X-CSRF-Token header for AJAX requests.

Note:

it is checked for POST requests only.

---

The documentation for this class was generated from the following file:

• cppcms/session_interface.h