mod_session_crypto.html.en revision 1a1356f375e36db7bee379ea0684ab389579f798
47feede6777f217fb2e2dff71635da04898e0077nd<?xml version="1.0" encoding="ISO-8859-1"?>
47feede6777f217fb2e2dff71635da04898e0077nd<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
47feede6777f217fb2e2dff71635da04898e0077nd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
47feede6777f217fb2e2dff71635da04898e0077nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
47feede6777f217fb2e2dff71635da04898e0077nd This file is generated from xml source: DO NOT EDIT
47feede6777f217fb2e2dff71635da04898e0077nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
47feede6777f217fb2e2dff71635da04898e0077nd -->
47feede6777f217fb2e2dff71635da04898e0077nd<title>mod_session_crypto - Apache HTTP Server</title>
47feede6777f217fb2e2dff71635da04898e0077nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
47feede6777f217fb2e2dff71635da04898e0077nd<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" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<script src="/style/scripts/prettify.js" type="text/javascript">
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen</script>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen
47feede6777f217fb2e2dff71635da04898e0077nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
47feede6777f217fb2e2dff71635da04898e0077nd<body>
47feede6777f217fb2e2dff71635da04898e0077nd<div id="page-header">
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen<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>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<p class="apache">Apache HTTP Server Version 2.5</p>
47feede6777f217fb2e2dff71635da04898e0077nd<img alt="" src="/images/feather.gif" /></div>
47feede6777f217fb2e2dff71635da04898e0077nd<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
47feede6777f217fb2e2dff71635da04898e0077nd<div id="path">
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
47feede6777f217fb2e2dff71635da04898e0077nd<div id="page-content">
47feede6777f217fb2e2dff71635da04898e0077nd<div id="preamble"><h1>Apache Module mod_session_crypto</h1>
47feede6777f217fb2e2dff71635da04898e0077nd<div class="toplang">
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English">&nbsp;en&nbsp;</a></p>
47feede6777f217fb2e2dff71635da04898e0077nd</div>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session encryption support</td></tr>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
47feede6777f217fb2e2dff71635da04898e0077nd<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>session_crypto_module</td></tr>
47feede6777f217fb2e2dff71635da04898e0077nd<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_session_crypto.c</td></tr>
47feede6777f217fb2e2dff71635da04898e0077nd<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
47feede6777f217fb2e2dff71635da04898e0077nd<h3>Summary</h3>
47feede6777f217fb2e2dff71635da04898e0077nd
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener <div class="warning"><h3>Warning</h3>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener <p>The session modules make use of HTTP cookies, and as such can fall
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener victim to Cross Site Scripting attacks, or expose potentially private
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener information to clients. Please ensure that the relevant risks have
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener been taken into account before enabling the session functionality on
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener your server.</p>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener </div>
47feede6777f217fb2e2dff71635da04898e0077nd
47feede6777f217fb2e2dff71635da04898e0077nd <p>This submodule of <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> provides support for the
47feede6777f217fb2e2dff71635da04898e0077nd encryption of user sessions before being written to a local database, or
47feede6777f217fb2e2dff71635da04898e0077nd written to a remote browser via an HTTP cookie.</p>
47feede6777f217fb2e2dff71635da04898e0077nd
47feede6777f217fb2e2dff71635da04898e0077nd <p>This can help provide privacy to user sessions where the contents of
47feede6777f217fb2e2dff71635da04898e0077nd the session should be kept private from the user, or where protection is
47feede6777f217fb2e2dff71635da04898e0077nd needed against the effects of cross site scripting attacks.</p>
47feede6777f217fb2e2dff71635da04898e0077nd
47feede6777f217fb2e2dff71635da04898e0077nd <p>For more details on the session interface, see the documentation for
47feede6777f217fb2e2dff71635da04898e0077nd the <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> module.</p>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh
47feede6777f217fb2e2dff71635da04898e0077nd</div>
47feede6777f217fb2e2dff71635da04898e0077nd<div id="quickview"><h3 class="directives">Directives</h3>
47feede6777f217fb2e2dff71635da04898e0077nd<ul id="toc">
47feede6777f217fb2e2dff71635da04898e0077nd<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li>
47feede6777f217fb2e2dff71635da04898e0077nd<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
47feede6777f217fb2e2dff71635da04898e0077nd<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
47feede6777f217fb2e2dff71635da04898e0077nd<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrasefile">SessionCryptoPassphraseFile</a></li>
47feede6777f217fb2e2dff71635da04898e0077nd</ul>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener<h3>Topics</h3>
47feede6777f217fb2e2dff71635da04898e0077nd<ul id="topics">
47feede6777f217fb2e2dff71635da04898e0077nd<li><img alt="" src="/images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener</ul><h3>See also</h3>
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener<ul class="seealso">
707c2713ba8f1aa11c1f22f69d3ec73522054b9fcovener<li><code class="module"><a href="/mod/mod_session.html">mod_session</a></code></li>
47feede6777f217fb2e2dff71635da04898e0077nd<li><code class="module"><a href="/mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
47feede6777f217fb2e2dff71635da04898e0077nd<li><code class="module"><a href="/mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
47feede6777f217fb2e2dff71635da04898e0077nd</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
47feede6777f217fb2e2dff71635da04898e0077nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<div class="section">
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
19737f4fbef1805f9c3e9e045bb6d710a1e5e10fhumbedooh
19737f4fbef1805f9c3e9e045bb6d710a1e5e10fhumbedooh <p>To create a simple encrypted session and store it in a cookie called
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <var>session</var>, configure the session as follows:</p>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">
19737f4fbef1805f9c3e9e045bb6d710a1e5e10fhumbedoohSession On
19737f4fbef1805f9c3e9e045bb6d710a1e5e10fhumbedoohSessionCookieName session path=/
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedoohSessionCryptoPassphrase secret
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh </pre>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh</div>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p>The session will be encrypted with the given key. Different servers can
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh be configured to share sessions by ensuring the same encryption key is used
19737f4fbef1805f9c3e9e045bb6d710a1e5e10fhumbedooh on each server.</p>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <p>If the encryption key is changed, sessions will be invalidated
5effc8b39fae5cd169d17f342bfc265705840014rbowen automatically.</p>
d229f940abfb2490dee17979e9a5ff31b7012eb5rbowen
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <p>For documentation on how the session can be used to store username
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd and password details, see the <code class="module"><a href="/mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd </div>
47feede6777f217fb2e2dff71635da04898e0077nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoCipher <var>name</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aes256</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
<p>The <code class="directive">SessionCryptoCipher</code> directive allows the cipher to
be used during encryption. If not specified, the cipher defaults to
<code>aes256</code>.</p>
<p>Possible values depend on the crypto driver in use, and could be one of:</p>
<ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
<p>The <code class="directive">SessionCryptoDriver</code> directive specifies the name of
the crypto driver to be used for encryption. If not specified, the driver defaults
to the recommended driver compiled into APR-util.</p>
<p>The <var>NSS</var> crypto driver requires some parameters for configuration,
which are specified as parameters with optional values after the driver name.</p>
<div class="example"><h3>NSS without a certificate database</h3><pre class="prettyprint lang-config">
SessionCryptoDriver nss
</pre>
</div>
<div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">
SessionCryptoDriver nss dir=certs
</pre>
</div>
<div class="example"><h3>NSS with certificate database and parameters</h3><pre class="prettyprint lang-config">
SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
</pre>
</div>
<div class="example"><h3>NSS with paths containing spaces</h3><pre class="prettyprint lang-config">
SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod
</pre>
</div>
<p>The <var>NSS</var> crypto driver might have already been configured by another
part of the server, for example from <code class="module"><a href="/mod/mod_nss.html">mod_nss</a></code> or
<code class="module"><a href="/mod/mod_ldap.html">mod_ldap</a></code>. If found to have already been configured,
a warning will be logged, and the existing configuration will have taken affect.
To avoid this warning, use the noinit parameter as follows.</p>
<div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">
SessionCryptoDriver nss noinit
</pre>
</div>
<p>To prevent confusion, ensure that all modules requiring NSS are configured with
identical parameters.</p>
<p>The <var>openssl</var> crypto driver supports an optional parameter to specify
the engine to be used for encryption.</p>
<div class="example"><h3>OpenSSL with engine support</h3><pre class="prettyprint lang-config">
SessionCryptoDriver openssl engine=name
</pre>
</div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
<p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the keys
to be used to enable symmetrical encryption on the contents of the session before
writing the session, or decrypting the contents of the session after reading the
session.</p>
<p>Keys are more secure when they are long, and consist of truly random characters.
Changing the key on a server has the effect of invalidating all existing sessions.</p>
<p>Multiple keys can be specified in order to support key rotation. The first key
listed will be used for encryption, while all keys listed will be attempted for
decryption. To rotate keys across multiple servers over a period of time, add a new
secret to the end of the list, and once rolled out completely to all servers, remove
the first key from the start of the list.</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoPassphraseFile" id="SessionCryptoPassphraseFile">SessionCryptoPassphraseFile</a> <a name="sessioncryptopassphrasefile" id="sessioncryptopassphrasefile">Directive</a></h2>
<table class="directive">
<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#Default">Default:</a></th><td><code>none</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#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
<p>The <code class="directive">SessionCryptoPassphraseFile</code> directive specifies the
name of a configuration file containing the keys to use for encrypting or decrypting
the session, specified one per line. The file is read on server start, and a graceful
restart will be necessary for httpd to pick up changes to the keys.</p>
<p>Unlike the <code class="directive">SessionCryptoPassphrase</code> directive, the keys are
not exposed within the httpd configuration and can be hidden by protecting the file
appropriately.</p>
<p>Multiple keys can be specified in order to support key rotation. The first key
listed will be used for encryption, while all keys listed will be attempted for
decryption. To rotate keys across multiple servers over a period of time, add a new
secret to the end of the list, and once rolled out completely to all servers, remove
the first key from the start of the list.</p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English">&nbsp;en&nbsp;</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>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_session_crypto.html';
(function(w, d) {
if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d.write('<div id="comments_thread"><\/div>');
var s = d.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
(d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
}
else {
d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
}
})(window, document);
//--><!]]></script></div><div id="footer">
<p class="apache">Copyright 2013 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[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>