| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_session_crypto.xml.meta"> |
| |
| <name>mod_session_crypto</name> |
| <description>Session encryption support</description> |
| <status>Experimental</status> |
| <sourcefile>mod_session_crypto.c</sourcefile> |
| <identifier>session_crypto_module</identifier> |
| <compatibility>Available in Apache 2.3 and later</compatibility> |
| |
| <summary> |
| <note type="warning"><title>Warning</title> |
| <p>The session modules make use of HTTP cookies, and as such can fall |
| victim to Cross Site Scripting attacks, or expose potentially private |
| information to clients. Please ensure that the relevant risks have |
| been taken into account before enabling the session functionality on |
| your server.</p> |
| </note> |
| |
| <p>This submodule of <module>mod_session</module> provides support for the |
| encryption of user sessions before being written to a local database, or |
| written to a remote browser via an HTTP cookie.</p> |
| |
| <p>This can help provide privacy to user sessions where the contents of |
| the session should be kept private from the user, or where protection is |
| needed against the effects of cross site scripting attacks.</p> |
| |
| <p>For more details on the session interface, see the documentation for |
| the <module>mod_session</module> module.</p> |
| |
| </summary> |
| <seealso><module>mod_session</module></seealso> |
| <seealso><module>mod_session_cookie</module></seealso> |
| <seealso><module>mod_session_dbd</module></seealso> |
| |
| <section id="basicusage"><title>Basic Usage</title> |
| |
| <p>To create a simple encrypted session and store it in a cookie called |
| <var>session</var>, configure the session as follows:</p> |
| |
| <example><title>Browser based encrypted session</title> |
| <highlight language="config"> |
| Session On |
| SessionCookieName session path=/ |
| SessionCryptoPassphrase secret |
| </highlight> |
| </example> |
| |
| <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 |
| on each server.</p> |
| |
| <p>If the encryption key is changed, sessions will be invalidated |
| automatically.</p> |
| |
| <p>For documentation on how the session can be used to store username |
| and password details, see the <module>mod_auth_form</module> module.</p> |
| |
| </section> |
| |
| <directivesynopsis> |
| <name>SessionCryptoDriver</name> |
| <description>The crypto driver to be used to encrypt the session</description> |
| <syntax>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| </contextlist> |
| <compatibility>Available in Apache 2.3.0 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>SessionCryptoDriver</directive> directive specifies the name of |
| the crypto driver to be used for encryption. If not specified, the driver defaults |
| to the recommended driver compiled into APR-util.</p> |
| |
| <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> |
| |
| <example><title>NSS without a certificate database</title> |
| <highlight language="config"> |
| SessionCryptoDriver nss |
| </highlight> |
| </example> |
| |
| <example><title>NSS with certificate database</title> |
| <highlight language="config"> |
| SessionCryptoDriver nss dir=certs |
| </highlight> |
| </example> |
| |
| <example><title>NSS with certificate database and parameters</title> |
| <highlight language="config"> |
| SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod |
| </highlight> |
| </example> |
| |
| <example><title>NSS with paths containing spaces</title> |
| <highlight language="config"> |
| SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod |
| </highlight> |
| </example> |
| |
| <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 <module>mod_ldap</module>. 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> |
| |
| <example><title>NSS with certificate database</title> |
| <highlight language="config"> |
| SessionCryptoDriver nss noinit |
| </highlight> |
| </example> |
| |
| <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> |
| |
| <example><title>OpenSSL with engine support</title> |
| <highlight language="config"> |
| SessionCryptoDriver openssl engine=name |
| </highlight> |
| </example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SessionCryptoPassphrase</name> |
| <description>The key used to encrypt the session</description> |
| <syntax>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| <context>.htaccess</context> |
| </contextlist> |
| <compatibility>Available in Apache 2.3.0 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>SessionCryptoPassphrase</directive> 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>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> |
| |
| <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> |
| <example><pre> |
| #key used as-is |
| SessionCryptoPassphrase secret |
| |
| #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></example> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SessionCryptoPassphraseFile</name> |
| <description>File containing keys used to encrypt the session</description> |
| <syntax>SessionCryptoPassphraseFile <var>filename</var></syntax> |
| <default>none</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| </contextlist> |
| <compatibility>Available in Apache 2.3.0 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>SessionCryptoPassphraseFile</directive> 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 <directive>SessionCryptoPassphrase</directive> directive, the keys are |
| not exposed within the httpd configuration and can be hidden by protecting the file |
| appropriately.</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> |
| |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>SessionCryptoCipher</name> |
| <description>The crypto cipher to be used to encrypt the session</description> |
| <syntax>SessionCryptoCipher <var>name</var></syntax> |
| <default>aes256</default> |
| <contextlist><context>server config</context> |
| <context>virtual host</context> |
| <context>directory</context> |
| <context>.htaccess</context> |
| </contextlist> |
| <compatibility>Available in Apache 2.3.0 and later</compatibility> |
| |
| <usage> |
| <p>The <directive>SessionCryptoCipher</directive> 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> |
| |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |