FTPS Connection using GnuTLS

Overview

FluentFTP normally uses .NET SslStream/SChannel for secure encrypted connections. This combination unfortunately currently does not support TLS 1.3 on MS Windows systems.

Therefore we integrated the powerful GnuTLS networking library, a C library that supports TLS 1.3 and also supports much more secure authentication methods, as an alternative secure and encrypted transport medium.

We developed a high-level .NET wrapper for GnuTLS called FluentFTP.GnuTLS, which works on Windows, Unix and Mac OSX.

All credits for the development and testing of our GnuTLS FTP stream and wrapper go to Michael Stiemke.

Packaging

It is published as an independent Nuget FluentFTP.GnuTLS, and integrates with the FluentFTP client object. See the diagram below for a visual explanation.

Note: This feature is bound by the LGPL 2.1 license so you CAN use it for commercial applications if you don't modify it.

Features

Benefits

Using GnuTLS FTP streams gives many benefits:

• Full support for TLS 1.3
• Fixes SSL session resume failures on TLS 1.2 which could not be fixed due to buggy .NET SSL Streams
• Fully supported on MS Windows, Linux, Mono, and Mac OSX

Known limitations

• Protocol: Only supports Explicit SSL mode. Implicit SSL may work, but use at your discretion.
• Certificates: Client certificate handling and preparation for verification by the server not yet implemented.
• API: Async API calls will be internally executed as synchronous operations within the GnuTLS wrapper library.
• CPU: Currently only supports x64 architectures.
• ZLIB: Not yet available

Settings

All these settings are properties of the FtpClient object.

• Config.CustomStream - Set this option to typeof(GnuTlsStream) to activate the GnuTLS package in your FTP client.

• Config.CustomStreamConfig - Set this to an instance of GnuConfig to configure the GnuTLS connection settings.

GnuTLS Settings

All these settings are properties of the GnuConfig object.

Encryption Settings

• SecuritySuite - Which security suite to use as a starting point. The suite enables a fully pre-configured configuration, which is then manually modified using SecurityOptions. Default: GnuSuite.Normal.

• SecurityOptions - Additional options to add to the basic security suite specified by SecuritySuite. Default: null.

• SecurityProfile - Which security profile to use. Not normally needed. If you set this, you don't need to set individual SecurityOptions. Default: GnuProfile.None

Connection Settings

• HandshakeTimeout - How long to wait for a handshake before giving up, in milliseconds. Set to zero to disable. Default: 5000.

• AdvancedOptions - Additional options to configure GnuTLS protocol handling. Not normally needed. Default: null.

Logging Settings

• LogMessages - Additional debug information. This is a bitwise flags value, so you can combine multiple values using the OR | operator. Default: None.

• LogLength - In case of a catastrophic failure, how many messages at maximum verbosity should be output prior to termination. Default: 150.

• LogLevel - Select the maximum verbosity of the GnuTLS messages which are logged with serverity "verbose". Allowed values are 0-99. Default: 1.

Value	Effect
0	To suppress GnuTls related messages entirely
1	To see messages originating in the GnuTls wrapper (labelled "Interop"). You can further customize which messages are logged using the LogMessages option.
3 to 99	To add messages from GnuTls processes (labelled "Internal").

Examples

C#

• ConnectFTPSGnuTLS.cs

How do I connect with TLS 1.3?

To use GnuTLS to connect to your FTP server:

1. Add the FluentFTP and FluentFTP.GnuTLS Nuget packages to your project.
2. Add this code where you create your FtpClient:

using FluentFTP.GnuTLS;
using FluentFTP.GnuTLS.Enums;

var client = new FtpClient(...); // or new AsyncFtpClient(...);
client.Config.CustomStream = typeof(GnuTlsStream);
client.Config.CustomStreamConfig = new GnuConfig(){ 
   // optional configuration
   SecuritySuite = GnuSuite.Secure128
};
client.Connect();
// now you can perform any FTP operations using client.XYZ()

All further code then transparently uses GnuTlsStream instead of SslStream for FTPS communications.

All FTPS operations and API can be used as usual with no further changes to your code.

Why is GnuTLS packaged seperately?

We have a separate repository for GnuTLS because it uses a license that is incompatible with our MIT license. It uses LGPL v2.

We publish GnuTLS as a separate Nuget because it adds dependencies on C library DLLs:

• libgnutls-30.dll
• libgcc_s_seh-1.dll
• libgmp-10.dll
• libhogweed-6.dll
• libnettle-8.dll
• libwinpthread-1.dll

How do I install the required libraries?

Windows

You need to explicitly use the libraries that the Nuget package brings in for you - they should be copied to the right place by your build process. These were made with a tool chain customized towards the special needs of FluentFTP.GnuTls and especially made for Windows.

Linux

You need to have the GnuTLS library installed on your system, it is NOT packaged along with our nuget package.

1. Many distros already have GnuTLS installed. It's version should be at least 3.7.x or higher for satisfactory performance. This library should be automatically located and loaded.
2. You can use the package manager of your distro to install libgnutls30 in the standard fashion, but in many cases it will not get you the required version (3.7.x+)
3. You can get the source code and build the libraries from source

The DllImport process on Linux will find the package because will be in the library search path. No need to copy or move the lib to anywhere.

Debian 11 Bullseye

Run this to verify that GnuTLS is installed on Debian 11 Bullseye:

> apt list --installed | grep gnutls30

libgnutls30/stable,stable-security,now 3.7.1-5+deb11u3 amd64 [installed]