Project Description


This projects provides a free FTP/FTPS client and class library available on any platform supporting the .Net Framework 2.0 or Mono 2.0. This currently includes: Microsoft Windows 2000 SP4/XP SP2/2003/Vista/2008, Linux, Mac OS X 10.4 and above, and, to some extent, Sun Solaris.

Please see http://www.mono-project.com for a complete list of platforms supported by Mono 2.0.

Implemented RFCs:

959, 2228, 2389, 2428, 2640, 3659, 4217

FTPS (sometimes called FTPES or explicit FTPS) is implemented as described in the RFC 4217 and RFC 2228 documents. http://www.ietf.org/rfc/rfc4217.txt Support for the so called implicit FTPS has also been added (although not standard).

FTPS should not be confused with SFTP (FTP over SSH).

For more information please see http://en.wikipedia.org/wiki/FTPS

Note: not all the FTP commands described in the RFC documents are curently implemented (some of them are obsolete, others were not necessary for the purposes of this project). Please see Implemented FTP commands below for a detailed list of implemeted commands

Follow alexpilotti on Twitter

CBSLogo_thumb.png

The FTP/FTPS Client

The aim of this FTP/FTPS client is to support the advanced features provided by most modern FTP servers, primarily, but not limited to, encryption via SSL/TLS and UTF8. A list of the implemented RFC standards and specific commands follows.

The idea of this client was born while preparing some material for a technical speech session I was going to give at the Italian Microsoft TechDays - WPC 2008, about IIS 7.0 new features, including the Microsoft FTP for IIS 7.0 add in and its freshly introduced support for SSL/TLS.

One of the main problems with standard FTP communications, is that all the username / password communication is performed in clear text, easily eavesdropped by sniffing the network traffic. Altough FTP is one of the oldest Internet protocols still in use today, some of its features are still largely needed as they can't be easily replaced by, for example, an HTTP server.

The SSL/TLS encryption feature, as stated in the RFC 4217 document http://www.ietf.org/rfc/rfc4217.txt, provides a solution for this and other security related limitations. Support for SSL/TLS has been introduced in the most used FTP servers: Microsoft FTP for IIS 7.0, vsftpd, wu-ftpd, FileZilla server, to name a few. Note: vsftpd FTPS support requires version 2.1.0 or a small patch for version 2.0.7.

Looking for a free client to be used during my session demos, showing interoperability with other platforms, I realized that there was no single piece of software supporting all the features I needed. Furthermore, I wanted to provide a sample on how to connect to a FTP server using SSL using Microsoft .Net and the Powershell, but the standard System.Net.FTPWebRequest provided by the framework was not powerful enough (more on this below).

That was enough to start this project. The client provides also a wide range of options and commands via command line arguments, making it fully functional when used in scripts, without the shortcomings of the standard FTP clients available on most platforms.

Portability among platforms (via the .Net Framework 2.0 and Mono 2.0) and compatibility with all the relevant FTPS servers is also a mandatory goal for this project.

Please see below for some Quick usage samples and the full Command line reference.

Microsoft Powershell integration

The development of specifc CmdLets is in progress. Please stay tuned.

Portable GUI

A free portable GUI is also planned and will be developed if there's enough feedback on the project.

Quick usage samples

Note: execute mono ftps.exe <arguments> when using Mono.

  • Show the directory contents of a remote directory using anonymous authentication on standard FTP (without SSL/TLS):

 

ftps -h ftp.yourserver.com -ssl ClearText -l /pub
  • Connect to the server using SSL/TLS during authentication or clear text mode (standard FTP) if FTPS is not supported:

 

ftps -h ftp.yourserver.com -U alex -l /some/path/
  • Connect to the server using SSL/TLS on the control channel, accepting invalid certificates without prompting:

 

ftps -h ftp.yourserver.com -U alex -ssl ControlChannelRequired 
     -sslInvalidServerCertHandling Accept -l /some/path
  • Download a remote file using control and data channel SSL/TLS encryption:

 

ftps -h ftp.yourserver.com -U alex -ssl DataChannelRequired 
     -g /remote/path/somefile.txt /local/path/
  • Upload a local file with a control channel encrypted during authentication only:

 

ftps -h ftp.yourserver.com -U alex -ssl CredentialsRequired 
     -p /local/path/somefile.txt /remote/path/
  • Recursively download a whole directory tree:

 

ftps -h ftp.yourserver.com -r -g /remote/path/* \local\path\
  • Export the server's X.509 certificate on a FTPS connection:

 

ftps -h ftp.yourserver.com -U alex -expCert serverCert.cer
  • Implicit FTPS connection on port 21:

 

ftps -h ftp.yourserver.com -U alex -port 21 -ssl Implicit -l


Command line reference

The command line reference, available by executing ftps -? or mono ftps.exe -? using Mono, follows:

Usage: ftps [options] <command> [command specific arguments]



Commands:

-?, -help

Shows help and usage info

-d, -delete

Deletes a remote file

-expCert, -exportSslServerCert

Exports the server's SSL/TLS X.509 certificate. The export format is managed by the "sslX509ExportFormat" option

-f, -features

Prints the list of features supported by the server, as returned by the FTP FEAT command

-g, -get, -download

Downloads the given files in the current directory. File names may include wildcards. Operates recursively if the "r" option is specified

-l, -list

Returns the contents of the given directory, or the default directory if no name is provided

-md, -mkdir

Creates a remote directory

-p, -put, -upload

Uploads the given files or directory contents. File names may include wildcards. Operates recursively if the "r" option is specified

-pa, -putAppend

Uploads a file appending it's contents if the given remote file already exists

-pu, -putUnique

Uploads a file with a unique name

-rd, -rmdir

Removes a remote directory

-rn, -rename

Renames a remote file

-sys, -system

Returns a brief description of the remote system

-cust, -custom

Sends the given FTP command to the server. Note: only the control channel reply is returned


Generic options:

-dm, -dataMode

Active or Passive (default) data connection mode

-h, -hostname

Name or IP address of the remote host to connect to

-lf, -logFile

ftp commands and server replies log file name

-ltfs, -logFileTimeStamp

Adds a timestamp to every command and reply in the log file

-noCopyrightInfo

Avoids displaying the copyright information header

-oda, -overrideDataAddress

Use the control connection's remote address instead of the one returned by the PASV command

-P, -password

Password to be used in case of non anonymous connections. If omitted it will be requested before connecting. Passing this information as a command line parameter is strongly discouraged for security reasons

-port

TCP/IP connection port, default is: 21 for standard FTP or explicit FTPS, 990 for implicit FTPS

-r, -recursive

Enable recursion to download or upload entire directory trees

-t, -timeout

TCP/IP connection timeout in seconds (default 120s)

-tm, -transferMode

Transfer mode / representation type. "ASCII" or "Binary" (default)

-U, -username

Username used to perform the connection. If omitted an anonymous connection will be performed

-v, -verbose

Verbose output


SSL/TLS specific options:

-ssl, -tls

SSL/TLS support. Possible values are:

  • ClearText (Standard FTP, no SSL/TLS support)
  • CredentialsRequested
  • CredentialsRequired
  • ControlChannelRequested
  • ControlChannelRequired
  • DataChannelRequested (Default)
  • DataChannelRequired
  • ControlAndDataChannelsRequested
  • ControlAndDataChannelsRequired (most secure)
  • All (alias for ControlAndDataChannelsRequired)
  • Implicit


-sslClientCertPath

X.509 client certificate file path

-sslInvalidServerCertHandling

Invalid X.509 server certificate handling. Valid values are:

  • Accept
  • Prompt (default)
  • Refuse


-sslMinCipherStrength

Min. cipher algorithm strength (e.g: 168). Default is 0

-sslMinHashStrength

Min. hash algorithm strength (e.g: 160). Default is 0

-sslMinKeyExStrength

Min. key exchange algorithm strength (e.g: 1024). Default is 0

-sslX509ExportFormat

X509 certificate export format. Not all formats are available on all platforms. Supported values are:

  • Cert (default)
  • Pkcs12
  • SerializedCert

The FTP/FTPS class library

The System.Net.FTPWebRequest class provided by the .Net Framework, is perfect for simple tasks (e.g. downloading or uploading a file or getting a directory list) and supports also SSL via the EnableSsl property See: http://blogs.msdn.com/adarshk/archive/2005/04/22/410925.aspx . So why a new class for that?

The point is that SSL support in FTP is more that an on/off switch (as in HTTP/HTTPS). FTP requires two separate connections: one for the commands (the control connection) and one for the data (the data connection), for downloads, uploads and directory listings.
FTPWebRequest.EnableSsl simply forces the use of SSL on both of them. The problem is that this is not always suitable.

FTP connections are tipically a pain for firewalls, because the control connection uses a standard TCP port (21), but data connections (in so called passive mode), tipically listen on a random port, communicated to the client on the control channel. Well, if the connection is not encrypted, as in standard FTP, firewalls are able to do some packet inspection, get the port number sent to the client and allow the connection from that client to the server. To cut a long story short, encrypting the control channel means that firewalls will not be able to do packet inspections and, you guessed it, this is where the problems begin. Please see http://en.wikipedia.org/wiki/FTPS for more on the subject.

There's a partial solution to this problem:

Encrypting the control channel during the credentials exchange (USER/PASS commands) and reverting to clear text after that. This is of course far below the goals of the SSL/TLS support, but it's enough for a very large number of needs and is supported by all the main FTPS servers.

This class library provides a number of SSL/TLS related options to deal with this and other issues.

Aside that, the class library provides support for a large number of standard FTP commands and some very useful features:

  • Tracking of the download status via delegate based callbacks (useful to display the download/upload progress)
  • Recursive directory trees downloads and uploads
  • Support for UTF8 in commands and directory listings (by explicitly setting OPTS UTF8 ON if available in the features returned by the FEAT command)
  • IPV6 support (planned)
  • Multi platform (Microsoft Windows, Linux, Mac OS X, did I already said that?) ;-)


The full MSDN style documentation will be released shortly.

In order to use the FTPS class library, add the AlexPilotti.FTPS.Client.dll assembly to your project References.
The assembly is available along with the FTPS client on the Releases page.

The class library is distributed as free software and can be freely used in your projects, under the terms of the LGPL license.

Simple class library usage sample in C# (any other CLR compliant language is also supported, e.g.: VB.Net, C++/CLI, etc.):

using AlexPilotti.FTPS.Client;
using AlexPilotti.FTPS.Common;
using System.Net;


class Test
{
    public static void Main()
    {
        using (FTPSClient client = new FTPSClient())
        {
            // Connect to the server, with mandatory SSL/TLS 
            // encryption during authentication and 
            // optional encryption on the data channel 
            // (directory lists, file transfers)
            client.Connect("ftp.yourserver.com", 
                           new NetworkCredential("yourUsername", 
                                                 "yourPassword"), 
                           ESSLSupportMode.CredentialsRequired | 
                           ESSLSupportMode.DataChannelRequested);
			
            // Download a file
            client.GetFile("/path/to/remotefile.jpg", "c:\\local\\path\\");
        }
    }
}

Snapshots

AlexFTPS on Windows:

This screenshots shows the transfer status available during downloads / uploads.

ftps_Vista_640.png

AlexFTPS on Linux:

ftps_Linux_640.png

AlexFTPS on Mac OS X:

ftps_Mac_OS_X.png

Implemented FTP commands

Note: RFC 959 is listed also for commands introduced in previous documents.

Command name Notes RFC
APPE   959
AUTH TLS supported 2228
CCC   2228
CDUP   959
CLNT Required by some servers ?
CWD   959
DELE   959
FEAT   2389
LANG   2640
LIST   959
MDTM   3659
MKD   959
NLST   959
NOOP   959
OPTS Mainly UTF8 support 2389
PASS   959
PASV   959
PROT PROT P, C support 2228
PSBZ   2228
PWD   959
QUIT   959
RETR   959
RMD   959
RNFR   959
RNTO   959
SIZE   3659
STOR   959
STOU   959
SYST   959
TYPE ASCII and Image (Binary) representation types supported 959
USER   959

 

NUnit tests

Will be posted shortly!

TODO

Here's the list of things that need to be implemented.

  • Proxy support
  • More RFC 2228 commands
  • Internationalization

vsftpd patch

There is a small bug in vsftpd 2.0.7 related to OpenSSL contexts, confirmed by the author and solved in version 2.1.0 which prevents full SSL/TLS compatibility.
Here's a workaround for version 2.0.7. Just apply this patch to ssl.c: vsftpd-2.0.7-ssl-diff.txt It's just 3 lines of code! :-)
Please note: this is an unofficial patch.


Well, that's all by now. Please provide your comments, feature requests, bug reports, etc. on the Discussion page.



Alessandro Pilotti
MVP / IIS

MVP_Horizontal_FullColor_small.png

Last edited Mar 16, 2013 at 4:33 PM by alexp, version 46