FTP/SSL Tutorial

Back to tutorial list...

Table of content

• FTP/SSL basics
• Namespaces and assemblies
• Connecting to an FTP/SSL server using SSL
• Getting information about SSL connection
• Specifying SSL parameters
• Validating and examining server certificates
• Authenticating the client using a certificate

# FTP/SSL basics

Rebex FTP/SSL for .NET is a versatile file-transfer component for .NET languages (such as C# or VB.NET). It allows you to transfer files directly from your application using FTPS, an extension of FTP which is quickly becoming a standard for secure FTP. This protocol is also known as FTP over SSL or FTP over TLS and is defined by RFC 4217.

Please note that SSL and TLS are different versions of the same protocol - TLS 1.0 is a name for what was supposed to be SSL 3.1. When we use the term "SSL", we generally mean "SSL or TLS".

back to top...

# Namespaces and assemblies

There are several assemblies you might need to reference in your project to be able to use all features of FTP/SSL for .NET. Rebex.Net.Ftp.dll is needed for any FTP operations. Rebex.Net.SecureSocket.dll contains classes used to specify additional SSL parameters or making it possible to implement advanced functionality. Rebex.Security.dll contains certificate management classes for working with certificates and certificate stores.

To gain access to all functionality, import the following namespaces in your source files.

C#

using Rebex.Net;
using Rebex.Security.Certificates;

VB.NET

Imports Rebex.Net
Imports Rebex.Security.Certificates

back to top...

# Connecting to an FTP/SSL server using SSL

There are two methods to connect to a secure FTP server:

1) Explicit SSL protection of the FTP session

Client connects to FTP server in a usual non-protected way, usually to port 21 was assigned to FTP protocol. When it is desired to protect the connection using SSL, an SSL negotiation is initialized, control connection is secured and all following communication is being protected. Protection of data connections is optional.

C#

// Create an instance of the Ftp class. 
Ftp ftp = new Ftp();

// Connect securely using explicit SSL. 
// Use the third argument to specify additional SSL parameters. 
ftp.Connect (hostname, 21, null, FtpSecurity.Explicit);

// Connection is protected now, we can log in safely. 
ftp.Login (username, password);

// Specifies whether protection of transferred data is required. 
// Default value of this property is "true", so this is not required. 
ftp.SecureTransfers = true;

VB.NET

' Create an instance of the Ftp class. 
Dim ftp As New Ftp()

' Connect securely using explicit SSL. 
' Use the third argument to specify additional SSL parameters. 
ftp.Connect(hostname, 21, Nothing, FtpSecurity.Explicit)

' Connection is protected now, we can log in safely. 
ftp.Login(username, password)

' Specifies whether protection of transferred data is required. 
' Default value of this property is "true", so this is not required. 
ftp.SecureTransfers = True 

Explicit protection means that it is possible to secure the connection at any moment. If you don't know whether you will need the protection on not at the connection time, you might want to connect using the ordinary unencrypted FTP protocol and secure the connection later.

C#

Ftp ftp = new Ftp();

// Connect to the server with no protection. 
ftp.Connect (hostname, 21);

// Upgrade connection to SSL. 
// This method also accepts an argument to specify SSL parameters. 
ftp.Secure ();

// Connection is protected now, we can log in safely. 
ftp.Login (username, password);

VB.NET

Dim ftp As New Ftp()

' Connect to the server with no protection. 
ftp.Connect(hostname, 21)

' Upgrade connection to SSL. 
' This method also accepts an argument to specify SSL parameters. 
ftp.Secure()

' Connection is protected now, we can log in safely. 
ftp.Login(username, password)

2) Implicit SSL protection of the FTP session

FTPS protocol was originally assigned a separate port by the IANA. Upon connection to this port, an SSL negotiation starts immediately and the control connection is secured. All data connections are also secured implicitly in the same way. This is similar to the approach used by HTTPS.

This approach is not favored by the IETF and is deprecated. It is supported by Rebex FTP/SSL for interoperability with older servers, but it is strongly recommended to use the explicit protection instead whenever possible.

C#

Ftp ftp = new Ftp();

// Connect securely using implicit SSL. 
// Use the third argument to specify additional SSL parameters. 
ftp.Connect (hostname, 990, null, FtpSecurity.Implicit);

// Connection is protected now, we can log in safely. 
ftp.Login (username, password);

VB.NET

Dim ftp As New Ftp()

' Connect securely using implicit SSL. 
' Use the third argument to specify additional SSL parameters. 
ftp.Connect(hostname, 990, Nothing, FtpSecurity.Implicit)

' Connection is protected now, we can log in safely. 
ftp.Login(username, password)

back to top...

# Getting information about SSL connection

You can easily get information about the SSL connection using properties of Ftp.TlsSocket.

C#

Ftp ftp = new Ftp();

// Connect securely using explicit SSL.  
ftp.Connect(hostname, port, null, FtpSecurity.Explicit);

// The Cipher property contains a lot of  
// information about the current cipher  
TlsCipher cipher = ftp.TlsSocket.Cipher;
Console.WriteLine("Protocol: {0}", cipher.Protocol);
Console.WriteLine("Cipher: {0}", cipher.CipherAlgorithm);
Console.WriteLine("Key exchange: {0}", cipher.KeyExchangeAlgorithm);
Console.WriteLine("MAC algorithm: {0}", cipher.MacAlgorithm);
Console.WriteLine("All together: {0}", cipher);

// ServerCertificate property provides access  
// to server certificate. The first certificate in the chain  
// is the server's certificate. 
CertificateChain serverCert = ftp.TlsSocket.ServerCertificate;
Console.WriteLine("Subject: {0}", serverCert[0].GetSubject());
Console.WriteLine("Issuer: {0}", serverCert[0].GetIssuer());

VB.NET

Dim ftp As New Ftp()

' Connect securely using explicit SSL.  
ftp.Connect(hostname, port, Nothing, FtpSecurity.Explicit)

' The Cipher property contains a lot of  
' information about the current cipher  
Dim cipher As TlsCipher = ftp.TlsSocket.Cipher
Console.WriteLine("Protocol: {0}", cipher.Protocol)
Console.WriteLine("Cipher: {0}", cipher.CipherAlgorithm)
Console.WriteLine("Key exchange: {0}", cipher.KeyExchangeAlgorithm)
Console.WriteLine("MAC algorithm: {0}", cipher.MacAlgorithm)
Console.WriteLine("All together: {0}", cipher)

' ServerCertificate property provides access  
' to server certificate chain. The first certificate in the chain 
' is the server's certificate. 
Dim serverCert As CertificateChain = ftp.TlsSocket.ServerCertificate
Console.WriteLine("Subject: {0}", serverCert(0).GetSubject())
Console.WriteLine("Issuer: {0}", serverCert(0).GetIssuer())

back to top...

# Specifying SSL parameters

It is possible to affect many aspects of SSL such us specifying which protocol versions to use or what cipher suites to allow.

It is a good idea to disable weak cipher suites and only allowing the strong ones.

C#

// Create an instance of TlsParameters class and 
// specify desired arguments. 
TlsParameters par = new TlsParameters ();
// Only use suites that are currently considered secure. 
par.AllowedSuites = TlsCipherSuite.Secure;
// Allow both SSL 3.0 and TLS 1.0 protocols to be used. 
par.Version = TlsVersion.SSL30 | TlsVersion.TLS10;
// You can also specify the common name of 
// the FTP server if you provide your own parameters. 
par.CommonName = hostname;

// Connect securely using explicit SSL. 
// The third argument refers to the parameters class. 
ftp.Connect (hostname, 21, par, FtpSecurity.Explicit);

// Connection is protected now, we can log in safely. 
ftp.Login (username, password);

VB.NET

' Create an instance of TlsParameters class and 
' specify desired arguments. 
Dim par As New TlsParameters()
' Only use suites that are currently considered secure. 
par.AllowedSuites = TlsCipherSuite.Secure
' Allow both SSL 3.0 and TLS 1.0 protocols to be used. 
par.Version = TlsVersion.SSL30 Or TlsVersion.TLS10
' You can also specify the common name of 
' the FTP server if you provide your own parameters. 
par.CommonName = hostname

' Connect securely using explicit SSL. 
' The third argument refers to the parameters class. 
ftp.Connect(hostname, 21, par, FtpSecurity.Explicit)

' Connection is protected now, we can log in safely. 
ftp.Login(username, password)

Specifying the supported set of ciphers one by one is also possible. If you only accept DSA certificates and AES encryption, you can have that.

C#

// Only use the specified cipher suites. 
TlsParameters par = new TlsParameters ();
par.AllowedSuites =
	TlsCipherSuite.DHE_DSS_WITH_AES_256_CBC_SHA |
	TlsCipherSuite.DHE_DSS_WITH_AES_128_CBC_SHA;

VB.NET

' Only use the specified cipher suites. 
Dim par As New TlsParameters()
par.AllowedSuites = _
	TlsCipherSuite.DHE_DSS_WITH_AES_256_CBC_SHA Or _
	TlsCipherSuite.DHE_DSS_WITH_AES_128_CBC_SHA

back to top...

# Validating and examining server certificates

Even though Rebex FTP/SSL validates server certificate automatically by default, it is often desired to extend this process, for example by adding the ability to ask the user whether to accept or reject the server certificate. In other scenarios, you might want to use your own code to decide. This is possible by implementing a custom certificate validator.

C#

// A custom certificate verifier class. 
// Implements ICertificateVerifier interface. 
public class CustomVerifier : ICertificateVerifier
{
    // This method gets called during the SSL handshake 
    // process when the certificate chain is received from the server. 
    public TlsCertificateAcceptance Verify
        (TlsSocket socket,
        string commonName,
        CertificateChain certChain)
    {
        // Use the build-in validation method to validate the chain. 
        // It is up to you to use another validation method if needed. 
        ValidationResult res = certChain.Validate (commonName, 0);

        // Accept the certificate if the chain is valid. 
        if (res.Valid)
            return TlsCertificateAcceptance.Accept;

        // If the chain is not valid, let's display the certificate 
        // information and validation status to the user and let 
        // him decide what to do. 
        
        Certificate cert = certChain[0];
        bool shouldAccept = SomeCustomDialog (cert, res.Status);

        if (shouldAccept)
            return TlsCertificateAcceptance.Accept;
        else 
            return TlsCertificateAcceptance.Other;
    }
}


// To make your validator the current validator for 
// an FTP session: 

Ftp ftp = new Ftp();

// Create an instance of TlsParameters class and 
// set the certificate verifier to an instance of CustomVerifier. 
// You also have to specify the common name of 
// the FTP server to be passed to your verifier. 
TlsParameters par = new TlsParameters ();
par.CertificateVerifier = new CustomVerifier ();
par.CommonName = hostname;

// Connect securely using explicit SSL. 
// The third argument refers to the parameters class. 
ftp.Connect (hostname, 21, par, FtpSecurity.Explicit);

// Connection is protected now, we can log in safely. 
ftp.Login (username, password);

VB.NET

' A custom certificate verifier class. 
' Implements ICertificateVerifier interface. 
Public Class CustomVerifier
    Implements Rebex.Net.ICertificateVerifier

    ' This method gets called during the SSL handshake 
    ' process when the certificate chain is received from the server. 
    Public Overloads Function Verify _
        (socket As TlsSocket, _
        commonName As String, _
        certChain As CertificateChain) _
        As TlsCertificateAcceptance _
        Implements ICertificateVerifier.Verify

        ' Use the build-in validation method to validate the chain. 
        ' It is up to you to use another validation method if needed. 
        Dim res As ValidationResult = certChain.Validate(commonName, 0)

        ' Accept the certificate if the chain is valid. 
        If res.Valid Then 
            Return TlsCertificateAcceptance.Accept
        End If 

        ' If the chain is not valid, let's display the certificate 
        ' information and validation status to the user and let 
        ' him decide what to do. 
        
        Dim cert As Certificate = certChain(0)
        Dim shouldAccept As Boolean = SomeCustomDialog(cert, res.Status)

        If shouldAccept Then 
            Return TlsCertificateAcceptance.Accept
        Else 
            Return TlsCertificateAcceptance.Other
        End If 
    End Function 
End Class 


' To make your validator the current validator for 
' an FTP session: 

Dim ftp As New Ftp()

' Create an instance of TlsParameters class and 
' set the certificate verifier to an instance of CustomVerifier. 
' You also have to specify the common name of 
' the FTP server to be passed to your verifier. 
Dim par As New TlsParameters()
par.CertificateVerifier = New CustomVerifier()
par.CommonName = hostname

' Connect securely using explicit SSL. 
' The third argument refers to the parameters class. 
ftp.Connect(hostname, 21, par, FtpSecurity.Explicit)

' Connection is protected now, we can log in safely. 
ftp.Login(username, password)

There are tow verifiers provided by Rebex FTP/SSL. The default verifier is CertificateVerifier.Default and uses CryptoAPI to validate the certificate chain. There is also CertificateVerifier.AcceptAll verifier that does no validation and accepts anything - this can be handy while testing, but don't use it in your production code.

back to top...

# Authenticating the client using a certificate

FTPS server might be configured to request the client to authenticate using its certificate during SSL negotiation. Client either complies or informs the server that no it has no suitable certificate available. In the latter case, the server can optionally refuse to proceed negotiating. Rebex FTP/SSL for .NET makes it possible to select one of the built-in certificate request handlers or to implement a custom handler if they are not sufficient.

By default, client authentication is disabled - certificate request handler is set to the built-in CertificateRequestHandler.NoCertificate handler that does not try to find any certificate and just informs the server that no certificate is available.

However, client authentication can be enabled easily by using the second build-in certificate request handler that is able to searches the user's certificate store for a suitable certificate with a private key, and if one is found, it is used to authenticate the client.

C#

Ftp ftp = new Ftp();

// Create an instance of TlsParameters class and 
// set the certificate request handler to  
// CertificateRequestHandler.StoreSearch. 
// You also have to specify the common name of 
// the FTP server if you provide your own parameters. 
TlsParameters par = new TlsParameters ();
par.CertificateRequestHandler = CertificateRequestHandler.StoreSearch;
par.CommonName = hostname;

// Connect securely using explicit SSL. 
// The third argument refers to the parameters class. 
ftp.Connect (hostname, 21, par, FtpSecurity.Explicit);

// Connection is protected now, we can log in safely. 
// Some servers may not require login if the client 
// successfully authenticated itself using a certificate 
// known to the server. 
ftp.Login (username, password);

VB.NET

Dim ftp As New Ftp()

' Create an instance of TlsParameters class and 
' set the certificate request handler to  
' CertificateRequestHandler.StoreSearch. 
' You also have to specify the common name of 
' the FTP server if you provide your own parameters. 
Dim par As New TlsParameters()
par.CertificateRequestHandler = CertificateRequestHandler.StoreSearch
par.CommonName = hostname

' Connect securely using explicit SSL. 
' The third argument refers to the parameters class. 
ftp.Connect(hostname, 21, par, FtpSecurity.Explicit)

' Connection is protected now, we can log in safely. 
' Some servers may not require login if the client 
' successfully authenticated itself using a certificate 
' known to the server. 
ftp.Login(username, password)

If you need to use another method of selecting a suitable certificate or if a GUI should be presented to the user to let him select the certificate, a custom certificate handler is to be used instead. The following sample handler will load a certificate from a PKCS#12 file.

C#

// A custom certificate request handler class. 
// Implements ICertificateRequestHandler interface. 
public class CustomRequestHandler : ICertificateRequestHandler
{
    // This method gets called during the SSL handshake 
    // process if the server requests the client's certificate. 
    public CertificateChain Request
        (TlsSocket socket,
        DistinguishedName[] issuers)
    {
        // Load the certificate with a private key from a PFX file. 
        string path = "myCertificate.pfx";
        Certificate cert = Certificate.LoadPfx (path, "password");
    
        // We actually need a certificate chain, so let's build one. 
        CertificateChain chain = CertificateChain.BuildFrom (cert);
        return chain;
    }
}


// To make your request handler the current request handler for 
// an FTP session: 

Ftp ftp = new Ftp();

// Create an instance of TlsParameters class and 
// set the certificate request handler to an instance 
// of CustomVerifier. 
// You also have to specify the common name of 
// the FTP server if you provide your own parameters. 
TlsParameters par = new TlsParameters ();
par.CertificateRequestHandler = new CustomRequestHandler ();
par.CommonName = hostname;

// Connect securely using explicit SSL. 
// The third argument refers to the parameters class. 
ftp.Connect (hostname, 21, par, FtpSecurity.Explicit);

// Connection is protected now, we can log in safely. 
// Some servers may not require login if the client 
// successfully authenticated itself using a certificate 
// known to the server. 
ftp.Login (username, password);

VB.NET

' A custom certificate request handler class. 
' Implements ICertificateRequestHandler interface. 
Public Class CustomRequestHandler
    Implements ICertificateRequestHandler

    ' This method gets called during the SSL handshake 
    ' process if the server requests the client's certificate. 
    Public Overloads Function Request _
        (socket As TlsSocket,
        issuers() As DistinguishedName) _
        As CertificateChain _
        Implements ICertificateRequestHandler.Request
    
        ' Load the certificate with a private key from a PFX file. 
        Dim path As String = "myCertificate.pfx"
        Dim cert As Certificate = Certificate.LoadPfx(path, "password")
    
        ' We actually need a certificate chain, so let's build one. 
        Dim chain As CertificateChain = CertificateChain.BuildFrom(cert)
        Return chain
    End Function 
End Class 


' To make your request handler the current request handler for 
' an FTP session: 

Dim ftp As New Ftp()

' Create an instance of TlsParameters class and 
' set the certificate request handler to an instance 
' of CustomVerifier. 
' You also have to specify the common name of 
' the FTP server if you provide your own parameters. 
Dim par As New TlsParameters()
par.CertificateRequestHandler = New CustomRequestHandler()
par.CommonName = hostname

' Connect securely using explicit SSL. 
' The third argument refers to the parameters class. 
ftp.Connect(hostname, 21, par, FtpSecurity.Explicit)

' Connection is protected now, we can log in safely. 
' Some servers may not require login if the client 
' successfully authenticated itself using a certificate 
' known to the server. 
ftp.Login(username, password)

back to top...

Back to tutorial list...