<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
+<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
+<!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
-<title>mod_session_crypto - Apache HTTP Server</title>
+<title>mod_session_crypto - Apache HTTP Server Version 2.5</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
-<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
+<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" />
+<script src="../style/scripts/prettify.min.js" type="text/javascript">
+</script>
+
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
-<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>
-<p class="apache">Apache HTTP Server Version 2.3</p>
-<img alt="" src="../images/feather.gif" /></div>
+<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>
+<p class="apache">Apache HTTP Server Version 2.5</p>
+<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
-<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>
+<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.
5</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_session_crypto</h1>
<div class="toplang">
the <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
</div>
-<div id="quickview"><h3 class="directives">Directives</h3>
+<div id="quickview"><h3>Topics</h3>
+<ul id="topics">
+<li><img alt="" src="../images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
+</ul><h3 class="directives">Directives</h3>
<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptocipher">SessionCryptoCipher</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptopassphrasefile">SessionCryptoPassphraseFile</a></li>
</ul>
-<h3>Topics</h3>
-<ul id="topics">
-<li><img alt="" src="../images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
-</ul><h3>See also</h3>
+<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__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_session_crypto">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_session_crypto">Report a bug</a></li></ul><h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
<li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
-</ul></div>
+<li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
<p>To create a simple encrypted session and store it in a cookie called
<var>session</var>, configure the session as follows:</p>
- <div class="example"><h3>Browser based encrypted session</h3><p><code>
- Session On<br />
- SessionCookieName session path=/<br />
- SessionCryptoPassphrase secret
- </code></p></div>
+ <div class="example"><h3>Browser based encrypted session</h3><pre class="prettyprint lang-config">Session On
+SessionCookieName session path=/
+SessionCryptoPassphrase secret</pre>
+</div>
<p>The session will be encrypted with the given key. Different servers can
be configured to share sessions by ensuring the same encryption key is used
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionCryptoCipher" id="SessionCryptoCipher">SessionCryptoCipher</a> <a name="sessioncryptocipher" id="sessioncryptocipher">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto cipher to be used to encrypt the session</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoCipher <var>name</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>aes256</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
+</table>
+ <p>The <code class="directive">SessionCryptoCipher</code> directive allows the cipher to
+ be used during encryption. If not specified, the cipher defaults to
+ <code>aes256</code>.</p>
+
+ <p>Possible values depend on the crypto driver in use, and could be one of:</p>
+
+ <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr>
<p>The <var>NSS</var> crypto driver requires some parameters for configuration,
which are specified as parameters with optional values after the driver name.</p>
- <div class="example"><h3>NSS without a certificate database</h3><p><code>
- SessionCryptoDriver nss
- </code></p></div>
+ <div class="example"><h3>NSS without a certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss</pre>
+</div>
- <div class="example"><h3>NSS with certificate database</h3><p><code>
- SessionCryptoDriver nss dir=certs
- </code></p></div>
+ <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss dir=certs</pre>
+</div>
- <div class="example"><h3>NSS with certificate database and parameters</h3><p><code>
- SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
- </code></p></div>
+ <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>
+</div>
- <p>The <var>NSS</var> crypto driver might have already been configured by another
- part of the server, for example from <code class="module"><a href="../mod/mod_nss.html">mod_nss</a></code> or
- <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>. If found to have already been configured,
- a warning will be logged, and the existing configuration will have taken affect.
- To avoid this warning, use the noinit parameter as follows.</p>
+ <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>
+</div>
- <div class="example"><h3>NSS with certificate database</h3><p><code>
- SessionCryptoDriver nss noinit
- </code></p></div>
+ <p>The <var>NSS</var> crypto driver might have already been
+ configured by another part of the server, for example from
+ <code>mod_nss</code> or <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>. If found to
+ have already been configured, a warning will be logged, and the
+ existing configuration will have taken affect. To avoid this
+ warning, use the noinit parameter as follows.</p>
+
+ <div class="example"><h3>NSS with certificate database</h3><pre class="prettyprint lang-config">SessionCryptoDriver nss noinit</pre>
+</div>
<p>To prevent confusion, ensure that all modules requiring NSS are configured with
identical parameters.</p>
+ <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
+ the engine to be used for encryption.</p>
+
+ <div class="example"><h3>OpenSSL with engine support</h3><pre class="prettyprint lang-config">SessionCryptoDriver openssl engine=name</pre>
+</div>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr>
-<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
- <p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the key
+ <p>The <code class="directive">SessionCryptoPassphrase</code> directive specifies the keys
to be used to enable symmetrical encryption on the contents of the session before
writing the session, or decrypting the contents of the session after reading the
session.</p>
<p>Keys are more secure when they are long, and consist of truly random characters.
Changing the key on a server has the effect of invalidating all existing sessions.</p>
- <p>The cipher can be set to <var>3des192</var> or <var>aes256</var> using the
- <var>cipher</var> parameter as per the example below. If not set, the cipher defaults
- to <var>aes256</var>.</p>
+ <p>Multiple keys can be specified in order to support key rotation. The first key
+ listed will be used for encryption, while all keys listed will be attempted for
+ decryption. To rotate keys across multiple servers over a period of time, add a new
+ secret to the end of the list, and once rolled out completely to all servers, remove
+ the first key from the start of the list.</p>
- <div class="example"><h3>Cipher</h3><p><code>
- SessionCryptoPassphrase secret cipher=aes256
- </code></p></div>
+ <p>As of version 2.4.7 if the value begins with <var>exec:</var> the resulting command
+ will be executed and the first line returned to standard output by the program will be
+ used as the key.</p>
+<div class="example"><pre>#key used as-is
+SessionCryptoPassphrase secret
- <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
- the engine to be used for encryption.</p>
+#Run /path/to/program to get key
+SessionCryptoPassphrase exec:/path/to/program
+
+#Run /path/to/otherProgram and provide arguments
+SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"</pre></div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="SessionCryptoPassphraseFile" id="SessionCryptoPassphraseFile">SessionCryptoPassphraseFile</a> <a name="sessioncryptopassphrasefile" id="sessioncryptopassphrasefile">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>File containing keys used to encrypt the session</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphraseFile <var>filename</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Experimental</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
+</table>
+ <p>The <code class="directive">SessionCryptoPassphraseFile</code> directive specifies the
+ name of a configuration file containing the keys to use for encrypting or decrypting
+ the session, specified one per line. The file is read on server start, and a graceful
+ restart will be necessary for httpd to pick up changes to the keys.</p>
+
+ <p>Unlike the <code class="directive">SessionCryptoPassphrase</code> directive, the keys are
+ not exposed within the httpd configuration and can be hidden by protecting the file
+ appropriately.</p>
- <div class="example"><h3>OpenSSL with engine support</h3><p><code>
- SessionCryptoPassphrase secret engine=name
- </code></p></div>
+ <p>Multiple keys can be specified in order to support key rotation. The first key
+ listed will be used for encryption, while all keys listed will be attempted for
+ decryption. To rotate keys across multiple servers over a period of time, add a new
+ secret to the end of the list, and once rolled out completely to all servers, remove
+ the first key from the start of the list.</p>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_crypto.html" title="English"> en </a></p>
-</div><div id="footer">
-<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>
-<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>
+</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>
+<script type="text/javascript"><!--//--><![CDATA[//><!--
+var comments_shortname = 'httpd';
+var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_session_crypto.html';
+(function(w, d) {
+ if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
+ d.write('<div id="comments_thread"><\/div>');
+ var s = d.createElement('script');
+ s.type = 'text/javascript';
+ s.async = true;
+ s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
+ (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
+ }
+ else {
+ d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
+ }
+})(window, document);
+//--><!]]></script></div><div id="footer">
+<p class="apache">Copyright 2016 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>
+<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[//><!--
+if (typeof(prettyPrint) !== 'undefined') {
+ prettyPrint();
+}
+//--><!]]></script>
</body></html>
\ No newline at end of file
projects / apache / blobdiff