session.c File Reference

Signed client-side session cookie implementation. More...

#include <cwist/net/http/session.h>
#include <cwist/net/http/cookie.h>
#include <cwist/core/mem/alloc.h>
#include "async_gc.h"
#include <cjson/cJSON.h>
#include <cwist/sys/platform.h>
#include <cwist/core/crypto/sha256.h>
#include <string.h>
#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <unistd.h>
#include <fcntl.h>

Include dependency graph for session.c:

Go to the source code of this file.

Macros
#define	_POSIX_C_SOURCE   200809L
#define	CWIST_SESSION_DEFAULT_NAME   "cwist_session"
#define	CWIST_SESSION_DEFAULT_MAX_AGE   86400

Functions
int	cwist_app_use_session (cwist_app *app, const char *secret)
	Enable signed session cookies for an app. Installs or replaces the app's session secret. If secret is NULL or empty, a random secret is generated. Also applies the default cookie name and max age when they have not been set.
void	cwist_app_set_session_name (cwist_app *app, const char *name)
	Set the session cookie name for an app. Replaces any previously set name. No-op if app or name is NULL.
void	cwist_app_set_session_max_age (cwist_app *app, int seconds)
	Set the session cookie lifetime in seconds. No-op if app is NULL or seconds is not positive.
cwist_session_t *	cwist_session_start (cwist_app *app, cwist_http_request *req, cwist_http_response *res)
	Create a session for a request, loading data from the signed session cookie if present and valid. If the app has no secret yet, one is generated. The session is stored in req->session.
const char *	cwist_session_get (cwist_session_t *session, const char *key)
	Get a session value by key.
int	cwist_session_set (cwist_session_t *session, const char *key, const char *value)
	Set a session value; NULL value stores an empty string. Marks the session as modified so it is written back on commit.
void	cwist_session_delete (cwist_session_t *session, const char *key)
	Delete a key from the session. Marks the session as modified so the change is written back on commit. No-op if session, its data, or key is NULL.
void	cwist_session_invalidate (cwist_session_t *session)
	Invalidate the session: the session cookie is expired on the next commit. Marks the session as modified.
void	cwist_session_destroy (cwist_session_t *session)
	Free a session and its data. Safe to call with NULL.
void	cwist_http_async_disown_session (cwist_session_t *session)
int	cwist_session_commit (cwist_session_t *session, cwist_http_response *res)
	Persist the session to the response cookie.
cwist_middleware_func	cwist_mw_session (cwist_app *app)
	Create the session middleware for an app. Ensures the app has a session secret, generating a random one if needed, so the middleware works without a prior cwist_app_use_session() call.

Detailed Description

Signed client-side session cookie implementation.

Definition in file session.c.

Macro Definition Documentation

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Definition at line 5 of file session.c.

CWIST_SESSION_DEFAULT_MAX_AGE

#define CWIST_SESSION_DEFAULT_MAX_AGE   86400

Definition at line 35 of file session.c.

CWIST_SESSION_DEFAULT_NAME

#define CWIST_SESSION_DEFAULT_NAME   "cwist_session"

Definition at line 34 of file session.c.

Function Documentation

cwist_app_set_session_max_age()

void cwist_app_set_session_max_age	(	cwist_app *	app,
		int	seconds
	)

Set the session cookie lifetime in seconds. No-op if app is NULL or seconds is not positive.

Set session cookie max-age in seconds. Defaults to 86400 (1 day).

Parameters

app	Application to configure.
seconds	Cookie max age in seconds; must be > 0.

Definition at line 274 of file session.c.

References cap, and cwist_app::session_max_age.

cwist_app_set_session_name()

void cwist_app_set_session_name	(	cwist_app *	app,
		const char *	name
	)

Set the session cookie name for an app. Replaces any previously set name. No-op if app or name is NULL.

Set session cookie name. Defaults to "cwist_session".

Parameters

app	Application to configure.
name	Cookie name; copied internally.

Definition at line 259 of file session.c.

References cwist_free(), cwist_strdup(), and cwist_app::session_name.

cwist_app_use_session()

int cwist_app_use_session	(	cwist_app *	app,
		const char *	secret
	)

Enable signed session cookies for an app. Installs or replaces the app's session secret. If secret is NULL or empty, a random secret is generated. Also applies the default cookie name and max age when they have not been set.

Initialize session handling for an app with a signing secret.

Parameters

app	Application to configure; must not be NULL.
secret	HMAC secret, or NULL/empty to generate one.

Returns

0 on success.

Return values

-1	if app is NULL or the secret could not be set.

Definition at line 239 of file session.c.

References cap, cwist_free(), CWIST_SESSION_DEFAULT_MAX_AGE, CWIST_SESSION_DEFAULT_NAME, cwist_strdup(), cwist_app::session_max_age, cwist_app::session_name, and cwist_app::session_secret.

Referenced by cwist_mw_session(), and cwist_session_start().

cwist_http_async_disown_session()

void cwist_http_async_disown_session

(

cwist_session_t *

session

)

Definition at line 470 of file session.c.

References cwist_full_gc_enabled(), and cwist_gc_scope_disown().

cwist_mw_session()

cwist_middleware_func cwist_mw_session

(

cwist_app *

app

)

Create the session middleware for an app. Ensures the app has a session secret, generating a random one if needed, so the middleware works without a prior cwist_app_use_session() call.

Session middleware factory.

Parameters

app	Application the middleware serves.

Returns

Middleware function that starts and commits sessions per request.

Definition at line 556 of file session.c.

References cap, cwist_app_use_session(), CWIST_UNUSED, and cwist_app::session_secret.

cwist_session_commit()

int cwist_session_commit	(	cwist_session_t *	session,
		cwist_http_response *	res
	)

Persist the session to the response cookie.

The session middleware calls this automatically after the handler. If you are not using the middleware, call it before sending the response.

Definition at line 477 of file session.c.

References cap, cwist_cookie_delete(), cwist_cookie_set(), cwist_free(), cwist_query_map_foreach(), cwist_cookie_options::http_only, cwist_cookie_options::max_age_seconds, cwist_cookie_options::path, and cwist_cookie_options::same_site.

cwist_session_delete()

void cwist_session_delete	(	cwist_session_t *	session,
		const char *	key
	)

Delete a key from the session. Marks the session as modified so the change is written back on commit. No-op if session, its data, or key is NULL.

Delete a session key.

Parameters

session	Session to update.
key	Key to remove.

Definition at line 443 of file session.c.

References cwist_query_map_delete().

cwist_session_destroy()

void cwist_session_destroy

(

cwist_session_t *

session

)

Free a session and its data. Safe to call with NULL.

Destroy a session handle and its data.

Parameters

session

Session to destroy; not usable afterwards.

Definition at line 464 of file session.c.

References cwist_free(), and cwist_query_map_destroy().

Referenced by cwist_http_request_destroy().

cwist_session_get()

const char * cwist_session_get	(	cwist_session_t *	session,
		const char *	key
	)

Get a session value by key.

Parameters

session	Session returned by cwist_session_start().
key	Key to look up.

Returns

Value string, or NULL if session/key is NULL or the key is not set. The returned pointer is owned by the session.

Definition at line 414 of file session.c.

References cap, and cwist_query_map_get().

cwist_session_invalidate()

void cwist_session_invalidate

(

cwist_session_t *

session

)

Invalidate the session: the session cookie is expired on the next commit. Marks the session as modified.

Mark the session for destruction (clears cookie on commit).

Parameters

session

Session to invalidate.

Definition at line 454 of file session.c.

cwist_session_set()

int cwist_session_set	(	cwist_session_t *	session,
		const char *	key,
		const char *	value
	)

Set a session value; NULL value stores an empty string. Marks the session as modified so it is written back on commit.

Set a session value. Value is copied.

Parameters

session	Session to update.
key	Key to set; must not be NULL.
value	Value string, or NULL to store "".

Returns

0 on success.

Return values

-1	if session, its data, or key is NULL.

Definition at line 428 of file session.c.

References cwist_query_map_set().

cwist_session_start()

cwist_session_t * cwist_session_start	(	cwist_app *	app,
		cwist_http_request *	req,
		cwist_http_response *	res
	)

Create a session for a request, loading data from the signed session cookie if present and valid. If the app has no secret yet, one is generated. The session is stored in req->session.

Load or create a session for the current request.

Parameters

app	Application holding session configuration.
req	Request to attach the session to.
res	Response used for cookie parsing context.

Returns

New empty or loaded session on success, NULL on invalid arguments or allocation failure. Caller must free with cwist_session_destroy().

Definition at line 366 of file session.c.

References cap, cwist_alloc(), cwist_app_use_session(), cwist_cookie_get(), cwist_cookie_parse(), cwist_free(), cwist_http_header_get(), cwist_query_map_create(), cwist_query_map_destroy(), cwist_strdup(), cwist_http_request::headers, cwist_http_request::session, cwist_app::session_name, and cwist_app::session_secret.