shelf_letsencrypt 2.0.8
shelf_letsencrypt: ^2.0.8 copied to clipboard
Let's Encrypt support for the shelf package (free and automatic HTTPS certificate support).
shelf_letsencrypt #
shelf_letsencrypt brings support for Let's Encrypt to the shelf package.
Developing with shelf_letsencrypt #
LetsEncrypt provide a few challenges for your development enviroment. Read on for a few hints.
Certificate storage security #
On Linux, Android, macOS and iOS, CertificatesHandlerIO uses an owner-only
storage backend. It creates managed directories with mode 0700 and private
keys with mode 0600 before writing key material. On reuse, it tightens
existing key permissions without changing the key bytes. Existing keys that
may already have been read by another user should be rotated by the operator.
On Linux this requires statx (glibc 2.28+, musl 1.2.5+ or Android API 30+).
On Windows, POSIX modes do not apply: keys inherit the ACLs of the storage directory, so place it in a directory that only the service account can read. POSIX mode checks also do not exclude readers granted access through macOS ACLs.
Use a service-owned certificate directory under trusted ancestors. Ancestors
must not be writable by group or others, unless sticky: a shared sticky parent
such as /tmp is suitable only when its owner is trusted. Symbolic links in
the storage path must be owned by root or the service user. The handler
resolves them, and checks and operates on the real path, which is what
directory returns. External private-key paths configured through the
constructor must already have an owner-only parent. The storage root and
configured PEM paths cannot contain .. path components. Network filesystems
and another process running as the service user are outside this backend's
protection. If an existing store has a different owner, a symlinked key, or an
external hard link, construction or key loading fails so the operator can
migrate it deliberately.
To check a directory before starting the server, run
shelf_letsencrypt check --dir <path> as the service user (see
Command-line tool). It applies the same checks without
changing anything.
Certificate domain names must be ASCII DNS names with at least two labels. Each label must be 1–63 letters, digits, or hyphens and start and end with a letter or digit, and the last label must contain a letter. This accepts multi-label and punycode names; it rejects IP addresses, path separators, traversal components, wildcards, and trailing dots before a domain can select a certificate path.
A word of caution #
LetsEncrypt rate limits the issuing of production certificates. It is very easy to get locked out of letsencrypt for an extended period of time (days) leaving you in the situation where you can't issue a production certificate.
CRITICAL: you could end up with your production systems down for days!!!!
I would advise you to read up on the Lets Encrypt rate limits:
https://letsencrypt.org/docs/rate-limits/
To avoid this (potentially) major issue make certain that you test with a STAGING certificate.
You do this by passing in 'production: false' (the default) when creating the LetsEncrypt certificate. Staging certificates still have rate limits but they are much more generours
final LetsEncrypt letsEncrypt = LetsEncrypt(certificatesHandler, production: false);
Permissions #
On Linux you need to be root (sudo) to open a port below 1024. If you try to start your server with the default ports (80, 443) you will fail.
NAT for your Development environment #
To issue a certificate LetsEncrypt needs to be able to connect to your webserver on port 80. This will work fine in production (with the write firewall rules) but in a development environment can be a bit tricky.
The above Permission limitations add to the complication.
The easist way to do this is (for dev):
- start your server on ports 8080 and 8443 (or any pair above 1024)
- set up two NATS on your router that forward ports to your dev machine. 80 -> 8080 443 -> 8443
DNS for development #
For Lets Encrypt to issue a certificate it must be able to resolve the domain name of the certificate that you are requesting.
To avoid tampering with your production DNS I keep a cheap domain name that I use in test. I then use cloudflare's free DNS hosting service to host the domain name which allows me to add the necessary A record which points to my WFH router on which I've configured the above NAT.
Multi-Domain Support #
Starting with shelf_letsencrypt: 2.0.0, support for multiple domains on the same HTTPS port has been introduced. This
enhancement allows shelf_letsencrypt to manage certificate requests and automatically serve multiple domains
seamlessly.
This functionality is powered by the multi_domain_secure_server package (developed
by gmpassos), specifically created for shelf_letsencrypt. It enables a SecureServerSocket to handle
different SecurityContext (certificates) on the same listening port. For more details, check out the source code
on GitHub.
Usage #
To use the LetsEncrypt class
import 'dart:io';
import 'package:cron/cron.dart';
import 'package:shelf/shelf.dart';
import 'package:shelf_letsencrypt/shelf_letsencrypt.dart';
/// Start the example with a list of domains and a reciprocal
/// e-mail address for the domain admin:
/// ```dart
/// dart shelf_letsencrypt_example.dart \
/// www.domain.com:www2.domain.com \
/// info@domain.com:info2@domain.com
/// ```
void main(List<String> args) async {
final domainNamesArg = args[0]; // Domains for the HTTPS certificate.
final domainEmailsArg = args[1]; // The domains e-mail.
final home = Platform.environment['HOME'];
var certificatesDirectory = args.length > 2
? args[2] // Optional argument.
: home == null
? (throw StateError('Pass a certificate directory as argument 3'))
: '$home/.shelf-letsencrypt-example';
final domains =
Domain.fromDomainsNamesAndEmailsArgs(domainNamesArg, domainEmailsArg);
// The Certificate handler, storing at `certificatesDirectory`.
final certificatesHandler =
CertificatesHandlerIO(Directory(certificatesDirectory));
// The Let's Encrypt integration tool in `staging` mode:
final letsEncrypt = LetsEncrypt(
certificatesHandler,
production: false, // If `true` uses Let's Encrypt production API.
port: 80,
securePort: 443,
);
var servers = await _startServer(letsEncrypt, domains);
_startRenewalService(letsEncrypt, domains, servers);
}
Future<({HttpServer http, HttpServer https})> _startServer(
LetsEncrypt letsEncrypt, List<Domain> domains) async {
// Build `shelf` Pipeline:
final pipeline = const Pipeline().addMiddleware(logRequests());
final handler = pipeline.addHandler(_processRequest);
// Start the HTTP and HTTPS servers:
final servers = await letsEncrypt.startServer(
handler,
domains,
loadAllHandledDomains: true,
);
var server = servers.http; // HTTP Server.
var serverSecure = servers.https; // HTTPS Server.
// Enable gzip:
server.autoCompress = true;
serverSecure.autoCompress = true;
print('Serving at http://${server.address.host}:${server.port}');
print('Serving at https://${serverSecure.address.host}:${serverSecure.port}');
return servers;
}
/// Check every hour if any of the certificates need to be renewed.
void _startRenewalService(LetsEncrypt letsEncrypt, List<Domain> domains,
({HttpServer http, HttpServer https}) servers) {
({HttpServer http, HttpServer https})? current = servers;
Cron().schedule(
Schedule(hours: '*/1'), // every hour
() async =>
current = await refreshIfRequired(letsEncrypt, domains, current));
}
/// Returns the servers to use from now on: new ones if they were restarted,
/// or `null` if they are stopped because the restart failed. Then [servers]
/// is `null` on the next call, which restarts them.
Future<({HttpServer http, HttpServer https})?> refreshIfRequired(
LetsEncrypt letsEncrypt,
List<Domain> domains,
({HttpServer http, HttpServer https})? servers,
) async {
print('-- Checking if any certificates need to be renewed');
// Without servers the HTTP challenge can't be served: restart first.
var restartRequired = servers == null;
for (final domain in servers == null ? <Domain>[] : domains) {
final result =
await letsEncrypt.checkCertificate(domain, requestCertificate: true);
if (result.isOkRefreshed) {
print('** Certificate for ${domain.name} was renewed');
restartRequired = true;
} else {
print('-- Renewal not required');
}
}
if (!restartRequired) return servers;
// Restart the servers:
if (servers != null) {
await Future.wait<void>([servers.http.close(), servers.https.close()]);
}
try {
final restarted = await _startServer(letsEncrypt, domains);
print('** Services restarted');
return restarted;
} catch (e) {
print('** Restart failed, retrying on the next check: $e');
return null;
}
}
Response _processRequest(Request request) =>
Response.ok('Requested: ${request.requestedUri}');
Renewals #
Each time your call startServer it will check if any certificates need to be renewed in the next 5 days (or if they are expired) and renew the certificate.
This however isn't sufficient for any long running service.
The example includes a renewal service that does a daily check if any certificate need renewing. If a cert needs to be renewed, it will renew it and then gracefully restart the server with the new certs.
Alternatively, run shelf_letsencrypt renew from cron, with hooks that stop
and restart your server (see below).
Command-line tool #
The package includes shelf_letsencrypt, a tool to inspect and manage the
certificates directory used by CertificatesHandlerIO:
dart pub global activate shelf_letsencrypt
shelf_letsencrypt --dir /var/lib/myapp/certs list
| Command | Description |
|---|---|
check [--fix] |
Checks the directory and its keys like the server does at startup. Read-only unless --fix is given. |
list [--days 30] |
Lists the stored domains, when their certificates expire, and their status: ok, expiring, expired, missing or invalid. |
show <domain> |
Shows a stored certificate (names, issuer, validity) and the permissions of its files. |
request <domain>... --email <e> |
Requests certificates for domains that have none or whose certificate expires within --days. Skips valid certificates unless --force is given. |
renew [<domain>...] --email <e> |
Renews the certificates that expire within --days (all stored domains by default). --dry-run only lists them. --pre-hook <command> runs first when a certificate is due (e.g. to stop the server holding port 80), and --post-hook <command> afterwards (e.g. to start it again). |
rotate-key <domain> --email <e> |
Generates a new private key and requests a certificate for it. The previous key and certificate are restored if the request fails. |
verify <domain>... |
Connects to the live HTTPS server and checks that its certificate is not close to expiry (--days 5) and, with --dir, that it is the stored one. --connect <address> tests a specific server. |
serve <domain>... --email <e> |
Runs an HTTPS server with automatic certificates and renewals, serving --static <dir> or an "OK" page. It restarts only for a renewed certificate that loads, and keeps serving the previous one otherwise. |
check, list, show and verify never create or change files.
Global options:
--dir,-d: the certificates directory, or$SHELF_LETSENCRYPT_DIR.--json: print the result as JSON.--verbose,-v: print the library log, including the ACME exchange, to stderr.--account-dir,--private-key-file,--public-key-file,--fullchain-file: for a handler created with non-default names.
Exit codes: 0 success, 1 failure (a failed check, request or
verification), 64 usage error.
Notes:
- The commands that talk to Let's Encrypt (
request,renew,rotate-key,serve) use the staging API unless--productionis given: staging certificates are not trusted by browsers, but staging has much higher rate limits. request,renewandrotate-keyanswer the HTTP-01 challenge themselves on--port(default80), so nothing else may listen on it. Let's Encrypt always connects to port 80; use a NAT or a redirect for another port.- Run the tool as the user the server runs as: the storage checks compare owners with the user running them.
- A running server does not reload a certificate renewed by the tool, and it
holds port 80. With
renew, use--pre-hookto stop it and--post-hookto start it again; the post-hook also runs if the renewal fails. Both run only when a certificate is due. Then useverifyto check the result.
A daily renewal with cron, as the service user (the hooks need a sudoers rule allowing it to stop and start the service):
0 3 * * * shelf_letsencrypt --dir /var/lib/myapp/certs renew --email admin@example.com --production --pre-hook 'sudo systemctl stop myapp' --post-hook 'sudo systemctl start myapp'
Source #
The official source code is hosted @ GitHub:
Features and bugs #
Please file feature requests and bugs at the issue tracker.
Contribution #
Any help from the open-source community is always welcome and needed:
- Found an issue?
- Please fill a bug report with details.
- Wish a feature?
- Open a feature request with use cases.
- Are you using and liking the project?
- Promote the project: create an article, do a post or make a donation.
- Are you a developer?
- Fix a bug and send a pull request.
- Implement a new feature.
- Improve the Unit Tests.
- Have you already helped in any way?
- Many thanks from me, the contributors and everybody that uses this project!
If you donate 1 hour of your time, you can contribute a lot, because others will do the same, just be part and start with your 1 hour.
TODO #
- Add support for multiple HTTPS domains and certificates.
- Add helper to generate self-signed certificates (for local tests).
Author #
Graciliano M. Passos: gmpassos@GitHub. Brett Sutton bsutton@GitHub
Sponsor #
Don't be shy, show some love, and become our GitHub Sponsor (gmpassos, bsutton). Your support means the world to us, and it keeps the code caffeinated! ☕✨
Thanks a million! 🚀😄