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, thenprot_p()afterlogin().
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.