granicus.if.org Git - apache/blob - docs/manual/mod/mod_session_crypto.html.en

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