Skip to content

TLS and certificates

uFTP supports explicit FTPS: the client connects to the normal FTP port and sends AUTH TLS to switch the connection to TLS, then PROT P to protect the data connections too. TLS 1.2 and 1.3 are accepted. Implicit FTPS (a dedicated port, usually 990) is not supported.

You need a build with OpenSSL (see Installation), a certificate and a private key.

Quick setup with a self-signed certificate

A self-signed certificate encrypts the connection. Clients ask you to trust it the first time, because no authority has signed it.

# 1. Create the certificate and the private key (use your host name)
sudo mkdir -p /etc/uFTP
sudo openssl req -x509 -newkey rsa:4096 -nodes -days 825 \
  -keyout /etc/uFTP/key.pem -out /etc/uFTP/cert.pem \
  -subj "/CN=ftp.example.com" -addext "subjectAltName=DNS:ftp.example.com"

# 2. Only root may read the private key
sudo chown root:root /etc/uFTP/key.pem /etc/uFTP/cert.pem
sudo chmod 600 /etc/uFTP/key.pem

Tell the server where the files are, in uftpd.cfg:

CERTIFICATE_PATH=/etc/uFTP/cert.pem
PRIVATE_CERTIFICATE_PATH=/etc/uFTP/key.pem
FORCE_TLS=true

FORCE_TLS=true refuses every connection that does not use TLS. Leave it false if you also have clients that cannot do TLS.

Restart uFTP and check:

openssl s_client -starttls ftp -connect ftp.example.com:21

The output shows the certificate and the protocol (TLSv1.3).

The private key must have no passphrase

-nodes creates a key without a passphrase. uFTP cannot ask for one when it starts.

In the client

  • FileZilla: Encryption: Require explicit FTP over TLS.
  • WinSCP: File protocol FTP, Encryption: TLS/SSL Explicit encryption.
  • lftp: set ftp:ssl-force yes; set ftp:ssl-protect-data yes.
  • Python: ftplib.FTP_TLS, then prot_p() after login().

A certificate from a certificate authority

If you have a certificate signed by an authority (for example from Let's Encrypt), put the server certificate (with the intermediate certificates, see below) in CERTIFICATE_PATH and its key in PRIVATE_CERTIFICATE_PATH. Clients then trust it without asking.

For a chain (your certificate and the intermediate certificates, as in the fullchain.pem of Let's Encrypt), put them all in CERTIFICATE_PATH, your certificate first. uFTP sends the whole chain, so clients can verify it with the root they already know.

Check when the certificate expires

# the file
openssl x509 -in /etc/uFTP/cert.pem -noout -enddate

# what the running server presents
echo | openssl s_client -starttls ftp -connect ftp.example.com:21 2>/dev/null | openssl x509 -noout -dates

An expired certificate does not stop the server: clients show an error or a warning, and some refuse to connect. To be warned in advance, run this from cron; it fails when the certificate expires in less than 30 days:

openssl x509 -in /etc/uFTP/cert.pem -noout -checkend 2592000 || echo "uFTP certificate expires soon"

Renew a certificate

uFTP reads the certificate when it starts. After you replace the files, restart the server.

Self-signed certificate: make a new one with the commands of the quick setup above (same paths, same name), then restart uFTP. Clients that trusted the old one ask again.

Let's Encrypt: certificates last 90 days and certbot renews them by itself (a timer or a cron job). Point uFTP at the files of certbot once:

CERTIFICATE_PATH=/etc/letsencrypt/live/ftp.example.com/fullchain.pem
PRIVATE_CERTIFICATE_PATH=/etc/letsencrypt/live/ftp.example.com/privkey.pem

The files in live/ are links that certbot updates at every renewal, so the paths do not change. The server runs as root, so it can read them. What is missing is the restart: add a hook that certbot runs after a renewal.

sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-uftp.sh >/dev/null <<'EOF'
#!/bin/sh
systemctl restart uftp
EOF
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-uftp.sh
sudo certbot renew --dry-run

If you do not use systemd, put the command that you use to restart uFTP in the hook. A restart closes the sessions in progress, and certbot only runs the hook when a certificate was really renewed.

If the same machine already has a web site with a Let's Encrypt certificate for the same name, you can use its files: the certificate is valid for every service that uses that name.

Check the result with the commands above (s_client must show the new dates).

Notes

  • After you change the certificate, restart uFTP.
  • The data connections do not send TLS session tickets: a client resumes the session of the control connection while it has tickets, then it does a full handshake.
  • Check that the clock of the server is right; a certificate is valid between two dates.