From db55a56f3f2088d828add8d5ef3641db4d0ec95f Mon Sep 17 00:00:00 2001 From: Graham Leggett Date: Fri, 4 Apr 2008 16:25:37 +0000 Subject: Run transformation on new documentation git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@644759 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_session.html.en | 426 ++++++++++++++++++++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 docs/manual/mod/mod_session.html.en (limited to 'docs/manual/mod/mod_session.html.en') diff --git a/docs/manual/mod/mod_session.html.en b/docs/manual/mod/mod_session.html.en new file mode 100644 index 0000000000..c2a03edc43 --- /dev/null +++ b/docs/manual/mod/mod_session.html.en @@ -0,0 +1,426 @@ + + + +mod_session - Apache HTTP Server + + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.3

+
+
<-
+
+Apache > HTTP Server > Documentation > Version 2.3 > Modules
+
+

Apache Module mod_session

+
+

Available Languages:  en 

+
+ + + +
Description:Session support
Status:Extension
Module Identifier:session_module
Source File:mod_session.c
+

Summary

+ +

Warning

+

The session modules make use of HTTP cookies, and as such can fall + victim to Cross Site Scripting attacks, or expose potentially private + information to clients. Please ensure that the relevant risks have + been taken into account before enabling the session functionality on + your server.

+
+ +

This module provides support for a server wide per user session + interface. Sessions can be used for keeping track of whether a user + has been logged in, or for other per user information that should + be kept available across requests.

+ +

Sessions may be stored on the server, or may be stored on the + browser. Sessions may also be optionally encrypted for added security. + These features are divided into several modules in addition to + mod_session: mod_session_crypto, + mod_session_cookie and mod_session_dbd. + Depending on the server requirements, load the appropriate modules + into the server (either statically at compile time or dynamically + via the LoalModule directive).

+ +

Sessions may be manipulated from other modules that depend on the + session, or the session may be read from and written to using + environment variables and HTTP headers, as appropriate.

+ +
+ +
top
+
+

What is a session?

+

At the core of the session interface is a table of key and value pairs + that are made accessible across browser requests.

+ +

These pairs can be set any valid set of strings, as needed by the + application making use of the session.

+ +
top
+
+

Who can use a session?

+

The session interface is primarily developed for the use by other + server modules, such as mod_auth_form, however CGI + based applications can optionally be granted access to the contents + of the session via the HTTP_SESSION environment variable. Sessions + have the option to be modified and/or updated by inserting an HTTP + response header containing the new session parameters.

+ +
top
+
+

Keeping sessions on the server

+

Apache can be configured to keep track of per user sessions stored + on a particular server or group of servers. This functionality is + similar to the sessions available in typical application servers.

+ +

If configured, sessions are tracked through the use of a session ID that + is stored inside a cookie, or extracted from the parameters embedded + within the URL query string, as found in a typical GET request.

+ +

As the contents of the session are stored exclusively on the server, + there is an expectation of privacy of the contents of the session. This + does have performance and resource implications should a large number + of sessions be present, or where a large number of webservers have to + share sessions with one another.

+ +

The mod_session_dbd module allows the storage of user + sessions within a SQL database via mod_dbd.

+ +
top
+
+

Keeping sessions on the browser

+

Where keeping track of a session on a server is too resource + intensive or inconvenient, the option exists to store the contents + of the session within a cookie on the client browser instead.

+ +

This has the advantage that minimal resources are required on the + server to keep track of sessions, and multiple servers within a server + farm have no need to share session information.

+ +

The contents of the session however are exposed to the client, with a + corresponding risk of a loss of privacy. The + mod_session_crypto module can be configured to encrypt the + contents of the session before writing the session to the client.

+ +

The mod_session_cookie allows the storage of user + sessions on the browser within an HTTP cookie.

+ +
top
+
+

Basic Examples

+ +

Creating a session is as simple as turning the session on, and deciding + where the session will be stored. In this example, the session will be + stored on the browser, in a cookie called session.

+ +

Browser based session

+ Session On
+ SessionCookieName session path=/
+

+ +

The session is not useful unless it can be written to or read from. The + following example shows how values can be injected into the session through + the use of a predetermined HTTP response header called + X-Replace-Session.

+ +

Writing to a session

+ Session On
+ SessionCookieName session path=/
+ SessionHeader X-Replace-Session
+

+ +

The header should contain name value pairs expressed in the same format + as a query string in a URL, as in the example below. Setting a key to the + empty string has the effect of removing that key from the session.

+ +

CGI to write to a session

+ #!/bin/bash
+ echo "Content-Type: text/plain"
+ echo "X-Replace-Session: key1=foo&key2=&key3=bar"
+ echo
+ env
+

+ +

If configured, the session can be read back from the HTTP_SESSION + environment variable. By default, the session is kept private, so this + has to be explicitly turned on with the + SessionEnv directive.

+ +

Read from a session

+ Session On
+ SessionEnv On
+ SessionCookieName session path=/
+ SessionHeader X-Replace-Session
+

+ +

Once read, the CGI variable HTTP_SESSION should contain + the value key1=foo&key3=bar.

+ +
top
+
+

Session Privacy

+ +

Using the "show cookies" feature of your browser, you would have seen + a clear text representation of the session. This could potentially be a + problem should the end user need to be kept unaware of the contents of + the session, or where a third party could gain unauthorised access to the + data within the session.

+ +

The contents of the session can be optionally encrypted before being + placed on the browser using the mod_session_crypto + module.

+ +

Browser based encrypted session

+ Session On
+ SessionCryptoPassphrase secret
+ SessionCookieName session path=/
+

+ +

The session will be automatically decrypted on load, and encrypted on + save by Apache, the underlying application using the session need have + no knowledge that encryption is taking place.

+ +

Sessions stored on the server rather than on the browser can also be + encrypted as needed, offering privacy where potentially sensitive + information is being shared between webservers in a server farm using + the mod_session_dbd module.

+ +
top
+
+

Cookie Privacy

+ +

The HTTP cookie mechanism also offers privacy features, such as the + ability to restrict cookie transport to SSL protected pages only, or + to prevent browser based javascript from gaining access to the contents + of the cookie.

+ +

Warning

+

Some of the HTTP cookie privacy features are either non standard, or + are not implemented consistently across browsers. The session modules + allow you to set cookie parameters, but it makes no guarantee that privacy + will be respected by the browser. If security is a concern, use the + mod_session_crypto to encrypt the contents of the session, + or store the session on the server using the mod_session_dbd + module.

+
+ +

Standard cookie parameters can be specified after the name of the cookie, + as in the example below.

+ +

Setting cookie parameters

+ Session On
+ SessionCryptoPassphrase secret
+ SessionCookieName session path=/private;domain=example.com;httponly;secure;
+

+ +

In cases where the Apache server forms the frontend for backend origin servers, + it is possible to have the session cookies removed from the incoming HTTP headers using + the SessionCookieRemove directive. + This keeps the contents of the session cookies from becoming accessible from the + backend server. +

+ +
top
+
+

Session Support for Authentication

+ +

As is possible within many application servers, authentication modules can use + a session for storing the username and password after login. The + mod_auth_form saves the user's login name and password within + the session.

+ +

Form based authentication

+ Session On
+ SessionCryptoPassphrase secret
+ SessionCookieName session path=/
+ AuthFormProvider file
+ AuthUserFile conf/passwd
+ AuthType form
+ AuthName realm
+ ...
+

+ +

See the mod_auth_form module for documentation and complete + examples.

+ +
+
top
+

Session Directive

+ + + + + + + + +
Description:Enables a session for the current directory or location
Syntax:Session On|Off
Default:Session Off
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

The Session directive enables a session for the + directory or location container. Further directives control where the + session will be stored and how privacy is maintained.

+ +
+
top
+

SessionEnv Directive

+ + + + + + + + +
Description:Control whether the contents of the session are written to the +HTTP_SESSION environment variable
Syntax:SessionEnv On|Off
Default:SessionEnv Off
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

If set to On, the SessionEnv directive + causes the contents of the session to be written to a CGI environment + variable called HTTP_SESSION.

+ +

The string is written in the URL query format, for example:

+ +

+ key1=foo&key3=bar +

+ + +
+
top
+

SessionExclude Directive

+ + + + + + + + +
Description:Define URL prefixes for which a session is ignored
Syntax:SessionExclude path
Default:none
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

The SessionExclude directive allows sessions to + be disabled specific URL prefixes only. This can be used to make a + website more efficient, by targeting a more precise URL space for which + a session should be maintained. By default, all URLs within the directory + or location are included in the session. The + SessionExclude directive takes + precedence over the + SessionInclude directive.

+ +

Warning

+

This directive has a similar purpose to the path attribute + in HTTP cookies, but should not be confused with this attribute. This + directive does not set the path attribute, which must be + configured separately.

+ +
+
top
+

SessionHeader Directive

+ + + + + + + + +
Description:Import session updates from a given HTTP response header
Syntax:SessionHeader header
Default:none
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

The SessionHeader directive defines the name of an + HTTP response header which, if present, will be parsed and written to the + current session.

+ +

The header value is expected to be in the URL query format, for example:

+ +

+ key1=foo&key2=&key3=bar +

+ +

Where a key is set to the empty string, that key will be removed from the + session.

+ + +
+
top
+

SessionInclude Directive

+ + + + + + + + +
Description:Define URL prefixes for which a session is valid
Syntax:SessionInclude path
Default:all URLs
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

The SessionInclude directive allows sessions to + be made valid for specific URL prefixes only. This can be used to make a + website more efficient, by targeting a more precise URL space for which + a session should be maintained. By default, all URLs within the directory + or location are included in the session.

+ +

Warning

+

This directive has a similar purpose to the path attribute + in HTTP cookies, but should not be confused with this attribute. This + directive does not set the path attribute, which must be + configured separately.

+ +
+
top
+

SessionMaxAge Directive

+ + + + + + + + +
Description:Define a maximum age in seconds for a session
Syntax:SessionMaxAge maxage
Default:SessionMaxAge 0
Context:directory
Status:Extension
Module:mod_session
Compatibility:Available in Apache 2.3.0 and later
+

The SessionMaxAge directive defines a time limit + for which a session will remain valid. When a session is saved, this time + limit is reset and an existing session can be continued. If a session + becomes older than this limit without a request to the server to refresh + the session, the session will time out and be removed. Where a session is + used to stored user login details, this has the effect of logging the user + out automatically after the given time.

+ +

Setting the maxage to zero disables session expiry.

+ +
+
+
+

Available Languages:  en 

+
+ \ No newline at end of file -- cgit v1.2.1