Update of /cvsroot/pdd/www.proftpd.org/docs/contrib
In directory sfp-cvsdas-2.v30.ch3.sourceforge.com:/tmp/cvs-serv14659
Modified Files:
mod_tls.html
Log Message:
Updated mod_tls docs for website.
Index: mod_tls.html
===================================================================
RCS file: /cvsroot/pdd/www.proftpd.org/docs/contrib/mod_tls.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -r1.2 -r1.3
*** mod_tls.html 5 Feb 2009 21:21:44 -0000 1.2
--- mod_tls.html 5 Apr 2010 16:20:33 -0000 1.3
***************
*** 24,28 ****
<p>
! This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/).
<p>
--- 24,28 ----
<p>
! This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).
<p>
***************
*** 51,54 ****
--- 51,55 ----
<li><a href="#TLSCertificateChainFile">TLSCertificateChainFile</a>
<li><a href="#TLSCipherSuite">TLSCipherSuite</a>
+ <li><a href="#TLSControlsACLs">TLSControlsACLs</a>
<li><a href="#TLSCryptoDevice">TLSCryptoDevice</a>
<li><a href="#TLSDHParamFile">TLSDHParamFile</a>
***************
*** 58,61 ****
--- 59,63 ----
<li><a href="#TLSLog">TLSLog</a>
<li><a href="#TLSOptions">TLSOptions</a>
+ <li><a href="#TLSPKCS12File">TLSPKCS12File</a>
<li><a href="#TLSPassPhraseProvider">TLSPassPhraseProvider</a>
<li><a href="#TLSProtocol">TLSProtocol</a>
***************
*** 65,68 ****
--- 67,71 ----
<li><a href="#TLSRSACertificateFile">TLSRSACertificateFile</a>
<li><a href="#TLSRSACertificateKeyFile">TLSRSACertificateKeyFile</a>
+ <li><a href="#TLSSessionCache">TLSSessionCache</a>
<li><a href="#TLSTimeoutHandshake">TLSTimeoutHandshake</a>
<li><a href="#TLSVerifyClient">TLSVerifyClient</a>
***************
*** 71,74 ****
--- 74,84 ----
</ul>
+ <h2>Control Actions</h2>
+ <ul>
+ <li><a href="#tls_sesscache_clear"><code>tls sesscache clear</code></a>
+ <li><a href="#tls_sesscache_info"><code>tls sesscache info</code></a>
+ <li><a href="#tls_sesscache_remove"><code>tls sesscache remove</code></a>
+ </ul>
+
<hr>
<h2><a name="TLSCACertificateFile">TLSCACertificateFile</a></h2>
***************
*** 258,261 ****
--- 268,278 ----
<p>
+ <b>Note</b>: If you use the <code>NoCertRequest</code>
+ <a href="#TLSOptions"><code>TLSOption</code></a>, then any configured
+ <code>TLSCertificateChainFile</code> directive will be ignored. It is a waste
+ of time to construct a certificate chain to send to the client if the server
+ does not request that the client send a certificate to be verified.
+
+ <p>
<hr>
<h2><a name="TLSCipherSuite">TLSCipherSuite</a></h2>
***************
*** 351,354 ****
--- 368,407 ----
<p>
<hr>
+ <h2><a name="TLSControlsACLs">TLSControlsACLs</a></h2>
+ <strong>Syntax:</strong> TLSControlsACLs <em>actions|"all" "allow"|"deny" "user"|"group" list</em><br>
+ <strong>Default:</strong> None<br>
+ <strong>Context:</strong> server config<br>
+ <strong>Module:</strong> mod_tls<br>
+ <strong>Compatibility:</strong> 1.3.3rc1 and later
+
+ <p>
+ The <code>TLSControlsACLs</code> directive configures access lists of
+ <em>users</em> or <em>groups</em> who are allowed (or denied) the ability to
+ use the <em>actions</em> implemented by <code>mod_tls</code>. The default
+ behavior is to deny everyone unless an ACL allowing access has been explicitly
+ configured.
+
+ <p>
+ If "allow" is used, then <em>list</em>, a comma-delimited list
+ of <em>users</em> or <em>groups</em>, can use the given <em>actions</em>; all
+ others are denied. If "deny" is used, then the <em>list</em> of
+ <em>users</em> or <em>groups</em> cannot use <em>actions</em> all others are
+ allowed. Multiple <code>TLSControlsACLs</code> directives may be used to
+ configure ACLs for different control actions, and for both users and groups.
+
+ <p>
+ The <em>actions</em> provided by <code>mod_tls</code> are
+ "sesscache clear" , "sesscache info", and
+ "sesscache remove".
+
+ <p>
+ Examples:
+ <pre>
+ # Allow only user root to examine/update the external SSL session cache
+ TLSControlsACLs all allow user root
+ </pre>
+
+ <p>
+ <hr>
<h2><a name="TLSCryptoDevice">TLSCryptoDevice</a></h2>
<strong>Syntax:</strong> TLSCryptoDevice <em>driver|"all"|"none"</em><br>
***************
*** 419,423 ****
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
! is restarted.
<p>
--- 472,477 ----
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
! is restarted. Alternatively, the <code>TLSPassPhraseProvider</code>
! directive can be used to supply a source for that passphrase.
<p>
***************
*** 514,517 ****
--- 568,586 ----
The currently implemented options are:
<ul>
+ <li><code>AllowClientRenegotiations</code><br>
+ <p>
+ The <code>mod_tls</code> will reject any SSL/TLS session renegotiation
+ attempts by the client, in order to mitigate any issues arising from the
+ <a href="http://www.educatedguesswork.org/2009/11/understanding_the_tls_renegoti.html">SSL/TLS session renegotiation vulnerability</a> (CVE-2009-3555).
+ If, however, your particular site or clients absolutely require support
+ for client-initiated SSL/TLS session renegotiations, then this option
+ can be used. <b>Not recommended.</b>
+
+ <p>
+ Note, however, that SSL/TLS session renegotiation requests that are
+ initiated by <code>mod_tls</code>, via the
+ <a href="#TLSRenegotiate"><code>TLSRenegotiate</code></a> directive, are
+ still handled (depending on the OpenSSL version).
+
<li><code>AllowDotLogin</code><br>
<p>
***************
*** 591,598 ****
<p>
Some FTP clients are known to be buggy when handling a server's certificate
! request. This option causes the server not to include such a request
during an SSL handshake.
<p>
<li><code>StdEnvVars</code><br>
<p>
--- 660,686 ----
<p>
Some FTP clients are known to be buggy when handling a server's certificate
! request. This option causes the server to <b>not</b> send such a request
during an SSL handshake.
<p>
+ <li><code>NoSessionReuseRequired</code><br>
+ <p>
+ As of ProFTPD 1.3.3rc1, <code>mod_tls</code> only accepts SSL/TLS data
+ connections that reuse the SSL session of the control connection, as a
+ security measure. Unfortunately, there are some clients (<i>e.g.</i>
+ curl) which do not reuse SSL sessions.
+
+ <p>
+ To relax the requirement that the SSL session from the control connection
+ be reused for data connections, use the following in the proftpd.conf:
+ <pre>
+ <IfModule mod_tls.c>
+ ...
+ TLSOptions NoSessionReuseRequired
+ ...
+ </IfModule>
+ </pre>
+
+ <p>
<li><code>StdEnvVars</code><br>
<p>
***************
*** 721,725 ****
<tr>
! <td><code>TLS_SERVER_S_DN_</code><i>x509<i></td>
<td>Component of server certificate's Subject DN, where <i>x509</i> is
a component of a X509 DN:<br>
--- 809,813 ----
<tr>
! <td><code>TLS_SERVER_S_DN_</code><i>x509</i></td>
<td>Component of server certificate's Subject DN, where <i>x509</i> is
a component of a X509 DN:<br>
***************
*** 766,769 ****
--- 854,884 ----
<p>
+ <li><code>UseImplicitSSL</code><br>
+ <p>
+ This option will cause the <code>mod_tls</code> module to handle <b>all</b>
+ connections as if they are SSL connections implicitly; the client does
+ <i>not</i> need to send the <code>AUTH TLS</code> FTP command. This can
+ cause issues for FTPS clients which are expecting explicit FTPS, not
+ implicit FTPS.
+
+ <p>
+ Thus if the <code>UseImplicitSSL</code> option is used, you will want to
+ have a separate <code><VirtualHost></code> section with
+ a different port number just for those clients which require/expect
+ implicit FTPS. For example:
+ <pre>
+ <IfModule mod_tls.c>
+ <VirtualHost a.b.c.d>
+ TLSEngine on
+ TLSOptions UseImplicitSSL
+
+ # The "standard" implicit FTPS port is 990
+ Port 990
+ ...
+ </VirtualHost>
+ </IfModule>
+ </pre>
+
+ <p>
<li><code>dNSNameRequired</code><br>
<p>
***************
*** 793,796 ****
--- 908,936 ----
<p>
<hr>
+ <h2><a name="TLSPKCS12File">TLSPKCS12File</a></h2>
+ <strong>Syntax:</strong> TLSPKCS12File <em>file</em><br>
+ <strong>Default:</strong> None<br>
+ <strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
+ <strong>Module:</strong> mod_tls<br>
+ <strong>Compatibility:</strong> 1.3.3rc1 and later
+
+ <p>
+ The <code>TLSPKCS12ile</code> directive points to the PKCS#12 file containing
+ the certificate file and its private key for the server.
+
+ <p>
+ If the PKCS#12 file is protected with a passphrase, the administrator will
+ be prompted for the passphrase when the daemon starts up, and when the daemon
+ is restarted. Alternatively, the <code>TLSPassPhraseProvider</code>
+ directive can be used to supply a source for that passphrase.
+
+ <p>
+ Example:
+ <pre>
+ TLSPKCS12File /etc/ftpd/server-cert.p12
+ </pre>
+
+ <p>
+ <hr>
<h2><a name="TLSPassPhraseProvider">TLSPassPhraseProvider</a></h2>
<strong>Syntax:</strong> TLSPassPhraseProvider <em>path</em><br>
***************
*** 1056,1060 ****
<p>
- <p>
The <code>TLSRSACertificateFile</code> directive points to the PEM-encoded
file containing the RSA certificate file for the server and optionally also
--- 1196,1199 ----
***************
*** 1064,1068 ****
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
! is restarted.
<p>
--- 1203,1208 ----
If the contained private key is encrypted, the administrator will be
prompted for the passphrase when the daemon starts up, and when the daemon
! is restarted. Alternatively, the <code>TLSPassPhraseProvider</code>
! directive can be used to supply a source for that passphrase.
<p>
***************
*** 1104,1107 ****
--- 1244,1293 ----
<p>
<hr>
+ <h2><a name="TLSSessionCache">TLSSessionCache</a></h2>
+ <strong>Syntax:</strong> TLSSessionCache <em>type:/info [timeout]</em><br>
+ <strong>Default:</strong> None<br>
+ <strong>Context:</strong> server config<br>
+ <strong>Module:</strong> mod_tls<br>
+ <strong>Compatibility:</strong> 1.3.3rc1 and later
+
+ <p>
+ The <code>TLSSessionCache</code> directive configures an external SSL session
+ cache, which can be used for storing and shared SSL sessions across multiple
+ processes. An external SSL session cache is an optional facility which speeds
+ up parallel FTPS session connections.
+
+ <p>
+ Modern FTP clients often create multiple simultaneous connections to an FTP
+ server, for downloading different chunks of data in parallel. Each FTP
+ connection will be handled by a different server process, and each one
+ will be required to perform a full SSL/TLS handshake. By using an
+ external SSL session cache, a cached SSL session can be "resumed" by the
+ client, which avoids the expensive portions of the handshake. FTPS clients
+ which cache the SSL session locally can also attempt to resume that cached
+ session at a later date; if the server still has that same session cached,
+ the FTPS client can again avoid the expensive portions of the handshake and
+ resume its previous SSL session.
+
+ <p>
+ If the <code>TLSSessionCache</code> directive is <i>not</i> used, then
+ OpenSSL's default internal SSL session caching will be used. Thus multiple
+ SSL sessions to the same server process (<i>e.g.</i> for FTP data transfers)
+ will benefit from the speedup, but parallel simultaneous FTP connections from
+ the same FTPS client will each need to perform the full SSL/TLS handshake.
+
+ <p>
+ The <em>type</em> and <em>info</em> parameters all depend on the module
+ implementing the external SSL session cache being configured. For example,
+ for using a shared memory external SSL session cache, see the
+ <a href="mod_tls_shmcache.html"><code>mod_tls_shmcache</code></a> documentation.
+
+ <p>
+ The optional <em>timeout</em> parameters sets the time-to-live, in seconds, for
+ the SSL session datal stored in the external SSL session cache. It can be set
+ as low as 15 for testing, but should be set to higher values like 600 in real
+ life. The default timeout is 1800 seconds (30 minutes).
+
+ <p>
+ <hr>
<h2><a name="TLSTimeoutHandshake">TLSTimeoutHandshake</a></h2>
<strong>Syntax:</strong> TLSTimeoutHandshake <em>seconds</em><br>
***************
*** 1213,1216 ****
--- 1399,1494 ----
<p>
<hr>
+ <h2>Control Actions</h2>
+
+ <p>
+ <hr>
+ <h3><a name="tls_sesscache_clear"><code>tls sesscache clear</code></a></h3>
+ <strong>Syntax:</strong> ftpdctl tls sesscache clear<br>
+ <strong>Purpose:</strong> Clears all cached sessions from the SSL session cache<br>
+
+ <p>
+ The <code>tls sesscache clear</code> action is used to clear all cached
+ sessions, whether they have expired or not, from the configured external
+ SSL session cache. For example:
+ <pre>
+ # ftpdctl tls sesscache clear
+ ftpdctl: tls sesscache: cleared 1 session from 'shm' session cache
+ </pre>
+
+ <p>
+ See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
+
+ <p>
+ <hr>
+ <h3><a name="tls_sesscache_info"><code>tls sesscache info</code></a></h3>
+ <strong>Syntax:</strong> ftpdctl tls sesscache info <em>[-v]</em><br>
+ <strong>Purpose:</strong> Displays status of session cache<br>
+
+ <p>
+ The <code>tls sesscache info</code> action is used to display information
+ about the configured external SSL session cache. If the optional <em>-v</em>
+ command-line option is used, then information about each cached session
+ will also be displayed.
+
+ <p>
+ For example:
+ <pre>
+ # ftpdctl tls sesscache info -v
+ ftpdctl: Shared memory (shm) SSL session cache provided by mod_tls_shmcache/0.1
+ ftpdctl:
+ ftpdctl: Shared memory segment ID: 589824
+ ftpdctl: Shared memory segment size: 1576960 bytes
+ ftpdctl: Shared memory cache created on: Mon Mar 9 21:18:05 2009
+ ftpdctl: Shared memory attach count: 1
+ ftpdctl:
+ ftpdctl: Max session cache size: 153
+ ftpdctl: Current session cache size: 1
+ ftpdctl:
+ ftpdctl: Cache lifetime hits: 0
+ ftpdctl: Cache lifetime misses: 0
+ ftpdctl:
+ ftpdctl: Cache lifetime sessions stored: 1
+ ftpdctl: Cache lifetime sessions deleted: 0
+ ftpdctl: Cache lifetime sessions expired: 0
+ ftpdctl:
+ ftpdctl: Cache lifetime errors handling sessions in cache: 0
+ ftpdctl: Cache lifetime sessions exceeding max entry size: 0
+ ftpdctl:
+ ftpdctl: Cached sessions:
+ ftpdctl: -----BEGIN SSL SESSION PARAMETERS-----
+ ftpdctl: Session ID: A9BB647E236BAB0EF128FE9EAD2ABEC6F8E65C9EB8F050A07D1F0F66EC3019DC
+ ftpdctl: Session ID Context: 00000000
+ ftpdctl: Protocol: TLSv1
+ ftpdctl: Started: Mon Mar 9 21:19:20 2009
+ ftpdctl: Expires: Tue Mar 10 21:19:20 2009 (86400 secs)
+ ftpdctl: -----END SSL SESSION PARAMETERS-----
+ </pre>
+
+ <p>
+ See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
+
+ <p>
+ <hr>
+ <h3><a name="tls_sesscache_remove"><code>tls sesscache remove</code></a></h3>
+ <strong>Syntax:</strong> ftpdctl tls sesscache remove<br>
+ <strong>Purpose:</strong> Removes the external SSL session cache<br>
+
+ <p>
+ The <code>tls sesscache remove</code> action is used to remove the
+ external SSL session cache entirely. Depending on the actual module providing
+ the session cache, this may or may not be implemented.
+
+ <p>
+ For example:
+ <pre>
+ # ftpdctl tls sesscache remove
+ ftpdctl: tls sesscache: removed 'shm' session cache
+ </pre>
+
+ <p>
+ See also: <a href="#TLSSessionCache"><code>TLSSessionCache</code></a>
+
+ <p>
+ <hr>
<h2><a name="Usage">Usage</a></h2>
Much of the documentation for Apache's <code>mod_ssl</code>, concerning
***************
*** 1260,1265 ****
Last Updated: <i>$Date$</i><br>
! <br><hr>
!
<font size=2><b><i>
© Copyright 2002-2009 TJ Saunders<br>
--- 1538,1542 ----
Last Updated: <i>$Date$</i><br>
! <hr>
<font size=2><b><i>
© Copyright 2002-2009 TJ Saunders<br>
|