mod_sftp
SFTP versus FTPS
There is a great deal of confusion and misunderstanding surrounding two very
different protocols: SFTP and FTPS.
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 mod_tls 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 CCC FTP
command, which clears the FTP control channel of encryption, once the user has
authenticated. Unfortunately, support for the CCC command is not
widespread among FTPS clients and servers; the mod_tls module does
support the CCC command.
By contrast, SFTP refers to "Secure File Transfer Protocol", and is not 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.
SSH2 RFCs and SFTP Drafts
For those wishing to learn more about the SSH2 and SFTP protocols, see:
The mod_sftp module for ProFTPD
The mod_sftp module implements the SSH2 protocol and its SFTP
subsystem, for secure file transfer over an SSH2 connection. The
mod_sftp module supports:
mod_sql, mod_ldap, mod_auth_file,
mod_auth_unix, mod_auth_pam)
mod_quotatab module)
TransferRate, and/or the
mod_shaper module)
The mod_sftp module does not currently support:
<Anonymous>
ListOptions
MaxRetrieveFileSize/MaxStoreFileSize
The mod_sftp module is contained in the mod_sftp/
directory, is intended for ProFTPD 1.3.3rc1 and later, and is not compiled by
default. Installation instructions are discussed
here.
The most current version of mod_sftp is distributed with the
ProFTPD source code.
This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). This product includes cryptographic software written by Eric Young (eay@cryptsoft.com).
Please contact TJ Saunders <tj at castaglia.org> with any questions, concerns, or suggestions regarding this module.
The SFTPAcceptEnv 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 SFTPAcceptEnv
directives.
Be warned that some environment variables may have special meaning to underlying libraries; care should be taken in the use of this directive.
The SFTPAuthMethods directive configures the list of available
authentication methods presented to connecting clients. The list of
currently supported methods is:
# Offer publickey and keyboard-interactive authentication only SFTPAuthMethods publickey keyboard-interactive
The hostbased authentication method is only offered to clients if
the SFTPAuthorizedHostKeys
directive is configured.
The publickey authentication method is only offered to clients if
the SFTPAuthorizedUserKeys
directive is configured.
The keyboard-interactive authentication method is only offered to
clients if the mod_sftp_pam
module is present.
The SFTPAuthorizedHostKeys directive configures the file that
mod_sftp 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.
Note that a SFTPAuthorizedHostKeys directive is
required for mod_sftp to handle sessions which want to use
hostbased authentication properly.
Note: In order to use OpenSSH public keys in a
SFTPAuthorizedHostKeys, you must convert them to the
RFC4716 format (see the Usage section).
This is done using OpenSSH's ssh-keygen tool:
# ssh-keygen -e -f /path/to/fileThe output from this command can then be added to the
SFTPAuthorizedHostKeys file.
The SFTPAuthorizedUserKeys directive configures the file that
mod_sftp 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.
Note that a SFTPAuthorizedUserKeys directive is
required for mod_sftp to handle sessions properly.
Note: In order to use OpenSSH public keys in a
SFTPAuthorizedUserKeys, you must convert them to the
RFC4716 format (see the Usage section).
This is done using OpenSSH's ssh-keygen tool:
# ssh-keygen -e -f ~/.ssh/id_rsa.pubThe output from this command can then be added to the
SFTPAuthorizedUserKeys file.
The configured path for a file containing authorized keys can use the
%u 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:
SFTPAuthorizedUserKeys file:/etc/sftp/authorized_keys/%u
The SFTPCiphers directive is used to specify the list of
cipher algorithms that mod_sftp should use. The current list
of supported cipher algorithms is, in the default order of preference:
The "none" cipher (i.e. no encryption) will not be presented to
the client by default; any sites which wish to use "none" will have to
explicitly configure it via SFTPCiphers.
Note that CTR mode ciphers (e.g. the aes128-ctr,
aes192-ctr, and aes256-ctr 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
here.
This attack is on the SSH2 protocol design itself; any SSH2 implementation
which conforms to the RFCs will have this weakness.
In general, there is no need to use this directive unless only one specific cipher must be used.
For comparison, the cipher algorithms used by OpenSSH by default are:
mod_sftp to present the same
cipher algorithms as OpenSSH, you would use:
# 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
The SFTPClientAlive directive configured mod_sftp
to send messages to a client, through the encrypted channel, to request a
response from the client. If count client alive messages are sent
without receiving any response messages from the client, the client will
be disconnected. The interval indicates how much time, in seconds,
that mod_sftp waits for data from the client before sending a
client alive message.
For example, using:
SFTPClientAlive 3 15will cause an unresponsive client to be disconnected after approximately 45 seconds.
The SFTPClientMatch directive is used to tune some of the
SSH2/SFTP values based on the connecting client, for better interoperability
with those clients. The pattern 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 pattern, then
the configured keys/values are used for that session.
The currently supported SSH2/SFTP keys which can be tuned via
SFTPClientMatch are:
The default mod_sftp channel packet size is 32KB.
The default mod_sftp 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.
mod_sftp module supports SFTP protocol versions 1-6;
using any other protocol versions will result in bad configuration.
mod_sftp 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.
For example, if you set:
SFTPClientMatch .* sftpUTF8ProtocolVersion 1
then mod_sftp will try to use UTF8 for all SFTP protocol
versions, all clients.
For example, to make mod_sftp only allow SFTP protocol version 3
to WinSCP clients, you would use:
SFTPClientMatch ".*WinSCP.*" sftpProtocolVersion 3Or for older OpenSSH clients, you may need to use a smaller channel window size, e.g.:
SFTPClientMatch "^OpenSSH_3\\.*" channelWindowSize 8MB
The SFTPCompression 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.
The delayed parameter tells mod_sftp to support a custom
extension used by OpenSSH, where compression is not actually enabled until
after the client has successfully authenticated.
The SFTPCryptoDevice directive is used to configure
mod_sftp to use an OpenSSL "engine", a cryptographic module
that OpenSSL library can use for accelerated cryptographic support, or
HSM keys, etc.
To use all of the engines compiled into OpenSSL, use:
SFTPCryptoDevice allOpenSSL 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, e.g.:
SFTPCryptoDevice chil
The OpenSSL command
openssl enginemay be used to list all of the engine drivers supported by OpenSSL.
The SFTPDHParamFile directive is used to configure the path
to a file containing pre-computed Diffie-Hellman (DH) group parameters.
These parameters will be used by mod_sftp when handling the
Diffie-Hellman group exchange (see RFC4419) portion of the key exchange.
The SFTPDHParamFile is produced using OpenSSL, which uses
PEM encodings of PKCS#3 DHparam structures. It is similar in
nature to OpenSSH's moduli(5) file.
The mod_sftp source code comes with a dhparams.pem
file which should be sufficient. If for any reason you find that you
need to generate your own SFTPDHParamFile, use one of the
following OpenSSL commands to create this file:
# openssl dhparam -outform PEM -2 nbits >> dhparams.pem # openssl dhparam -outform PEM -5 nbits >> dhparams.pemUsing either
-2 or -5 as the generator is fine.
The nbits value used should vary between 1024 and 8192, inclusive.
Beware: this process is quite slow, and CPU/memory intensive!
The SFTPDigests directive is used to specify the list of
MAC digest algorithms that mod_sftp should use. The current list
of supported MAC algorithms is:
The "none" MAC (i.e. no MAC) will not be presented to the client
by default; any sites which wish to use "none" will have to explicitly
configure it via SFTPDigests.
In general, there is no need to use this directive unless only one specific MAC algorithm must be used.
For comparison, the MAC algorithms used by OpenSSH by default are:
mod_sftp to present the same
MAC algorithms as OpenSSH, you would use:
# Make mod_sftp present the MAC ciphers as OpenSSH SFTPDigests hmac-md5 hmac-sha1 hmac-ripemd160 hmac-sha1-96 hmac-md5-96
The SFTPDisplayBanner 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.
The SFTPEngine directive toggles the use of the SSH2/SFTP protocols
engine (e.g. mod_sftp). This is usually used inside a
<VirtualHost> section to enable SFTP sessions for a
particular virtual host. By default mod_sftp is disabled for both
the main server and all configured virtual hosts.
The SFTPExtensions directive can be used to enable/disable
support for the various SFTP extensions supported by mod_sftp.
The extension names used for the SFTPExtensions directive are:
vendorID are enabled by default.
To enable an extension, preface the extension name with a '+' (plus) character; to disable the extension, use a '-' (minus) character prefix. For example:
# Allow the copy-file extension, but not version-select SFTPExtensions +copyFile -versionSelect
The SFTPHostKey directive configures the path to a host key file.
The mod_sftp module uses the keys thus configured as part of
the SSH2 key exchange process.
Note that the SFTPHostKey directive is required. You
can use either an RSA key, a DSA key, or both. These should be the exact
same host key files as used by your SSH2 server, e.g.:
SFTPHostKey /etc/ssh_host_dsa_key SFTPHostKey /etc/ssh_host_rsa_keyor the equivalents in the
/usr/local/etc/ directory. Using
different host keys between your SSH2 server and mod_sftp 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 host (even the same port), just different services.
Thus having different host keys for an SSH2 server and mod_sftp
will cause clients to constantly switch the host keys they record for the
same host (and cause confusion for users).
The SFTPKeyBlacklist 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
CivicActions. For the original
posting, and further information, see:
http://www.openwall.com/lists/oss-security/2008/05/27/3
These known weak public keys arose because of a vulnerability in the OpenSSL packages distributed by Debian:
http://www.debian.org/security/2008/dsa-1571
The mod_sftp source code comes with a blacklist.dat
file which should be sufficient. If for any reason you find that you
need to generate your own SFTPDKeyBlacklist, use the
blacklist-encode program mentioned in the above URLs.
The SFTPKeyExchanges directive is used to specify the list of
key exchange algorithms that mod_sftp should use. The current list
of supported key exchange algorithms is:
In general, there is no need to use this directive unless only one specific key exchange algorithm must be used.
The SFTPLog directive is used to specify a log file for
mod_sftp's reporting on a per-server basis. The file
parameter given must be the full path to the file to use for logging.
Note that this path must not be to a world-writable directory and,
unless AllowLogSymlinks is explicitly set to on
(generally a bad idea), the path must not be a symbolic link.
<VirtualHost>, <Global>
The SFTPMaxChannels directive is used to configure the maximum
number of simultaneously open channels permitted for a client. The
default value is 10.
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.
<VirtualHost>, <Global>
The SFTPOptions directive is used to configure various optional
behavior of mod_sftp. Note: all of the configured
SFTPOptions parameters must appear on the same line in the
configuration; only the first SFTPOptions directive that
appears in the configuration is used.
For example:
SFTPOptions IgnoreSFTPUploadPerms IgnoreSCPUploadPerms PessimisticKexinit
The currently implemented options are:
IgnoreSFTPSetPerms
Use this option to have mod_sftp silently ignore any
permissions sent by SFTP clients via the SETSTAT or
FSETSTAT SFTP requests; these are equivlant to
an FTP SITE CHMOD command.
Note that this option first appeared in
proftpd-1.3.4rc2.
IgnoreSFTPSetTimes
Use this option to have mod_sftp silently ignore any
timestamps sent by SFTP clients via the SETSTAT or
FSETSTAT SFTP requests; these are equivlant to
an FTP SITE UTIMES command.
Note that this option first appeared in
proftpd-1.3.4rc4.
IgnoreSFTPUploadPerms
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 not include the file
permissions in an upload.) If you need more FTP-like functionality for any
reason and wish to have mod_sftp silently ignore any
permissions sent by the SFTP client, use this option.
IgnoreSCPUploadPerms
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 not include the file permissions in an upload.)
If you need more FTP-like functionality for any reason and wish to
have mod_sftp silently ignore any permissions sent by the
SCP client, use this option.
MatchKeySubject
When this option is used, if public key authentication is used, the
mod_sftp module will check if the public key has a "Subject"
header. If so, that the value of that header must match the
name of the authenticating user/host.
Note that this option first appeared in
proftpd-1.3.4rc1.
OldProtocolCompat
Older clients identity their protocol versions as "1.99", rather than as
"2.0". By default, mod_sftp 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.
Note that this option automatically enables the
PessimisticKexinit SFTPOption as well.
Note that this option first appeared in
proftpd-1.3.4rc1.
PessimisticKexinit
As described here, the mod_sftp
module tries to reduce the connection latency by optimistically sending
the KEXINIT key exchange message. However, some SSH clients
cannot handle this behavior. Use this option to disable the optimistic
sending of the KEXINIT message.
Note that this option first appeared in
proftpd-1.3.4rc1.
The SFTPPassPhraseProvider directive is used to specify an
external program which will be called, when mod_sftp starts up,
for each encrypted host key file. The program will be invoked with two
command-line arguments, passed on stdin to the program:
servername:portnumber filewhere
servername:portnumber indicates the
server using that encrypted certificate key, and file indicates the
host key file in question. The program then must print the corresponding
passphrase for the key to stdout.
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.
Example:
SFTPPassPhraseProvider /etc/ftpd/sftp/get-passphrase
The SFTPRekey directive configures the session rekey policy
used by the mod_sftp 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".
By default, mod_sftp will only require rekeying when
the packet sequence number (for sent or 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 RFC4344). Outside of these sequence number limits, however,
mod_sftp will not attempt to initiate rekeying.
To prevent mod_sftp from attempting rekeying, use:
SFTPRekey noneNote that disabling rekeying altogether is a Very Bad Idea. While rekeying can cause delays in the SSH2 sesssion, it is intended to guard against certain attacks. You should therefore only disable rekeying for certain SSH2 clients which cannot support rekeying. Please report those clients (including 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.
To require rekeying, simply use:
SFTPRekey requiredWith this parameter,
mod_sftp will default to requiring a rekey
within 1 hour (3600 seconds) or after 2GB of data sent or received,
whichever happens first. There will be no timeout once a rekeying has been
requested.
However, administrators wishing to use different rekey intervals or rekey byte limits can use the optional interval (in seconds) and bytes (in MB) parameters, e.g.:
# Require rekeying after 30 minutes, or 4 GB SFTPRekey required 1800 4096
Finally, the paranoid administrator may wish to set a timeout, in seconds, in which a client must complete a session rekeying, otherwise the client will be disconnected. This would look like:
# 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 300Note that normally such rekey timeouts are not necessary.
The SFTPTrafficPolicy 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.
The SSH2 protocol includes a particular message, SSH_MSG_IGNORE,
which all implementations (both clients and servers) must handle by
dropping on the floor. Implementations, like mod_sftp, can
use these messages to add random data to the session in the hopes of making
such traffic analyses more difficult.
The SFTPTrafficPolicy directive supports the following range
of policies; the chances columns list the probability that
mod_sftp will send an SSH_MSG_IGNORE message.
| Policy Name | Chances | Checks |
| "none" | Never | Never |
| "low" | 1 in 1000 | Every 5 seconds |
| "medium" | 1 in 100 | Every 5 seconds |
| "high" | 1 in 10 | Every second |
| "paranoid" | Always | Every second |
The default SFTPTrafficPolicy setting is "none".
mod_sftp, go to the third-party module area in
the proftpd source code and unpack the mod_sftp source tarball:
cd proftpd-dir/contrib/ tar zxvf /path/to/mod_sftp-version.tar.gzafter unpacking the latest proftpd-1.3.2 source code. For including
mod_sftp as a staticly linked module:
./configure --enable-openssl --with-modules=mod_sftp ...Alternatively,
mod_sftp can be built as a DSO module:
./configure --enable-dso --enable-openssl --with-shared=mod_sftp ...Then follow the usual steps:
make make install
Compiler Warnings
When compiling mod_sftp, you may notice the following compiler
warning:
contrib/mod_sftp/mod_sftp.a(fxp.o): In function `fxp_handle_create': fxp.c:(.text+0x4dc8): warning: the use of `mktemp' is dangerous, better use `mkstemp'This warning can be ignored.
The mktemp(3) function is generally considered unsafe because,
in the past, many applications would use this function to create the names of
temporary files. The actual problem was not the mktemp(3)
function itself, but rather that the applications did not check to see
if the name generated by mktemp(3) already existed in filesytem
first. This lead to race conditions where local users could create symlinks
of the generated names, and the application would overwrite the symlinked file.
In the case of mod_sftp, however, the mktemp(3)
function is not used to create files. Instead, it is used to create
arbitrary unique strings that are used as "handles", as references, in the
protocol. These strings have no relation to any actual path on the filesystem,
and thus do not suffer from the above race condition.
Access Controls for SFTP Requests
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
<Limit> sections for access controls in mod_sftp
a little interesting.
First, the familiar territory. The following shows the
<Limit> sections for FTP commands (just as for normal FTP
sessions) which are honored by mod_sftp:
<Limit DELE>REMOVE SFTP request
<Limit MKD XMKD>MKDIR SFTP request
<Limit LIST NLST>READDIR SFTP request
<Limit RETR>READ SFTP request
<Limit RNFR RNTO>RENAME SFTP request
<Limit RMD XRMD>RMDIR SFTP request
<Limit STOR>WRITE SFTP request
<Limit SITE_CHMOD>SETSTAT and FSETSTAT SFTP
requests when they change file permissions
mod_sftp will reuse much of your existing
<Limit>-based access controls for SFTP sessions.
For those SFTP requests which have no direct FTP equivalents elsewhere in
proftpd, the mod_sftp module supports some
slightly different <Limit> sections. Note that
the following does not apply to FTP sessions, nor does it imply
that FTP supports these commands:
<Limit FSTAT>FSTAT SFTP request
<Limit LSTAT>LSTAT SFTP request
<Limit LOCK>LOCK and UNLOCK SFTP requests
<Limit OPEN>OPEN SFTP request
<Limit SETSTAT>FSETSTAT and SETSTAT SFTP requests
<Limit STAT>STAT SFTP request
<Limit SYMLINK>LINK and SYMLINK SFTP requests
LOCK and UNLOCK requests, for example, appear
only in later versions of SFTP.
What about the READ and WRITE command groups?
<Limit READ>SYMLINK and READ SFTP requests
<Limit WRITE>SETSTAT, SYMLINK, and
LOCK SFTP requests
Environment Variables
The mod_sftp module will set the following environment
variables whenever an SSH2 client connects:
SFTP
SFTP_LIBRARY_VERSION
SSH_CONNECTION
mod_sftp:
These environment variables are intended for informational purposes,
e.g. ExtendedLog or SQLLog directives.
SSH2 Public Key Formats
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 mod_sftp module uses a different
format for public keys, specifically, the format specified in
RFC 4716. The hope
is that this format is more interoperable with other SSH2/SFTP implementations.
This means that if you wish to use your OpenSSH public keys with the
mod_sftp module, you will need to convert them from OpenSSH's
format to the RFC4716 format. Fortunately, this is supported by
OpenSSH's ssh-keygen utility, e.g.:
# ssh-keygen -e -f ~/.ssh/id_rsa.pubThe output from this command can be added to the
SFTPAuthorizedUserKeys used by mod_sftp.
Note that the RFC4716 format is not to be used with the
SFTPHostKey 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.
Known Client Issues
The following lists some of the various client interoperability issues that
have been encountered, and how to address them.
SSH Channel Window Sizes
Some SFTP client implementations do not support the large SSH channel window
size that the mod_sftp module uses by default. These clients
include:
SSH Protocol Version
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
SFTPLog when trying to connect to mod_sftp:
Bad protocol version 'SSH-1.99-3.2.9.1 SSH Secure Shell (non-commercial)' from x.x.x.xTo support such clients in
mod_sftp, use
SFTPOptions to enable compatibility with
older protocol versions, e.g.:
# Support old ssh.com/Tectia clients SFTPOptions OldProtocolCompat
SFTP Protocol Versions
Some SFTP clients do not properly handle some of the newer SFTP protocol
versions. These clients include:
SFTPClientMatch rule to restrict
the SFTP protocol versions offered by the mod_sftp module,
e.g.:
# Only support SFTP protocol version 1 through 3 for WinSCP and CuteFTP SFTPClientMatch WinSCP|ClientSftp sftpProtocolVersion 1-3
KEXINIT Optimization
Some SFTP clients do not like this
KEXINIT optimization that the
mod_sftp module uses. These clients include:
Net::SSH::Perl, Net::SFTP Perl modules
# Disable the KEXINIT optimization at the cost of latency SFTPOptions PessimisticKexinit
FIPS Compliance
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
FIPS-140.
How then would you build OpenSSL and mod_sftp, and use them
such that mod_sftp would be FIPS-compliant? Using OpenSSL in
FIPS mode requires quite a few steps. First, you would configure
proftpd to use the mod_sftp module as normal,
assuming your OpenSSL installation has been compiled with FIPS support:
./configure --enable-openssl --with-modules=mod_sftp ...
Compiling proftpd requires the following, for FIPS support
to work properly:
make CC=/path/to/openssl/bin/fipsld FIPSLD_CC=gccThe
FIPSLD_CC variable should point to your normal C compiler,
e.g. gcc. The use of this fipsld program
is mandatory. The FIPS standard requires that the linking process
happen a very specific way, involving verification of calculated and expected
checksums of compiled code, etc. The OpenSSL packages with FIPS
support supply this fipsld program which will link the compiled
code according to the FIPS specifications. If you do not use
fipsld, then attempts to use OpenSSL in FIPS mode will fail.
For example, you would see the following if starting a proftpd
daemon which has not been linked using fipsld while requesting
use of FIPS:
- mod_sftp/0.0: unable to use FIPS mode: (unknown) - Fatal: unable to load module 'mod_sftp.c': Operation not permitted
Now, assuming you have compiled and installed your proftpd
properly, e.g.:
make CC=/path/to/openssl/bin/fipsld FIPSLD_CC=gcc make CC=/path/to/openssl/bin/fipsld FIPSLD_CC=gcc installyou will now be ready to start
proftpd.
In order for FIPS mode to be effective, OpenSSL must be told to run in FIPS
mode from the very beginning. The mod_sftp module initializes the
OpenSSL library when the mod_sftp module is loaded, before the
proftpd.conf file is parsed. Thus the requesting of FIPS mode
cannot be done via a setting in proftpd.conf. (Annoying,
I know.)
Instead, you must use the -D command-line parameter when starting
proftpd (see the docs for the <IfDefine> and
Define directives) to define a specific variable, which the
mod_sftp module will look for. Specifically, you will need to
start proftpd like thus:
/path/to/proftpd -DSFTP_USE_FIPS ...This will define the
SFTP_USE_FIPS variable; this tells
mod_sftp to initialize OpenSSL using FIPS mode. When this works,
you will see the following when proftpd starts up:
- mod_sftp/0.0: FIPS mode enabled
For additional reading on OpenSSL and FIPS, see:
http://www.openssl.org/docs/fips/SecurityPolicy-1.1.1.pdf http://www.openssl.org/docs/fips/UserGuide-1.1.1.pdf
Example Configuration
When using mod_sftp to handle SFTP connections, you will want
to create a separate <VirtualHost> section for the
mod_sftp configuration. SSH2 (and thus SFTP) requires a different
port than FTP; in order to listen on different ports, proftpd
requires different <VirtualHost> sections. You can have
multiple <VirtualHost> sections for the same address
(IP address or DNS name), just different Port directives.
<IfModule mod_sftp.c>
<VirtualHost a.b.c.d>
SFTPEngine on
SFTPLog /etc/proftpd/sftp/sftp.log
# Configure the server to listen on the normal SSH2 port, port 22
Port 22
# Configure both the RSA and DSA host keys, using the same host key
# files that OpenSSH uses.
SFTPHostKey /etc/ssh_host_rsa_key
SFTPHostKey /etc/ssh_host_dsa_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>
Logging
The mod_sftp module supports different forms of logging. The
main module logging is done via the SFTPLog directive. For
debugging purposes, the module also uses trace logging, via the module-specific "scp", "sftp",
and "ssh2" log channels. Thus for trace logging, to aid in debugging, you
would use the following in your proftpd.conf:
TraceLog /path/to/sftp-trace.log Trace scp:20 sftp:20 ssh2:20This trace logging can generate large files; it is intended for debugging use only, and should be removed from any production configuration.
Suggested Future Features
The following lists the features I hope to add to mod_sftp,
according to need, demand, inclination, and time:
MaxTransferPerHost,
MaxTransfersPerUser, MaxRetrieveFileSize,
MaxStoreFileSize directives
Frequently Asked Questions
Question: When I telnet to port 22 of other SSH2 servers,
I see the SSH2 version banner displayed, e.g.:
This pre-emptive sending of the first key exchange message is an optimization.
The SSH2 protocol (and many SSH2 servers) start off doing:
The
This optimization was added after reading this informative paper on SSH and
SSL/TLS by Peter Gutmann:
Question: My SSH2/SFTP client dies when trying to
connect to
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.e. 2 ^ 32 - 1).
This maximum window size is what
As another example, the WS_FTP Pro
client has this same problem; in the client, you will see something like
the following error:
There are two approaches for handling such cases. You can use the
The larger the channel window size, the better. (Note that the SSH2 channel
window size has absolutely no 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.
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.
Question: Can I configure
Question: How can I configure
Question: How can I configure
Question: I followed the instructions to convert
my authorized keys from OpenSSH to RFC4716 format, yet I see the following
error in my
Chances are that the offending line in the RFC4716 key is a "Comment: " header
that is too long. Simply delete that "Comment: " line; the
Question: Is it true that using CBC mode ciphers in
SSH is insecure?
However, these attacks can be mitigated by countermeasures in the SSH
implementation. The use of
Question: I am trying to use
Question: If I use a configuration like this:
However, the SFTP protocol sends the file metadata as part of the normal upload. In the configuration above, the limit on
Question: I use
By default, the
In ProFTPD 1.3.4rc1, honoring of the
Question: Why can't I use
# telnet example.com 22
Trying 1.2.3.4...
Connected to example.com.
Escape character is '^]'.
SSH-1.99-OpenSSH_5.1
However, when I telnet to the port on which mod_sftp is listening,
I see the version banner plus some data which can't be rendered in the terminal.
What is that extra data?
Answer: The short answer is that mod_sftp
is pre-emptively sending the first key exchange data; it is this data which is
not displayed well.
(1) client ------------ connect -------------> server
(2) client <-------- version banner ---------- server
(3) client --- client's first key exchange --> server
(4) client <-- server's first key exchange --- server
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.
mod_sftp module avoids one unnecessary TCP packet+ACK by
sending its version banner and its first key exchange message in the same TCP
packet:
(1) client ------------ connect -------------> server
(2) client <-- version banner/1st key exch---- server
(3) client --- client's first key exchange --> server
This helps cut down on the latency during startup, since mod_sftp
saves on one TCP round-trip time.
Performance Characteristics of Application-level Security Protocols
mod_sftp. The login succeeds, but then the client
is disconnected. The client logs show something like:
ServerMaxPacket(32768) ServerWindow(-1) (from WS_FTP)
or
debug1: channel 0: open confirm rwindow -1 rmax 32768 (from OpenSSH_3.0.2p1)
Answer: 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.)
mod_sftp uses by default.
However, some client implementations use a signed data type for
holding this value. This means that the value that mod_sftp
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.
Started subsystem "sftp" on channel 0760a2ce
error 84350000 initializing sftp protocol
Sending channel close message for channel 0760a2ce
SSH Transport closed.
SFTPClientMatch directive to
set a smaller channel window size for that particular client, e.g.:
SFTPClientMatch ".*WS_FTP.*" channelWindowSize 256MB
SFTPClientMatch ".*Axway" channelWindowSize 256MB
or you can use SFTPClientMatch to set a general channel window
size for all clients:
SFTPClientMatch .* channelWindowSize 256MB
mod_sftp to be
an OpenSSH subsystem, e.g. by using the following in my
sshd_config file:
Subsystem sftp /usr/local/sbin/proftpd
Answer: No. The mod_sftp 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, etc.
proftpd
so that it can handle both FTP and SFTP at the same time?
Answer: The key to doing this is to create a
<VirtualHost> section just for the mod_sftp
configuration, listening on the address and port that you wish, e.g.:
# The FTP configuration
DefaultAddress a.b.c.d
Port 21
<IfModule mod_sftp.c>
<VirtualHost a.b.c.d>
# The SFTP configuration
Port 22
SFTPEngine on
...
</VirtualHost>
</IfModule>
proftpd
so that it only accepts SFTP connections (via mod_sftp), and no
FTP connections?
Answer: Use the following in your
proftpd.conf:
<Limit LOGIN>
DenyAll
</Limit>
<VirtualHost a.b.c.d>
<Limit LOGIN>
AllowAll
</Limit>
SFTPEngine on
...
</VirtualHost>
The idea is to use the <Limit LOGIN> to deny all logins to
any/all virtual host sections except for the mod_sftp
section.
SFTPLog:
mod_sftp/0.9.7[31050]: line too long (74) on line 1 of 'authorized_keys'
What can I do to fix this?
Answer: OpenSSH's ssh-keygen tool had a
bug where the RFC4716 keys it would generate might not comply to the RFC; see
the OpenSSH bug
filed for this issue.
mod_sftp ignores this header.
Answer: It is true that there are a couple of published
theoretical attacks against the SSH protocol when CBC ciphers are
used, including Rogaway, Wai, and Bellare (see RFC4251, Section 9.3.1) and
"Plaintext Recovery Attacks Against SSH" (CPNI-957037).
SSH_MSG_IGNORE 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
mod_sftp module as security measures.
ListOptions
to change what is displayed for files in my SFTP clients, but it is not working.
Why?
Answer: Unlike FTP, in SFTP it is the client,
not the server, which determines what to display to the end user.
Thus the ListOptions directive is not honored by
mod_sftp.
<Directory /path/to/upload>
<Limit WRITE>
AllowAll
</Limit>
<Limit SITE_CHMOD>
DenyAll
</Limit>
</Directory>
then why do my SFTP uploads fail, when the same configuration allows uploads to succeed using FTP?
Answer: When a file is uploaded using FTP, the only
parts of the file uploaded are its contents but not the file
metadata (e.g. not the file timestamps or permissions). Separate
FTP commands are used to sent the file metadata to the server.
SITE CHMOD
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:
SFTPOptions IgnoreSFTPUploadPerms
in your mod_sftp configuration.
UserOwner and
GroupOwner in my mod_sftp configuration, but they
are not being applied properly. Is this a bug?
Answer: No.
mod_sftp module drops root privileges as soon
as it can, which is just after the user has been authenticated. Without
root privileges, mod_sftp cannot change the ownership of files
uploaded via SFTP/SCP as per UserOwner/GroupOwner
settings.
UserOwner and
GroupOwner directives was added to the mod_sftp
module. However, you will also need to add the following to your
mod_sftp configuration to make them work properly:
RootRevoke off
This explicitly tells the mod_sftp to not drop root
privileges after authentication, and instead to keep them for the duration
of the session.
ssh to connect
to my proftpd+mod_sftp server? When I try, I see:
# ssh user@host
Enter passphrase for key '/home/user/.ssh/id_rsa':
PTY allocation request failed on channel 0
shell request failed on channel 0
Answer: The mod_sftp module supports
file transfers via SFTP and SCP. It does not support shell access,
which is what the ssh command-line client tries to use. The
above error messages from ssh show that mod_sftp
refused the shell access requests.