roman

README

roman

Roman is a Go library that obtains, caches, and automatically reloads TLS certificates from an ACME server. Roman is inspired by golang.org/x/crypto/acme/autocert with the primary difference being pluggable challenge performers.

Example

import (
    "os"
    "net/http"

	golang_acme "golang.org/x/crypto/acme"
	"golang.org/x/crypto/acme/autocert"

    "github.com/mailgun/roman"
    "github.com/mailgun/roman/acme"
    "github.com/mailgun/roman/challenge"
)

func main() {
    // create a certificate manager
    m := roman.CertificateManager{
      ACMEClient:  &acme.Client{
          Directory:          acme.LetsEncryptProduction,
          AgreeTOS:           golang_acme.AcceptTOS,
          Email:              "foo@example.com",
          ChallengePerformer: &challenge.Route53 {
             Region:           "us-east-1",
             AccessKeyID:      "AK000000000000000000",
             SecretAccessKey:  "a000000000000000000000000000000000000000",
             HostedZoneID:     "Z0000000000000",
             HostedDomainName: "example.com.",
             WaitForSync:      true,
          },
       },
       Cache:       autocert.DirCache(".")
       KnownHosts:  []string{"foo.example.com"},
       RenewBefore: 30 * 24 * time.Hour, // 30 days
    }

    // start the certificate manager, this is a blocking call that
    // ensures that certificates are ready before the server starts
    // accepting connections
    err := m.Start()
    if err != nil {
        fmt.Printf("Unable to start the CertificateManager: %v", err)
        os.Exit(255)
    }

    // start the http server with a *tls.Config that uses the certificate manager
    // to obtain certificates
    s := &http.Server{
        Addr: ":https",
        TLSConfig: &tls.Config{GetCertificate: m.GetCertificate},
    }
    s.ListenAndServeTLS("", "")
}

Documentation

Index

• type CertificateManager
  • func (m *CertificateManager) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (m *CertificateManager) Start() error

Types

type CertificateManager

type CertificateManager struct {
	sync.RWMutex

	// Cache is used to speed up process start up and to avoid hitting any
	// rate limits imposed by the ACME server.
	Cache autocert.Cache

	// KnownHosts is a slice of hosts for whom the CertificateManager will try
	// to obtain tls certificates for.
	KnownHosts []string

	// ACMEClient is something that implements CertificateForDomainer (simple
	// wrapper around a golang.org/x/crypto/acme.Client).
	ACMEClient acme.CertificateForDomainer

	// RenewBefore represents how long before certificate expiration a new
	// certificate will be requested from the ACME server.
	RenewBefore time.Duration
	// contains filtered or unexported fields
}

CertificateManager will obtain and cache TLS certificates from an ACME server. CertificateManager is inspired by autocert.Manager with the primary difference being pluggable challenge performers.

func (*CertificateManager) GetCertificate

func (m *CertificateManager) GetCertificate(clientHello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate is passed into a *tls.Config so that an *http.Server can automatically reload certificates. GetCertificate always retrieves certificates from a cache while a background go routine updates certificates.

func (*CertificateManager) Start

func (m *CertificateManager) Start() error

Start is a blocking function that ensures the CertificateManager cache contains valid certificates for all known hosts. If it doesn't contain a cached TLS certificate, it requests one and put its in the cache.