<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<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>If the value begins with exec: 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>