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:

## 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.

References cppcms::serialization_traits< Object >::load().

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

References cppcms::serialization_traits< Object >::save().

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