<?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>Extension</status>

<sourcefile>mod_session_crypto.c</sourcefile>

<identifier>session_crypto_module</identifier>

<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 remove 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>

Session On<br />

SessionCookieName session path=/<br />

SessionCryptoPassphrase secret

</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>SessionCryptoPassphrase</name>

<description>The key used to encrypt the session</description>

<syntax>SessionCryptoPassphrase <var>secret</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoPassphrase</directive> directive specifies the key

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>If the <directive module="mod_session_crypto">SessionCryptoCertificateFile</directive>

directive is set and asymmetrical encryption is enabled instead, the

<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive

will be interpreted as the passphrase of the key, if the key is encrypted.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SessionCryptoCertificateFile</name>

<description>The certificate used to encrypt and decrypt the session</description>

<syntax>SessionCryptoCertificateFile <var>file</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoCertificateFile</directive> directive specifies the name

of a certificate to be used to asymmetrically encrypt the contents of the session before

writing the session, or decrypting the content of the session after reading the session.</p>

<p>Changing the certificate on a server has the effect of invalidating all existing

sessions.</p>

<p>If the key associated with this certificate is protected with a passphrase, the

<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive

will be interpreted as the passphrase to use to decrypt the key.</p>

<note type="warning"><title>Experimental</title>

<p>This directive is dependent on experimental support for assymetrical encryption

support currently available in prerelease versions of OpenSSL, and will only be

available on platforms that support it.</p>

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SessionCryptoCertificateKeyFile</name>

<description>The certificate key used to encrypt and decrypt the session</description>

<syntax>SessionCryptoCertificateKeyFile <var>file</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoCertificateKeyFile</directive> directive specifies the name

of a certificate key to be used alongside a certificate to encrypt the contents of the

session before writing the session, or decrypting the content of the session after reading

the session.</p>

<p>Changing the certificate or key on a server has the effect of invalidating all existing

sessions.</p>

<p>If this key is protected with a passphrase, the

<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive

will be interpreted as the passphrase to use to decrypt the key.</p>

<note type="warning"><title>Experimental</title>

<p>This directive is dependent on experimental support for asymmetrical encryption

support currently available in prerelease versions of OpenSSL, and will only be

available on platforms that support it.</p>

</note>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SessionCryptoCipher</name>

<description>The name of the cipher to use during encryption / decryption</description>

<syntax>SessionCryptoCipher <var>cipher</var></syntax>

<default>AES256</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoCipher</directive> directive specifies the name

of the cipher to use during encryption. The ciphers available will depend on the

underlying encryption toolkit on the server platform.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SessionCryptoDigest</name>

<description>The name of the digest to use during encryption / decryption</description>

<syntax>SessionCryptoDigest <var>cipher</var></syntax>

<default>SHA</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoDigest</directive> directive specifies the name

of the digest to use during encryption. The list of digests available will depend

on the underlying encryption toolkit on the server platform.</p>

</usage>

</directivesynopsis>

<directivesynopsis>

<name>SessionCryptoEngine</name>

<description>The name of the engine to use during encryption / decryption</description>

<syntax>SessionCryptoEngine <var>engine</var></syntax>

<default>none</default>

<contextlist><context>directory</context>

</contextlist>

<compatibility>Available in Apache 2.3.0 and later</compatibility>

<usage>

<p>The <directive>SessionCryptoEngine</directive> directive specifies the name

of the engine to use during encryption, depending on the capabilities of the

underlying encryption toolkit on the server platform.</p>

</usage>

</directivesynopsis>

</modulesynopsis>