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