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 calledimplicit 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 seeImplemented FTP commands below for a detailed list of implemeted commands
![Follow alexpilotti on Twitter]()
![CBSLogo_thumb.png]( "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 theItalian Microsoft TechDays - WPC 2008, about IIS 7.0 new features, including theMicrosoft 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 smallpatch 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 standardSystem.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 fullCommand 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 theEnableSsl 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 (thecontrol connection) and one for the data (thedata 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 calledpassive 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 seehttp://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
{
publicstaticvoid 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 Vista:
This screenshots shows the transfer status available during downloads / uploads.
![ftps_Vista_640.png]( "ftps_Vista_640.png")
AlexFTPS on Linux:
![ftps_Linux_640.png]( "ftps_Linux_640.png")
AlexFTPS on Mac OS X:
![ftps_Mac_OS_X.png]( "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]( "MVP_Horizontal_FullColor_small.png")
