README
¶
autocert
The autocert package provides automatic SSL certificate issuance & renewal from LetsEncrypt (and any other ACME-based CA). It is intended to be used as a drop-in library for go http servers.
The main motivation is to provide a closely-compatible golang.org/x/crypto/acme/autocert library replacement that also handles DNS verification and will work well in distributed environments.
The API is based strongly on the golang.org/x/crypto/acme/autocert package so it can provide an easy transition. The ACME implementation is provided by the excellent github.com/xenolf/lego package.
Usage
m := &autocert.Manager{
Endpoint: "https://acme-v02.api.letsencrypt.org/directory",
Store: dir.Store("secret-dir"), // or consul.Store, etcd.Store
Notifier: autocert.SlackNotifier("https://hooks.slack.com/services/..."),
Prompt: autocert.AcceptTOS,
Email: "user@example.com",
}
// HTTP verification
m.Add(&autocert.Request{
Hosts: []string{"example.com", "www.example.com"},
})
// DNS verification
m.Add(&autocert.Request{
Hosts: []string{"example.com"},
DNSProviderName: autocert.DNSimpleProvider,
DNSCredentials: []string{"API_KEY"},
})
go http.ListenAndServe(":http", m.HTTPHandler(nil))
// m.Run() // optional blocking call to ensure all certificates are issued before starting https server
// go m.Monitor() // optionally renew certificates in the background
s := &http.Server{
Addr: ":https",
TLSConfig: &tls.Config{GetCertificate: m.GetCertificate},
}
s.ListenAndServeTLS("", "")
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type DNSProviderName ¶
type DNSProviderName string
DNSProviderName holds the name of a provider
const DNSMadeEasyProvider DNSProviderName = "dnsmadeeasy"
DNSMadeEasyProvider the DNSMadeEasy provider
type Manager ¶
type Manager struct {
Endpoint string
// Store optionally stores and retrieves previously-obtained certificates.
// If nil, certs will only be cached for the lifetime of the Manager.
//
// Manager passes the Store certificates data encoded in PEM, with private/public
// parts combined in a single Cache.Put call, private key first.
Store kvstore.Store
// Notifier sends notifications about certificate issuance, renewal or errors
// If nil, no notifications will be sent.
Notifier Notifier
// Prompt specifies a callback function to conditionally accept a CA's Terms of Service (TOS).
// The registration may require the caller to agree to the CA's TOS.
// If so, Manager calls Prompt with a TOS URL provided by the CA. Prompt should report
// whether the caller agrees to the terms.
//
// To always accept the terms, the callers can use AcceptTOS.
Prompt func(tosURL string) bool
// RenewBefore optionally specifies how early certificates should
// be renewed before they expire.
//
// If zero, they're renewed 30 days before expiration.
RenewBefore time.Duration
// Email optionally specifies a contact email address.
// This is used by CAs, such as Let's Encrypt, to notify about problems
// with issued certificates.
//
// If the Client's account key is already registered, Email is not used.
Email string
// contains filtered or unexported fields
}
Manager is a stateful certificate manager. It obtains and refreshes certificates automatically using "http-01", and "dns-01" challenge types, as well as providing them to a TLS server via tls.Config.
You must specify a store implementation, such as DirStore, ConsulStore or EtcdStore to reuse obtained certificates across program restarts. Otherwise your server is very likely to exceed the certificate issuer's request rate limits.
You can provide an optional Notifier implementation that will send notifications about certificate issuance, renewal and any errors.
Example ¶
package main
import (
"crypto/tls"
"net/http"
"github.com/moomerman/go-lib/autocert"
"github.com/moomerman/go-lib/kvstore/dir"
)
func main() {
m := &autocert.Manager{
Store: dir.Store("secret-dir"), // or consul.Store, etcd.Store
Notifier: autocert.SlackNotifier("https://hooks.slack.com/services/..."),
Prompt: autocert.AcceptTOS,
Email: "user@example.com",
}
// HTTP verification
m.Add(&autocert.Request{
Hosts: []string{"example.com", "www.example.com"},
})
// // DNS verification
// m.Add(&autocert.Request{
// Hosts: []string{"example.com"},
// DNSProviderName: autocert.DNSimpleProvider,
// DNSCredentials: []string{"API_KEY"},
// })
go http.ListenAndServe(":http", m.HTTPHandler(nil))
// m.Run() // optional blocking call to ensure all certificates are issued before starting https server
// go m.Monitor() // optionally renew certificates in the background
s := &http.Server{
Addr: ":https",
TLSConfig: &tls.Config{GetCertificate: m.GetCertificate},
}
s.ListenAndServeTLS("", "")
}
Output:
func (*Manager) GetCertificate ¶
func (m *Manager) GetCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)
GetCertificate implements the tls.Config.GetCertificate hook. It provides a TLS certificate for a given hello.ServerName host
func (*Manager) HTTPHandler ¶
HTTPHandler returns a handler to verify http-01 challenges
type Notifier ¶
type Notifier interface {
// contains filtered or unexported methods
}
Notifier is used by Manager to send notifications on main events
type Request ¶
type Request struct {
Hosts []string
DNSProviderName DNSProviderName
DNSCredentials []string
// contains filtered or unexported fields
}
Request holds all the details required to request a certificate
type SlackNotifier ¶
type SlackNotifier string
SlackNotifier implements Notifier for Slack with a provided Webhook URL
type User ¶
type User struct {
Email string
Registration *registration.Resource
// contains filtered or unexported fields
}
User implements the required interface for acme
func (*User) GetPrivateKey ¶
func (u *User) GetPrivateKey() crypto.PrivateKey
GetPrivateKey returns the user privat key
func (*User) GetRegistration ¶
func (u *User) GetRegistration() *registration.Resource
GetRegistration returns the user registration
Source Files
Directories