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