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