Add Let's Encrypt (ACME) support to generate and renew SSL certificates to go servers using the DNS provider challenge so that it can be used for internal servers.
The library is built upon lego. It will generate the certificates and store them in a pluggable storage backend. It will renew the certificates automatically 7 days before they expire.
If the certificates are found in the storage backend, they will be reused, which prevents from hitting
Let’s Encrypt rate limits of
20 certificates per domain per week. It is recommended to use a distributed storage backend to avoid
this issue (currently only s3
is implemented).
For local development, it can generate self signed certificates instead of calling Let's Encrypt.
Example with a standard http server:
ACME := &acme.ACME{
BackendName: "s3",
Email: "[email protected]",
DNSProvider: "route53",
Domain: &types.Domain{Main: "foo.my-domain.io"},
}
tlsConfig := &tls.Config{}
if err := ACME.CreateConfig(tlsConfig); err != nil {
panic(err)
}
listener, err := tls.Listen("tcp", ":443", tlsConfig)
if err != nil {
panic("Listener: " + err.Error())
}
mux := http.NewServeMux()
mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { w.Write([]byte("ok")) })
// To enable http2, we need http.Server to have reference to tlsConfig
// https://github.com/golang/go/issues/14374
server := &http.Server{
Addr: ":443",
Handler: mux,
TLSConfig: tlsConfig,
}
server.Serve(listener)
Example with a gRPC.io server:
func main() {
flag.Parse()
ACME := &acme.ACME{
Email: email,
DNSProvider: "route53",
Domain: &types.Domain{Main: domain},
}
tlsConfig := &tls.Config{}
if err := ACME.CreateConfig(tlsConfig); err != nil {
panic(err)
}
ta := credentials.NewTLS(tlsConfig)
listener, err := net.Listen("tcp", address)
if err != nil {
panic("failed to listen: " + err.Error())
}
grpcServer := grpc.NewServer(grpc.Creds(ta))
pb.RegisterGreeterServer(grpcServer, &server{})
if err = grpcServer.Serve(listener); err != nil {
panic(err)
}
}
See examples for complete http and gRPC implementations.
BackendName
: the name of the storage backend e.g. fs, s3 (defaultfs
), see below for environment variablesCAServer
: optional CA server url (default tohttps://acme-v01.api.letsencrypt.org/directory
)DNSProvider
: mandatory DNS provider name e.g.route53
.Domain
: struct containing the main domain name and optional SANs (Subject Alternate Names)Email
: email address to register the accountSelfSigned
: set to true if you want to generate self signed certificates instead of Let's Encrypt ones
All DNS providers offered by lego at the time of publishing are supported. Environment variables need to be set depending on provider as per lego.
Pluggable storage backends are supported, and only need to implement the backend.Interface. Currently the following backend are supported:
This backend stores the account details and certificate on the filesystem. The following environment variables can be set:
STORAGE_DIR
: set the directory to store the account and certificate information (default to current directory). The information will be saved to adomain.name.json
file.
This backend stores the account details and certificate on the filesystem. The following environment variables can to be set:
AWS_BUCKET
: set the bucket to store the account and certificate information. The information will be saved to aname/domain/cert.json
file e.g.bucket/io/domain/label/cert.json
.AWS_REGION
: set the region for the bucket.AWS_ENCRYPTION_KEY
: set the encryption key for s3 server side encryption (optional).AWS_ENCRYPTION_ALG
: set the encryption algorithm for s3 server side encryption e.g.AES256
(optional).
This project is in an alpha state, and therefore should be considered as unreliable and the API is likely to have breaking changes in the future.
- traefik is a reverse proxy and load balancer that supports several backends
e.g. etcd, kubernetes, etc. and allow generating certificates automatically. The
go-acme
library is based ontraefik
's original code. - acmewrapper allows generating certificate using the HTTP/TLS challenge. So not appropriate for internal services with no public internet access. Only offers a filesystem storage backend.
- caddy server is another go reverse proxy with support for Let's Encrypt certificates.
- Generate and Use Free TLS Certificates with Lego
Jerome Touffe-Blin, @jtblin, About me
go-acme is copyright 2015 Jerome Touffe-Blin and contributors. It is licensed under the BSD license. See the include LICENSE file for details.