3085 lines
118 KiB
HTML
3085 lines
118 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<title>ProFTPD module mod_sftp</title>
|
|
</head>
|
|
|
|
<body bgcolor=white>
|
|
|
|
<hr>
|
|
<center>
|
|
<h2><b>ProFTPD module <code>mod_sftp</code></b></h2>
|
|
</center>
|
|
<hr><br>
|
|
|
|
<p>
|
|
<b>SFTP versus FTPS</b><br>
|
|
There is a great deal of confusion and misunderstanding surrounding two very
|
|
different protocols: SFTP and FTPS.
|
|
|
|
<p>
|
|
FTPS stands for "FTP over SSL/TLS". It is the existing FTP protocol,
|
|
made to run over an SSL/TLS connection; in this manner, it is very similar to
|
|
HTTPS (HTTP over SSL/TLS). In fact, that is where the name "FTPS" comes from.
|
|
The <a href="http://www.proftpd.org/docs/contrib/mod_tls.html"><code>mod_tls</code></a> module for ProFTPD implements FTPS. Since FTPS is still FTP, any
|
|
FTPS sessions require multiple TCP connections: one TCP connection for the
|
|
FTP control channel, and separate TCP connections for each FTP data channel.
|
|
The need for these multiple connections is undesirable for many network
|
|
administrators, especially those that wish to restrict all protocols to a
|
|
single TCP connection which can be passed through firewalls/NAT/router
|
|
equipment. The network equipment, now, often inspects the application-level
|
|
data in FTP packets in order to dynamically open the necessary firewall rules
|
|
for the FTP data channels. However, FTPS encrypts those packets, and thus
|
|
the network firewall must resort to using a statically configured range of
|
|
ports, or not allow FTPS. There is a third solution: the <code>CCC</code> FTP
|
|
command, which clears the FTP control channel of encryption, once the user has
|
|
authenticated. Unfortunately, support for the <code>CCC</code> command is not
|
|
widespread among FTPS clients and servers; the <code>mod_tls</code> module does
|
|
support the <code>CCC</code> command.
|
|
|
|
<p>
|
|
By contrast, SFTP refers to "Secure File Transfer Protocol", and is <b>not</b>
|
|
related to FTP in any way. SFTP is based on the SSH2 protocol, which uses
|
|
binary encoding of messages over a secure channel. Unlike FTP, SSH2 only
|
|
uses a single TCP connection, and multiplexes multiple transfers or "channels"
|
|
over that single connection. For this reason, many sites prefer SFTP
|
|
to FTPS for secure transfer of data.
|
|
|
|
<p>
|
|
<b>SSH2 RFCs and SFTP Drafts</b><br>
|
|
For those wishing to learn more about the SSH2 and SFTP protocols, see:
|
|
<ul>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4250.html">SSH Assigned Numbers (RFC 4250)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4251.html">SSH Architecture (RFC 4251)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4252.html">SSH Authentication (RFC 4252)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4253.html">SSH Transport Layer (RFC 4253)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4254.html">SSH Connection (RFC 4254)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4256.html">SSH Keyboard-Interactive Authentication (RFC 4256)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4335.html">SSH Channel "Break" Extension (RFC 4335)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4344.html">SSH Transport Encryption Modes (RFC 4344)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4345.html">SSH Improved Arcfour Modes (RFC 4345)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4419.html">SSH Diffie-Hellman Group Exchange Protocol (RFC 4419)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4432.html">SSH RSA Key Exchange Protocol (RFC 4432)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc4716.html">SSH Public Key File Format (RFC 4716)</a>
|
|
<li><a href="http://www.vandyke.com/technology/draft-ietf-secsh-filexfer.txt">SFTP Draft</a>
|
|
<li><a href="http://tools.ietf.org/html/draft-ietf-secsh-filexfer-extensions-00">SFTP Extensions Draft</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc5656.html">SSH Elliptic Curve Algorithms (RFC 5656)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc6668.html">SSH SHA-2 HMACs (RFC 6668)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc8270.html">SSH Increased Minimum DH Group Size (RFC 8270)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc8308.html">SSH Extension Negotiation (RFC 8308)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc8332.html">Use of RSA Keys with SHA-256 and SHA-512 in the SSH Protocol (RFC 8332)</a>
|
|
<li><a href="http://www.faqs.org/rfcs/rfc8731.html">SSH Key Exchange Method Using Curve25519 and Curve448 (RFC 8731)</a>
|
|
</ul>
|
|
|
|
<p>
|
|
<b>The <code>mod_sftp</code> module for ProFTPD</b><br>
|
|
The <code>mod_sftp</code> module implements the SSH2 protocol and its SFTP
|
|
subsystem, for secure file transfer over an SSH2 connection. The
|
|
<code>mod_sftp</code> module supports:
|
|
<ul>
|
|
<li>Public key authentication
|
|
<li>Password authentication (<i>e.g.</i> user authentication via
|
|
<code>mod_sql</code>, <code>mod_ldap</code>, <code>mod_auth_file</code>,
|
|
<code>mod_auth_unix</code>, <code>mod_auth_pam</code>)
|
|
<li>SCP support
|
|
<li>Quotas (via the <code>mod_quotatab</code> module)
|
|
<li>FIPS support (see <a href="#Usage">Usage</a> section)
|
|
<li>Throttled transfers (via <code>TransferRate</code>, and/or the
|
|
<code>mod_shaper</code> module)
|
|
<li>Blacklisted public keys
|
|
<li>Configurable traffic analysis protection
|
|
<li>Passphrase-protected host keys
|
|
<li>SFTP extensions: check-file, copy-file, vendor-id, version-select, posix-rename@openssh.com, statvfs@openssh.com, fstatvfs@openssh.com, hardlink@openssh.com
|
|
</ul>
|
|
This module supports the SFTP and SCP file transfer protocols; it does
|
|
<b>not</b> support shell access.
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> module does <b>not</b> currently support:
|
|
<ul>
|
|
<li><code><Anonymous></code>
|
|
<li><code>ListOptions</code>
|
|
<li><code>MaxRetrieveFileSize</code>
|
|
</ul>
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> module is contained in the <code>mod_sftp/</code>
|
|
directory, is intended for ProFTPD 1.3.3rc1 and later, and is not compiled by
|
|
default. Installation instructions are discussed
|
|
<a href="#Installation">here</a>.
|
|
|
|
<p>
|
|
The most current version of <code>mod_sftp</code> is distributed with the
|
|
ProFTPD source code.
|
|
|
|
<p>
|
|
This product includes software developed by the OpenSSL Project for use in the
|
|
OpenSSL Toolkit (<a href="http://www.openssl.org/">http://www.openssl.org/</a>).
|
|
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
|
|
|
|
<h2>Author</h2>
|
|
<p>
|
|
Please contact TJ Saunders <tj <i>at</i> castaglia.org> with any
|
|
questions, concerns, or suggestions regarding this module.
|
|
|
|
<h2>Directives</h2>
|
|
<ul>
|
|
<li><a href="#SFTPAcceptEnv">SFTPAcceptEnv</a>
|
|
<li><a href="#SFTPAuthMethods">SFTPAuthMethods</a>
|
|
<li><a href="#SFTPAuthPublicKeys">SFTPAuthPublicKeys</a>
|
|
<li><a href="#SFTPAuthorizedHostKeys">SFTPAuthorizedHostKeys</a>
|
|
<li><a href="#SFTPAuthorizedUserKeys">SFTPAuthorizedUserKeys</a>
|
|
<li><a href="#SFTPCiphers">SFTPCiphers</a>
|
|
<li><a href="#SFTPClientAlive">SFTPClientAlive</a>
|
|
<li><a href="#SFTPClientMatch">SFTPClientMatch</a>
|
|
<li><a href="#SFTPCompression">SFTPCompression</a>
|
|
<li><a href="#SFTPCryptoDevice">SFTPCryptoDevice</a>
|
|
<li><a href="#SFTPDHParamFile">SFTPDHParamFile</a>
|
|
<li><a href="#SFTPDigests">SFTPDigests</a>
|
|
<li><a href="#SFTPDisplayBanner">SFTPDisplayBanner</a>
|
|
<li><a href="#SFTPEngine">SFTPEngine</a>
|
|
<li><a href="#SFTPExtensions">SFTPExtensions</a>
|
|
<li><a href="#SFTPHostKey">SFTPHostKey</a>
|
|
<li><a href="#SFTPHostKeys">SFTPHostKeys</a>
|
|
<li><a href="#SFTPKeyBlacklist">SFTPKeyBlacklist</a>
|
|
<li><a href="#SFTPKeyExchanges">SFTPKeyExchanges</a>
|
|
<li><a href="#SFTPKeyLimits">SFTPKeyLimits</a>
|
|
<li><a href="#SFTPLog">SFTPLog</a>
|
|
<li><a href="#SFTPMaxChannels">SFTPMaxChannels</a>
|
|
<li><a href="#SFTPOptions">SFTPOptions</a>
|
|
<li><a href="#SFTPPassPhraseProvider">SFTPPassPhraseProvider</a>
|
|
<li><a href="#SFTPRekey">SFTPRekey</a>
|
|
<li><a href="#SFTPTrafficPolicy">SFTPTrafficPolicy</a>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPAcceptEnv">SFTPAcceptEnv</a></h3>
|
|
<strong>Syntax:</strong> SFTPAcceptEnv <em>env1 ...</em><br>
|
|
<strong>Default:</strong> <em>LANG</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.3rc3 and later
|
|
|
|
<p>
|
|
The <code>SFTPAcceptEnv</code> directive specifies which environment variables
|
|
sent by the client, if any, will be used in the session environment.
|
|
Environment variables are specified by name, and may contain the '*' and '?'
|
|
wildcard characters. Multiple environment variables may be configured, either
|
|
separated by whitespace or spread across multiple <code>SFTPAcceptEnv</code>
|
|
directives.
|
|
|
|
<p>
|
|
Be warned that some environment variables may have special meaning to
|
|
underlying libraries; care should be taken in the use of this directive.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPAuthMethods">SFTPAuthMethods</a></h3>
|
|
<strong>Syntax:</strong> SFTPAuthMethods <em>meth1 ...</em><br>
|
|
<strong>Default:</strong> <em>publickey password</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPAuthMethods</code> directive configures the list of available
|
|
authentication methods presented to connecting clients. The list of
|
|
currently supported methods is:
|
|
<ul>
|
|
<li>hostbased
|
|
<li>keyboard-interactive
|
|
<li>password
|
|
<li>publickey
|
|
</ul>
|
|
In general, there is no need to use this directive unless only one specific
|
|
authentication method must be used. Should it be needed, the list of
|
|
authentication methods to use is provided as a space-delimited list,
|
|
<i>e.g.</i>:
|
|
<pre>
|
|
# Offer publickey and keyboard-interactive authentication only
|
|
SFTPAuthMethods publickey keyboard-interactive
|
|
</pre>
|
|
|
|
<p>
|
|
The <em>hostbased</em> authentication method is only offered to clients if
|
|
the <a href="#SFTPAuthorizedHostKeys"><code>SFTPAuthorizedHostKeys</code></a>
|
|
directive is configured.
|
|
|
|
<p>
|
|
The <em>publickey</em> authentication method is only offered to clients if
|
|
the <a href="#SFTPAuthorizedUserKeys"><code>SFTPAuthorizedUserKeys</code></a>
|
|
directive is configured.
|
|
|
|
<p>
|
|
The <em>keyboard-interactive</em> authentication method is only offered to
|
|
clients if the <a href="mod_sftp_pam.html"><code>mod_sftp_pam</code></a>
|
|
or <a href="mod_auth_otp.html"><code>mod_auth_otp</code></a> module is present.
|
|
|
|
<p>
|
|
As of <code>proftpd-1.3.6rc2</code> and later, you can use the
|
|
<code>SFTPAuthMethods</code> directive to configure <em>chains</em> of
|
|
methods. An authentication <em>chain</em> is a list of authentication
|
|
methods, <b>all</b> of which must succeed in order for login to succeed.
|
|
For example, using:
|
|
<pre>
|
|
# Require both publickey and password authentication
|
|
SFTPAuthMethods publickey+password
|
|
</pre>
|
|
Note that <i>order of the methods in a chain is important</i>. In the above
|
|
example, the publickey authentication <b>must</b> succeed first, before
|
|
password authentication will be offered. If you want require both
|
|
publickey and password authentication, but that they can be used in any
|
|
order, you can configure multiple chains:
|
|
<pre>
|
|
# Require both publickey and password authentication, in any order
|
|
SFTPAuthMethods publickey+password password+publickey
|
|
</pre>
|
|
As long as any <i>one</i> chain is completed, login will succeed.
|
|
|
|
<p>
|
|
You can even require that multiple different keys be used (<i>e.g.</i> a
|
|
RSA and a DSA public key, or multiple different RSA/DSA keys) using:
|
|
<pre>
|
|
# Require different keys for publickey authentication
|
|
SFTPAuthMethods publickey+publickey
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPAuthPublicKeys">SFTPAuthPublicKeys</a></h3>
|
|
<strong>Syntax:</strong> SFTPAuthPublicKeys <em>algo1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.9rc3 and later
|
|
|
|
<p>
|
|
The <code>SFTPAuthPublicKeys</code> directive is used to specify the list of
|
|
public key algorithms that <code>mod_sftp</code> allows during authentication.
|
|
The current list of supported public key algorithms is:
|
|
<ul>
|
|
<li>ssh-dss
|
|
<li>ssh-rsa
|
|
<li>rsa-sha2-256
|
|
<li>rsa-sha2-512
|
|
<li>ecdsa-sha2-nistp256
|
|
<li>ecdsa-sha2-nistp384
|
|
<li>ecdsa-sha2-nistp521
|
|
<li>sk-ecdsa-sha2-nistp256@openssh.com
|
|
<li>ssh-ed25519 (<i>requires Sodium</i>)
|
|
<li>sk-ssh-ed25519@openssh.com (<i>requires Sodium</i>)
|
|
<li>ssh-ed448 (<i>requires OpenSSL 1.1.1 or later</i>)
|
|
</ul>
|
|
By default, all of the above public key algorithms are allowed.
|
|
|
|
<p>
|
|
In general, there is no need to use this directive unless specific public key
|
|
algorithms must be used (or avoided).
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPAuthorizedHostKeys">SFTPAuthorizedHostKeys</a></h3>
|
|
<strong>Syntax:</strong> SFTPAuthorizedHostKeys <em>store1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPAuthorizedHostKeys</code> directive configures the file that
|
|
<code>mod_sftp</code> will use during the handling of hostbased authentication
|
|
of users. The configured file may contain several public keys in RFC4716
|
|
format, in no particular order.
|
|
|
|
<p>
|
|
<b>Note</b> that a <code>SFTPAuthorizedHostKeys</code> directive is
|
|
required for <code>mod_sftp</code> to handle sessions which want to use
|
|
hostbased authentication properly.
|
|
|
|
<p>
|
|
<b>Note:</b> In order to use OpenSSH public keys in a
|
|
<code>SFTPAuthorizedHostKeys</code>, you <b>must</b> convert them to the
|
|
RFC4716 format (see the <a href="#UsageRFC4716Format">Usage</a> section).
|
|
This is done using OpenSSH's <code>ssh-keygen</code> tool:
|
|
<pre>
|
|
$ ssh-keygen -e -f /path/to/file
|
|
</pre>
|
|
The output from this command can then be added to the
|
|
<code>SFTPAuthorizedHostKeys</code> file.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPAuthorizedUserKeys">SFTPAuthorizedUserKeys</a></h3>
|
|
<strong>Syntax:</strong> SFTPAuthorizedUserKeys <em>store1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPAuthorizedUserKeys</code> directive configures the file that
|
|
<code>mod_sftp</code> will use during the handling of publickey authentication
|
|
of users. The configured file may contain several public keys in RFC4716
|
|
format, in no particular order.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
SFTPAuthorizedUserKeys file:~/.sftp/authorized_keys
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Note:</b> In order to use OpenSSH public keys in a
|
|
<code>SFTPAuthorizedUserKeys</code>, you <b>must</b> convert them to the
|
|
RFC4716 format (see the <a href="#UsageRFC4716Format">Usage</a> section).
|
|
This is done using OpenSSH's <code>ssh-keygen</code> tool:
|
|
<pre>
|
|
$ ssh-keygen -e -f ~/.ssh/id_rsa.pub -m RFC4716
|
|
</pre>
|
|
The output from this command can then be added to the
|
|
<code>SFTPAuthorizedUserKeys</code> file.
|
|
|
|
<p>
|
|
The configured path for a file containing authorized keys can use the
|
|
<code>%u</code> variable, which will be interpolated with the name of the user
|
|
being authenticated. This feature supports having per-user files of authorized
|
|
keys that reside in a central location, rather than requiring (or allowing)
|
|
users to manage their own authorized keys. For example:
|
|
<pre>
|
|
SFTPAuthorizedUserKeys file:/etc/sftp/authorized_keys/%u
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPCiphers">SFTPCiphers</a></h3>
|
|
<strong>Syntax:</strong> SFTPCiphers <em>algo1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPCiphers</code> directive is used to specify the list of
|
|
cipher algorithms that <code>mod_sftp</code> should use. The current list
|
|
of supported cipher algorithms is, in the default order of preference:
|
|
<ul>
|
|
<li>chacha20-poly1305@openssh.com
|
|
<li>aes256-ctr
|
|
<li>aes192-ctr
|
|
<li>aes128-ctr
|
|
<li>aes256-gcm@openssh.com
|
|
<li>aes128-gcm@openssh.com
|
|
<li>aes256-cbc
|
|
<li>aes192-cbc
|
|
<li>aes128-cbc
|
|
<li>cast128-cbc
|
|
<li>3des-ctr
|
|
<li>3des-cbc
|
|
</ul>
|
|
By default, all of the above cipher algorithms are presented to the client,
|
|
in the above order, during the key exchange.
|
|
|
|
<p>
|
|
In ProFTPD 1.3.7rc1 and later, the following list of algorithms are
|
|
<em>supported</em>, but <b>not</b> presented to clients by default. These
|
|
algorithms must be <em>explicitly</em> configured via <code>SFTPCiphers</code>
|
|
to be available for use by clients:
|
|
<ul>
|
|
<li>blowfish-ctr
|
|
<li>blowfish-cbc
|
|
<li>arcfour256
|
|
<li>arcfour128
|
|
</ul>
|
|
|
|
<p>
|
|
The "none" cipher (<i>i.e.</i> no encryption) will <b>not</b> be presented to
|
|
the client by default; any sites which wish to use "none" will have to
|
|
explicitly configure it via <code>SFTPCiphers</code>.
|
|
|
|
<p>
|
|
Note that CTR mode ciphers (<i>e.g.</i> the <code>aes128-ctr</code>,
|
|
<code>aes192-ctr</code>, and <code>aes256-ctr</code> ciphers) are recommended.
|
|
Any CBC mode cipher allows for the possibility of an attack which causes
|
|
several bits of plaintext to be leaked; the attack is described
|
|
<a href="http://www.cpni.gov.uk/Docs/Vulnerability_Advisory_SSH.txt">here</a>.
|
|
This attack is on the SSH2 protocol design itself; any SSH2 implementation
|
|
which conforms to the RFCs will have this weakness.
|
|
|
|
<p>
|
|
In general, there is no need to use this directive unless only one specific
|
|
cipher must be used.
|
|
|
|
<p>
|
|
For comparison, the cipher algorithms used by OpenSSH by default are:
|
|
<ul>
|
|
<li>aes128-cbc
|
|
<li>3des-cbc
|
|
<li>blowfish-cbc
|
|
<li>cast128-cbc
|
|
<li>arcfour128
|
|
<li>arcfour256
|
|
<li>aes192-cbc
|
|
<li>aes256-cbc
|
|
<li>aes128-ctr
|
|
<li>aes192-ctr
|
|
<li>aes256-ctr
|
|
<li>aes128-gcm@openssh.com
|
|
<li>aes256-gcm@openssh.com
|
|
<li>chacha20-poly1305@openssh.com
|
|
</ul>
|
|
Thus if you wanted to configure <code>mod_sftp</code> to present the same
|
|
cipher algorithms as OpenSSH, you would use:
|
|
<pre>
|
|
# Make mod_sftp present the same ciphers as OpenSSH
|
|
SFTPCiphers aes128-cbc 3des-cbc blowfish-cbc cast128-cbc arcfour128 \
|
|
arcfour256 aes192-cbc aes256-cbc aes128-ctr aes192-ctr aes256-ctr \
|
|
aes128-gcm@openssh.com aes256-gcm@openssh.com \
|
|
chacha20-poly1305@openssh.com
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPClientAlive">SFTPClientAlive</a></h3>
|
|
<strong>Syntax:</strong> SFTPClientAlive <em>count</em> <em>interval</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.4rc1 and later
|
|
|
|
<p>
|
|
The <code>SFTPClientAlive</code> directive configured <code>mod_sftp</code>
|
|
to send messages to a client, through the encrypted channel, to request a
|
|
response from the client. If <em>count</em> client alive messages are sent
|
|
without receiving any response messages from the client, the client will
|
|
be disconnected. The <em>interval</em> indicates how much time, in seconds,
|
|
that <code>mod_sftp</code> waits for data from the client before sending a
|
|
client alive message.
|
|
|
|
<p>
|
|
For example, using:
|
|
<pre>
|
|
SFTPClientAlive 3 15
|
|
</pre>
|
|
will cause an unresponsive client to be disconnected after approximately 45
|
|
seconds.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPClientMatch">SFTPClientMatch</a></h3>
|
|
<strong>Syntax:</strong> SFTPClientMatch <em>pattern key1 val1 ...</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPClientMatch</code> directive is used to tune some of the
|
|
SSH2/SFTP values based on the connecting client, for better interoperability
|
|
with those clients. The <em>pattern</em> parameter specifies a POSIX regular
|
|
expression which will be matched against the connecting client's SSH version
|
|
banner. If the client's banner version matches <em>pattern</em>, then
|
|
the configured keys/values are used for that session.
|
|
|
|
<p>
|
|
The currently supported SSH2/SFTP keys which can be tuned via
|
|
<code>SFTPClientMatch</code> are:
|
|
<ul>
|
|
<li>channelPacketSize<br>
|
|
The <em>value</em> for this key can be a number, with an optional "KB"
|
|
(kilobytes) suffix.
|
|
|
|
<p>
|
|
The default <code>mod_sftp</code> channel packet size is 32KB.
|
|
</li>
|
|
|
|
<p>
|
|
<li>channelWindowSize</br>
|
|
The <em>value</em> for this key can be a number, with an optional
|
|
"GB" (gigabytes), "MB" (megabytes), or "KB" (kilobytes) suffix.
|
|
|
|
<p>
|
|
The default <code>mod_sftp</code> channel window size is 4GB. Using
|
|
smaller window sizes may be necessary for some clients; larger window
|
|
sizes can help reduce latency for bulk data transfers.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpCiphers</br>
|
|
The <em>value</em> for this key should be a comma-separated list
|
|
of cipher algorithms, as for the
|
|
<a href="#SFTPCiphers><code>SFTPCiphers</code></a> directive. Use of
|
|
this <em>key</em> automatically enables the <code>PessimisticKexinit</code>
|
|
SFTPOption as well.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpDigests</br>
|
|
The <em>value</em> for this key should be a comma-separated list
|
|
of digest algorithms, as for the
|
|
<a href="#SFTPDigests><code>SFTPDigests</code></a> directive. Use of
|
|
this <em>key</em> automatically enables the <code>PessimisticKexinit</code>
|
|
SFTPOption as well.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpHostKeys</br>
|
|
The <em>value</em> for this key should be a comma-separated list
|
|
of host key algorithms, as for the
|
|
<a href="#SFTPHostKeys><code>SFTPHostKeys</code></a> directive. Use of
|
|
this <em>key</em> automatically enables the <code>PessimisticKexinit</code>
|
|
SFTPOption as well.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpKeyExchanges</br>
|
|
The <em>value</em> for this key should be a comma-separated list
|
|
of key exchange algorithms, as for the
|
|
<a href="#SFTPKeyExchanges"><code>SFTPKeyExchanges</code></a> directive.
|
|
Use of this <em>key</em> automatically enables the
|
|
<code>PessimisticKexinit</code> SFTPOption as well.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpProtocolVersion</br>
|
|
The <em>value</em> for this key can be a specific version number,
|
|
<i>e.g.</i> "3", or it can be a range such as "1-3". The
|
|
<code>mod_sftp</code> module supports SFTP protocol versions 1-6;
|
|
using any other protocol versions will result in bad configuration.
|
|
</li>
|
|
|
|
<p>
|
|
<li>sftpUTF8ProtocolVersion</br>
|
|
The <em>value</em> for this key is a specific version number,
|
|
<i>e.g.</i> "3". The <code>mod_sftp</code> module uses UTF8 encoding
|
|
for handling paths/strings in SFTP messages for protocol version 4 and
|
|
above by default; this key can be used to change the protocol versions for
|
|
which UTF8 encoding is used.
|
|
|
|
<p>
|
|
For example, if you set:
|
|
<pre>
|
|
SFTPClientMatch .* sftpUTF8ProtocolVersion 1
|
|
</pre>
|
|
then <code>mod_sftp</code> will try to use UTF8 for all SFTP protocol
|
|
versions, all clients.
|
|
|
|
<p>
|
|
<b>Note</b>: the <code>sftpUTF8ProtocolVersion</code> key <b>requires</b>
|
|
NLS support (<i>i.e.</i> the <code>--enable-nls</code> configure option).
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
For example, to make <code>mod_sftp</code> only allow SFTP protocol version 3
|
|
to WinSCP clients, you would use:
|
|
<pre>
|
|
SFTPClientMatch ".*WinSCP.*" sftpProtocolVersion 3
|
|
</pre>
|
|
Or for older OpenSSH clients, you may need to use a smaller channel window
|
|
size, <i>e.g.</i>:
|
|
<pre>
|
|
SFTPClientMatch "^OpenSSH_3\\.*" channelWindowSize 8MB
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPCompression">SFTPCompression</a></h3>
|
|
<strong>Syntax:</strong> SFTPCompression <em>on|off|delayed</em><br>
|
|
<strong>Default:</strong> <em>off</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPCompression</code> directive enables the use of zlib compression
|
|
of the payload of SSH2 packets. This can make for smaller packets, but require
|
|
more CPU time to compress/uncompress the data.
|
|
|
|
<p>
|
|
The <em>delayed</em> parameter tells <code>mod_sftp</code> to support a custom
|
|
extension used by OpenSSH, where compression is not actually enabled until
|
|
after the client has successfully authenticated.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPCryptoDevice">SFTPCryptoDevice</a></h3>
|
|
<strong>Syntax:</strong> SFTPCryptoDevice <em>driver|"all"|"none"</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPCryptoDevice</code> directive is used to configure
|
|
<code>mod_sftp</code> to use an OpenSSL "engine", a cryptographic module
|
|
that OpenSSL library can use for accelerated cryptographic support, or
|
|
HSM keys, <i>etc</i>.
|
|
|
|
<p>
|
|
To use all of the engines compiled into OpenSSL, use:
|
|
<pre>
|
|
SFTPCryptoDevice all
|
|
</pre>
|
|
OpenSSL will find, from the list of supported engines, the first one
|
|
usable, if any. If no usable engines are found, OpenSSL will default to
|
|
its normal software implementation. If a specific engine is desired as
|
|
the default engine to use, specify the engine name, <i>e.g.</i>:
|
|
<pre>
|
|
SFTPCryptoDevice chil
|
|
</pre>
|
|
|
|
<p>
|
|
The OpenSSL command
|
|
<pre>
|
|
openssl engine
|
|
</pre>
|
|
may be used to list all of the engine drivers supported by OpenSSL.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPDHParamFile">SFTPDHParamFile</a></h3>
|
|
<strong>Syntax:</strong> SFTPDHParamFile <em>path</em><br>
|
|
<strong>Default:</strong> <em>dhparams.pem</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPDHParamFile</code> directive is used to configure the path
|
|
to a file containing pre-computed Diffie-Hellman (DH) group parameters.
|
|
These parameters will be used by <code>mod_sftp</code> when handling the
|
|
Diffie-Hellman group exchange (see RFC 4419) portion of the key exchange.
|
|
|
|
<p>
|
|
The <code>SFTPDHParamFile</code> is produced using OpenSSL, which uses
|
|
PEM encodings of PKCS#3 <code>DHparam</code> structures. It is similar in
|
|
nature to OpenSSH's <code>moduli(5)</code> file.
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> source code comes with a <code>dhparams.pem</code>
|
|
file which should be sufficient. If for any reason you find that you
|
|
need to generate your own <code>SFTPDHParamFile</code>, use one of the
|
|
following OpenSSL commands to create this file:
|
|
<pre>
|
|
# openssl dhparam -outform PEM -2 <i>nbits</i> >> dhparams.pem
|
|
# openssl dhparam -outform PEM -5 <i>nbits</i> >> dhparams.pem
|
|
</pre>
|
|
Using either <code>-2</code> or <code>-5</code> as the generator is fine.
|
|
The <em>nbits</em> value used should vary between 1024 and 8192, inclusive.
|
|
<b>Beware</b>: this process is quite slow, and CPU/memory intensive!
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPDigests">SFTPDigests</a></h3>
|
|
<strong>Syntax:</strong> SFTPDigests <em>algo1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPDigests</code> directive is used to specify the list of
|
|
MAC digest algorithms that <code>mod_sftp</code> should use. The current list
|
|
of supported MAC algorithms is:
|
|
<ul>
|
|
<li>hmac-sha2-256
|
|
<li>hmac-sha2-256-etm@openssh.com
|
|
<li>hmac-sha2-512
|
|
<li>hmac-sha2-512-etm@openssh.com
|
|
<li>hmac-sha1
|
|
<li>hmac-sha1-etm@openssh.com
|
|
<li>hmac-sha1-96
|
|
<li>hmac-sha1-96-etm@openssh.com
|
|
<li>umac-64@openssh.com
|
|
<li>umac-64-etm@openssh.com
|
|
<li>umac-128@openssh.com
|
|
<li>umac-128-etm@openssh.com
|
|
</ul>
|
|
By default, all of the above MAC algorithms are presented to the client,
|
|
in the above order, during the key exchange. <b>Note</b> that some algorithms
|
|
(<i>e.g.</i> the SHA256 and SHA512 algorithms) may not be supported by
|
|
the version of OpenSSL used; this will be automatically detected.
|
|
|
|
<p>
|
|
The following list of algorithms are <em>supported</em>, but <b>not</b>
|
|
presented to clients by default. These algorithms must be <em>explicitly</em>
|
|
configured via <code>SFTPDigests</code> to be available for use by clients:
|
|
<ul>
|
|
<li>hmac-md5
|
|
<li>hmac-md5-etm@openssh.com
|
|
<li>hmac-md5-96
|
|
<li>hmac-ripemd160
|
|
</ul>
|
|
|
|
<p>
|
|
The "none" MAC (<i>i.e.</i> no MAC) will <b>not</b> be presented to the client
|
|
by default; any sites which wish to use "none" will have to explicitly
|
|
configure it via <code>SFTPDigests</code>.
|
|
|
|
<p>
|
|
In general, there is no need to use this directive unless only one specific
|
|
MAC algorithm must be used.
|
|
|
|
<p>
|
|
For comparison, the MAC algorithms used by OpenSSH (depending on the version)
|
|
by default are:
|
|
<ul>
|
|
<li>hmac-md5
|
|
<li>hmac-md5-etm@openssh.com
|
|
<li>hmac-sha1
|
|
<li>hmac-sha1-etm@openssh.com
|
|
<li>hmac-sha2-256
|
|
<li>hmac-sha2-256-etm@openssh.com
|
|
<li>hmac-sha2-512
|
|
<li>hmac-sha2-512-etm@openssh.com
|
|
<li>hmac-ripemd160
|
|
<li>hmac-sha1-96
|
|
<li>hmac-md5-96
|
|
<li>umac-64@openssh.com
|
|
<li>umac-64-etm@openssh.com
|
|
<li>umac-128@openssh.com
|
|
<li>umac-128-etm@openssh.com
|
|
</ul>
|
|
Thus if you wanted to configure <code>mod_sftp</code> to present the same
|
|
MAC algorithms as OpenSSH, you would use:
|
|
<pre>
|
|
# Make mod_sftp present the MAC ciphers as OpenSSH
|
|
SFTPDigests hmac-md5 hmac-sha1 hmac-sha2-256 hmac-sha2-512 \
|
|
hmac-ripemd160 hmac-sha1-96 hmac-md5-96 umac-64@openssh.com \
|
|
umac-128@openssh.com
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPDisplayBanner">SFTPDisplayBanner</a></h3>
|
|
<strong>Syntax:</strong> SFTPDisplayBanner <em>path</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPDisplayBanner</code> directive is used to configure the path
|
|
of a file which will be sent to the client prior to authentication. Such
|
|
files are often used to sent terms of use or other such policy terms to
|
|
connecting clients.
|
|
|
|
<p>
|
|
See the <a href="../howto/DisplayFiles.html">Display files</a> howto for
|
|
more information on the variables that can be used in an
|
|
<code>SFTPDisplayBanner</code> file.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPEngine">SFTPEngine</a></h3>
|
|
<strong>Syntax:</strong> SFTPEngine <em>on|off</em><br>
|
|
<strong>Default:</strong> <em>off</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPEngine</code> directive toggles the use of the SSH2/SFTP protocols
|
|
engine (<i>e.g.</i> <code>mod_sftp</code>). This is usually used inside a
|
|
<code><VirtualHost></code> section to enable SFTP sessions for a
|
|
particular virtual host. By default <code>mod_sftp</code> is disabled for both
|
|
the main server and all configured virtual hosts.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPExtensions">SFTPExtensions</a></h3>
|
|
<strong>Syntax:</strong> SFTPExtensions <em>ext1 ... extN</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.3rc3 and later
|
|
|
|
<p>
|
|
The <code>SFTPExtensions</code> directive can be used to enable/disable
|
|
support for the various SFTP extensions supported by <code>mod_sftp</code>.
|
|
The extension names used for the <code>SFTPExtensions</code> directive are:
|
|
<ul>
|
|
<li>checkFile
|
|
<li>copyFile
|
|
<li>fsync
|
|
<li>hardlink
|
|
<li>homeDirectory
|
|
<li>limits
|
|
<li>posixRename
|
|
<li>spaceAvailable
|
|
<li>statvfs
|
|
<li>userGroupNames
|
|
<li>vendorID
|
|
<li>versionSelect
|
|
<li>xattr
|
|
</ul>
|
|
All extensions <i>except</i> <code>vendorID</code> <b>and</b>
|
|
<code>xattr</code> are enabled by default.
|
|
|
|
<p>
|
|
To enable an extension, preface the extension name with a '+' (plus) character;
|
|
to disable the extension, use a '-' (minus) character prefix. For example:
|
|
<pre>
|
|
# Allow the copy-file extension, but not version-select
|
|
SFTPExtensions +copyFile -versionSelect
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPHostKey">SFTPHostKey</a></h3>
|
|
<strong>Syntax:</strong> SFTPHostKey <em>file</em>|agent:<em>/path</em>|"NoRSA"|"NoDSA"|"NoECDSA"<br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPHostKey</code> directive configures the path to a host key file.
|
|
The <code>mod_sftp</code> module uses the keys thus configured as part of
|
|
the SSH2 key exchange process.
|
|
|
|
<p>
|
|
Note that the <code>SFTPHostKey</code> directive is <b>required</b>. You
|
|
can use either an RSA key, a DSA key, and/or ECDSA keys. These should be the
|
|
<b>exact same host key files as used by your SSH2 server</b>, <i>e.g.</i>:
|
|
<pre>
|
|
SFTPHostKey /etc/ssh_host_dsa_key
|
|
SFTPHostKey /etc/ssh_host_rsa_key
|
|
SFTPHostKey /etc/ssh_host_ecdsa_key
|
|
SFTPHostKey /etc/ssh_host_ed25519_key
|
|
</pre>
|
|
or the equivalents in the <code>/usr/local/etc/</code> directory. Using
|
|
different host keys between your SSH2 server and <code>mod_sftp</code> will
|
|
only cause confusion and problems for any SFTP clients. Most SFTP clients
|
|
will assume that the host uses the same keys for SSH2 and SFTP; after all,
|
|
it is the same <i>host</i> (even the same port), just different services.
|
|
Thus having different host keys for an SSH2 server and <code>mod_sftp</code>
|
|
will cause clients to constantly switch the host keys they record for the
|
|
same host (and cause confusion for users).
|
|
|
|
<p>
|
|
The <code>SFTPHostKey</code> directive, as of <code>proftpd-1.3.5rc1</code>
|
|
and later, can also be used to load host keys from an SSH agent such as
|
|
OpenSSH's <code>ssh-agent</code>. For example:
|
|
<pre>
|
|
# Load all of the keys from the ssh-agent configured for server use
|
|
SFTPHostKey agent:%{env:SSH_AUTH_SOCK}
|
|
</pre>
|
|
Using an SSH agent for storing host keys allows for configurations where
|
|
the host keys are not stored on files on the server system, <i>e.g.</i>
|
|
the keys can be loaded into the SSH agent from a PKCS#11 token.
|
|
|
|
<p>
|
|
The <code>SFTPHostKey</code> directive, as of <code>proftpd-1.3.6rc1</code>
|
|
and later, can be used to <em>disable</em> host keys configured via
|
|
<code><Global></code>. For example, if you have a global RSA key that
|
|
you wish to disable in all vhosts, you might use the "NoRSA" flag, <i>e.g.</i>:
|
|
<pre>
|
|
<Global>
|
|
SFTPHostKey /path/to/ssh_rsa_host_key
|
|
...
|
|
</Global>
|
|
|
|
<VirtualHost a.b.c.d>
|
|
...
|
|
# Configure our per-vhost DSA host key
|
|
SFTPHostKey /path/to/ssh_dsa_host_key
|
|
|
|
# ...and disable the global RSA host key
|
|
SFTPHostKey NoRSA
|
|
...
|
|
</VirtualHost>
|
|
</pre>
|
|
|
|
<p>
|
|
OpenSSH started using an OpenSSH-specific private key format in version 7.8.
|
|
ProFTPD did not support reading this OpenSSH-specific format until 1.3.7. Thus
|
|
if you need to use SSH hostkeys in the OpenSSH-specific private key format
|
|
with ProFTPD prior to 1.3.7, you will need to convert those private keys to
|
|
the more conventional PEM format that <code>mod_sftp</code> supported. If
|
|
your <code>SFTPHostKey</code> file starts with:
|
|
<pre>
|
|
-----BEGIN OPENSSH PRIVATE KEY-----
|
|
</pre>
|
|
then it is using the OpenSSH-specific private key format. To convert this
|
|
private key to a PEM private key, use <i>e.g.</i>:
|
|
<pre>
|
|
$ cp /etc/ssh/ssh_host_rsa_key /etc/proftpd/ssh_host_rsa_key
|
|
$ ssh-keygen -p -f /etc/proftpd/ssh_host_rsa_key -m PEM
|
|
</pre>
|
|
<b>Note</b> that you <b>cannot</b> use the <code>-e</code> option for this:
|
|
<pre>
|
|
$ ssh-keygen -e -f /etc/ssh/ssh_host_rsa_key -m PEM > /etc/proftpd/ssh_host_rsa_key
|
|
</pre>
|
|
Since that "exports" the corresponding <b><i>public key</i></b>, not the
|
|
<em>private key</em> as you would want for a hostkey.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPHostKeys">SFTPHostKeys</a></h3>
|
|
<strong>Syntax:</strong> SFTPHostKeys <em>algo1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.8rc4 and later
|
|
|
|
<p>
|
|
The <code>SFTPHostKeys</code> directive is used to specify the list of host
|
|
key algorithms that <code>mod_sftp</code> should use. The current list
|
|
of supported host key algorithms is:
|
|
<ul>
|
|
<li>ssh-ed25519 (<i>requires Sodium</i>)
|
|
<li>ssh-ed448 (<i>requires OpenSSL 1.1.1 or later</i>)
|
|
<li>ecdsa-sha2-nistp256
|
|
<li>ecdsa-sha2-nistp384
|
|
<li>ecdsa-sha2-nistp521
|
|
<li>rsa-sha2-512
|
|
<li>rsa-sha2-256
|
|
<li>ssh-rsa
|
|
<li>ssh-dss
|
|
</ul>
|
|
By default, all of the above host key algorithms are presented to the
|
|
client, in the above order, during the key exchange, <em>assuming</em> that
|
|
a suitable <code>SFTPHostKey</code> file for that algorithm has been provided.
|
|
|
|
<p>
|
|
In general, there is no need to use this directive unless specific host keys
|
|
algorithm must be used (or avoided).
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPKeyBlacklist">SFTPKeyBlacklist</a></h3>
|
|
<strong>Syntax:</strong> SFTPKeyBlacklist <em>"none"|path</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPKeyBlacklist</code> directive configures the path to
|
|
a specially formatted dictionary of known weak public keys. This key
|
|
blacklist, and the code for using it, was primarily developed by
|
|
Dmitry V. Levin under sponsorship by
|
|
<a href="http://www.civicactions.com">CivicActions</a>. For the original
|
|
posting, and further information, see:
|
|
<pre>
|
|
<a href="http://www.openwall.com/lists/oss-security/2008/05/27/3">http://www.openwall.com/lists/oss-security/2008/05/27/3</a>
|
|
</pre>
|
|
|
|
<p>
|
|
These known weak public keys arose because of a vulnerability in the OpenSSL
|
|
packages distributed by Debian:
|
|
<pre>
|
|
<a href="http://www.debian.org/security/2008/dsa-1571">http://www.debian.org/security/2008/dsa-1571</a>
|
|
</pre>
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> source code comes with a <code>blacklist.dat</code>
|
|
file which should be sufficient. If for any reason you find that you
|
|
need to generate your own <code>SFTPDKeyBlacklist</code>, use the
|
|
<code>blacklist-encode</code> program mentioned in the above URLs.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPKeyExchanges">SFTPKeyExchanges</a></h3>
|
|
<strong>Syntax:</strong> SFTPKeyExchanges <em>algo1 ...</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPKeyExchanges</code> directive is used to specify the list of
|
|
key exchange algorithms that <code>mod_sftp</code> should use. The current list
|
|
of supported key exchange algorithms is:
|
|
<ul>
|
|
<li>curve448-sha512
|
|
<li>curve25519-sha256
|
|
<li>ecdh-sha2-nistp521
|
|
<li>ecdh-sha2-nistp384
|
|
<li>ecdh-sha2-nistp256
|
|
<li>diffie-hellman-group18-sha512
|
|
<li>diffie-hellman-group16-sha512
|
|
<li>diffie-hellman-group14-sha256
|
|
<li>diffie-hellman-group-exchange-sha256
|
|
<li>diffie-hellman-group-exchange-sha1
|
|
<li>diffie-hellman-group14-sha1
|
|
<li>diffie-hellman-group1-sha1
|
|
<li>rsa1024-sha1
|
|
</ul>
|
|
By default, all of the above key exchange algorithms <i>except
|
|
<code>diffie-hellman-group1-sha1</code></i> are presented to the client, in
|
|
the above order, during the key exchange.
|
|
|
|
<p>
|
|
<b>Note</b> that the <code>diffie-hellman-group1-sha1</code> key exchange
|
|
algorithm uses a weak hardcoded Diffie-Hellman group, and thus is <b>not</b>
|
|
enabled by default. To enable this key exchange algorithm, you must
|
|
configure the <code>SFTPKeyExchanges</code> list to <b>explicitly</b> include
|
|
this algorithm, <i>or</i> use the following in your configuration:
|
|
<pre>
|
|
SFTPOptions AllowWeakDH
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Note</b> that the <code>curve448-sha512</code> key exchange algorithm
|
|
requires an Ed448 SSH host key. To generate such a key, use:
|
|
<pre>
|
|
openssl genpkey -out /etc/ssh/ssh_host_ed448_key -algorithm ED448
|
|
</pre>
|
|
|
|
<p>
|
|
In general, there is no need to use this directive unless only one specific
|
|
key exchange algorithm must be used.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPKeyLimits">SFTPKeyLimits</a></h3>
|
|
<strong>Syntax:</strong> SFTPKeyLimits <em>limit1 ...</em><br>
|
|
<strong>Default:</strong> MinimumRSASize 768 MinimumDSASize 384 MinimumECSize 160<em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.6rc3 and later
|
|
|
|
<p>
|
|
The <code>SFTPKeyLimits</code> directive is used to configure limits on the
|
|
sizes of keys (in terms of <em>bits</em>), both host keys <b>and</b> user keys.
|
|
The currently supported limits are:
|
|
<ul>
|
|
<li><code>MinimumDSASize</code>
|
|
<li><code>MinimumECSize</code>
|
|
<li><code>MinimumRSASize</code>
|
|
</ul>
|
|
|
|
<p>
|
|
Examples:
|
|
<pre>
|
|
# Require at least 1024-bit RSA keys; leave other default limits alone
|
|
SFTPKeyLimits MinimumRSASize 1024
|
|
|
|
# Require at least 256-bit EC keys, and remove other default limits
|
|
SFTPKeyLimits MinimumECSize 256 MinimumDSASize 0 MinimumRSASize 0
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPLog">SFTPLog</a></h3>
|
|
<strong>Syntax:</strong> SFTPLog <em>file|"none"</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPLog</code> directive is used to specify a log file for
|
|
<code>mod_sftp</code>'s reporting on a per-server basis. The <em>file</em>
|
|
parameter given must be the full path to the file to use for logging.
|
|
|
|
<p>
|
|
Note that this path must <b>not</b> be to a world-writable directory and,
|
|
unless <code>AllowLogSymlinks</code> is explicitly set to <em>on</em>
|
|
(generally a bad idea), the path must <b>not</b> be a symbolic link.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPMaxChannels">SFTPMaxChannels</a></h3>
|
|
<strong>Syntax:</strong> SFTPMaxChannels <em>count</em><br>
|
|
<strong>Default:</strong> 10<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPMaxChannels</code> directive is used to configure the maximum
|
|
number of simultaneously open channels permitted for a client. The
|
|
default value is 10.
|
|
|
|
<p>
|
|
A malicious client might try to abuse the server's resources by opening
|
|
an large number of SSH2 channels and then not using them. Most well-behaved
|
|
SSH2 clients only ever open one channel.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPOptions">SFTPOptions</a></h3>
|
|
<strong>Syntax:</strong> SFTPOptions <em>opt1 ...</em><br>
|
|
<strong>Default:</strong> None<br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPOptions</code> directive is used to configure various optional
|
|
behavior of <code>mod_sftp</code>.
|
|
|
|
<p>
|
|
For example:
|
|
<pre>
|
|
SFTPOptions IgnoreSFTPUploadPerms IgnoreSCPUploadPerms PessimisticKexinit
|
|
</pre>
|
|
|
|
<p>
|
|
The currently implemented options are:
|
|
<ul>
|
|
<li><code>AllowInsecureLogin</code><br>
|
|
<p>
|
|
By default, <code>mod_sftp</code> will <b>not</b> allow password or
|
|
keyboard-interactive authentication <b>if</b> either the 'none' cipher
|
|
<b>or</b> MAC/digest is selected. (These must be explicitly allowed via
|
|
<code>SFTPCiphers</code> and <code>SFTPDigests</code> as well.) However,
|
|
some sites may deliberately wish to allow such logins, as for <i>e.g.</i>
|
|
performance testing. To allow such logins/sessions, then, use this option.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.5</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>AllowWeakDH</code><br>
|
|
<p>
|
|
The <code>mod_sftp</code> will not use Diffie-Hellman groups of less
|
|
than 2048 bits, due to <a href="https://www.weakdh.org">weaknesses</a>
|
|
that can downgrade the security of an SSH session. If for any reason
|
|
your SFTP/SCP clients <b>require</b> smaller Diffie-Hellman groups, then
|
|
use this option.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>FIDOTouchRequired</code><br>
|
|
<p>
|
|
When a FIDO security key is used for authentication, <code>mod_sftp</code>
|
|
will require that the signature prove user presence, usually via touching
|
|
the authenticator. A security key which does not prove user presence
|
|
will be rejected. Note that this option only applies to the FIDO
|
|
authenticator algorithms "ecdsa-sk" and "ed25519-sk".
|
|
|
|
<p>
|
|
However, the <code>SFTPAuthorizedHostKeys</code>/
|
|
<code>SFTPAuthorizedUserKeys</code> entries for such FIDO keys
|
|
<em>can</em> indicate that proof of user presence is <b>not</b> required
|
|
for a given key. There are cases where this is useful.
|
|
|
|
<p>
|
|
This option should be used by site administrators who always want to
|
|
require proof of user presence for FIDO keys, <em>regardless</em> of
|
|
any per-key overrides configured elsewhere.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.9rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>FIDOVerifyRequired</code><br>
|
|
<p>
|
|
When a FIDO security key is used for authentication, <code>mod_sftp</code>
|
|
does not require that the signature prove user <em>verification</em>,
|
|
such as via PIN or biometrics. Use this option to require such
|
|
user verification for all security keys; a security key which does not
|
|
prove user verification will be rejected. Note that this option only
|
|
applies to the FIDO authenticator algorithms "ecdsa-sk" and "ed25519-sk".
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.9rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreFIFOs</code>
|
|
<p>
|
|
By default, <code>mod_sftp</code> allows uploading and downloading of FIFOs,
|
|
just as if they were regular files. However, in some cases this can lead
|
|
to "hangs" on the SFTP/SCP client end, especially when the FIFO
|
|
reader/writer processes are not running at the time. Thus to tell
|
|
<code>mod_sftp</code> to ignore/reject requests to read from/write to FIFOs,
|
|
for both SFTP and SCP, use this option.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc3</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSCPUploadPerms</code><br>
|
|
<p>
|
|
When an SCP client uploads a file, the desired permissions on the file
|
|
are sent to the server as part of the upload. (This is different from
|
|
FTP, which does <b>not</b> include the file permissions in an upload.)
|
|
If you need more FTP-like functionality for any reason and wish to
|
|
have <code>mod_sftp</code> silently ignore any permissions sent by the
|
|
SCP client, use this option.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSCPUploadTimes</code><br>
|
|
<p>
|
|
Use this option to have <code>mod_sftp</code> silently ignore any
|
|
timestamps sent by SCP clients as part of the upload.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.5rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPSetExtendedAttributes</code><br>
|
|
<p>
|
|
Use this option to have <code>mod_sftp</code> silently ignore any
|
|
extended attributes sent by SFTP clients via the <code>SETSTAT</code> or
|
|
<code>FSETSTAT</code> SFTP requests.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc3</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPSetOwners</code><br>
|
|
<p>
|
|
Use this option to have <code>mod_sftp</code> silently ignore any
|
|
ownership changes sent by SFTP clients via the <code>SETSTAT</code> or
|
|
<code>FSETSTAT</code> SFTP requests; these are equivalent to
|
|
an FTP <code>SITE CHGRP</code> command.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.5rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPSetPerms</code><br>
|
|
<p>
|
|
Use this option to have <code>mod_sftp</code> silently ignore any
|
|
permissions sent by SFTP clients via the <code>SETSTAT</code> or
|
|
<code>FSETSTAT</code> SFTP requests; these are equivalent to
|
|
an FTP <code>SITE CHMOD</code> command.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.4rc2</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPSetTimes</code><br>
|
|
<p>
|
|
Use this option to have <code>mod_sftp</code> silently ignore any
|
|
timestamps sent by SFTP clients via the <code>SETSTAT</code> or
|
|
<code>FSETSTAT</code> SFTP requests; these are equivalent to
|
|
an FTP <code>SITE UTIMES</code> command.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.4rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPUploadExtendedAttributes</code><br>
|
|
<p>
|
|
When an SFTP client uploads a file or creates a directory, the desired
|
|
extended attributes ("xattrs") on the path are sent to the server as part
|
|
of the upload. (This is different from FTP, which does <b>not</b> include
|
|
the file attributes in an upload.) If you need more FTP-like functionality
|
|
for any reason and wish to have <code>mod_sftp</code> silently ignore any
|
|
extended attributes sent by the SFTP client, use this option.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc3</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IgnoreSFTPUploadPerms</code><br>
|
|
<p>
|
|
When an SFTP client uploads a file or creates a directory, the desired
|
|
permissions on the path are sent to the server as part of the upload.
|
|
(This is different from FTP, which does <b>not</b> include the file
|
|
permissions in an upload.) If you need more FTP-like functionality for any
|
|
reason and wish to have <code>mod_sftp</code> silently ignore any
|
|
permissions sent by the SFTP client, use this option.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>IncludeSFTPTimes</code><br>
|
|
<p>
|
|
Some SFTP clients (<i>e.g.</i> the Rebex SFTP library) do not implement
|
|
SFTP protocol versions 4+ well, and do not <em>request</em> the
|
|
access/modify time attributes but <em>expect/assume</em> that those
|
|
time attributes will be present in the <code>STAT</code> responses.
|
|
Use this option to tell <code>mod_sftp</code> to always include the
|
|
access and modify time attributes in <code>STAT</code> responses for
|
|
clients using SFTP protocol version 4 and higher.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.7rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>InsecureHostKeyPerms</code><br>
|
|
<p>
|
|
When this option is used, <code>mod_sftp</code> will ignore insecure
|
|
permissions (<i>i.e.</i> group- or world-readable) on
|
|
<code>SFTPHostKey</code> files. This option should appear <em>before</em>
|
|
any <code>SFTPHostKey</code> directives in the configuration, as hostkey
|
|
permissions are checked at configuration parse time.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.6rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>MatchKeySubject</code><br>
|
|
<p>
|
|
When this option is used, if public key authentication is used, the
|
|
<code>mod_sftp</code> module will check if the public key has a "Subject"
|
|
header. If so, that the value of that header <b>must</b> match the
|
|
name of the authenticating user/host.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.4rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoExtensionNegotiation</code><br>
|
|
<p>
|
|
By default, <code>mod_sftp</code> will offer/support the SSH extension
|
|
negotiation, defined by
|
|
<a href="https://tools.ietf.org/html/rfc8308">RFC 8308</a>. Use this
|
|
option to disable support for extension negotiations.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.7rc4</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoHostkeyRotation</code><br>
|
|
<p>
|
|
By default, <code>mod_sftp</code> will offer/support the OpenSSH
|
|
hostkey rotation extensions, "hostkeys-00@openssh.com" and
|
|
"hostkeys-prove-00@openssh.com". Use this option to disable support for
|
|
these custom OpenSSH extensions.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.8rc3</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>NoStrictKex</code><br>
|
|
<p>
|
|
By default, <code>mod_sftp</code> will honor/support the OpenSSH
|
|
"strict KEX" mode extension, "kex-strict-c-v00@openssh.com" and
|
|
"kex-strict-s-v00@openssh.com". Use this option to disable support for
|
|
these custom OpenSSH extensions.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.9rc2</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>OldProtocolCompat</code><br>
|
|
<p>
|
|
Older clients identity their protocol versions as "1.99", rather than as
|
|
"2.0". By default, <code>mod_sftp</code> will refuse to handle connections
|
|
from such clients. To enable compatibility with these clients (which
|
|
tend to be derived from ssh.com/Tectia code), use this option.
|
|
|
|
<p>
|
|
Note that this option automatically enables the
|
|
<code>PessimisticKexinit</code> SFTPOption as well.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.4rc1</code>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code>PessimisticKexinit</code><br>
|
|
<p>
|
|
As described <a href="#SFTPTelnetBanner">here</a>, the <code>mod_sftp</code>
|
|
module tries to reduce the connection latency by optimistically sending
|
|
the <code>KEXINIT</code> key exchange message. However, some SSH clients
|
|
cannot handle this behavior. Use this option to disable the optimistic
|
|
sending of the <code>KEXINIT</code> message.
|
|
|
|
<p>
|
|
<b>Note</b> that this option first appeared in
|
|
<code>proftpd-1.3.4rc1</code>.
|
|
</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPPassPhraseProvider">SFTPPassPhraseProvider</a></h3>
|
|
<strong>Syntax:</strong> SFTPPassPhraseProvider <em>path</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config<br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPPassPhraseProvider</code> directive is used to specify an
|
|
external program which will be called, when <code>mod_sftp</code> starts up,
|
|
for each encrypted host key file. The program will be invoked with two
|
|
command-line arguments, passed on <code>stdin</code> to the program:
|
|
<pre>
|
|
<em>servername</em>:<em>portnumber</em> <em>file</em>
|
|
</pre>
|
|
where <code><em>servername</em>:<em>portnumber</em></code> indicates the
|
|
server using that encrypted certificate key, and <em>file</em> indicates the
|
|
host key file in question. The program then must print the corresponding
|
|
passphrase for the key to <code>stdout</code>.
|
|
|
|
<p>
|
|
The intent is that this external program can perform any security checks
|
|
necessary, to make sure that the system is not compromised by an attacker,
|
|
and only when these checks pass successfully will the passphrase be provided.
|
|
These security checks, and the way the passphrase is determined, can be as
|
|
complex as you like.
|
|
|
|
<p>
|
|
Example:
|
|
<pre>
|
|
SFTPPassPhraseProvider /etc/ftpd/sftp/get-passphrase
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPRekey">SFTPRekey</a></h3>
|
|
<strong>Syntax:</strong> SFTPRekey <em>"none"|"required" [[interval bytes] timeout]</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPRekey</code> directive configures the session rekey policy
|
|
used by the <code>mod_sftp</code> module. When an SSH2 client connects,
|
|
there is an initial exchange of hostkey, cipher, digest, and compression
|
|
algorithms, followed by sharing of information which leads to the calculation
|
|
of shared session keys. These keys are used in the various algorithms.
|
|
The exchange of algorithms and calculation of new session keys can happen
|
|
at any time during the SSH2 session; this is known as "rekeying".
|
|
|
|
<p>
|
|
By default, <code>mod_sftp</code> will only <b>require</b> rekeying when
|
|
the packet sequence number (for sent <i>or</i> received SSH2 packets) reaches
|
|
a rather high limit. The digest algorithm used, for example, might begin
|
|
to leak cryptographically sensitive information if used for too many
|
|
packets (see RFC 4344). Outside of these sequence number limits, however,
|
|
<code>mod_sftp</code> will not attempt to initiate rekeying.
|
|
|
|
<p>
|
|
To prevent <code>mod_sftp</code> from attempting rekeying, use:
|
|
<pre>
|
|
SFTPRekey none
|
|
</pre>
|
|
Note that disabling rekeying altogether is a Very Bad Idea. While rekeying
|
|
can cause delays in the SSH2 session, it is intended to guard against certain
|
|
attacks. You should therefore <b>only</b> disable rekeying for certain
|
|
SSH2 clients which cannot support rekeying. Please report those clients
|
|
(<b>including</b> the client version) to the mod_sftp maintainer, so that that
|
|
client can be added to the list of known clients which cannot handle rekeying.
|
|
|
|
<p>
|
|
To require rekeying, simply use:
|
|
<pre>
|
|
SFTPRekey required
|
|
</pre>
|
|
With this parameter, <code>mod_sftp</code> will default to requiring a rekey
|
|
within 1 hour (3600 seconds) or after 2GB of data sent <i>or</i> received,
|
|
whichever happens first. There will be no timeout once a rekeying has been
|
|
requested.
|
|
|
|
<p>
|
|
However, administrators wishing to use different rekey intervals or rekey
|
|
byte limits can use the optional <em>interval</em> (in seconds) and
|
|
<em>bytes</em> (in MB) parameters, <i>e.g.</i>:
|
|
<pre>
|
|
# Require rekeying after 30 minutes, or 4 GB
|
|
SFTPRekey required 1800 4096
|
|
</pre>
|
|
|
|
<p>
|
|
Finally, the paranoid administrator may wish to set a timeout, in seconds,
|
|
in which a client <b>must</b> complete a session rekeying, otherwise the
|
|
client will be disconnected. This would look like:
|
|
<pre>
|
|
# Require rekeying after 30 minutes, or 4 GB. If the rekeying is not
|
|
# completed within 5 minutes of a rekey request, disconnect the client.
|
|
SFTPRekey required 1800 4096 300
|
|
</pre>
|
|
Note that normally such rekey timeouts are not necessary.
|
|
|
|
<p>
|
|
<hr>
|
|
<h3><a name="SFTPTrafficPolicy">SFTPTrafficPolicy</a></h3>
|
|
<strong>Syntax:</strong> SFTPTrafficPolicy <em>policy</em><br>
|
|
<strong>Default:</strong> <em>None</em><br>
|
|
<strong>Context:</strong> server config, <code><VirtualHost></code>, <code><Global></code><br>
|
|
<strong>Module:</strong> mod_sftp<br>
|
|
<strong>Compatibility:</strong> 1.3.2rc2 and later
|
|
|
|
<p>
|
|
The <code>SFTPTrafficPolicy</code> directive is used to configure a measure
|
|
of protection against traffic analysis attacks. Such attacks use the number
|
|
of packets sent, the size of the packets, and the timing of the packets to try
|
|
to gain information about the nature of the data being transmitted.
|
|
|
|
<p>
|
|
The SSH2 protocol includes a particular message, <code>SSH_MSG_IGNORE</code>,
|
|
which all implementations (both clients and servers) must handle by
|
|
dropping on the floor. Implementations, like <code>mod_sftp</code>, can
|
|
use these messages to add random data to the session in the hopes of making
|
|
such traffic analyses more difficult.
|
|
|
|
<p>
|
|
The <code>SFTPTrafficPolicy</code> directive supports the following range
|
|
of policies; the chances columns list the probability that
|
|
<code>mod_sftp</code> will send an <code>SSH_MSG_IGNORE</code> message.
|
|
|
|
<p>
|
|
<table border=1 summary="SFTP Traffic Policies">
|
|
<tr>
|
|
<td><b>Policy Name</b></td>
|
|
<td><b>Chances</b></td>
|
|
<td><b>Checks</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"none"</td>
|
|
<td>Never</td>
|
|
<td>Never</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"low"</td>
|
|
<td>1 in 1000</td>
|
|
<td>Every 5 seconds</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"medium"</td>
|
|
<td>1 in 100</td>
|
|
<td>Every 5 seconds</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"high"</td>
|
|
<td>1 in 10</td>
|
|
<td>Every second</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td>"paranoid"</td>
|
|
<td>Always</td>
|
|
<td>Every second</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>
|
|
The default <code>SFTPTrafficPolicy</code> setting is "none".
|
|
|
|
<p>
|
|
<b>However</b>, <i>if</i> a client negotiates the use of a CBC cipher, then a
|
|
defensive traffic policy will <b>automatically</b> be used.
|
|
<a href="http://www.faqs.org/rfcs/rfc4251.html">RFC 4251</a>, Section 9.3.1,
|
|
specifically mentions the insertion of <code>SSH_MSG_IGNORE</code> messages as
|
|
a way of mitigating the "Rogaway" attack on CBC ciphers. In order to disable
|
|
this automatic mitigation behavior, you must <i>explicitly</i> configure
|
|
a <code>SFTPTrafficPolicy</code> setting in your configuration, <i>e.g.</i>
|
|
<pre>
|
|
# Disable any automatic protection when CBC ciphers are used
|
|
SFTPTrafficPolicy none
|
|
</pre>
|
|
<b>Note that this is not recommended</b>!
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Installation">Installation</a></h2>
|
|
The <code>mod_sftp</code> module is distributed with ProFTPD. For including
|
|
<code>mod_sftp</code> as a statically linked module, use:
|
|
<pre>
|
|
$ ./configure --enable-openssl --with-modules=mod_sftp ...
|
|
</pre>
|
|
Alternatively, <code>mod_sftp</code> can be built as a DSO module:
|
|
<pre>
|
|
$ ./configure --enable-dso --enable-openssl --with-shared=mod_sftp ...
|
|
</pre>
|
|
Then follow the usual steps:
|
|
<pre>
|
|
$ make
|
|
$ make install
|
|
</pre>
|
|
<b>Note</b> that if the <code>libsodium</code> library is available,
|
|
<code>mod_sftp</code> will auto-detect this, which enables other supported
|
|
algorithms. You can ensure that <code>mod_sftp</code> compiles with the
|
|
<code>libsodium</code> library like so:
|
|
<pre>
|
|
$ ./configure --enable-openssl --with-modules=mod_sftp ... \
|
|
--with-includes=/path/to/libsodium/include \
|
|
--with-libraries=/path/to/libsodium/lib
|
|
</pre>
|
|
|
|
<p>
|
|
<hr>
|
|
<h2><a name="Usage">Usage</a></h2>
|
|
<p>
|
|
|
|
<p>
|
|
<b>Access Controls for SFTP Requests</b><br>
|
|
Some of the requests supported by SFTP have FTP command equivalents. Other
|
|
requests in SFTP have no FTP command equivalent. This makes the use of
|
|
<code><Limit></code> sections for access controls in <code>mod_sftp</code>
|
|
a little interesting.
|
|
|
|
<p>
|
|
First, the familiar territory. The following shows the
|
|
<code><Limit></code> sections for FTP commands (just as for normal FTP
|
|
sessions) which are honored by <code>mod_sftp</code>:
|
|
<ul>
|
|
<li><code><Limit DELE></code><br>
|
|
Applies to the <code>REMOVE</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit MKD XMKD></code><br>
|
|
Applies to the <code>MKDIR</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit MLSD></code><br>
|
|
Applies to the <code>OPENDIR</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit LIST NLST></code><br>
|
|
Applies to the <code>READDIR</code> SFTP request, resulting in an
|
|
<em>empty directory listing</em>.
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit RETR></code><br>
|
|
Applies to the <code>READ</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit RNFR RNTO></code><br>
|
|
Applies to the <code>RENAME</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit RMD XRMD></code><br>
|
|
Applies to the <code>RMDIR</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit STOR></code><br>
|
|
Applies to the <code>WRITE</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit SITE_CHGRP></code><br>
|
|
Applies to the <code>SETSTAT</code> and <code>FSETSTAT</code> SFTP
|
|
requests when they change file ownership
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit SITE_CHMOD></code><br>
|
|
Applies to the <code>SETSTAT</code> and <code>FSETSTAT</code> SFTP
|
|
requests when they change file permissions
|
|
</li>
|
|
</ul>
|
|
Thus you can see that <code>mod_sftp</code> will reuse much of your existing
|
|
<code><Limit></code>-based access controls for SFTP sessions.
|
|
|
|
<p>
|
|
For those SFTP requests which have no direct FTP equivalents elsewhere in
|
|
<code>proftpd</code>, the <code>mod_sftp</code> module supports some
|
|
slightly different <code><Limit></code> sections. <b>Note</b> that
|
|
the following does <b>not</b> apply to FTP sessions, nor does it imply
|
|
that FTP supports these commands:
|
|
<ul>
|
|
<li><code><Limit FSTAT></code><br>
|
|
Applies to the <code>FSTAT</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit LSTAT></code><br>
|
|
Applies to the <code>LSTAT</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit LOCK></code><br>
|
|
Applies to the <code>LOCK</code> and <code>UNLOCK</code> SFTP requests
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit OPEN></code><br>
|
|
Applies to the <code>OPEN</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit READLINK></code><br>
|
|
Applies to the <code>READLINK</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit SETSTAT></code><br>
|
|
Applies to the <code>FSETSTAT</code> and <code>SETSTAT</code> SFTP requests
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit STAT></code><br>
|
|
Applies to the <code>STAT</code> SFTP request
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit SYMLINK></code><br>
|
|
Applies to the <code>LINK</code> and <code>SYMLINK</code> SFTP requests
|
|
</li>
|
|
</ul>
|
|
Not all versions of SFTP support all of these requests; the <code>LOCK</code>
|
|
and <code>UNLOCK</code> requests, for example, appear only in later versions
|
|
of the SFTP protocol.
|
|
|
|
<p>
|
|
What about the <code>READ</code> and <code>WRITE</code> command groups?
|
|
<ul>
|
|
<li><code><Limit READ></code><br>
|
|
Applies to the <code>SYMLINK</code> and <code>READ</code> SFTP requests
|
|
</li>
|
|
|
|
<p>
|
|
<li><code><Limit WRITE></code><br>
|
|
Applies to the <code>LOCK</code>, <code>SETSTAT</code>,
|
|
<code>SYMLINK</code>, and <code>WRITE</code> SFTP requests
|
|
</li>
|
|
</ul>
|
|
|
|
<p><a name="ExtendedLogClasses">
|
|
Here is table of the supported <a href="../modules/mod_log.html#ExtendedLog"><code>ExtendedLog</code></a> directive <em>command classes</em> for SFTP sessions:
|
|
<p>
|
|
<table border=1 summary="Command Classes">
|
|
<tr>
|
|
<td><b>Command Class</b></td>
|
|
<td><b>SSH, SFTP Requests</b></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>ALL</code></td>
|
|
<td>All requests <i>except</i> the <code>EXIT</code> pseudo-command (<i>default</i>)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>NONE</code></td>
|
|
<td>No requests</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>AUTH</code></td>
|
|
<td>Authentication requests: <code>USERAUTH_REQUEST</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>INFO</code></td>
|
|
<td>Informational commands: <code>EXT_INFO</code>
|
|
(SSH extension negotiation), <code>REALPATH</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>DIRS</code></td>
|
|
<td>Directory commands: <code>MKDIR</code>, <code>OPENDIR</code>,
|
|
<code>READDIR</code>, <code>REALPATH</code>, <code>RMDIR</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>READ</code></td>
|
|
<td>File reading: <code>CLOSE</code>, <code>FSTAT</code>,
|
|
<code>LSTAT</code>, <code>OPEN</code>, <code>READ</code>,
|
|
<code>READLINK</code>, <code>STAT</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>WRITE</code></td>
|
|
<td>File/directory writing or creation: <code>CLOSE</code>,
|
|
<code>FSETSTAT</code>, <code>LINK</code>, <code>LOCK</code>,
|
|
<code>MKDIR</code>, <code>OPEN</code>, <code>REMOVE</code>,
|
|
<code>RENAME</code>, <code>RMDIR</code>, <code>SETSTAT</code>,
|
|
<code>SYMLINK</code>, <code>WRITE</code>, <code>UNLOCK</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>MISC</code></td>
|
|
<td>Miscellaneous commands: <code>EXTENDED</code>, <code>FSYNC</code>,
|
|
<code>HARDLINK</code>, <code>HOMEDIR</code>, <code>INIT</code>,
|
|
<code>RENAME</code>, <code>SERVICE_REQUEST</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>SEC</code></td>
|
|
<td>SSH security requests: <code>DH_GEX_INIT</code>,
|
|
<code>DH_GEX_REQUEST</code>, <code>DH_INIT</code>, <code>ECDH_INIT</code>,
|
|
<code>KEXINIT</code>, <code>KEXRSA_SECRET</code>,
|
|
<code>NEWKEYS</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>SSH</code></td>
|
|
<td>SSH protocol requests: <code>CHANNEL_CLOSE</code>,
|
|
<code>CHANNEL_EOF</code>, <code>CHANNEL_OPEN</code>,
|
|
<code>CHANNEL_REQUEST</code>, <code>CHANNEL_WINDOW_ADJUST</code>,
|
|
<code>DH_GEX_INIT</code>, <code>DH_GEX_REQUEST</code>,
|
|
<code>DH_INIT</code>, <code>ECDH_INIT</code>, <code>EXT_INFO</code>,
|
|
<code>KEXINIT</code>, <code>KEXRSA_SECRET</code>, <code>NEWKEYS</code>,
|
|
<code>SERVICE_REQUEST</code>, <code>USERAUTH_REQUEST</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>SFTP</code></td>
|
|
<td>SFTP protocol requests: <code>CLOSE</code>, <code>EXTENDED</code>,
|
|
<code>FSETSTAT</code>, <code>FSTAT</code>, <code>FSYNC</code>,
|
|
<code>HARDLINK</code>, <code>HOMEDIR</code>, <code>INIT</code>,
|
|
<code>LINK</code>, <code>LOCK</code>, <code>LSTAT</code>,
|
|
<code>MKDIR</code>, <code>OPEN</code>, <code>OPENDIR</code>,
|
|
<code>READ</code>, <code>READDIR</code>, <code>READLINK</code>,
|
|
<code>REALPATH</code>, <code>REMOVE</code>, <code>RENAME</code>,
|
|
<code>RMDIR</code>, <code>SETSTAT</code>, <code>STAT</code>,
|
|
<code>SYMLINK</code>, <code>WRITE</code>, <code>UNLOCK</code></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td><code>EXIT</code></td>
|
|
<td>Logs the configured <code>LogFormat</code> at session exit.<br>
|
|
<b>NOTE</b>: <code>EXIT</code> is <b>not</b> part of the
|
|
<code>ALL</code> command class, in order to preserve
|
|
backward-compatible <code>ALL</code> behavior.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><a name="EnvironmentVariables">
|
|
<b>Environment Variables</b><br>
|
|
The <code>mod_sftp</code> module will set the following environment
|
|
variables whenever an SSH2 client connects:
|
|
<ul>
|
|
<li><code>SFTP</code>
|
|
<li><code>SFTP_LIBRARY_VERSION</code>
|
|
<li><code>SSH_CONNECTION</code>
|
|
</ul>
|
|
In addition, the following environment variables will be set (with appropriate
|
|
values), once the client has successfully exchanged keys with
|
|
<code>mod_sftp</code>:
|
|
<ul>
|
|
<li><code>SFTP_CLIENT_BANNER</code>
|
|
<li><code>SFTP_CLIENT_CIPHER_ALGO</code>
|
|
<li><code>SFTP_CLIENT_COMPRESSION_ALGO</code>
|
|
<li><code>SFTP_CLIENT_MAC_ALGO</code>
|
|
<li><code>SFTP_KEX_ALGO</code>
|
|
<li><code>SFTP_HOST_KEY_ALGO</code>
|
|
<li><code>SFTP_SERVER_CIPHER_ALGO</code>
|
|
<li><code>SFTP_SERVER_COMPRESSION_ALGO</code>
|
|
<li><code>SFTP_SERVER_MAC_ALGO</code>
|
|
</ul>
|
|
When a client attempts to use publickey authentication, the following variables
|
|
<i>may</i> be set:
|
|
<ul>
|
|
<li><code>SFTP_USER_AUTH_METHOD</code>
|
|
<li><code>SFTP_USER_PUBLICKEY_ALGO</code>
|
|
<li><code>SFTP_USER_PUBLICKEY_FINGERPRINT</code>
|
|
<li><code>SFTP_USER_PUBLICKEY_FINGERPRINT_ALGO</code>
|
|
</ul>
|
|
<b>Note</b> that the above variables may be present even if the user was
|
|
authenticated by a mechanism <i>other than publickey authentication</i>. This
|
|
is intentional; the logs may be used to help troubleshoot <i>failed</i>
|
|
authentication attempts, as well as successful authentications.
|
|
|
|
<p>
|
|
These values are also available in the <code>session.notes</code> table,
|
|
under keys of the names above. These note variables are intended for
|
|
informational purposes, <i>e.g.</i> <code>ExtendedLog</code> or
|
|
<code>SQLLog</code> directives via the <code>%{note:...}</code> syntax.
|
|
|
|
<p><a name="UsageRFC4716Format">
|
|
<b>SSH2 Public Key Formats</b><br>
|
|
SSH2 uses public keys for authentication and message protection. The very
|
|
popular OpenSSH server uses a particular file format for storing public
|
|
keys in files. However, that format is not portable; it uses a format very
|
|
specific to OpenSSH. Thus the <code>mod_sftp</code> module uses a different
|
|
format for public keys, specifically, the format specified in
|
|
<a href="http://www.faqs.org/rfcs/rfc4716.html">RFC 4716</a>. The hope
|
|
is that this format is more interoperable with other SSH2/SFTP implementations.
|
|
|
|
<p>
|
|
This means that if you wish to use your OpenSSH public keys with the
|
|
<code>mod_sftp</code> module, you will need to convert them from OpenSSH's
|
|
format to the RFC4716 format. Fortunately, this is supported by
|
|
OpenSSH's <code>ssh-keygen</code> utility, <i>e.g.</i>:
|
|
<pre>
|
|
$ ssh-keygen -e -f ~/.ssh/id_rsa.pub -m RFC4716
|
|
</pre>
|
|
The output from this command can be added to the
|
|
<code>SFTPAuthorizedUserKeys</code> used by <code>mod_sftp</code>.
|
|
|
|
<p>
|
|
Now that <code>mod_sftp</code> supports FIDO security keys, it is possible
|
|
to configure policy requirements for a given key, using the RFC4716 format.
|
|
For example, you might generate a FIDO security key using OpenSSH that does
|
|
not require touching the authenticator, using <i>e.g.</i>:
|
|
<pre>
|
|
$ ssh-keygen -t edcsa-sk -O no-touch-required -f ./id_ecdsa_sk
|
|
</pre>
|
|
You then export that public key to the RFC 4716 format, for use by
|
|
<code>mod_sftp</code>:
|
|
<pre>
|
|
$ ssh-keygen -e -f ./id_ecdsa_sk.pub -m RFC4716
|
|
---- BEGIN SSH2 PUBLIC KEY ----
|
|
Comment: "256-bit ECDSA-SK, converted by ... from OpenSSH"
|
|
AAAAInNrLWVjZHNhLXNoYTItbmlzdHAyNTZAb3BlbnNzaC5jb20AAAAIbmlzdHAyNTYAAA
|
|
...
|
|
---- END SSH2 PUBLIC KEY ----
|
|
</pre>
|
|
Now you can manually add more headers, underneath <code>Comment:</code>,
|
|
to indicate whether this key requires proof of user presence ("touch required"),
|
|
and/or proof of user verification ("verify required"). How? Using the
|
|
custom <code>X-FIDO-Touch-Required</code> and
|
|
<code>X-FIDO-Verify-Required</code> headers supported by <code>mod_sftp</code>:
|
|
</pre>
|
|
---- BEGIN SSH2 PUBLIC KEY ----
|
|
Comment: "256-bit ECDSA-SK, converted by ... from OpenSSH"
|
|
x-fido-touch-required: false
|
|
AAAAInNrLWVjZHNhLXNoYTItbmlzdHAyNTZAb3BlbnNzaC5jb20AAAAIbmlzdHAyNTYAAA
|
|
...
|
|
---- END SSH2 PUBLIC KEY ----
|
|
</pre>
|
|
The values for these headers are expected to be Boolean values.
|
|
|
|
<p>
|
|
These <code>X-FIDO-Touch-Required</code>, <code>X-FIDO-Verify-Required</code>
|
|
headers are handled in a case-insensitive manner, per RFC. These headers are
|
|
only applied to keys that use the FIDO authenticator algorithms "ecdsa-sk" and
|
|
"ed25519-sk", and are ignored for other keys.
|
|
|
|
<p>
|
|
<b>Note</b> that the RFC4716 format is <b>not</b> to be used with the
|
|
<code>SFTPHostKey</code> directive. Even though OpenSSH's host keys have
|
|
".pub" public equivalents, host keys are different from the per-user keys
|
|
that are used for authentication.
|
|
|
|
<p><a name="ClientIssues"></a>
|
|
<b>Known Client Issues</b><br>
|
|
The following lists some of the various client interoperability issues that
|
|
have been encountered, and how to address them.
|
|
|
|
<p>
|
|
<i>SSH Channel Window Sizes</i><br>
|
|
Some SFTP client implementations do not support the large SSH channel window
|
|
size that the <code>mod_sftp</code> module uses by default. These clients
|
|
include:
|
|
<ul>
|
|
<li><a href="http://www.ipswitch.com/WS_FTP">WS_FTP Pro</a>
|
|
<li>OpenSSH 3.0 and older
|
|
<li><a href="http://www.axway.com">Axway</a>
|
|
</ul>
|
|
This <a href="#SFTPBadWindowSize">FAQ</a> describes the configuration to use
|
|
for such clients.
|
|
|
|
<p>
|
|
<i>SSH Protocol Version</i><br>
|
|
If you are using an old ssh.com client, or perhaps a client which derives
|
|
from the ssh.com (or Tectia) code, you may see the following error in the
|
|
<code>SFTPLog</code> when trying to connect to <code>mod_sftp</code>:
|
|
<pre>
|
|
Bad protocol version 'SSH-1.99-3.2.9.1 SSH Secure Shell (non-commercial)' from <i>x.x.x.x</i>
|
|
</pre>
|
|
To support such clients in <code>mod_sftp</code>, use
|
|
<a href="#SFTPOptions"><code>SFTPOptions</code></a> to enable compatibility with
|
|
older protocol versions, <i>e.g.</i>:
|
|
<pre>
|
|
<font color=green># Support old ssh.com/Tectia clients</font>
|
|
SFTPOptions OldProtocolCompat
|
|
</pre>
|
|
|
|
<p>
|
|
<i>SFTP Protocol Versions</i><br>
|
|
Some SFTP clients do not properly handle some of the newer SFTP protocol
|
|
versions. These clients include:
|
|
<ul>
|
|
<li><a href="http://winscp.net/">WinSCP</a>
|
|
<li><a href="http://www.cuteftp.com/products/ftp_clients.aspx">CuteFTP</a>
|
|
</ul>
|
|
For these clients, use a
|
|
<a href="#SFTPClientMatch"><code>SFTPClientMatch</code></a> rule to restrict
|
|
the SFTP protocol versions offered by the <code>mod_sftp</code> module,
|
|
<i>e.g.</i>:
|
|
<pre>
|
|
<font color=green># Only support SFTP protocol version 1 through 3 for WinSCP and CuteFTP</font>
|
|
SFTPClientMatch WinSCP|ClientSftp sftpProtocolVersion 1-3
|
|
</pre>
|
|
|
|
<p>
|
|
<i><code>KEXINIT</code> Optimization</i><br>
|
|
Some SFTP clients do not like this
|
|
<a href="#SFTPTelnetBanner">KEXINIT optimization</a> that the
|
|
<code>mod_sftp</code> module uses. These clients include:
|
|
<ul>
|
|
<li><code>Net::SSH::Perl</code>, <code>Net::SFTP</code> Perl modules
|
|
<li><a href="http://www.enterprisedt.com/products/edtftpj/">edtFTPj</a>
|
|
</ul>
|
|
For these clients, use this configuration to disable the optimization:
|
|
<pre>
|
|
<font color=green># Disable the KEXINIT optimization at the cost of latency</font>
|
|
SFTPOptions PessimisticKexinit
|
|
</pre>
|
|
|
|
<p>
|
|
<i>Cipher Implementations</i><br>
|
|
Some SFTP clients (most notably the SecureBlackBox libraries) do not implement
|
|
the <code>blowfish-ctr</code> cipher correctly. If your site needs to
|
|
support such clients, then you will need to use the
|
|
<a href="#SFTPCiphers"><code>SFTPCiphers</code></a> directive to configure
|
|
a list of ciphers which does <b>not</b> include <code>blowfish-ctr</code>.
|
|
Clients with this bug will show up in the <code>SFTPLog</code> with this
|
|
log message:
|
|
<pre>
|
|
client sent buggy/malicious packet payload length, ignoring
|
|
</pre>
|
|
<b>However</b>, this log message can also be caused by other factors. It
|
|
is the combination of this error message, <b>and</b> the negotiation of
|
|
the <code>blowfish-ctr</code> cipher, that indicates the use of these
|
|
buggy clients.
|
|
|
|
<p><a name="ClientMatches"></a>
|
|
<b>Recommended <code>SFTPClientMatch</code> Settings</b><br>
|
|
Based on the above client issues, the following is the recommended list of
|
|
configurations -- contributed by the <a href="https://forums.proftpd.org/smf/index.php/topic,4616.0/all.html">ProFTPD community</a> -- to use as workarounds
|
|
for all of the clients' known issues:
|
|
<pre>
|
|
<IfModule mod_sftp.c>
|
|
<Global>
|
|
# The default values used by mod_sftp are:
|
|
# channelPacketSize 32KB
|
|
# channelWindowSize 4GB
|
|
# sftpProtocolVersion 1-6
|
|
|
|
# Axway (SSH-2.0-XFB.Gateway Unix)
|
|
SFTPClientMatch .*Axway channelWindowSize 1GB
|
|
SFTPClientMatch ".*XFB.*" channelWindowSize 1GB
|
|
|
|
# CoreFTP LE (free version 2.2)
|
|
SFTPClientMatch CoreFTP channelWindowSize 1GB
|
|
|
|
# CuteFTPPro8
|
|
SFTPClientMatch ".*ClientSftp" sftpProtocolVersion 3
|
|
|
|
# Network Automation (SSH-2.0-EldoS.SSHBlackbox.3)
|
|
# http://www.networkautomation.com/
|
|
SFTPClientMatch ".*EldoS.SSHBlackbox.3.*" channelWindowSize 1GB sftpProtocolVersion 3
|
|
|
|
# GlobalScape FTP application (SSH2 client 'GSSFTP1.0') - (needs v2)
|
|
# http://www.globalscape.com/downloads/
|
|
# GoAnywhere (SSH-2.0-1.0)
|
|
# http://www.goanywheremft.com/products
|
|
SFTPClientMatch "1.0" channelWindowSize 1GB sftpProtocolVersion 2
|
|
|
|
# JaSFtp (SSH-2.0-J2SSH_Maverick_1.2.10_Sterling Commerce)
|
|
# http://www.hiteksoftware.com/jasf/
|
|
SFTPClientMatch ".*J2SSH_Maverick.*" channelWindowSize 1GB
|
|
|
|
# JSch - Java Secure Channel (SSH-2.0-JSCH-0.1.39)
|
|
# http://www.jcraft.com/jsch/
|
|
SFTPClientMatch "JSCH.*" channelWindowSize 1GB
|
|
|
|
# Robo-FTP (SSH-2.0-WeOnlyDo)
|
|
# http://www.robo-ftp.com/
|
|
SFTPClientMatch ".*WeOnlyDo.*" channelWindowSize 1GB sftpProtocolVersion 3
|
|
|
|
# SecureBlackbox (SSH-2.0-SecureBlackbox.7)
|
|
# http://www.eldos.com/sbb/download-release.php
|
|
SFTPClientMatch ".*SecureBlackbox.*" sftpProtocolVersion 3
|
|
|
|
# SecureFX - SSH2 client 'SecureFX_2_2_5_225 SecureFX'
|
|
# http://www.vandyke.com/products/securefx/
|
|
SFTPClientMatch "SecureFX.*" sftpProtocolVersion 3
|
|
|
|
# SSH-2.0-1.30
|
|
SFTPClientMatch "1.30" channelPacketSize 16KB channelWindowSize 256MB
|
|
|
|
# SSH-2.0-Sun_SSH_1.0.1
|
|
SFTPClientMatch ".*Sun_SSH.*" channelWindowSize 1GB
|
|
|
|
# SSH-2.0-SharpSSH-1.1.1.13-JSCH-0.1.28
|
|
SFTPClientMatch ".*SharpSSH.*" channelWindowSize 256MB
|
|
|
|
# WinSCP
|
|
SFTPClientMatch ".*WinSCP.*" sftpProtocolVersion 3
|
|
|
|
# WS_FTP
|
|
SFTPClientMatch ".*WS_FTP.*" channelWindowSize 1GB
|
|
|
|
# /n Software BizTalk SFTP Receive (SSH-2.0-IP*Works! SSH Client v8.0)
|
|
# http://www.nsoftware.com/products/biztalk/adapters/sftp.aspx
|
|
SFTPClientMatch ".*IP.Works.*" channelWindowSize 1GB
|
|
</Global>
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<p>
|
|
<b>FIPS Compliance</b><br>
|
|
FIPS stands for "Federal Information Processing Standard", and refers to
|
|
a series of information processing standards issued and used by the US
|
|
government. When speaking of FIPS and cryptographic software, the pertinent
|
|
standard in particular is
|
|
<a href="http://en.wikipedia.org/wiki/FIPS_140">FIPS-140</a>.
|
|
|
|
<p>
|
|
How then would you build OpenSSL and <code>mod_sftp</code>, and use them
|
|
such that <code>mod_sftp</code> would be FIPS-compliant? Using OpenSSL in
|
|
FIPS mode requires quite a few steps. First, you would configure
|
|
<code>proftpd</code> to use the <code>mod_sftp</code> module as normal,
|
|
assuming your OpenSSL installation has been compiled with FIPS support:
|
|
<pre>
|
|
./configure --enable-openssl --with-modules=mod_sftp ...
|
|
</pre>
|
|
|
|
<p>
|
|
Compiling <code>proftpd</code> requires the following, for FIPS support
|
|
to work properly:
|
|
<pre>
|
|
make CC=<em>/path/to/openssl/bin/</em>fipsld FIPSLD_CC=<em>gcc</em>
|
|
</pre>
|
|
The <code>FIPSLD_CC</code> variable should point to your normal C compiler,
|
|
<i>e.g.</i> <code>gcc</code>. The use of this <code>fipsld</code> program
|
|
is <b>mandatory</b>. The FIPS standard requires that the linking process
|
|
happen a very specific way, involving verification of calculated and expected
|
|
checksums of compiled code, <i>etc</i>. The OpenSSL packages with FIPS
|
|
support supply this <code>fipsld</code> program which will link the compiled
|
|
code according to the FIPS specifications. <i>If you do not use
|
|
<code>fipsld</code>, then attempts to use OpenSSL in FIPS mode will fail.</i>
|
|
For example, you would see the following if starting a <code>proftpd</code>
|
|
daemon which has not been linked using <code>fipsld</code> while requesting
|
|
use of FIPS:
|
|
<pre>
|
|
- mod_sftp/0.0: unable to use FIPS mode: (unknown)
|
|
- Fatal: unable to load module 'mod_sftp.c': Operation not permitted
|
|
</pre>
|
|
|
|
<p>
|
|
Now, assuming you have compiled and installed your <code>proftpd</code>
|
|
properly, <i>e.g.</i>:
|
|
<pre>
|
|
make CC=<em>/path/to/openssl/bin/</em>fipsld FIPSLD_CC=<em>gcc</em>
|
|
make CC=<em>/path/to/openssl/bin/</em>fipsld FIPSLD_CC=<em>gcc</em> install
|
|
</pre>
|
|
you will now be ready to start <code>proftpd</code>.
|
|
|
|
<p>
|
|
In order for FIPS mode to be effective, OpenSSL must be told to run in FIPS
|
|
mode from the very beginning. The <code>mod_sftp</code> module initializes the
|
|
OpenSSL library when the <code>mod_sftp</code> module is loaded, <i>before the
|
|
<code>proftpd.conf</code> file is parsed</i>. Thus the requesting of FIPS mode
|
|
<b>cannot</b> be done via a setting in <code>proftpd.conf</code>. (Annoying,
|
|
I know.)
|
|
|
|
<p>
|
|
Instead, you must use the -D command-line parameter when starting
|
|
<code>proftpd</code> (see the docs for the <code><IfDefine></code> and
|
|
<code>Define</code> directives) to define a specific variable, which the
|
|
<code>mod_sftp</code> module will look for. Specifically, you will need to
|
|
start <code>proftpd</code> like thus:
|
|
<pre>
|
|
/path/to/proftpd -DSFTP_USE_FIPS ...
|
|
</pre>
|
|
This will define the <code>SFTP_USE_FIPS</code> variable; this tells
|
|
<code>mod_sftp</code> to initialize OpenSSL using FIPS mode. When this works,
|
|
you will see the following when <code>proftpd</code> starts up:
|
|
<pre>
|
|
- mod_sftp/0.0: FIPS mode enabled
|
|
</pre>
|
|
|
|
<p>
|
|
When <code>mod_sftp</code> detects that OpenSSL has been configured for FIPS
|
|
mode, it will refuse to advertise support for the following cipher algorithms:
|
|
<ul>
|
|
<li><code>arcfour128</code>
|
|
<li><code>arcfour256</code>
|
|
<li><code>blowfish-cbc</code>
|
|
<li><code>blowfish-ctr</code>
|
|
<li><code>cast128-cbc</code>
|
|
</ul>
|
|
and for the following digest algorithms:
|
|
<ul>
|
|
<li><code>hmac-md5</code>
|
|
<li><code>hmac-md5-96</code>
|
|
<li><code>hmac-ripemd160</code>
|
|
</ul>
|
|
as these algorithms are not compliant with the FIPS specification.
|
|
|
|
<p>
|
|
For additional reading on OpenSSL and FIPS, see:
|
|
<pre>
|
|
<a href="http://www.openssl.org/docs/fips/SecurityPolicy-1.1.1.pdf">http://www.openssl.org/docs/fips/SecurityPolicy-1.1.1.pdf</a>
|
|
<a href="http://www.openssl.org/docs/fips/UserGuide-1.1.1.pdf">http://www.openssl.org/docs/fips/UserGuide-1.1.1.pdf</a>
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Example Configuration</b><br>
|
|
When using <code>mod_sftp</code> to handle SFTP connections, you will want
|
|
to create a separate <code><VirtualHost></code> section for the
|
|
<code>mod_sftp</code> configuration. SSH2 (and thus SFTP) requires a different
|
|
port than FTP; in order to listen on different ports, <code>proftpd</code>
|
|
requires different <code><VirtualHost></code> sections. You can have
|
|
multiple <code><VirtualHost></code> sections for the same <i>address</i>
|
|
(IP address or DNS name), just different <code>Port</code> directives.
|
|
<pre>
|
|
<IfModule mod_sftp.c>
|
|
<VirtualHost <i>a.b.c.d</i>>
|
|
SFTPEngine on
|
|
SFTPLog /etc/proftpd/sftp/sftp.log
|
|
|
|
# Configure the server to listen on the normal SSH2 port, port 22
|
|
Port 22
|
|
|
|
# Configure the RSA, DSA, and ECDSA host keys, using the same host key
|
|
# files that OpenSSH uses.
|
|
SFTPHostKey /etc/ssh_host_rsa_key
|
|
SFTPHostKey /etc/ssh_host_dsa_key
|
|
SFTPHostKey /etc/ssh_host_ecdsa_key
|
|
|
|
# Configure the file used for comparing authorized public keys of users.
|
|
SFTPAuthorizedUserKeys file:~/.sftp/authorized_keys
|
|
|
|
# Enable compression
|
|
SFTPCompression delayed
|
|
|
|
# Allow the same number of authentication attempts as OpenSSH.
|
|
#
|
|
# It is recommended that you explicitly configure MaxLoginAttempts
|
|
# for your SSH2/SFTP instance to be higher than the normal
|
|
# MaxLoginAttempts value for FTP, as there are more ways to authenticate
|
|
# using SSH2.
|
|
MaxLoginAttempts 6
|
|
|
|
</VirtualHost>
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<p>
|
|
<b>Logging</b><br>
|
|
The <code>mod_sftp</code> module supports different forms of logging. The
|
|
main module logging is done via the <code>SFTPLog</code> directive. For
|
|
debugging purposes, the module also uses <a href="../howto/Tracing.html">trace logging</a>, via the module-specific log channels:
|
|
<ul>
|
|
<li>ssh2
|
|
<li>sftp
|
|
<li>scp
|
|
</ul>
|
|
Thus for trace logging, to aid in debugging, you would use the following in
|
|
your <code>proftpd.conf</code>:
|
|
<pre>
|
|
TraceLog /path/to/sftp-trace.log
|
|
Trace scp:20 sftp:20 ssh2:20
|
|
</pre>
|
|
This trace logging can generate large files; it is intended for debugging
|
|
use only, and should be removed from any production configuration.
|
|
|
|
<p>
|
|
<b>Suggested Future Features</b><br>
|
|
The following lists the features I hope to add to <code>mod_sftp</code>,
|
|
according to need, demand, inclination, and time:
|
|
<ul>
|
|
<li>Look up authorized public keys from LDAP directories
|
|
<li>Honor the <code>MaxTransferPerHost</code>,
|
|
<code>MaxTransfersPerUser</code>, <code>MaxRetrieveFileSize</code>
|
|
directives
|
|
</ul>
|
|
|
|
<p><a name="FAQ">
|
|
<b>Frequently Asked Questions</b><br>
|
|
|
|
<p><a name="SFTPTelnetBanner">
|
|
<font color=red>Question</font>: When I telnet to port 22 of other SSH2 servers,
|
|
I see the SSH2 version banner displayed, <i>e.g.</i>:
|
|
<pre>
|
|
# telnet example.com 22
|
|
Trying 1.2.3.4...
|
|
Connected to example.com.
|
|
Escape character is '^]'.
|
|
SSH-1.99-OpenSSH_5.1
|
|
</pre>
|
|
However, when I telnet to the port on which <code>mod_sftp</code> is listening,
|
|
I see the version banner plus some data which can't be rendered in the terminal.
|
|
What is that extra data?<br>
|
|
<font color=blue>Answer</font>: The short answer is that <code>mod_sftp</code>
|
|
is pre-emptively sending the first key exchange data; it is this data which is
|
|
not displayed well.
|
|
|
|
<p>
|
|
This pre-emptive sending of the first key exchange message is an optimization.
|
|
The SSH2 protocol (and many SSH2 servers) start off doing:
|
|
<pre>
|
|
(1) <i>client</i> ------------ connect -------------> <i>server</i>
|
|
(2) <i>client</i> <-------- version banner ---------- <i>server</i>
|
|
(3) <i>client</i> --- client's first key exchange --> <i>server</i>
|
|
(4) <i>client</i> <-- server's first key exchange --- <i>server</i>
|
|
</pre>
|
|
So you can see that there's some back and forth. The "first key exchange"
|
|
messages sent by the client are always the same for that client, likewise the
|
|
server always sends the same "first key exchange" message (based on its
|
|
configuration). So the above has several TCP packets and ACKs that need to be
|
|
sent back and forth.
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> module avoids one unnecessary TCP packet+ACK by
|
|
sending its version banner and its first key exchange message in the same TCP
|
|
packet:
|
|
<pre>
|
|
(1) <i>client</i> ------------ connect -------------> <i>server</i>
|
|
(2) <i>client</i> <-- version banner/1st key exch---- <i>server</i>
|
|
(3) <i>client</i> --- client's first key exchange --> <i>server</i>
|
|
</pre>
|
|
This helps cut down on the latency during startup, since <code>mod_sftp</code>
|
|
saves on one TCP round-trip time.
|
|
|
|
<p>
|
|
This optimization was added after reading this informative paper on SSH and
|
|
SSL/TLS by Peter Gutmann:
|
|
<pre>
|
|
<a href="http://www.cs.auckland.ac.nz/~pgut001/pubs/app_sec.pdf">Performance Characteristics of Application-level Security Protocols</a>
|
|
</pre>
|
|
|
|
<p><a name="SFTPBadWindowSize">
|
|
<font color=red>Question</font>: My SSH2/SFTP client dies when trying to
|
|
connect to <code>mod_sftp</code>. The login succeeds, but then the client
|
|
is disconnected. The client logs show something like:
|
|
<pre>
|
|
ServerMaxPacket(32768) ServerWindow(-1) (<i>from WS_FTP</i>)
|
|
</pre>
|
|
or
|
|
<pre>
|
|
debug1: channel 0: open confirm rwindow -1 rmax 32768 (<i>from OpenSSH_3.0.2p1</i>)
|
|
</pre>
|
|
<font color=blue>Answer</font>: The issue, in short, involves that "-1" value
|
|
you see, and the particular client implementation in question. (The example
|
|
error above is from an old OpenSSH client.)
|
|
|
|
<p>
|
|
The SSH2 protocol specifications say that implementations must encode
|
|
the SSH2 channel "window size" as a 32-bit unsigned number. This means that
|
|
the maximum window size is effectively 4294967295 (<i>i.e.</i> 2 ^ 32 - 1).
|
|
This maximum window size is what <code>mod_sftp</code> uses by default.
|
|
However, some client implementations use a <i>signed</i> data type for
|
|
holding this value. This means that the value that <code>mod_sftp</code>
|
|
sends to the client becomes a negative signed number to the client (the
|
|
large value "wraps around" to the negative value), and the client chokes.
|
|
|
|
<p>
|
|
As another example, the <a href="http://www.ipswitch.com/WS_FTP">WS_FTP Pro</a>
|
|
client has this same problem; in the client, you will see something like
|
|
the following error:
|
|
<pre>
|
|
Started subsystem "sftp" on channel 0760a2ce
|
|
error 84350000 initializing sftp protocol
|
|
Sending channel close message for channel 0760a2ce
|
|
SSH Transport closed.
|
|
</pre>
|
|
|
|
<p>
|
|
There are two approaches for handling such cases. You can use the
|
|
<a href="#SFTPClientMatch"><code>SFTPClientMatch</code></a> directive to
|
|
set a smaller channel window size for that particular client, <i>e.g.</i>:
|
|
<pre>
|
|
SFTPClientMatch ".*WS_FTP.*" channelWindowSize 256MB
|
|
SFTPClientMatch ".*Axway" channelWindowSize 256MB
|
|
</pre>
|
|
or you can use <code>SFTPClientMatch</code> to set a general channel window
|
|
size for all clients:
|
|
<pre>
|
|
SFTPClientMatch .* channelWindowSize 256MB
|
|
</pre>
|
|
|
|
<p>
|
|
The larger the channel window size, the better. (Note that the SSH2 channel
|
|
window size has absolutely <b>no</b> relation to the TCP window size.)
|
|
The smaller this SSH2 channel window size, the more frequently the peer needs
|
|
to send a "window size adjustment" SSH2 request (which entails its own TCP
|
|
packet and ACK) in order to keep the window size open. The larger the channel
|
|
window size, the fewer "window size adjustment" requests the peer has to send,
|
|
and thus the fewer TCP packets/ACKs are needed. Since each TCP packet adds
|
|
latency, the smaller channel window sizes can increase the latency for data
|
|
transfers.
|
|
|
|
<p>
|
|
For this reason, my personal recommendation is to only set smaller channel
|
|
window sizes for those SSH2/SFTP clients which need it; no need to incur
|
|
the additional latency if the client supports the larger window sizes.
|
|
|
|
<p><a name="SFTPSubsystem">
|
|
<font color=red>Question</font>: Can I configure <code>mod_sftp</code> to be
|
|
an OpenSSH subsystem, <i>e.g.</i> by using the following in my
|
|
<code>sshd_config</code> file:
|
|
<pre>
|
|
Subsystem sftp /usr/local/sbin/proftpd
|
|
</pre>
|
|
<font color=blue>Answer</font>: No. The <code>mod_sftp</code> module cannot
|
|
be used as an OpenSSH subsystem because proftpd needs more information about
|
|
the session than is provided to OpenSSH subsystems. ProFTPD needs to know all
|
|
of the information about the authenticated user, the SSH2 channel IDs being
|
|
used for the SFTP/SCP sessions, <i>etc</i>.
|
|
|
|
<p><a name="SFTPAndFTP">
|
|
<font color=red>Question</font>: How can I configure <code>proftpd</code>
|
|
so that it can handle both FTP and SFTP at the same time?<br>
|
|
<font color=blue>Answer</font>: The key to doing this is to create a
|
|
<code><VirtualHost></code> section just for the <code>mod_sftp</code>
|
|
configuration, listening on the address and port that you wish, <i>e.g.</i>:
|
|
<pre>
|
|
# The FTP configuration
|
|
DefaultAddress <i>a.b.c.d</i>
|
|
Port 21
|
|
|
|
<IfModule mod_sftp.c>
|
|
<VirtualHost <i>a.b.c.d</i>>
|
|
# The SFTP configuration
|
|
Port 22
|
|
|
|
SFTPEngine on
|
|
...
|
|
</VirtualHost>
|
|
</IfModule>
|
|
</pre>
|
|
<b>Note</b> that if you use the above configuration, and you wish to handle
|
|
<b><i>any</i></b> address requested by incoming connections, use
|
|
<code>0.0.0.0</code> as the <i>a.b.c.d</i> IP address. <code>0.0.0.0</code>
|
|
is known as the "wildcard address", and indicates that ProFTPD wants to listen
|
|
on any/all addresses, on those ports.
|
|
|
|
<p><a name="SFTPOnly">
|
|
<font color=red>Question</font>: How can I configure <code>proftpd</code>
|
|
so that it only accepts SFTP connections (via <code>mod_sftp</code>), and no
|
|
FTP connections?<br>
|
|
<font color=blue>Answer</font>: Use the following in your
|
|
<code>proftpd.conf</code>:
|
|
<pre>
|
|
<Limit LOGIN>
|
|
DenyAll
|
|
</Limit>
|
|
|
|
<VirtualHost <i>a.b.c.d</i>>
|
|
<Limit LOGIN>
|
|
AllowAll
|
|
</Limit>
|
|
|
|
SFTPEngine on
|
|
...
|
|
</VirtualHost>
|
|
</pre>
|
|
The idea is to use the <code><Limit LOGIN></code> to deny all logins to
|
|
any/all virtual host sections <i>except</i> for the <code>mod_sftp</code>
|
|
section.
|
|
|
|
<p><a name="SFTPAuthorizedKeyTooLong">
|
|
<font color=red>Question</font>: I followed the instructions to convert
|
|
my authorized keys from OpenSSH to RFC4716 format, yet I see the following
|
|
error in my <code>SFTPLog</code>:
|
|
<pre>
|
|
mod_sftp/0.9.7[31050]: line too long (74) on line 1 of '<i>authorized_keys</i>'
|
|
</pre>
|
|
What can I do to fix this?<br><br>
|
|
<font color=blue>Answer</font>: OpenSSH's <code>ssh-keygen</code> tool had a
|
|
bug where the RFC4716 keys it would generate might not comply to the RFC; see
|
|
the <a href="https://bugzilla.mindrot.org/show_bug.cgi?id=1630">OpenSSH bug</a>
|
|
filed for this issue.
|
|
|
|
<p>
|
|
Chances are that the offending line in the RFC4716 key is a "Comment: " header
|
|
that is too long. Simply delete that "Comment: " line; the
|
|
<code>mod_sftp</code> ignores this header.
|
|
|
|
<p><a name="SFTPAuthorizedKeyFormat">
|
|
<font color=red>Question</font>: I generated an SSH key using
|
|
<code>ssh-keygen</code>, then added it to my <code>authorized_keys</code> file
|
|
using:
|
|
<pre>
|
|
$ cat id_rsa.pub >> authorized_keys
|
|
</pre>
|
|
But logging into <code>mod_sftp</code> still prompts me for my password.
|
|
Why?<br>
|
|
<font color=blue>Answer</font>: The most likely culprit is that the format
|
|
of your <code>authorized_keys</code> file is not what <code>mod_sftp</code>
|
|
expects.
|
|
|
|
Per the <a href="#SFTPAuthorizedUserKeys"><code>SFTPAuthorizedUserKeys</code></a> documentation, <code>mod_sftp</code> expects that the keys be in RFC 4716
|
|
format. If your <code>authorized_keys</code> file contains data that looks
|
|
like this:
|
|
<pre>
|
|
ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDN1tCK5uHUGl....
|
|
</pre>
|
|
rather than looking like this:
|
|
<pre>
|
|
---- BEGIN SSH2 PUBLIC KEY ----
|
|
AAAAB3NzaC1yc2EAAAADAQABAAABAQDN1tCK5uHUGlpxye+KEmB0EIr9zqvMmgyNdWvJBW
|
|
...
|
|
PZ1+hOi5QECWQYD0BpiWvj
|
|
---- END SSH2 PUBLIC KEY ----
|
|
</pre>
|
|
Then the format of some of the keys in your <code>authorized_keys</code> file
|
|
is wrong. Make sure that you convert your OpenSSH-generated keys to RFC 4716
|
|
format using <code>ssh-keygen</code>, <em>before</em> adding it to your
|
|
<code>authorized_keys</code> file, using something like this:
|
|
<pre>
|
|
$ ssh-keygen -e -f ~/.ssh/id_rsa.pub -m RFC4716 >> authorized_keys
|
|
</pre>
|
|
See the <a href="#UsageRFC4716Format">Usage</a> documentation for more
|
|
information.
|
|
|
|
<p><a name="SFTPBrokenMaxFileSize">
|
|
<font color=red>Question</font>: I'm using the <a href="../modules/mod_xfer.html"><code>MaxStoreFileSize</code></a> directive in my <code>mod_sftp</code>
|
|
configuration, but when I upload a file using <i>e.g.</i> OpenSSH's
|
|
<code>sftp</code> client, I see the file uploaded past my configured limit. Is
|
|
this a bug?<br>
|
|
<font color=blue>Answer</font>: No. The <code>mod_sftp</code> module honors
|
|
a configured <code>MaxStoreFileSize</code> limit properly. <i>However</i>,
|
|
what you see <i>in the SFTP client</i> may not reflect this as you would expect.
|
|
Some SFTP clients, like that from OpenSSH, will only reflect the failure
|
|
<i>after the entire file has been uploaded</i>:
|
|
<pre>
|
|
sftp> put /path/to/file.dat
|
|
Uploading /path/to/file.dat to /file.dat
|
|
/path/to/file.dat 100% 704KB 704.1KB/s 00:00
|
|
Couldn't write to remote file "/file.dat": Failure
|
|
</pre>
|
|
In the <code>SFTPLog</code> for the above situation, you would most likely
|
|
see log messages about the SFTP <code>WRITE</code> requests being rejected:
|
|
<pre>
|
|
mod_sftp/0.9.9[32297]: error writing 32768 bytes to '/file.dat': File too large (MaxStoreFileSize 204800 exceeded)
|
|
mod_sftp/0.9.9[32297]: error writing 32768 bytes to '/file.dat': File too large (MaxStoreFileSize 204800 exceeded)
|
|
</pre>
|
|
|
|
<p>
|
|
<b>There is a discrepancy between what the client shows the user, and what the
|
|
server is actually doing.</b> The <code>mod_sftp</code> module, when handling
|
|
SFTP uploads, checks the size of the file on disk, after receiving the buffer
|
|
of data from the network, but <i>before</i> writing that data to disk. If the
|
|
size of the file on disk exceeds the <code>MaxStoreFileSize</code> limit, then
|
|
that SFTP <code>WRITE</code> request is denied.
|
|
|
|
<p>
|
|
Many SFTP clients will send multiple SFTP <code>WRITE</code> requests
|
|
concurrently, optimistically hoping that they will succeed; this makes for
|
|
faster SFTP uploads. This is why you might see multiple "File too large"
|
|
messages logged by <code>mod_sftp</code>. And it also means that the client
|
|
<i>thinks</i> it has sent more data to the server than has actually been
|
|
written to disk.
|
|
|
|
<p>
|
|
Now, this may lead you to ask "Due to SFTP protocol itself, there is no way to
|
|
control the file size uploaded by a client, right?" This is not quite correct.
|
|
|
|
<p>
|
|
There's no way <em>for an SFTP server</em> to control how much data the
|
|
SFTP client will send. But there <em>is</em> a way to control how much data is
|
|
written to disk by the SFTP server; that is what <code>MaxStoreFileSize</code>
|
|
does. But this means that the SFTP client may report how much data it sent
|
|
over the network, which <b>is not the same</b> as how much data was actually
|
|
stored by the SFTP server. Believing what your client shows you, though, is
|
|
always suspect, since what the client shows may not actually reflect the
|
|
reality of things on the server side of things.
|
|
|
|
<p><a name="SFTPPCBCModeAttacks">
|
|
<font color=red>Question</font>: Is it true that using CBC mode ciphers in
|
|
SSH is insecure?<br>
|
|
<font color=blue>Answer</font>: It is true that there are a couple of published
|
|
<i>theoretical</i> attacks against the SSH protocol when CBC ciphers are
|
|
used, including Rogaway, Wai, and Bellare (see RFC 4251, Section 9.3.1) and
|
|
<a href="http://www.cpni.gov.uk/Docs/Vulnerability_Advisory_SSH.txt">"Plaintext Recovery Attacks Against SSH"</a> (CPNI-957037).
|
|
|
|
<p>
|
|
However, these attacks can be mitigated by countermeasures in the SSH
|
|
implementation. The use of <code>SSH_MSG_IGNORE</code> messages for the
|
|
Rogaway attack, and the delayed checking of packet length fields until the MAC
|
|
check has passed (and then reading in a random amount of additional data from
|
|
the network) to migitate CPNI-957037, are both implemented within the
|
|
<code>mod_sftp</code> module as security measures.
|
|
|
|
<p><a name="SFTPListOptions">
|
|
<font color=red>Question</font>: I am trying to use <code>ListOptions</code>
|
|
to change what is displayed for files in my SFTP clients, but it is not working.
|
|
Why?<br>
|
|
<font color=blue>Answer</font>: Unlike FTP, in SFTP it is the <i>client</i>,
|
|
<b>not</b> the server, which determines what to display to the end user.
|
|
Thus the <code>ListOptions</code> directive is not honored by
|
|
<code>mod_sftp</code>.
|
|
|
|
<p><a name="SFTPUploadChmod">
|
|
<font color=red>Question</font>: If I use a configuration like this:
|
|
<pre>
|
|
<Directory /path/to/upload>
|
|
<Limit WRITE>
|
|
AllowAll
|
|
</Limit>
|
|
|
|
<Limit SITE_CHMOD>
|
|
DenyAll
|
|
</Limit>
|
|
</Directory>
|
|
</pre>
|
|
then why do my SFTP uploads fail, when the same configuration allows uploads to succeed using FTP?<br>
|
|
<font color=blue>Answer</font>: When a file is uploaded using FTP, the only
|
|
parts of the file uploaded are its <i>contents</i> but <b>not</b> the file
|
|
<i>metadata</i> (<i>e.g.</i> not the file timestamps or permissions). Separate
|
|
FTP commands are used to send the file metadata to the server.
|
|
|
|
<p>
|
|
However, the SFTP protocol sends the file metadata <i>as part of the normal upload</i>. In the configuration above, the limit on <code>SITE CHMOD</code>
|
|
is being applied to the SFTP upload. If you do not want this, and want
|
|
your SFTP uploads to be more like your FTP uploads, then you should use:
|
|
<pre>
|
|
SFTPOptions IgnoreSFTPUploadPerms
|
|
</pre>
|
|
in your <code>mod_sftp</code> configuration.
|
|
|
|
<p><a name="SFTPOwner">
|
|
<font color=red>Question</font>: I use <code>UserOwner</code> and
|
|
<code>GroupOwner</code> in my <code>mod_sftp</code> configuration, but they
|
|
are not being applied properly. Is this a bug?<br>
|
|
<font color=blue>Answer</font>: No.
|
|
|
|
<p>
|
|
By default, the <code>mod_sftp</code> module drops root privileges as soon
|
|
as it can, which is just after the user has been authenticated. Without
|
|
root privileges, <code>mod_sftp</code> cannot change the ownership of files
|
|
uploaded via SFTP/SCP as per <code>UserOwner</code>/<code>GroupOwner</code>
|
|
settings.
|
|
|
|
<p>
|
|
In ProFTPD 1.3.4rc1, honoring of the <code>UserOwner</code> and
|
|
<code>GroupOwner</code> directives was added to the <code>mod_sftp</code>
|
|
module. <b>However</b>, you will <i>also</i> need to add the following to your
|
|
<code>mod_sftp</code> configuration to make them work properly:
|
|
<pre>
|
|
RootRevoke off
|
|
</pre>
|
|
This explicitly tells the <code>mod_sftp</code> to <b>not</b> drop root
|
|
privileges after authentication, and instead to keep them for the duration
|
|
of the session.
|
|
|
|
<p>
|
|
In addition, <b>if</b> you are on a Linux machine, you may <em>also</em>
|
|
need to disable the <a href="../modules/mod_cap.html"><code>mod_cap</code></a>
|
|
module, as that can also restrict what can be done with root privileges:
|
|
<pre>
|
|
<IfModule mod_cap.c>
|
|
CapabilitiesEngine off
|
|
</IfModule>
|
|
</pre>
|
|
|
|
<p><a name="SFTPShell">
|
|
<font color=red>Question</font>: Why can't I use <code>ssh</code> to connect
|
|
to my proftpd+mod_sftp server? When I try, I see:
|
|
<pre>
|
|
# ssh <i>user</i>@<i>host</i>
|
|
Enter passphrase for key '/home/<i>user</i>/.ssh/id_rsa':
|
|
PTY allocation request failed on channel 0
|
|
shell request failed on channel 0
|
|
</pre>
|
|
<font color=blue>Answer</font>: The <code>mod_sftp</code> module supports
|
|
file transfers via SFTP and SCP. It does <b>not</b> support shell access,
|
|
which is what the <code>ssh</code> command-line client tries to use. The
|
|
above error messages from <code>ssh</code> show that <code>mod_sftp</code>
|
|
refused the shell access requests.
|
|
|
|
<p><a name="SFTPDirFakeUserGroup">
|
|
<font color=red>Question</font>: I am using <code>DirFakeUser</code> and
|
|
<code>DirFakeGroup</code> in my <code>mod_sftp</code> configuration, but
|
|
they do not work when I run the <code>ls -lh</code> command in the
|
|
<code>sftp</code> command-line client. Is this a bug?<br><br>
|
|
<font color=blue>Answer</font>: This is unfortunately an issue with OpenSSH's
|
|
<code>sftp</code> command-line client.
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> module always sends the same information for an
|
|
SFTP directory listing, assuming SFTP protocol version 3 or lower (which is
|
|
what OpenSSH uses); see <a href="https://github.com/proftpd/proftpd/blob/master/contrib/mod_sftp/fxp.c#L2801">here</a>. The <code>DirFakeUser</code> and
|
|
<code>DirFakeGroup</code> directives will affect the user/group names in that
|
|
"longname" string, which is defined for the <code>SSH_FXP_NAME</code> packet
|
|
described in <a href="https://tools.ietf.org/html/draft-ietf-secsh-filexfer-02#section-7">draft-ietf-secsh-filexfer-02</a>.
|
|
|
|
<p>
|
|
In looking at the OpenSSH 7.9p1 implementation, we can see the issue in its
|
|
code. When <code>ls -l</code> is used, the <code>sftp</code> command-line
|
|
client will display the "longname" sent by mod_sftp as-is. But when
|
|
<code>ls -lh</code> is used, that <code>-h</code> flag causes <code>sftp</code>
|
|
to <b>ignore the "longname"</b>, and try to use only the UID/GID <i>numeric
|
|
values</i> (which are <b>not</b> affected by the
|
|
<code>DirFakeUser/DirFakeGroup</code> directives).
|
|
|
|
<p><a name="SFTPTectiaHostKey">
|
|
<font color=red>Question</font>: When I try to start proftpd with
|
|
<code>mod_sftp</code> configured to use my existing host key, it fails with
|
|
one of the following error messages:
|
|
<pre>
|
|
error reading passphrase for SFTPHostKey '<i>hostkey</i>': Invalid argument
|
|
error reading passphrase for SFTPHostKey '<i>hostkey</i>': (unknown)
|
|
</pre>
|
|
The permissions on my hostkey are fine, and it is not passphrase-protected.
|
|
Is this a bug?<br><br>
|
|
<font color=blue>Answer</font>: You are probably trying to use a host key
|
|
generated by Tectia's SSH software (or an older <code>ssh.com</code> host key).
|
|
|
|
<p>
|
|
The <code>mod_sftp</code> module expects the configured
|
|
<code>SFTPHostKey</code> file to be in the same format as used by OpenSSH.
|
|
To check the format, run this command:
|
|
<pre>
|
|
# grep BEGIN <i>hostkey</i>
|
|
</pre>
|
|
If you see either of the following lines:
|
|
<pre>
|
|
-----BEGIN RSA PRIVATE KEY-----
|
|
-----BEGIN DSA PRIVATE KEY-----
|
|
</pre>
|
|
then the format should be correct. If instead you see:
|
|
<pre>
|
|
---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
|
|
</pre>
|
|
then the format is incorrect. The above line indicates that your host key
|
|
was generated by Tectia (<i>nee</i> <code>ssh.com</code>), and needs to
|
|
be converted to a different format.
|
|
|
|
<p>
|
|
To convert the format of your Tectia host key, use OpenSSH's
|
|
<code>ssh-keygen</code> (<b>not</b> Tectia's <code>ssh-keygen</code>) and
|
|
do the following:
|
|
<pre>
|
|
# ssh-keygen -i -f <i>hostkey</i> > /path/to/new-file
|
|
</pre>
|
|
The configure your <code>SFTPHostKey</code> directive with the path to the
|
|
new file.
|
|
|
|
<p><a name="SFTPOpenSSLVersionMismatch">
|
|
<font color=red>Question</font>: When I start <code>proftpd</code>, I
|
|
see warnings that look like this:
|
|
<pre>
|
|
- mod_sftp/0.9.7: compiled using OpenSSL version 'OpenSSL 0.9.8n 24 Mar 2010' headers, but linked to OpenSSL version 'OpenSSL 0.9.8q 2 Dec 2010' library
|
|
</pre>
|
|
What does this mean?<br>
|
|
<font color=blue>Answer</font>: That is an informational/warning message.
|
|
|
|
<p>
|
|
Some systems are badly maintained by their admins (and/or by the packages
|
|
installed on the systems), such that the OpenSSL headers can become quite badly
|
|
out of sync with the OpenSSL libraries. If this discrepancy becomes bad
|
|
enough, you can see strange behavior from OpenSSL, ranging from random behavior
|
|
to segfaults. So <code>mod_sftp</code> tries to let the admin know about the
|
|
system's mismatched OpenSSL header/library versions.
|
|
|
|
<p>
|
|
Usually a minor OpenSSL version difference like the example above is OK,
|
|
but it really depends on exactly what changed in OpenSSL, and how.
|
|
|
|
<p>
|
|
If you see the above message, it is not a <i>requirement</i> that you recompile
|
|
<code>proftpd</code> against the OpenSSL headers of the same version as the
|
|
OpenSSL libraries. However, the version discrepancy <em>is</em> a possible
|
|
source of trouble.
|
|
|
|
<p><a name="SFTPVersionId">
|
|
<font color=red>Question</font>: When a client first connects to
|
|
<code>mod_sftp</code> and starts the SSH handshake, the client sees that
|
|
<code>mod_sftp</code> provides an SSH version identifier like "SSH-2.0-mod_sftp/0.9.8". Is there any way I can tell <code>mod_sftp</code> to hide/change
|
|
that version?<br>
|
|
<font color=blue>Answer</font>: Yes. As of <code>proftpd-1.3.5rc1</code>,
|
|
the <code>mod_sftp</code> module will honor the <a href="../modules/mod_core.html#ServerIdent"><code>ServerIdent</code></a> directive.
|
|
|
|
<p>
|
|
For example, to see just "SSH-2.0-mod_sftp", without any <code>mod_sftp</code>
|
|
version suffix, use the following within your <code>mod_sftp</code> <code><VirtualHost></code>:
|
|
<pre>
|
|
# Tell mod_sftp to not reveal its module version in the SSH version
|
|
# identification
|
|
ServerIdent off
|
|
</pre>
|
|
You can also use <code>ServerIdent</code> to make <code>mod_sftp</code> say
|
|
it is something else completely, like this:
|
|
<pre>
|
|
# Tell mod_sftp to advertise itself as an OpenSSH server
|
|
ServerIdent on "OpenSSH_5.6p1"
|
|
</pre>
|
|
|
|
<p><a name="SFTPTrafficPolicyNetworkPerformance">
|
|
<font color=red>Question</font>: I notice that when I use some SFTP clients
|
|
(<i>e.g.</i> DreamWeaver) with <code>mod_sftp</code>, the network performance
|
|
is 5-6 times slower than with other SFTP clients. Using the same SFTP client
|
|
against OpenSSH doesn't show the same slowdown. Network tools such as
|
|
Wireshark show that <code>mod_sftp</code> is sending 2 TCP packets for each
|
|
SFTP request, whereas OpenSSH only sends 1 TCP packet for each SFTP request.
|
|
Why is <code>mod_sftp</code> so much slower than OpenSSH, but only for some
|
|
SFTP clients?<br>
|
|
<font color=blue>Answer</font>: Investigations into this <code>mod_sftp</code>
|
|
behavior have shown it to be caused by the
|
|
<a href="#SFTPTrafficPolicy"><code>SFTPTrafficPolicy</code></a> behavior,
|
|
particularly when the SFTP client negotiates the use of a CBC cipher.
|
|
|
|
<p>
|
|
The recommended action to take is to disable the use of CBC ciphers,
|
|
which will cause the <code>SFTPTrafficPolicy</code> mitigation to not go
|
|
into effect, which keeps the number of SSH messages lower, thus improving
|
|
network latency. Thus the change to make for your <code>mod_sftp</code>
|
|
configuration is:
|
|
<pre>
|
|
# Remove the CBC ciphers from the ciphers we advertise
|
|
SFTPCiphers aes256-ctr aes192-ctr aes128-ctr blowfish-ctr arcfour256 arcfour128 3des-ctr
|
|
</pre>
|
|
|
|
<p><a name="SFTPLocalisedTimes">
|
|
<font color=red>Question</font>: When I use <code>mod_sftp</code> and get
|
|
a directory listing, I notice that the timestamps on the files are
|
|
localised (<i>e.g.</i> are in French). When I use OpenSSH, the timestamps
|
|
are always in English. How I get get <code>mod_sftp</code> to behave like
|
|
OpenSSH, and not localise the timestamps?<br>
|
|
<font color=blue>Answer</font>: This happens when your <code>proftpd</code>
|
|
has been built with the <code>--enable-nls</code> configure option. To
|
|
check, use <code>`proftpd -V'</code>:
|
|
<pre>
|
|
...
|
|
Features:
|
|
...
|
|
+ NLS support
|
|
...
|
|
</pre>
|
|
This means that <code>proftpd</code> honors any locale-related environment
|
|
variables when it starts up. The reason you see localised timestamps
|
|
in the directory listings is probably because your environment has something
|
|
like <code>LANG=fr_FR.utf8</code>.
|
|
|
|
<p>
|
|
To tell <code>proftpd</code> to ignore that environment variable, you need
|
|
to use this at the top of your <code>proftpd.conf</code>:
|
|
<pre>
|
|
Unsetenv LANG
|
|
</pre>
|
|
|
|
<p><a name="SFTPVersion6">
|
|
<font color=red>Question</font>: My SFTP client wants to use SFTP protocol
|
|
version 6, but <code>mod_sftp</code> only accepts protocol version 3. These
|
|
docs say that protocol versions 1-6 are supported. Is this a bug?<br>
|
|
<font color=blue>Answer</font>: The most likely cause of this behavior is that
|
|
your <code>proftpd</code> installation was not compiled with the
|
|
<code>--enable-nls</code> configure option. The <code>--enable-nls</code>
|
|
configure option is required to enable NLS support, which includes support
|
|
for UTF8. SFTP protocol versions 4-6 require UTF8 support, which is why
|
|
the <code>--enable-nls</code> configure option is needed.
|
|
|
|
<p><a name="SFTPExtraREADs">
|
|
<font color=red>Question</font>: Why is my <code>SFTPLog</code> often spammed
|
|
with lots of messages that look like:
|
|
<pre>
|
|
requested read offset (20480 bytes) greater than size of '/some/path/to.file' (20307 bytes)
|
|
</pre>
|
|
Is there something wrong with my SFTP client, or my configuration?<br>
|
|
<font color=blue>Answer</font>: The short answer is that these extraneous
|
|
<code>READ</code> requests <i>are</i> normal, and do <i>not</i> indicate any
|
|
problem or issue.
|
|
|
|
<p>
|
|
Many SFTP clients try to improve their download speed by issuing many
|
|
concurrent <code>READ</code> requests, each request with a different
|
|
<em>offset</em>. Thus the client can read multiple "chunks" simultaneously,
|
|
and do the reassembly of the "chunks" into the file itself. However, sometimes
|
|
these SFTP clients do not necessarily know how <i>many</i> such
|
|
<code>READ</code> requests are needed before the end-of-file is reached. So
|
|
the SFTP client sends more <code>READ</code>s that might be necessary; the
|
|
server will reply with an error if the requested <em>offset</em> is beyond the
|
|
end of the file. When this "end of file" reply is received by the SFTP client,
|
|
it will know that it is done downloading. On the server side, though, this
|
|
behavior results in the above log messages.
|
|
|
|
<p><a name="SFTPNotUnderstood">
|
|
<font color=red>Question</font>: When I use my SFTP client, I see something
|
|
like this when I try to connect to <code>proftpd</code> with
|
|
<code>mod_sftp</code>:
|
|
<pre>
|
|
500 SSH-2.0-OPENSSH 6.2 not understood
|
|
</pre>
|
|
Why would this happen?<br>
|
|
<font color=blue>Answer</font>: A "500 ... not understood" is an
|
|
<b><i>FTP</i></b> response, not an SFTP response. This usually happens
|
|
when your SFTP client connects to an FTP virtual host/port (versus an SFTP
|
|
virtual host/port). So either <i>a)</i> the SFTP client is connecting to
|
|
the wrong port on your server, or <i>b)</i> perhaps "SFTPEngine on" is not
|
|
set in the virtual host for that port.
|
|
|
|
<p><a name="SFTPPTYAllocationFailed">
|
|
<font color=red>Question</font>: I try to connect to <code>proftpd</code>
|
|
with <code>mod_sftp</code> and the connection fails with an error messages
|
|
like "PTY allocation request failed on channel 0" or "Server refused to
|
|
allocate pty". What is going wrong?<br>
|
|
<font color=blue>Answer</font>: This error message happens when you
|
|
try to connect to <code>mod_sftp</code> using an SSH client which wants
|
|
a <em>shell</em> session, rather than an SFTP session or an SCP transfer.
|
|
The <code>mod_sftp</code> module does <b>not</b> support shell sessions
|
|
(unlike OpenSSH). In the <code>SFTPLog</code>, you would see such
|
|
connection attempts logged like so:
|
|
<pre>
|
|
mod_sftp/0.9.9[6304]: unsupported 'pty-req' channel requested, ignoring
|
|
mod_sftp/0.9.9[6304]: unsupported 'shell' channel requested, ignoring
|
|
</pre>
|
|
|
|
<p><a name="SFTPDirectorySGID">
|
|
<font color=red>Question</font>: When I create a directory via SFTP, in
|
|
a directory with the SGID bit set, the created directory does <b>not</b>
|
|
have the SGID bit set as expected. How do I fix this?<br>
|
|
<font color=blue>Answer</font>: Preserving the SGID bit for a created directory
|
|
usually require root privs; the <code>mod_sftp</code> module automatically
|
|
drops all root privs. So to get the directory SGID bit functionality,
|
|
you will need to use the following in your <code>mod_sftp</code>
|
|
<code><VirtualHost></code> section:
|
|
<pre>
|
|
RootRevoke off
|
|
</pre>
|
|
In addition, if your <code>proftpd</code> is running on Linux, you may
|
|
need to disable the <a href="../modules/mod_cap.html"><code>mod_cap</code></a>
|
|
module, or configure it to preserve the SGID bit (<i>e.g.</i> via the
|
|
<a href="../modules/mod_cap.html#CapabilitiesSet"><code>CAP_FSETID</code></a>
|
|
capability).
|
|
|
|
<p><a name="SFTPEd25519">
|
|
<font color=red>Question</font>: I see that Ed25519 SSH keys are supported
|
|
as of ProFTPD 1.3.7rc3 (see <a href="http://bugs.proftpd.org/show_bug.cgi?id=4221">Bug #4221</a>), but when I try to use one with <code>mod_sftp</code>, my
|
|
login fails. The <code>SFTPLog</code> shows this error; why?
|
|
<pre>
|
|
USER user1 (Login failed): unsupported public key algorithm 'ssh-ed25519' requested
|
|
</pre>
|
|
<font color=blue>Answer</font>: Support for the Ed25519 algorithm requires
|
|
the <a href="https://github.com/jedisct1/libsodium">libsodium</a> library.
|
|
You may need to install this library, and recompile ProFTPD with
|
|
<code>mod_sftp</code> in order for the library to be detected and used.
|
|
|
|
<p><a name="SFTPWarnings">
|
|
<font color=red>Question</font>: In my SFTP logs, I see these warnings:
|
|
<pre>
|
|
WARNING: unable to read SFTPDHParamFile '<i>path</i>': Permission denied
|
|
unable to open SFTPKeyBlacklist '<i>path</i>': Permission denied
|
|
</pre>
|
|
What can I do to fix this?<br>
|
|
<font color=blue>Answer</font>: This indicates that the files are not
|
|
readable (usually <i>world</i>-readable) by the users logging in,
|
|
<b>or</b> that the directories containing the files are not readable
|
|
by the users.
|
|
|
|
<p>
|
|
Fortunately <code>mod_sftp</code> will function without issue if it
|
|
cannot read either the <code>SFTPDHParamFile</code> or the
|
|
<code>SFTPKeyBlacklist</code> files.
|
|
|
|
<p><a name="SFTPSHA2">
|
|
<font color=red>Question</font>: I see that many sites are phasing out their
|
|
use of the SHA-1 algorithm as it is felt to be <em>unsafe</em>. How can I
|
|
configure <code>mod_sftp</code> to no longer use SHA-1?<br>
|
|
<font color=blue>Answer</font>: The main uses of SHA-1 in <code>mod_sftp</code>
|
|
are in the algorithms for MACs (the
|
|
<a href="#SFTPDigests"><code>SFTPDigests</code></a> directive) and key exchanges
|
|
(the <a href="#SFTPKeyExchanges"><code>SFTPKeyExchanges</code></a> directive).
|
|
|
|
<p>
|
|
For <code>SFTPDigests</code>, the algorithms that <em>use</em> SHA-1, and thus
|
|
the ones to <em>avoid</em> are:
|
|
<ul>
|
|
<li>hmac-sha1
|
|
<li>hmac-sha1-96
|
|
<li>hmac-md5
|
|
<li>hmac-md5-96
|
|
</ul>
|
|
Then you would want to use something like this in your <code>mod_sftp</code>
|
|
configuration:
|
|
<pre>
|
|
SFTPDigests \
|
|
umac-128@openssh.com \
|
|
umac-64@openssh.com \
|
|
hmac-sha2-256 \
|
|
hmac-sha2-512
|
|
</pre>
|
|
Note that some of the algorithms above may not be supported by your version
|
|
of <code>mod_sftp</code>.
|
|
|
|
<p>
|
|
Similarly, for key exchanges, the algorithms to avoid because they use SHA-1
|
|
are:
|
|
<ul>
|
|
<li>diffie-hellman-group-exchange-sha1
|
|
<li>diffie-hellman-group14-sha1
|
|
<li>diffie-hellman-group1-sha1
|
|
</li>rsa1024-sha1
|
|
</ul>
|
|
And to do this, you might use something like this in your configuration:
|
|
<pre>
|
|
SFTPKeyExchanges \
|
|
curve448-sha512 \
|
|
curve25519-sha256 \
|
|
ecdh-sha2-nistp521 \
|
|
ecdh-sha2-nistp384 \
|
|
ecdh-sha2-nistp256 \
|
|
diffie-hellman-group18-sha512 \
|
|
diffie-hellman-group16-sha512 \
|
|
diffie-hellman-group14-sha256 \
|
|
diffie-hellman-group-exchange-sha256 \
|
|
</pre>
|
|
|
|
<p><a name="SFTPOpenSSL1.1.x">
|
|
<font color=red>Question</font>: I am using ProFTPD 1.3.5, and I am unable to
|
|
use <code>mod_sftp</code>. When I connect, I see these errors in my
|
|
<code>SFTPLog</code>:
|
|
<pre>
|
|
2017-07-28 22:38:13,904 mod_sftp/0.9.9[24363]: error setting key/IV for aes256-ctr cipher for decryption:
|
|
(1) error:0906D06C:PEM routines:PEM_read_bio:no start line
|
|
(2) error:0607B083:digital envelope routines:EVP_CipherInit_ex:no cipher set
|
|
</pre>
|
|
Is this a bug?<br>
|
|
<font color=blue>Answer</font>: These error messages indicate that you are
|
|
using a newer version of OpenSSL, <i>e.g.</i> OpenSSL 1.1.<i>x</i>, than
|
|
ProFTPD 1.3.5 can support.
|
|
|
|
<p>
|
|
The OpenSSL APIs <em>changed</em> from OpenSSL 1.0.<i>x</i> to OpenSSL
|
|
1.1.<i>x</i>, requiring changes in the applications that use OpenSSL (see
|
|
<a href="http://bugs.proftpd.org/show_bug.cgi?id=4240">Bug#4240</a>). To
|
|
deal with this issue, then, you can hopefully upgrade to ProFTPD 1.3.6 or later,
|
|
<i>or</i> downgrade your OpenSSL version to 1.0.<i>x</i>.
|
|
|
|
<p>
|
|
<hr>
|
|
<font size=2><b><i>
|
|
© Copyright 2008-2024 TJ Saunders<br>
|
|
All Rights Reserved<br>
|
|
</i></b></font>
|
|
<hr>
|
|
|
|
</body>
|
|
</html>
|