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

About this project

this project was fork from github.com/jtblin/go-acme and made lots of change thus it is not compatible with the old package anymore

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(ctx context.Context, outSuccCh chan<- struct{}, interval time.Duration, ...) (updated bool, err error)
• type HostPolicy
  • func HostWhitelist(hosts ...string) HostPolicy

Types

type ACME

type ACME struct {
	Domain *types.Domain
	Logger logger.Interface

	// HostPolicy controls which domains the Manager will attempt
	// to retrieve new certificates for. It does not affect cached certs.
	//
	// If non-nil, HostPolicy is called before requesting a new cert.
	// If nil, all hosts are currently allowed. This is not recommended,
	// as it opens a potential attack where clients connect to a server
	// by IP address and pretend to be asking for an incorrect host name.
	// Manager will attempt to obtain a certificate for that host, incorrectly,
	// eventually reaching the CA's rate limit for certificate requests
	// and making it impossible to obtain actual certificates.
	//
	// See GetCertificate for more details.
	HostPolicy HostPolicy

	BackendName string
	CAServer    string
	DNSProvider string
	Email       string
	KeyType     string
	KeyPath     string
	CertPath    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(ctx context.Context, outSuccCh chan<- struct{}, interval time.Duration, tlsConfig *tls.Config) (updated bool, err error)

CreateConfig creates a tls.config from using ACME configuration

type HostPolicy

type HostPolicy func(host string) error

HostPolicy borrowed from golang.org/x/crypto/acme/autocert HostPolicy specifies which host names the Manager is allowed to respond to. It returns a non-nil error if the host should be rejected. The returned error is accessible via tls.Conn.Handshake and its callers. See Manager's HostPolicy field and GetCertificate method docs for more details.

func HostWhitelist

func HostWhitelist(hosts ...string) HostPolicy

HostWhitelist returns a policy where only the specified host names are allowed. Only exact matches are currently supported. Subdomains, regexp or wildcard will not match. waring: in here, we do not convert hosts to Punycode via idna.Lookup.ToASCII like golang.org/x/crypto/acme/autocert but only convert to lower case, since idna.Lookup.ToASCII("TEST-UPPER-CASE.com") will result in "test-upper-case.com" Invalid hosts will be silently ignored.