mod_session_crypto.xml revision 72c3c99143571371be76ed3916b19bd3214b4363
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<!-- $LastChangedRevision: 634760 $ -->
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin Licensed to the Apache Software Foundation (ASF) under one or more
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin contributor license agreements. See the NOTICE file distributed with
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin this work for additional information regarding copyright ownership.
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin The ASF licenses this file to You under the Apache License, Version 2.0
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin (the "License"); you may not use this file except in compliance with
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin the License. You may obtain a copy of the License at
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin Unless required by applicable law or agreed to in writing, software
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin distributed under the License is distributed on an "AS IS" BASIS,
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin See the License for the specific language governing permissions and
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin limitations under the License.
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<modulesynopsis metafile="mod_session_crypto.xml.meta">
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<description>Session encryption support</description>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>The session modules make use of HTTP cookies, and as such can fall
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin victim to Cross Site Scripting attacks, or expose potentially private
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin information to clients. Please ensure that the relevant risks have
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin been taken into account before enabling the session functionality on
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin your server.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>This submodule of <module>mod_session</module> provides support for the
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin encryption of user sessions before being written to a local database, or
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin written to a remote browser via an HTTP cookie.</p>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <p>This can help provide privacy to user sessions where the contents of
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin the session should be kept private from the user, or where protection is
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin needed against the effects of cross site scripting attacks.</p>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <p>For more details on the session interface, see the documentation for
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<seealso><module>mod_session_cookie</module></seealso>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>To create a simple encrypted session and store it in a cookie called
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <var>session</var>, configure the session as follows:</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <example><title>Browser based encrypted session</title>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin Session On<br />
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin SessionCookieName session path=/<br />
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin SessionCryptoPassphrase secret
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>The session will be encrypted with the given key. Different servers can
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin be configured to share sessions by ensuring the same encryption key is used
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin on each server.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>If the encryption key is changed, sessions will be invalidated
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin automatically.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>For documentation on how the session can be used to store username
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin and password details, see the <module>mod_auth_form</module> module.</p>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf<directivesynopsis>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<description>The key used to encrypt the session</description>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<syntax>SessionCryptoPassphrase <var>secret</var></syntax>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin</contextlist>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf<compatibility>Available in Apache 2.3.0 and later</compatibility>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>The <directive>SessionCryptoPassphrase</directive> directive specifies the key
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin to be used to enable symmetrical encryption on the contents of the session before
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin writing the session, or decrypting the contents of the session after reading the session.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>Keys are more secure when they are long, and consist of truly random characters.
c1e61f5534383913a1cb952f927348037b1c1922minfrin Changing the key on a server has the effect of invalidating all existing sessions.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>If the <directive module="mod_session_crypto">SessionCryptoCertificateFile</directive>
c1e61f5534383913a1cb952f927348037b1c1922minfrin directive is set and asymmetrical encryption is enabled instead, the
7f0952c0239ea2d6e37b472db6fde4ef2718343dsf <directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin will be interpreted as the passphrase of the key, if the key is encrypted.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin</directivesynopsis>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<directivesynopsis>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<description>The certificate used to encrypt and decrypt the session</description>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<syntax>SessionCryptoCertificateFile <var>file</var></syntax>
c1e61f5534383913a1cb952f927348037b1c1922minfrin</contextlist>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<compatibility>Available in Apache 2.3.0 and later</compatibility>
c1e61f5534383913a1cb952f927348037b1c1922minfrin <p>The <directive>SessionCryptoCertificateFile</directive> directive specifies the name
c1e61f5534383913a1cb952f927348037b1c1922minfrin of a certificate to be used to asymmetrically encrypt the contents of the session before
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin writing the session, or decrypting the content of the session after reading the session.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin <p>Changing the certificate on a server has the effect of invalidating all existing
c1e61f5534383913a1cb952f927348037b1c1922minfrin sessions.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin <p>If the key associated with this certificate is protected with a passphrase, the
c1e61f5534383913a1cb952f927348037b1c1922minfrin <directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
c1e61f5534383913a1cb952f927348037b1c1922minfrin will be interpreted as the passphrase to use to decrypt the key.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>This directive is dependent on experimental support for assymetrical encryption
c1e61f5534383913a1cb952f927348037b1c1922minfrin support currently available in prerelease versions of OpenSSL, and will only be
c1e61f5534383913a1cb952f927348037b1c1922minfrin available on platforms that support it.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin</directivesynopsis>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<directivesynopsis>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<description>The certificate key used to encrypt and decrypt the session</description>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<syntax>SessionCryptoCertificateKeyFile <var>file</var></syntax>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin</contextlist>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<compatibility>Available in Apache 2.3.0 and later</compatibility>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>The <directive>SessionCryptoCertificateKeyFile</directive> directive specifies the name
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin of a certificate key to be used alongside a certificate to encrypt the contents of the
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin session before writing the session, or decrypting the content of the session after reading
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin the session.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin <p>Changing the certificate or key on a server has the effect of invalidating all existing
c1e61f5534383913a1cb952f927348037b1c1922minfrin sessions.</p>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>If this key is protected with a passphrase, the
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
fac8c35bfb158112226ab43ddf84d59daca5dc30nd will be interpreted as the passphrase to use to decrypt the key.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin <p>This directive is dependent on experimental support for asymmetrical encryption
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf support currently available in prerelease versions of OpenSSL, and will only be
c1e61f5534383913a1cb952f927348037b1c1922minfrin available on platforms that support it.</p>
c1e61f5534383913a1cb952f927348037b1c1922minfrin</directivesynopsis>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<directivesynopsis>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<description>The name of the cipher to use during encryption / decryption</description>
c1e61f5534383913a1cb952f927348037b1c1922minfrin<syntax>SessionCryptoCipher <var>cipher</var></syntax>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin</contextlist>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin<compatibility>Available in Apache 2.3.0 and later</compatibility>
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin <p>The <directive>SessionCryptoCipher</directive> directive specifies the name
9c1260efa52c82c2a58e5b5f20cd6902563d95f5rbowen of the cipher to use during encryption. The ciphers available will depend on the
4277c95b5a9454a5c25f8d8762634fcff37aa840minfrin underlying encryption toolkit on the server platform.</p>