acme

README

go-acme

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.

Usage

Example with a standard http server:

	ACME := &acme.ACME{
		BackendName: "s3",
		Email:       "user@gmail.com",
		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.

ACME config

• BackendName: the name of the storage backend e.g. fs, s3 (default fs), see below for environment variables
• CAServer: optional CA server url (default to https://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 account
• SelfSigned: set to true if you want to generate self signed certificates instead of Let's Encrypt ones

DNS providers

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.

Storage backends

Pluggable storage backends are supported, and only need to implement the backend.Interface. Currently the following backend are supported:

fs

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 a domain.name.json file.

s3

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 a name/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).

Disclaimer

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.

Credits, reference and similar projects

• 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 on traefik'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

Author

Jerome Touffe-Blin, @jtblin, About me

License

go-acme is copyright 2015 Jerome Touffe-Blin and contributors. It is licensed under the BSD license. See the include LICENSE file for details.

Documentation

Index

• type ACME
  • func (a *ACME) CreateConfig(tlsConfig *tls.Config) error

Types

type ACME

type ACME struct {
	Domain      *types.Domain
	Logger      logger.Interface
	BackendName string
	CAServer    string
	DNSProvider string
	Email       string
	SelfSigned  bool
	// contains filtered or unexported fields
}

ACME allows to connect to lets encrypt and retrieve certs.

func (*ACME) CreateConfig

func (a *ACME) CreateConfig(tlsConfig *tls.Config) error

CreateConfig creates a tls.config from using ACME configuration