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>Experimental</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       <highlight language="config">
  64 Session On
  65 SessionCookieName session path=/
  66 SessionCryptoPassphrase secret
  67     </highlight>
  68       </example>
  69
  70       <p>The session will be encrypted with the given key. Different servers can
  71       be configured to share sessions by ensuring the same encryption key is used
  72       on each server.</p>
  73
  74       <p>If the encryption key is changed, sessions will be invalidated
  75       automatically.</p>
  76
  77       <p>For documentation on how the session can be used to store username
  78       and password details, see the <module>mod_auth_form</module> module.</p>
  79
  80     </section>
  81
  82 <directivesynopsis>
  83 <name>SessionCryptoDriver</name>
  84 <description>The crypto driver to be used to encrypt the session</description>
  85 <syntax>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></syntax>
  86 <default>none</default>
  87 <contextlist><context>server config</context>
  88 </contextlist>
  89 <compatibility>Available in Apache 2.3.0 and later</compatibility>
  90
  91 <usage>
  92     <p>The <directive>SessionCryptoDriver</directive> directive specifies the name of
  93     the crypto driver to be used for encryption. If not specified, the driver defaults
  94     to the recommended driver compiled into APR-util.</p>
  95
  96     <p>The <var>NSS</var> crypto driver requires some parameters for configuration,
  97     which are specified as parameters with optional values after the driver name.</p>
  98
  99     <example><title>NSS without a certificate database</title>
 100     <highlight language="config">
 101       SessionCryptoDriver nss
 102       </highlight>
 103     </example>
 104
 105     <example><title>NSS with certificate database</title>
 106     <highlight language="config">
 107       SessionCryptoDriver nss dir=certs
 108       </highlight>
 109     </example>
 110
 111     <example><title>NSS with certificate database and parameters</title>
 112     <highlight language="config">
 113       SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
 114       </highlight>
 115     </example>
 116
 117     <example><title>NSS with paths containing spaces</title>
 118     <highlight language="config">
 119       SessionCryptoDriver nss "dir=My Certs" key3=key3.db cert7=cert7.db secmod=secmod
 120       </highlight>
 121     </example>
 122
 123     <p>The <var>NSS</var> crypto driver might have already been
 124     configured by another part of the server, for example from
 125     <code>mod_nss</code> or <module>mod_ldap</module>. If found to
 126     have already been configured, a warning will be logged, and the
 127     existing configuration will have taken affect.  To avoid this
 128     warning, use the noinit parameter as follows.</p>
 129
 130     <example><title>NSS with certificate database</title>
 131     <highlight language="config">
 132       SessionCryptoDriver nss noinit
 133       </highlight>
 134     </example>
 135
 136     <p>To prevent confusion, ensure that all modules requiring NSS are configured with
 137     identical parameters.</p>
 138
 139     <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
 140     the engine to be used for encryption.</p>
 141
 142     <example><title>OpenSSL with engine support</title>
 143     <highlight language="config">
 144       SessionCryptoDriver openssl engine=name
 145       </highlight>
 146     </example>
 147
 148 </usage>
 149 </directivesynopsis>
 150
 151 <directivesynopsis>
 152 <name>SessionCryptoPassphrase</name>
 153 <description>The key used to encrypt the session</description>
 154 <syntax>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </syntax>
 155 <default>none</default>
 156 <contextlist><context>server config</context>
 157 <context>virtual host</context>
 158 <context>directory</context>
 159 <context>.htaccess</context>
 160 </contextlist>
 161 <override>AuthConfig</override>
 162 <compatibility>Available in Apache 2.3.0 and later</compatibility>
 163
 164 <usage>
 165     <p>The <directive>SessionCryptoPassphrase</directive> directive specifies the keys
 166     to be used to enable symmetrical encryption on the contents of the session before
 167     writing the session, or decrypting the contents of the session after reading the
 168     session.</p>
 169
 170     <p>Keys are more secure when they are long, and consist of truly random characters.
 171     Changing the key on a server has the effect of invalidating all existing sessions.</p>
 172
 173     <p>Multiple keys can be specified in order to support key rotation. The first key
 174     listed will be used for encryption, while all keys listed will be attempted for
 175     decryption. To rotate keys across multiple servers over a period of time, add a new
 176     secret to the end of the list, and once rolled out completely to all servers, remove
 177     the first key from the start of the list.</p>
 178
 179     <p>As of version 2.4.7 if the value begins with <var>exec:</var> the resulting command
 180     will be executed and the first line returned to standard output by the program will be
 181     used as the key.</p>
 182 <example><pre>
 183 #key used as-is
 184 SessionCryptoPassphrase secret
 185
 186 #Run /path/to/program to get key
 187 SessionCryptoPassphrase exec:/path/to/program
 188
 189 #Run /path/to/otherProgram and provide arguments
 190 SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"
 191 </pre></example>
 192
 193 </usage>
 194 </directivesynopsis>
 195
 196 <directivesynopsis>
 197 <name>SessionCryptoPassphraseFile</name>
 198 <description>File containing keys used to encrypt the session</description>
 199 <syntax>SessionCryptoPassphraseFile <var>filename</var></syntax>
 200 <default>none</default>
 201 <contextlist><context>server config</context>
 202 <context>virtual host</context>
 203 <context>directory</context>
 204 </contextlist>
 205 <compatibility>Available in Apache 2.3.0 and later</compatibility>
 206
 207 <usage>
 208     <p>The <directive>SessionCryptoPassphraseFile</directive> directive specifies the
 209     name of a configuration file containing the keys to use for encrypting or decrypting
 210     the session, specified one per line. The file is read on server start, and a graceful
 211     restart will be necessary for httpd to pick up changes to the keys.</p>
 212
 213     <p>Unlike the <directive>SessionCryptoPassphrase</directive> directive, the keys are
 214     not exposed within the httpd configuration and can be hidden by protecting the file
 215     appropriately.</p>
 216
 217     <p>Multiple keys can be specified in order to support key rotation. The first key
 218     listed will be used for encryption, while all keys listed will be attempted for
 219     decryption. To rotate keys across multiple servers over a period of time, add a new
 220     secret to the end of the list, and once rolled out completely to all servers, remove
 221     the first key from the start of the list.</p>
 222
 223 </usage>
 224 </directivesynopsis>
 225
 226 <directivesynopsis>
 227 <name>SessionCryptoCipher</name>
 228 <description>The crypto cipher to be used to encrypt the session</description>
 229 <syntax>SessionCryptoCipher <var>name</var></syntax>
 230 <default>aes256</default>
 231 <contextlist><context>server config</context>
 232 <context>virtual host</context>
 233 <context>directory</context>
 234 <context>.htaccess</context>
 235 </contextlist>
 236 <override>AuthConfig</override>
 237 <compatibility>Available in Apache 2.3.0 and later</compatibility>
 238
 239 <usage>
 240     <p>The <directive>SessionCryptoCipher</directive> directive allows the cipher to
 241     be used during encryption. If not specified, the cipher defaults to
 242     <code>aes256</code>.</p>
 243
 244     <p>Possible values depend on the crypto driver in use, and could be one of:</p>
 245
 246     <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>
 247
 248 </usage>
 249 </directivesynopsis>
 250
 251 </modulesynopsis>