mod_session_crypto.html.en revision f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
af4381d113faafc97340eaaa008840c7fcbcc8fdsf XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
af4381d113faafc97340eaaa008840c7fcbcc8fdsf This file is generated from xml source: DO NOT EDIT
af4381d113faafc97340eaaa008840c7fcbcc8fdsf XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>mod_session_crypto - Apache HTTP Server</title>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div id="preamble"><h1>Apache Module mod_session_crypto</h1>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English"> en </a></p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session encryption support</td></tr>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>session_crypto_module</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_session_crypto.c</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>The session modules make use of HTTP cookies, and as such can fall
c44eeebd065e2c8cd028016b45c58afb480aaf8fdruggeri victim to Cross Site Scripting attacks, or expose potentially private
c44eeebd065e2c8cd028016b45c58afb480aaf8fdruggeri information to clients. Please ensure that the relevant risks have
c44eeebd065e2c8cd028016b45c58afb480aaf8fdruggeri been taken into account before enabling the session functionality on
c44eeebd065e2c8cd028016b45c58afb480aaf8fdruggeri your server.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>This submodule of <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> provides support for the
c44eeebd065e2c8cd028016b45c58afb480aaf8fdruggeri encryption of user sessions before being written to a local database, or
af4381d113faafc97340eaaa008840c7fcbcc8fdsf written to a remote browser via an HTTP cookie.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>This can help provide privacy to user sessions where the contents of
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar the session should be kept private from the user, or where protection is
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar needed against the effects of cross site scripting attacks.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>For more details on the session interface, see the documentation for
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar the <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> module.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<div id="quickview"><h3 class="directives">Directives</h3>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><img alt="" src="/images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><code class="module"><a href="/mod/mod_session.html">mod_session</a></code></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><code class="module"><a href="/mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<li><code class="module"><a href="/mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>To create a simple encrypted session and store it in a cookie called
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <var>session</var>, configure the session as follows:</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <div class="example"><h3>Browser based encrypted session</h3><p><code>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar Session On<br />
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar SessionCookieName session path=/<br />
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar SessionCryptoPassphrase secret
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>The session will be encrypted with the given key. Different servers can
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar be configured to share sessions by ensuring the same encryption key is used
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar on each server.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>If the encryption key is changed, sessions will be invalidated
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar automatically.</p>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <p>For documentation on how the session can be used to store username
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf and password details, see the <code class="module"><a href="/mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoCipher <var>name</var></code></td></tr>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aes256</code></td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
7f0952c0239ea2d6e37b472db6fde4ef2718343dsf<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
b09fcdfc59ada4712150e7bcc7b502bb9e4601d8rjung<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>The <code class="directive">SessionCryptoCipher</code> directive allows the cipher to
af4381d113faafc97340eaaa008840c7fcbcc8fdsf be used during encryption. If not specified, the cipher defaults to
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>Possible values depend on the crypto driver in use, and could be one of:</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf<div class="directive-section"><h2><a name="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2>
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></code></td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>The <code class="directive">SessionCryptoDriver</code> directive specifies the name of
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf the crypto driver to be used for encryption. If not specified, the driver defaults
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf to the recommended driver compiled into APR-util.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>The <var>NSS</var> crypto driver requires some parameters for configuration,
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf which are specified as parameters with optional values after the driver name.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>NSS without a certificate database</h3><p><code>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf SessionCryptoDriver nss
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>NSS with certificate database</h3><p><code>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss dir=certs
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf <div class="example"><h3>NSS with certificate database and parameters</h3><p><code>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf <div class="example"><h3>NSS with paths containing spaces</h3><p><code>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>The <var>NSS</var> crypto driver might have already been configured by another
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf part of the server, for example from <code class="module"><a href="/mod/mod_nss.html">mod_nss</a></code> or
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <code class="module"><a href="/mod/mod_ldap.html">mod_ldap</a></code>. If found to have already been configured,
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf a warning will be logged, and the existing configuration will have taken affect.
af4381d113faafc97340eaaa008840c7fcbcc8fdsf To avoid this warning, use the noinit parameter as follows.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>NSS with certificate database</h3><p><code>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss noinit
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>To prevent confusion, ensure that all modules requiring NSS are configured with
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf identical parameters.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf the engine to be used for encryption.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>OpenSSL with engine support</h3><p><code>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver openssl engine=name
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </code></td></tr>
727872d18412fc021f03969b8641810d8896820bhumbedooh<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
0d0ba3a410038e179b695446bb149cce6264e0abnd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
727872d18412fc021f03969b8641810d8896820bhumbedooh<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
0d0ba3a410038e179b695446bb149cce6264e0abnd<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
727872d18412fc021f03969b8641810d8896820bhumbedooh <p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the keys
0d0ba3a410038e179b695446bb149cce6264e0abnd to be used to enable symmetrical encryption on the contents of the session before
0d0ba3a410038e179b695446bb149cce6264e0abnd writing the session, or decrypting the contents of the session after reading the
0d0ba3a410038e179b695446bb149cce6264e0abnd session.</p>
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>Keys are more secure when they are long, and consist of truly random characters.
0d0ba3a410038e179b695446bb149cce6264e0abnd Changing the key on a server has the effect of invalidating all existing sessions.</p>
727872d18412fc021f03969b8641810d8896820bhumbedooh <p>Multiple keys can be specified in order to support key rotation. The first key
0d0ba3a410038e179b695446bb149cce6264e0abnd listed will be used for encryption, while all keys listed will be attempted for
0d0ba3a410038e179b695446bb149cce6264e0abnd decryption. To rotate keys across multiple servers over a period of time, add a new
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh secret to the end of the list, and once rolled out completely to all servers, remove
205f749042ed530040a4f0080dbcb47ceae8a374rjung the first key from the start of the list.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English"> en </a></p>
<p class="apache">Copyright 2011 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>