summaryrefslogtreecommitdiff
path: root/docs/manual/mod/mod_session_crypto.html.en
blob: 6d64986b14151a2e26dafa930a90765545da9abd (plain)
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
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              This file is generated from xml source: DO NOT EDIT
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      -->
<title>mod_session_crypto - Apache HTTP Server</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.3</p>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.3</a> &gt; <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_session_crypto</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_crypto.html" title="English">&nbsp;en&nbsp;</a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Session encryption support</td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>session_crypto_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_session_crypto.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3 and later</td></tr></table>
<h3>Summary</h3>

    <div class="warning"><h3>Warning</h3>
      <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>
    </div>

    <p>This submodule of <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> 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 <code class="module"><a href="../mod/mod_session.html">mod_session</a></code> module.</p>
    
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptodriver">SessionCryptoDriver</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sessioncryptopassphrase">SessionCryptoPassphrase</a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#basicusage">Basic Usage</a></li>
</ul><h3>See also</h3>
<ul class="seealso">
<li><code class="module"><a href="../mod/mod_session.html">mod_session</a></code></li>
<li><code class="module"><a href="../mod/mod_session_cookie.html">mod_session_cookie</a></code></li>
<li><code class="module"><a href="../mod/mod_session_dbd.html">mod_session_dbd</a></code></li>
</ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="basicusage" id="basicusage">Basic Usage</a></h2>
    
      <p>To create a simple encrypted session and store it in a cookie called
      <var>session</var>, configure the session as follows:</p>
      
      <div class="example"><h3>Browser based encrypted session</h3><p><code>
        Session On<br />
        SessionCookieName session path=/<br />
        SessionCryptoPassphrase secret
      </code></p></div>
      
      <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 <code class="module"><a href="../mod/mod_auth_form.html">mod_auth_form</a></code> module.</p>

    </div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoDriver" id="SessionCryptoDriver">SessionCryptoDriver</a> <a name="sessioncryptodriver" id="sessioncryptodriver">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The crypto driver to be used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoDriver <var>name</var> <var>[param[=value]]</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
    <p>The <code class="directive">SessionCryptoDriver</code> 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>

    <div class="example"><h3>NSS without a certificate database</h3><p><code>
      SessionCryptoDriver nss
    </code></p></div>

    <div class="example"><h3>NSS with certificate database</h3><p><code>
      SessionCryptoDriver nss dir=certs
    </code></p></div>

    <div class="example"><h3>NSS with certificate database and parameters</h3><p><code>
      SessionCryptoDriver nss dir=certs key3=key3.db cert7=cert7.db secmod=secmod
    </code></p></div>

    <p>The <var>NSS</var> crypto driver might have already been configured by another
    part of the server, for example from <code class="module"><a href="../mod/mod_nss.html">mod_nss</a></code> or
    <code class="module"><a href="../mod/mod_ldap.html">mod_ldap</a></code>. 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>

    <div class="example"><h3>NSS with certificate database</h3><p><code>
      SessionCryptoDriver nss noinit
    </code></p></div>

    <p>To prevent confusion, ensure that all modules requiring NSS are configured with
    identical parameters.</p>


</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="SessionCryptoPassphrase" id="SessionCryptoPassphrase">SessionCryptoPassphrase</a> <a name="sessioncryptopassphrase" id="sessioncryptopassphrase">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The key used to encrypt the session</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>SessionCryptoPassphrase <var>secret</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>none</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_session_crypto</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.0 and later</td></tr>
</table>
    <p>The <code class="directive">SessionCryptoPassphrase</code> 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>The cipher can be set to <var>3des192</var> or <var>aes256</var> using the
    <var>cipher</var> parameter as per the example below. If not set, the cipher defaults
    to <var>aes256</var>.</p>
    
    <div class="example"><h3>Cipher</h3><p><code>
      SessionCryptoPassphrase secret cipher=aes256
    </code></p></div>

    <p>The <var>openssl</var> crypto driver supports an optional parameter to specify
    the engine to be used for encryption.</p>

    <div class="example"><h3>OpenSSL with engine support</h3><p><code>
      SessionCryptoPassphrase secret engine=name
    </code></p></div>


</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_session_crypto.html" title="English">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2010 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
</body></html>