5.7. Let’s Encrypt Certificate Automation¶
- General description
- Available Challenge
- HTTP-01 Challenge Deployment
- Running SFTPPlus behind a firewall or load balancer
- Running SFTPPlus together with an external web server on port 80
- Setting Let’s Encrypt for a new service
- Certificate Generation / Renewal
- Account Registration
- Testing and Experimentation
- Let’s Encrypt Request Limits
Via the lets-encrypt resource, SFTPPlus can act as an ACME client, in order to generate or renew certificates signed by Let’s Encrypt’s CA.
This page focuses on the implementation and operation of SFTPPlus’ Let’s Encrypt ACME client. For configuration information, refer to the dedicated Let’s Encrypt configuration reference page.
A challenge is a method/process used by SFTPPlus to prove that it has control over a specific domain. This is done in order to prevent other people from obtaining certificates for the domains you own.
HTTP-01 is the only challenge supported, and it uses port 80. SFTPPlus provides a self-contained implementation of the HTTP-01 challenge, and you don’t need an external web server.
TLS-SNI-01, which uses port 443 is not supported, as it was discontinued for security reasons.
DNS-01 requires configuration of a DNS server on port 53, and it’s not supported. Most often, the DNS server doesn’t run on the same machine as SFTPPlus, making the deployment more complicated and introducing dependencies on external services.
In order for SFTPPlus to prove that it is the legitimate owner of the requested domain, the Let’s Encrypt server will ask SFTPPlus to host a file at a fixed URL.
For example, to get a certificate for domain ftp.example.com, the SFTPPlus server should be reachable at http://ftp.example.com:80/.
This means that port 80 should be open on the server hosting the SFTPPlus instance, or be forwarded to the SFTPPlus instance.
In order to successfully obtain a certificate for a domain like ftp.your-domain.com you need to configure your DNS so that the ftp.your-domain.com domain will resolve to an IP address used by SFTPPlus. The DNS record should be configured and active before making any certificate requests.
When SFTPPlus is behind a firewall or a load balancer, it’s important to make sure that port 80 is forwarded to SFTPPlus’ Let’s Encrypt resource.
In such a setup, SFTPPlus’s Let’s Encrypt resource can be configured with any port, as long as the public port 80 is forwarded to SFTPPlus.
If you already have another server on port 80 handling the http://ftp.your-domain.com/ URLs, you should configure a proxy or redirection for the .well-known/acme-challenge/ URL.
Any request made to http://ftp.your-domain.com/.well-known/acme-challenge/ should be forwarded to http://126.96.36.199:1234/.well-known/acme-challenge/ where 188.8.131.52 and 1234 is the IP address and port of the SFTPPlus instance.
SFTPPlus can automatically manage the SSL/TLS certificates for any file transfer service which uses it.
When adding a new service, a Let’s Encrypt issued certificate might not be already available. The new service will start with a provisional self-signed certificate. SFTPPlus will automatically update the certificate as soon as a new certificate is obtained from Let’s Encrypt.
A self-signed certificate is auto-generated with each new SFTPPlus installation, and used by default for services created via the Local Manager.
By starting with a self-signed certificate, you can validate that all the other configurations are set up and working according to your needs. Once the service works with a self-signed certificate, you can move to using Let’s Encrypt certificates.
When the SFTPPlus lets-encrypt resource starts, it will automatically generate certificates for all newly configured domains. At start, it will check all the previously generated certificates and automatically renew certificates which are older than 60 days.
Any certificate generated by Let’s Encrypt is valid for 90 days.
While the SFTPPlus lets-encrypt resource is running, it will schedule automatic renewal for the configured domains, one per day.
Once a certificate is generated or renewed, SFTPPlus will automatically restart the file transfer services configured to use those certificates.
If a certificate is about to expire in less than 15 days, SFTPPlus will emit a dedicated failure event and will try again the next day.
No manual account creation is required.
SFTPPlus will automatically create an account and register it to the Let’s Encrypt server.
A registered account is required before asking the Let’s Encrypt server to issue new certificates.
If you already have a Let’s Encrypt account and would like to use that account for the certificates managed by SFTPPlus, get in touch at firstname.lastname@example.org, and we will provide instructions for setting up an existing account.
You can check that SFTPPlus’ Let’s Encrypt resource is correctly configured by accessing the following URL from a remote computer: http://ftp.your-domain.com/.well-known/acme-challenge/test.txt.
You should see a page with the Let’s Encrypt Ready text.
For testing or casually checking out the Let’s Encrypt integration, we highly recommend testing against the Let’s Encrypt staging environment before using the Let’s Encrypt production environment.
This will allow you to get things right before issuing trusted certificates, and reduce the chance of hitting the request rate limits.
The acme_url configuration option is used to instruct SFTPPlus to use different Let’s Encrypt environments.
For production, the configuration will look like:
[resources/17c97aa6-1c17-4485-878c-68b427b82f35] type = lets-encrypt name = lets-encrypt-public address = 0.0.0.0 port = 80 acme_url = https://acme-v01.api.letsencrypt.org/directory
For testing/staging, the configuration will look like:
[resources/17c97aa6-1c17-4485-878c-68b427b82f35] type = lets-encrypt name = lets-encrypt-testing address = 0.0.0.0 port = 80 acme_url = https://acme-staging.api.letsencrypt.org/directory
The main Let’s Encrypt ACME server imposes a set of limits, in terms of how often you can request new certificates.
SFTPPlus does not impose any extra limit, and will rely on the limits defined on the remote Let’s Encrypt / ACME server.
You will see an error message when SFTPPlus operations exceed a certain limit.
You can find up to date information about the certificate generation limits on the Let’s Encrypt Rate Limit <https://letsencrypt.org/docs/rate-limits/> page.
When testing an SFTPPlus deployment, use the Let’s Encrypt staging environment, as documented in previous sections.