_ _ _
___(_)_ __ ___ _ __ | | ___ ___ ___ _ __| |_
/ __| | '_ ` _ \| '_ \| |/ _ \/ __/ _ \ '__| __|
\__ \ | | | | | | |_) | | __/ (_| __/ | | |_
|___/_|_| |_| |_| .__/|_|\___|\___\___|_| \__|
|_|
Golang Library for automatic LetsEncrypt SSL Certificates
Obtains certificates automatically, and manages renewal and hot reload for your Golang application. It uses the LEGO Library to perform ACME challenges, and the mkcert utility to generate self-signed trusted certificates for local development.
Main goals:
- ease of use: simplicity and integration with go standard library
- transparency: products of intermediate steps are preserved, dedicated logfile for simplecert
- flexibility: configurable design and cross platform support
UPDATE: The vendored lego version has been updated to v2.2.0 and now supports issuing wildcard certificates by using ACMEv2 challenges.
You need to supply the following data to simplecert: Domains, Contact Email and a Directory to store the certs in (CacheDir). On startup, call the simplecert.Init() function and pass your config. You will receive a certReloader instance, that has a GetCertificateFunc to allow hot reloading the cert upon renewal. See Usage for a detailed example.
A new certificate will be obtained automatically if the domains have changed, both in local and in production mode.
For more advanced usage, see the config section for all configuration options.
Index
Install
API
Simplecert provides a few wrappers similar to http.ListenAndServe from the go standard library:
For running on a production server:
For local development:
The custom wrapper allows to pass a simplecert.Config and a tls.Config:
There is a util for redirecting HTTP requests to HTTPS:
And a function to initialize simplecert after applying the desired configuration:
The cleanup function will be called upon receiving the syscall.SIGINT or syscall.SIGABRT signal and can be used to stop your backend gracefully. If you don't need it, simpy pass nil.
Local Development
To make local development less of a pain, simplecert integrates mkcert, to obtain self signed certificates for your desired domains, trusted by your computer.
Follow the installation instructions to install the mkcert commandline tool.
In order to use simplecert for local development, set the Local field in the config to true.
Certificates generated for local development are not checked for expiry, the certificates generated by mkcert are valid for 10 years!
Important:
Using wildcard certificates in local mode does not work out of the box, since /etc/hosts doesn't support resolving wild card entries.
You'll have to use other services like dnsmasq. Just edit dnsmasq.conf and add the following line:
address=/yourdomain.com/127.0.0.1
This will resolve all requests to domains that end on yourdomain.com with 127.0.0.1.
Host Entries
To resolve the domain name for your certificate to your localhost, simplecert adds an entry for each domain name to your /etc/hosts file.
This can be disabled by setting the UpdateHosts field in the config to false.
Usage
Simplecert has a default configuration available: simplecert.Default
You will need to update the Domains, CacheDir and SSLEmail and you are ready to go.
Challenges
Simplecert uses the letsencrypt ACMEv2 API and supports HTTP, TLS and DNS Challenges.
For the DNS challenge, an API token of an provider must be exported as environment variable.
Graceful service shutdown and restart
In case of using the HTTP or TLS challenges, port 80 or 443 must temporarily be freed.
The simplecert.Config contains two functions that can be set to accomplish this:
- WillRenewCertificate, called just before the certificate will be renewed.
- DidRenewCertificate, called after the certificate was renewed.
These functions can be used to gracefully stop the running service, and bring it back up once the certificate renewal is complete.
If you want to exchange the certificates manually on disk and force the running service to reload them, simply send a SIGHUP signal to your running instance:
kill -HUP <pid>
Backup mechanism
Simplecert creates a backup of your old certificate when it is being renewed.
All data is stored in the configured CacheDir.
In case something goes wrong while renewing, simplecert will rollback to the original cert.
Configuration
You can pass a custom simplecert.Config to suit your needs.
Parameters are explained below.
Examples
The examples directory contains two simple use cases.
A custom initialization:
go run examples/custom/main.go
And a simple example for local development with a locally trusted certificate (requires mkcert to be installed):
go run examples/simple/main.go
Debug
Simplecert writes all its logs to the simplecert.log file inside the configured cache directory.
License
MIT