Menu
▾
▴
[Proftpd-docs] CVS: www.proftpd.org/docs/contrib mod_tls.html, 1.2, 1.3
|
From: TJ S. <cas...@us...> - 2010-04-05 16:20:44
|
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> |
