mirror of
https://github.com/apache/httpd.git
synced 2025-08-20 16:09:55 +00:00
f429387652
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1793934 13f79535-47bb-0310-9956-ffa450edef68
252 lines
9.7 KiB
XML
252 lines
9.7 KiB
XML
<?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>
|
|
<override>AuthConfig</override>
|
|
<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>
|
|
<override>AuthConfig</override>
|
|
<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>
|