1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_session_crypto - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<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" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<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> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<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.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_session_crypto</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English"> en </a> | 28<a href="/fr/mod/mod_session_crypto.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 29</div> 30<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session encryption support</td></tr> 31<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Experimental</td></tr> 32<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>session_crypto_module</td></tr> 33<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_session_crypto.c</td></tr> 34<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table> 35<h3>Summary</h3> 36 37 <div class="warning"><h3>Warning</h3> 38 <p>The session modules make use of HTTP cookies, and as such can fall 39 victim to Cross Site Scripting attacks, or expose potentially private 40 information to clients. Please ensure that the relevant risks have 41 been taken into account before enabling the session functionality on 42 your server.</p> 43 </div> 44 45 <p>This submodule of <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> provides support for the 46 encryption of user sessions before being written to a local database, or 47 written to a remote browser via an HTTP cookie.</p> 48 49 <p>This can help provide privacy to user sessions where the contents of 50 the session should be kept private from the user, or where protection is 51 needed against the effects of cross site scripting attacks.</p> 52 53 <p>For more details on the session interface, see the documentation for 54 the <code class="module"><a href="/mod/mod_session.html">mod_session</a></code> module.</p> 55 56</div> 57<div id="quickview"><h3 class="directives">Directives</h3> 58<ul id="toc"> 59<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li> 60<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li> 61<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li> 62<li><img alt="" src="/images/down.gif" /> <a href="#sessioncryptopassphrasefile">SessionCryptoPassphraseFile</a></li> 63</ul> 64<h3>Topics</h3> 65<ul id="topics"> 66<li><img alt="" src="/images/down.gif" /> <a href="#basicusage">Basic Usage</a></li> 67</ul><h3>See also</h3> 68<ul class="seealso"> 69<li><code class="module"><a href="/mod/mod_session.html">mod_session</a></code></li> 70<li><code class="module"><a href="/mod/mod_session_cookie.html">mod_session_cookie</a></code></li> 71<li><code class="module"><a href="/mod/mod_session_dbd.html">mod_session_dbd</a></code></li> 72</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 73<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 74<div class="section"> 75<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2> 76 77 <p>To create a simple encrypted session and store it in a cookie called 78 <var>session</var>, configure the session as follows:</p> 79 80 <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">Session On 81SessionCookieName session path=/ 82SessionCryptoPassphrase secret</pre> 83</div> 84 85 <p>The session will be encrypted with the given key. Different servers can 86 be configured to share sessions by ensuring the same encryption key is used 87 on each server.</p> 88 89 <p>If the encryption key is changed, sessions will be invalidated 90 automatically.</p> 91 92 <p>For documentation on how the session can be used to store username 93 and password details, see the <code class="module"><a href="/mod/mod_auth_form.html">mod_auth_form</a></code> module.</p> 94 95 </div> 96<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 97<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2> 98<table class="directive"> 99<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr> 100<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoCipher <var>name</var></code></td></tr> 101<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aes256</code></td></tr> 102<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 103<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> 104<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr> 105<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr> 106</table> 107 <p>The <code class="directive">SessionCryptoCipher</code> directive allows the cipher to 108 be used during encryption. If not specified, the cipher defaults to 109 <code>aes256</code>.</p> 110 111 <p>Possible values depend on the crypto driver in use, and could be one of:</p> 112 113 <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul> 114 115 116</div> 117<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 118<div class="directive-section"><h2><a name="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2> 119<table class="directive"> 120<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr> 121<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></code></td></tr> 122<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> 123<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr> 124<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> 125<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr> 126<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr> 127</table> 128 <p>The <code class="directive">SessionCryptoDriver</code> directive specifies the name of 129 the crypto driver to be used for encryption. If not specified, the driver defaults 130 to the recommended driver compiled into APR-util.</p> 131 132 <p>The <var>NSS</var> crypto driver requires some parameters for configuration, 133 which are specified as parameters with optional values after the driver name.</p> 134 135 <div class="example"><h3>NSS without a certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss</pre> 136</div> 137 138 <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss dir=certs</pre> 139</div> 140 141 <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> 142</div> 143 144 <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> 145</div> 146 147 <p>The <var>NSS</var> crypto driver might have already been 148 configured by another part of the server, for example from 149 <code>mod_nss</code> or <code class="module"><a href="/mod/mod_ldap.html">mod_ldap</a></code>. If found to 150 have already been configured, a warning will be logged, and the 151 existing configuration will have taken affect. To avoid this 152 warning, use the noinit parameter as follows.</p> 153 154 <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss noinit</pre> 155</div> 156 157 <p>To prevent confusion, ensure that all modules requiring NSS are configured with 158 identical parameters.</p> 159 160 <p>The <var>openssl</var> crypto driver supports an optional parameter to specify 161 the engine to be used for encryption.</p> 162 163 <div class="example"><h3>OpenSSL with engine support</h3><pre class="prettyprint lang-config">SessionCryptoDriver openssl engine=name</pre> 164</div> 165 166 167</div> 168<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 169<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2> 170<table class="directive"> 171<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr> 172<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </code></td></tr> 173<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> 174<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 175<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> 176<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr> 177<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr> 178</table> 179 <p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the keys 180 to be used to enable symmetrical encryption on the contents of the session before 181 writing the session, or decrypting the contents of the session after reading the 182 session.</p> 183 184 <p>Keys are more secure when they are long, and consist of truly random characters. 185 Changing the key on a server has the effect of invalidating all existing sessions.</p> 186 187 <p>Multiple keys can be specified in order to support key rotation. The first key 188 listed will be used for encryption, while all keys listed will be attempted for 189 decryption. To rotate keys across multiple servers over a period of time, add a new 190 secret to the end of the list, and once rolled out completely to all servers, remove 191 the first key from the start of the list.</p> 192 193 <p>If the value begins with exec: the resulting command will be executed and the 194 first line returned to standard output by the program will be used as the key.</p> 195<div class="example"><pre>#key used as-is 196SessionCryptoPassphrase secret 197 198#Run /path/to/program to get key 199SessionCryptoPassphrase exec:/path/to/program 200 201#Run /path/to/otherProgram and provide arguments 202SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"</pre></div> 203 204 205</div> 206<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 207<div class="directive-section"><h2><a name="SessionCryptoPassphraseFile" id="SessionCryptoPassphraseFile">SessionCryptoPassphraseFile</a> <a name="sessioncryptopassphrasefile" id="sessioncryptopassphrasefile">Directive</a></h2> 208<table class="directive"> 209<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File containing keys used to encrypt the session</td></tr> 210<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphraseFile <var>filename</var></code></td></tr> 211<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr> 212<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 213<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr> 214<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr> 215<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr> 216</table> 217 <p>The <code class="directive">SessionCryptoPassphraseFile</code> directive specifies the 218 name of a configuration file containing the keys to use for encrypting or decrypting 219 the session, specified one per line. The file is read on server start, and a graceful 220 restart will be necessary for httpd to pick up changes to the keys.</p> 221 222 <p>Unlike the <code class="directive">SessionCryptoPassphrase</code> directive, the keys are 223 not exposed within the httpd configuration and can be hidden by protecting the file 224 appropriately.</p> 225 226 <p>Multiple keys can be specified in order to support key rotation. The first key 227 listed will be used for encryption, while all keys listed will be attempted for 228 decryption. To rotate keys across multiple servers over a period of time, add a new 229 secret to the end of the list, and once rolled out completely to all servers, remove 230 the first key from the start of the list.</p> 231 232 233</div> 234</div> 235<div class="bottomlang"> 236<p><span>Available Languages: </span><a href="/en/mod/mod_session_crypto.html" title="English"> en </a> | 237<a href="/fr/mod/mod_session_crypto.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a></p> 238</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&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> 239<script type="text/javascript"><!--//--><![CDATA[//><!-- 240var comments_shortname = 'httpd'; 241var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_session_crypto.html'; 242(function(w, d) { 243 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 244 d.write('<div id="comments_thread"><\/div>'); 245 var s = d.createElement('script'); 246 s.type = 'text/javascript'; 247 s.async = true; 248 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 249 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 250 } 251 else { 252 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 253 } 254})(window, document); 255//--><!]]></script></div><div id="footer"> 256<p class="apache">Copyright 2014 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> 257<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[//><!-- 258if (typeof(prettyPrint) !== 'undefined') { 259 prettyPrint(); 260} 261//--><!]]></script> 262</body></html>
