mod_session_cookie.xml revision 7d4ff16d849b1b7cda8b88c60fe6cc94bbe6b09f
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
7968d3a131e5a684ec1ff0c6d88aae638549153dChristian Maeder<!-- $LastChangedRevision$ -->
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder Licensed to the Apache Software Foundation (ASF) under one or more
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder contributor license agreements. See the NOTICE file distributed with
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder this work for additional information regarding copyright ownership.
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski The ASF licenses this file to You under the Apache License, Version 2.0
679d3f541f7a9ede4079e045f7758873bb901872Till Mossakowski (the "License"); you may not use this file except in compliance with
679d3f541f7a9ede4079e045f7758873bb901872Till Mossakowski the License. You may obtain a copy of the License at
c83546084a1344bb2ef752b83d0e082823508db2Christian Maeder Unless required by applicable law or agreed to in writing, software
9248af0871ebcf3796514f8d835cb5d6ca0b0398Christian Maeder distributed under the License is distributed on an "AS IS" BASIS,
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder See the License for the specific language governing permissions and
f69658e57cba7ecb37c0d84181f4c563215c2534Till Mossakowski limitations under the License.
7bf4436b6f9987b070033a323757b206c898c1beChristian Maeder<modulesynopsis metafile="mod_session_cookie.xml.meta">
d420c2a27c4dfa0a9c8031449db2e1a89ad2cc3aChristian Maeder<description>Cookie based session support</description>
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder<sourcefile>mod_session_cookie.c</sourcefile>
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder<identifier>session_cookie_module</identifier>
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder<compatibility>Available in Apache 2.3 and later</compatibility>
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder <p>The session modules make use of HTTP cookies, and as such can fall
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski victim to Cross Site Scripting attacks, or expose potentially private
56cd0da55d058b262b1626ddcd78db6bd9a90551Christian Maeder information to clients. Please ensure that the relevant risks have
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder been taken into account before enabling the session functionality on
7f7460e7095628f3437b116ee78d3043d11f8febChristian Maeder your server.</p>
89ab08979dc23d72e9e09c8990a8c44847041d6fChristian Maeder <p>This submodule of <module>mod_session</module> provides support for the
ad270004874ce1d0697fb30d7309f180553bb315Christian Maeder storage of user sessions on the remote browser within HTTP cookies.</p>
43b4c41fbb07705c9df321221ab9cb9832460407Christian Maeder <p>Using cookies to store a session removes the need for the server or
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder a group of servers to store the session locally, or collaborate to share
b9804822fb178b0fc27ce967a6a8cedc42c5bf90Christian Maeder a session, and can be useful for high traffic environments where a
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder server based session might be too resource intensive.</p>
c4040537e6f2153af475dd8b07260a1ee9a56ac0Christian Maeder <p>If session privacy is required, the <module>mod_session_crypto</module>
c4040537e6f2153af475dd8b07260a1ee9a56ac0Christian Maeder module can be used to encrypt the contents of the session before writing
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski the session to the client.</p>
c83546084a1344bb2ef752b83d0e082823508db2Christian Maeder <p>For more details on the session interface, see the documentation for
1e3950d5c1f0e041dd7677856e43f07796567d5bChristian Maeder the <module>mod_session</module> module.</p>
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder<seealso><module>mod_session</module></seealso>
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder<seealso><module>mod_session_crypto</module></seealso>
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder<seealso><module>mod_session_dbd</module></seealso>
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder <section id="basicexamples"><title>Basic Examples</title>
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder <p>To create a simple session and store it in a cookie called
9248af0871ebcf3796514f8d835cb5d6ca0b0398Christian Maeder <var>session</var>, configure the session as follows:</p>
9248af0871ebcf3796514f8d835cb5d6ca0b0398Christian Maeder <example><title>Browser based session</title>
9248af0871ebcf3796514f8d835cb5d6ca0b0398Christian Maeder Session On<br />
c83546084a1344bb2ef752b83d0e082823508db2Christian Maeder SessionCookieName session path=/<br />
8a2f18f56cc083acea15615185e5e9366bc9eceeChristian Maeder <p>For more examples on how the session can be configured to be read
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder from and written to by a CGI application, see the
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder <module>mod_session</module> examples section.</p>
daec53c285f692c56db0cefe16061b46ba602cf0Christian Maeder <p>For documentation on how the session can be used to store username
daec53c285f692c56db0cefe16061b46ba602cf0Christian Maeder and password details, see the <module>mod_auth_form</module> module.</p>
85211b47d269cda6a9e5b1446b99f19eae1f3c73Christian Maeder<directivesynopsis>
c83546084a1344bb2ef752b83d0e082823508db2Christian Maeder<description>Name and attributes for the RFC2109 cookie storing the session</description>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski<syntax>SessionCookieName <var>name</var> <var>attributes</var></syntax>
74885352ea11b26253d453af28dc904dadc4d530Christian Maeder<contextlist><context>server config</context>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski</contextlist>
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder <p>The <directive>SessionCookieName</directive> directive specifies the name and
a1c6679d00e15a949730ab640159e0adc5b0e3e7Christian Maeder optional attributes of an RFC2109 compliant cookie inside which the session will
2604ffeb18ba727a1c9a683f86629c4ce01b06acChristian Maeder be stored. RFC2109 cookies are set using the <code>Set-Cookie</code> HTTP header.
dc8100ead1e97ea34c9ff3fe4af14d37510bf8aeChristian Maeder <p>An optional list of cookie attributes can be specified, as per the example below.
1e3950d5c1f0e041dd7677856e43f07796567d5bChristian Maeder These attributes are inserted into the cookie as is, and are not interpreted by
4fc3dccf009f8ad9522960e54ab7a5c3d601e342Klaus Luettich Apache. Ensure that your attributes are defined correctly as per the cookie specification.
4fc3dccf009f8ad9522960e54ab7a5c3d601e342Klaus Luettich <example><title>Cookie with attributes</title>
4fc3dccf009f8ad9522960e54ab7a5c3d601e342Klaus Luettich Session On<br />
4fc3dccf009f8ad9522960e54ab7a5c3d601e342Klaus Luettich SessionCookieName session path=/private;domain=example.com;httponly;secure;version=1;<br />
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder</directivesynopsis>
c4040537e6f2153af475dd8b07260a1ee9a56ac0Christian Maeder<directivesynopsis>
8a2f18f56cc083acea15615185e5e9366bc9eceeChristian Maeder<description>Name and attributes for the RFC2965 cookie storing the session</description>
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder<syntax>SessionCookieName2 <var>name</var> <var>attributes</var></syntax>
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder<contextlist><context>server config</context>
3bcd9d942601d59dd55a6069d8b2d1c33d7ced0eChristian Maeder</contextlist>
7f7460e7095628f3437b116ee78d3043d11f8febChristian Maeder <p>The <directive>SessionCookieName2</directive> directive specifies the name and
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder optional attributes of an RFC2965 compliant cookie inside which the session will
e97bcfa4f74907e1a5ccfc3bc1509d1849cda603Christian Maeder be stored. RFC2965 cookies are set using the <code>Set-Cookie2</code> HTTP header.
ff21411cdf7c6d8d3acebbdebeade1d5ac502b83Christian Maeder <p>An optional list of cookie attributes can be specified, as per the example below.
ff21411cdf7c6d8d3acebbdebeade1d5ac502b83Christian Maeder These attributes are inserted into the cookie as is, and are not interpreted by
ade09f8be34b77402276c524bf29f2e5df666a94Christian Maeder Apache. Ensure that your attributes are defined correctly as per the cookie specification.
e97bcfa4f74907e1a5ccfc3bc1509d1849cda603Christian Maeder <example><title>Cookie2 with attributes</title>
ff21411cdf7c6d8d3acebbdebeade1d5ac502b83Christian Maeder Session On<br />
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder SessionCookieName2 session path=/private;domain=example.com;httponly;secure;version=1;<br />
15bceb77af626f79747d46d35979640f229a4c71Christian Maeder</directivesynopsis>
0ea2cddb8715a770e646895e16b7b8085f49167cChristian Maeder<directivesynopsis>
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder<description>Control for whether session cookies should be removed from incoming HTTP headers</description>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski<contextlist><context>server config</context>
89ab08979dc23d72e9e09c8990a8c44847041d6fChristian Maeder</contextlist>
42972ddff400840d46eb54422b60083228b2996cChristian Maeder <p>The <directive>SessionCookieRemove</directive> flag controls whether the cookies
b03274844ecd270f9e9331f51cc4236a33e2e671Christian Maeder containing the session will be removed from the headers during request processing.</p>
99aecbb3a3f935dd4663a45760a703faabdd04fbChristian Maeder <p>In a reverse proxy situation where the Apache server acts as a server frontend for
99aecbb3a3f935dd4663a45760a703faabdd04fbChristian Maeder a backend origin server, revealing the contents of the session cookie to the backend
cd84b488be8f6fbb674c28b8403279f13f6df015Christian Maeder could be a potential privacy violation. When set to on, the session cookie will be
42972ddff400840d46eb54422b60083228b2996cChristian Maeder removed from the incoming HTTP headers.</p>
c092fcac4b8f5c524c22ca579189c4487c13edf7Christian Maeder</directivesynopsis>
7f7460e7095628f3437b116ee78d3043d11f8febChristian Maeder</modulesynopsis>