1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
<?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>Extension</status>
<sourcefile>mod_session_crypto.c</sourcefile>
<identifier>session_crypto_module</identifier>
<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>
Session On<br />
SessionCookieName session path=/<br />
SessionCryptoPassphrase secret
</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>SessionCryptoPassphrase</name>
<description>The key used to encrypt the session</description>
<syntax>SessionCryptoPassphrase <var>secret</var></syntax>
<default>none</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoPassphrase</directive> directive specifies the key
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>If the <directive module="mod_session_crypto">SessionCryptoCertificateFile</directive>
directive is set and asymmetrical encryption is enabled instead, the
<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
will be interpreted as the passphrase of the key, if the key is encrypted.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SessionCryptoCertificateFile</name>
<description>The certificate used to encrypt and decrypt the session</description>
<syntax>SessionCryptoCertificateFile <var>file</var></syntax>
<default>none</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoCertificateFile</directive> directive specifies the name
of a certificate to be used to asymmetrically encrypt the contents of the session before
writing the session, or decrypting the content of the session after reading the session.</p>
<p>Changing the certificate on a server has the effect of invalidating all existing
sessions.</p>
<p>If the key associated with this certificate is protected with a passphrase, the
<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
will be interpreted as the passphrase to use to decrypt the key.</p>
<note type="warning"><title>Experimental</title>
<p>This directive is dependent on experimental support for asymmetrical encryption
support currently available in prerelease versions of OpenSSL, and will only be
available on platforms that support it.</p>
</note>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SessionCryptoCertificateKeyFile</name>
<description>The certificate key used to encrypt and decrypt the session</description>
<syntax>SessionCryptoCertificateKeyFile <var>file</var></syntax>
<default>none</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoCertificateKeyFile</directive> directive specifies the name
of a certificate key to be used alongside a certificate to encrypt the contents of the
session before writing the session, or decrypting the content of the session after reading
the session.</p>
<p>Changing the certificate or key on a server has the effect of invalidating all existing
sessions.</p>
<p>If this key is protected with a passphrase, the
<directive module="mod_session_crypto">SessionCryptoPassphrase</directive> directive
will be interpreted as the passphrase to use to decrypt the key.</p>
<note type="warning"><title>Experimental</title>
<p>This directive is dependent on experimental support for asymmetrical encryption
support currently available in prerelease versions of OpenSSL, and will only be
available on platforms that support it.</p>
</note>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SessionCryptoCipher</name>
<description>The name of the cipher to use during encryption / decryption</description>
<syntax>SessionCryptoCipher <var>cipher</var></syntax>
<default>AES256</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoCipher</directive> directive specifies the name
of the cipher to use during encryption. The ciphers available will depend on the
underlying encryption toolkit on the server platform.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SessionCryptoDigest</name>
<description>The name of the digest to use during encryption / decryption</description>
<syntax>SessionCryptoDigest <var>cipher</var></syntax>
<default>SHA</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoDigest</directive> directive specifies the name
of the digest to use during encryption. The list of digests available will depend
on the underlying encryption toolkit on the server platform.</p>
</usage>
</directivesynopsis>
<directivesynopsis>
<name>SessionCryptoEngine</name>
<description>The name of the engine to use during encryption / decryption</description>
<syntax>SessionCryptoEngine <var>engine</var></syntax>
<default>none</default>
<contextlist><context>server config</context>
<context>virtual host</context>
<context>directory</context>
<context>.htaccess</context>
</contextlist>
<compatibility>Available in Apache 2.3.0 and later</compatibility>
<usage>
<p>The <directive>SessionCryptoEngine</directive> directive specifies the name
of the engine to use during encryption, depending on the capabilities of the
underlying encryption toolkit on the server platform.</p>
</usage>
</directivesynopsis>
</modulesynopsis>
|
