granicus.if.org Git - apache/blob - docs/manual/mod/mod_session_crypto.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_session_crypto.xml.meta">
  24
  25 <name>mod_session_crypto</name>
  26 <description>Session encryption support</description>
  27 <status>Extension</status>
  28 <sourcefile>mod_session_crypto.c</sourcefile>
  29 <identifier>session_crypto_module</identifier>
  30 <compatibility>Available in Apache 2.3 and later</compatibility>
  31
  32 <summary>
  33     <note type="warning"><title>Warning</title>
  34       <p>The session modules make use of HTTP cookies, and as such can fall
  35       victim to Cross Site Scripting attacks, or expose potentially private
  36       information to clients. Please ensure that the relevant risks have
  37       been taken into account before enabling the session functionality on
  38       your server.</p>
  39     </note>
  40
  41     <p>This submodule of <module>mod_session</module> provides support for the
  42     encryption of user sessions before being written to a local database, or
  43     written to a remote browser via an HTTP cookie.</p>
  44
  45     <p>This can help provide privacy to user sessions where the contents of
  46     the session should be kept private from the user, or where protection is
  47     needed against the effects of cross site scripting attacks.</p>
  48
  49     <p>For more details on the session interface, see the documentation for
  50     the <module>mod_session</module> module.</p>
  51
  52 </summary>
  53 <seealso><module>mod_session</module></seealso>
  54 <seealso><module>mod_session_cookie</module></seealso>
  55 <seealso><module>mod_session_dbd</module></seealso>
  56
  57     <section id="basicusage"><title>Basic Usage</title>
  58
  59       <p>To create a simple encrypted session and store it in a cookie called
  60       <var>session</var>, configure the session as follows:</p>
  61
  62       <example><title>Browser based encrypted session</title>
  63         Session On<br />
  64         SessionCookieName session path=/<br />
  65         SessionCryptoPassphrase secret
  66       </example>
  67
  68       <p>The session will be encrypted with the given key. Different servers can
  69       be configured to share sessions by ensuring the same encryption key is used
  70       on each server.</p>
  71
  72       <p>If the encryption key is changed, sessions will be invalidated
  73       automatically.</p>
  74
  75       <p>For documentation on how the session can be used to store username
  76       and password details, see the <module>mod_auth_form</module> module.</p>
  77
  78     </section>
  79
  80 <directivesynopsis>
  81 <name>SessionCryptoDriver</name>
  82 <description>The crypto driver to be used to encrypt the session</description>
  83 <syntax>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></syntax>
  84 <default>none</default>
  85 <contextlist><context>server config</context>
  86 </contextlist>
  87 <compatibility>Available in Apache 2.3.0 and later</compatibility>
  88
  89 <usage>
  90     <p>The <directive>SessionCryptoDriver</directive> directive specifies the name of
  91     the crypto driver to be used for encryption. If not specified, the driver defaults
  92     to the recommended driver compiled into APR-util.</p>
  93
  94     <p>The <var>NSS</var> crypto driver requires some parameters for configuration,
  95     which are specified as parameters with optional values after the driver name.</p>
  96
  97     <example><title>NSS without a certificate database</title>
  98       SessionCryptoDriver nss
  99     </example>
 100
 101     <example><title>NSS with certificate database</title>
 102       SessionCryptoDriver nss dir=certs
 103     </example>
 104
 105     <example><title>NSS with certificate database and parameters</title>
 106       SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
 107     </example>
 108
 109     <p>The <var>NSS</var> crypto driver might have already been configured by another
 110     part of the server, for example from <module>mod_nss</module> or
 111     <module>mod_ldap</module>. If found to have already been configured,
 112     a warning will be logged, and the existing configuration will have taken affect.
 113     To avoid this warning, use the noinit parameter as follows.</p>
 114
 115     <example><title>NSS with certificate database</title>
 116       SessionCryptoDriver nss noinit
 117     </example>
 118
 119     <p>To prevent confusion, ensure that all modules requiring NSS are configured with
 120     identical parameters.</p>
 121
 122 </usage>
 123 </directivesynopsis>
 124
 125 <directivesynopsis>
 126 <name>SessionCryptoPassphrase</name>
 127 <description>The key used to encrypt the session</description>
 128 <syntax>SessionCryptoPassphrase <var>secret</var></syntax>
 129 <default>none</default>
 130 <contextlist><context>server config</context>
 131 <context>virtual host</context>
 132 <context>directory</context>
 133 <context>.htaccess</context>
 134 </contextlist>
 135 <compatibility>Available in Apache 2.3.0 and later</compatibility>
 136
 137 <usage>
 138     <p>The <directive>SessionCryptoPassphrase</directive> directive specifies the key
 139     to be used to enable symmetrical encryption on the contents of the session before
 140     writing the session, or decrypting the contents of the session after reading the
 141     session.</p>
 142
 143     <p>Keys are more secure when they are long, and consist of truly random characters.
 144     Changing the key on a server has the effect of invalidating all existing sessions.</p>
 145
 146     <p>The cipher can be set to <var>3des192</var> or <var>aes256</var> using the
 147     <var>cipher</var> parameter as per the example below. If not set, the cipher defaults
 148     to <var>aes256</var>.</p>
 149
 150     <example><title>Cipher</title>
 151       SessionCryptoPassphrase secret cipher=aes256
 152     </example>
 153
 154     <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
 155     the engine to be used for encryption.</p>
 156
 157     <example><title>OpenSSL with engine support</title>
 158       SessionCryptoPassphrase secret engine=name
 159     </example>
 160
 161 </usage>
 162 </directivesynopsis>
 163
 164 </modulesynopsis>