mod_session_crypto.html.en revision 30471a4650391f57975f60bbb6e4a90be7b284bf
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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.js" type="text/javascript">
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<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.5</a> > <a href="./">Modules</a></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div id="preamble"><h1>Apache Module mod_session_crypto</h1>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<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>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
7f0952c0239ea2d6e37b472db6fde4ef2718343dsf<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>
b09fcdfc59ada4712150e7bcc7b502bb9e4601d8rjung<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>The session modules make use of HTTP cookies, and as such can fall
af4381d113faafc97340eaaa008840c7fcbcc8fdsf victim to Cross Site Scripting attacks, or expose potentially private
af4381d113faafc97340eaaa008840c7fcbcc8fdsf information to clients. Please ensure that the relevant risks have
af4381d113faafc97340eaaa008840c7fcbcc8fdsf been taken into account before enabling the session functionality on
af4381d113faafc97340eaaa008840c7fcbcc8fdsf 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
af4381d113faafc97340eaaa008840c7fcbcc8fdsf encryption of user sessions before being written to a local database, or
af4381d113faafc97340eaaa008840c7fcbcc8fdsf written to a remote browser via an HTTP cookie.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>This can help provide privacy to user sessions where the contents of
af4381d113faafc97340eaaa008840c7fcbcc8fdsf the session should be kept private from the user, or where protection is
af4381d113faafc97340eaaa008840c7fcbcc8fdsf needed against the effects of cross site scripting attacks.</p>
20f499565e77defe9dab24dd85c02f38a1175855nd <p>For more details on the session interface, see the documentation for
a4784b5a082381b03e972caf3aa052a64c68f06dhumbedooh the <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> module.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div id="quickview"><h3 class="directives">Directives</h3>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li>
48b62528cd9513fe8b5f1bbcee92ab3b28c94807rbowen<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrasefile">SessionCryptoPassphraseFile</a></li>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<li><img alt="" src="/images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<li><code class="module"><a href="/mod/mod_session.html">mod_session</a></code></li>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<li><code class="module"><a href="/mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<li><code class="module"><a href="/mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
a4784b5a082381b03e972caf3aa052a64c68f06dhumbedooh<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>To create a simple encrypted session and store it in a cookie called
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf <var>session</var>, configure the session as follows:</p>
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sfSessionCookieName session path=/
20f499565e77defe9dab24dd85c02f38a1175855ndSessionCryptoPassphrase secret
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>The session will be encrypted with the given key. Different servers can
af4381d113faafc97340eaaa008840c7fcbcc8fdsf be configured to share sessions by ensuring the same encryption key is used
af4381d113faafc97340eaaa008840c7fcbcc8fdsf on each server.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>If the encryption key is changed, sessions will be invalidated
af4381d113faafc97340eaaa008840c7fcbcc8fdsf automatically.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>For documentation on how the session can be used to store username
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf and password details, see the <code class="module"><a href="/mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr>
b09fcdfc59ada4712150e7bcc7b502bb9e4601d8rjung<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>
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>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<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
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf <p>Possible values depend on the crypto driver in use, and could be one of:</p>
cb8646cb564e6b2f7b1580b01ba4fbfd26231253sf <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
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="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<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>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf<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>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>The <code class="directive">SessionCryptoDriver</code> directive specifies the name of
2e0e3814627be5f1f08d890663cfa6c1f7671a4crpluem 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,
af4381d113faafc97340eaaa008840c7fcbcc8fdsf which are specified as parameters with optional values after the driver name.</p>
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>NSS without a certificate database</h3><pre class="prettyprint lang-config">
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">
16a0ba19b2cecf27e48c0c197ae1f3a96f447949sf SessionCryptoDriver nss dir=certs
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <div class="example"><h3>NSS with certificate database and parameters</h3><pre class="prettyprint lang-config">
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <div class="example"><h3>NSS with paths containing spaces</h3><pre class="prettyprint lang-config">
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <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.
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf To avoid this warning, use the noinit parameter as follows.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf SessionCryptoDriver nss noinit
efb3a31a4ca193ac8629a4c039d481c29171d6e0sf <p>To prevent confusion, ensure that all modules requiring NSS are configured with
af4381d113faafc97340eaaa008840c7fcbcc8fdsf identical parameters.</p>
af4381d113faafc97340eaaa008840c7fcbcc8fdsf <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
af4381d113faafc97340eaaa008840c7fcbcc8fdsf the engine to be used for encryption.</p>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <div class="example"><h3>OpenSSL with engine support</h3><pre class="prettyprint lang-config">
727872d18412fc021f03969b8641810d8896820bhumbedooh SessionCryptoDriver openssl engine=name
727872d18412fc021f03969b8641810d8896820bhumbedooh<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0d0ba3a410038e179b695446bb149cce6264e0abnd<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2>
0d0ba3a410038e179b695446bb149cce6264e0abnd<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr>
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </code></td></tr>
0d0ba3a410038e179b695446bb149cce6264e0abnd<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>
0d0ba3a410038e179b695446bb149cce6264e0abnd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
727872d18412fc021f03969b8641810d8896820bhumbedooh<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>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the keys
07dc96d063d49299da433f84b5c5681da9bbdf68rbowen to be used to enable symmetrical encryption on the contents of the session before
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen writing the session, or decrypting the contents of the session after reading the
0d0ba3a410038e179b695446bb149cce6264e0abnd session.</p>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <p>Keys are more secure when they are long, and consist of truly random characters.
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd Changing the key on a server has the effect of invalidating all existing sessions.</p>
<div class="directive-section"><h2><a name="SessionCryptoPassphraseFile" id="SessionCryptoPassphraseFile">SessionCryptoPassphraseFile</a> <a name="sessioncryptopassphrasefile" id="sessioncryptopassphrasefile">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File containing keys used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphraseFile <var>filename</var></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English"> en </a></p>
</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div><div id="disqus_thread" /><script type="text/javascript"><!--//--><![CDATA[//><!--
var disqus_identifier = window.location.href.replace(/(current|trunk)/, "2.4").replace(/\/[a-z]{2}\//, "/").replace(window.location.protocol, "http:") + '.' + lang;
if (disqus_identifier.indexOf("httpd.apache.org") != -1) {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = window.location.protocol + '//' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
var text = document.createTextNode("Comments have been disabled for offline viewing.");
document.getElementById('disqus_thread').appendChild(text);
<p class="apache">Copyright 2012 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="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--