2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
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
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_session_crypto.xml.meta">
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>
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
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>
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>
49 <p>For more details on the session interface, see the documentation for
50 the <module>mod_session</module> module.</p>
53 <seealso><module>mod_session</module></seealso>
54 <seealso><module>mod_session_cookie</module></seealso>
55 <seealso><module>mod_session_dbd</module></seealso>
57 <section id="basicusage"><title>Basic Usage</title>
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>
62 <example><title>Browser based encrypted session</title>
63 <highlight language="config">
65 SessionCookieName session path=/
66 SessionCryptoPassphrase secret
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
74 <p>If the encryption key is changed, sessions will be invalidated
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>
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>
89 <compatibility>Available in Apache 2.3.0 and later</compatibility>
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>
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>
99 <example><title>NSS without a certificate database</title>
100 <highlight language="config">
101 SessionCryptoDriver nss
105 <example><title>NSS with certificate database</title>
106 <highlight language="config">
107 SessionCryptoDriver nss dir=certs
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
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
123 <p>The <var>NSS</var> crypto driver might have already been configured by another
124 part of the server, for example from <module>mod_nss</module> or
125 <module>mod_ldap</module>. If found to have already been configured,
126 a warning will be logged, and the existing configuration will have taken affect.
127 To avoid this warning, use the noinit parameter as follows.</p>
129 <example><title>NSS with certificate database</title>
130 <highlight language="config">
131 SessionCryptoDriver nss noinit
135 <p>To prevent confusion, ensure that all modules requiring NSS are configured with
136 identical parameters.</p>
138 <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
139 the engine to be used for encryption.</p>
141 <example><title>OpenSSL with engine support</title>
142 <highlight language="config">
143 SessionCryptoDriver openssl engine=name
151 <name>SessionCryptoPassphrase</name>
152 <description>The key used to encrypt the session</description>
153 <syntax>SessionCryptoPassphrase <var>secret</var> [ <var>secret</var> ... ] </syntax>
154 <default>none</default>
155 <contextlist><context>server config</context>
156 <context>virtual host</context>
157 <context>directory</context>
158 <context>.htaccess</context>
160 <compatibility>Available in Apache 2.3.0 and later</compatibility>
163 <p>The <directive>SessionCryptoPassphrase</directive> directive specifies the keys
164 to be used to enable symmetrical encryption on the contents of the session before
165 writing the session, or decrypting the contents of the session after reading the
168 <p>Keys are more secure when they are long, and consist of truly random characters.
169 Changing the key on a server has the effect of invalidating all existing sessions.</p>
171 <p>Multiple keys can be specified in order to support key rotation. The first key
172 listed will be used for encryption, while all keys listed will be attempted for
173 decryption. To rotate keys across multiple servers over a period of time, add a new
174 secret to the end of the list, and once rolled out completely to all servers, remove
175 the first key from the start of the list.</p>
177 <p>If the value begins with exec: the resulting command will be executed and the
178 first line returned to standard output by the program will be used as the key.</p>
181 SessionCryptoPassphrase secret
183 #Run /path/to/program to get key
184 SessionCryptoPassphrase exec:/path/to/program
186 #Run /path/to/otherProgram and provide arguments
187 SessionCryptoPassphrase "exec:/path/to/otherProgram argument1"
194 <name>SessionCryptoPassphraseFile</name>
195 <description>File containing keys used to encrypt the session</description>
196 <syntax>SessionCryptoPassphraseFile <var>filename</var></syntax>
197 <default>none</default>
198 <contextlist><context>server config</context>
199 <context>virtual host</context>
200 <context>directory</context>
202 <compatibility>Available in Apache 2.3.0 and later</compatibility>
205 <p>The <directive>SessionCryptoPassphraseFile</directive> directive specifies the
206 name of a configuration file containing the keys to use for encrypting or decrypting
207 the session, specified one per line. The file is read on server start, and a graceful
208 restart will be necessary for httpd to pick up changes to the keys.</p>
210 <p>Unlike the <directive>SessionCryptoPassphrase</directive> directive, the keys are
211 not exposed within the httpd configuration and can be hidden by protecting the file
214 <p>Multiple keys can be specified in order to support key rotation. The first key
215 listed will be used for encryption, while all keys listed will be attempted for
216 decryption. To rotate keys across multiple servers over a period of time, add a new
217 secret to the end of the list, and once rolled out completely to all servers, remove
218 the first key from the start of the list.</p>
224 <name>SessionCryptoCipher</name>
225 <description>The crypto cipher to be used to encrypt the session</description>
226 <syntax>SessionCryptoCipher <var>name</var></syntax>
227 <default>aes256</default>
228 <contextlist><context>server config</context>
229 <context>virtual host</context>
230 <context>directory</context>
231 <context>.htaccess</context>
233 <compatibility>Available in Apache 2.3.0 and later</compatibility>
236 <p>The <directive>SessionCryptoCipher</directive> directive allows the cipher to
237 be used during encryption. If not specified, the cipher defaults to
238 <code>aes256</code>.</p>
240 <p>Possible values depend on the crypto driver in use, and could be one of:</p>
242 <ul><li>3des192</li><li>aes128</li><li>aes192</li><li>aes256</li></ul>