letsencrypt

Documentation

Overview

Package letsencrypt integrates Let's Encrypt functionality into Caddy with first-class support for creating and renewing certificates automatically. It is designed to configure sites for HTTPS by default.

Index

• Constants
• Variables
• func Activate(configs []server.Config) ([]server.Config, error)
• func Deactivate() (err error)
• func HostQualifies(hostname string) bool
• func Revoke(host string) error
• type Handler
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)
• type KeySize
• type Storage
  • func (s Storage) Site(domain string) string
  • func (s Storage) SiteCertFile(domain string) string
  • func (s Storage) SiteKeyFile(domain string) string
  • func (s Storage) SiteMetaFile(domain string) string
  • func (s Storage) Sites() string
  • func (s Storage) User(email string) string
  • func (s Storage) UserKeyFile(email string) string
  • func (s Storage) UserRegFile(email string) string
  • func (s Storage) Users() string
• type User
  • func (u User) GetEmail() string
  • func (u User) GetPrivateKey() *rsa.PrivateKey
  • func (u User) GetRegistration() *acme.RegistrationResource

Constants

const (
	ECC_224  KeySize = 224
	ECC_256          = 256
	RSA_2048         = 2048
	RSA_4096         = 4096
)

Key sizes are used to determine the strength of a key.

Variables

var (
	// DefaultEmail represents the Let's Encrypt account email to use if none provided
	DefaultEmail string

	// Agreed indicates whether user has agreed to the Let's Encrypt SA
	Agreed bool

	// CAUrl represents the base URL to the CA's ACME endpoint
	CAUrl string
)

var OnChange func() error

OnChange is a callback function that will be used to restart the application or the part of the application that uses the certificates maintained by this package. When at least one certificate is renewed or an OCSP status changes, this function will be called.

Functions

func Activate

func Activate(configs []server.Config) ([]server.Config, error)

Activate sets up TLS for each server config in configs as needed. It only skips the config if the cert and key are already provided, if plaintext http is explicitly specified as the port, TLS is explicitly disabled, or the host looks like a loopback or wildcard address.

This function may prompt the user to provide an email address if none is available through other means. It prefers the email address specified in the config, but if that is not available it will check the command line argument. If absent, it will use the most recent email address from last time. If there isn't one, the user will be prompted and shown SA link.

Also note that calling this function activates asset management automatically, which keeps certificates renewed and OCSP stapling updated. This has the effect of causing restarts when assets are updated.

Activate returns the updated list of configs, since some may have been appended, for example, to redirect plaintext HTTP requests to their HTTPS counterpart. This function only appends; it does not prepend or splice.

func Deactivate

func Deactivate() (err error)

Deactivate cleans up long-term, in-memory resources allocated by calling Activate(). Essentially, it stops the asset maintainer from running, meaning that certificates will not be renewed, OCSP staples will not be updated, etc.

func HostQualifies

func HostQualifies(hostname string) bool

HostQualifies returns true if the hostname alone appears eligible for automatic HTTPS. For example, localhost, empty hostname, and wildcard hosts are not eligible because we cannot obtain certificates for those names.

func Revoke

func Revoke(host string) error

Revoke revokes the certificate for host via ACME protocol.

Types

type Handler

type Handler struct {
	Next middleware.Handler
}

Handler is a Caddy middleware that can proxy ACME challenge requests to the real ACME client endpoint. This is necessary to renew certificates while the server is running.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) (int, error)

ServeHTTP is basically a no-op unless an ACME challenge is active on this host and the request path matches the expected path exactly.

type KeySize

type KeySize int

KeySize represents the length of a key in bits.

type Storage

type Storage string

Storage is a root directory and facilitates forming file paths derived from it.

func (Storage) Site

func (s Storage) Site(domain string) string

Site returns the path to the folder containing assets for domain.

func (Storage) SiteCertFile

func (s Storage) SiteCertFile(domain string) string

SiteCertFile returns the path to the certificate file for domain.

func (Storage) SiteKeyFile

func (s Storage) SiteKeyFile(domain string) string

SiteKeyFile returns the path to domain's private key file.

func (Storage) SiteMetaFile

func (s Storage) SiteMetaFile(domain string) string

SiteMetaFile returns the path to the domain's asset metadata file.

func (Storage) Sites

func (s Storage) Sites() string

Sites gets the directory that stores site certificate and keys.

func (Storage) User

func (s Storage) User(email string) string

User gets the account folder for the user with email.

func (Storage) UserKeyFile

func (s Storage) UserKeyFile(email string) string

UserKeyFile gets the path to the private key file for the user with the given email address.

func (Storage) UserRegFile

func (s Storage) UserRegFile(email string) string

UserRegFile gets the path to the registration file for the user with the given email address.

func (Storage) Users

func (s Storage) Users() string

Users gets the directory that stores account folders.

type User

type User struct {
	Email        string
	Registration *acme.RegistrationResource
	// contains filtered or unexported fields
}

User represents a Let's Encrypt user account.

func (User) GetEmail

func (u User) GetEmail() string

GetEmail gets u's email.

func (User) GetPrivateKey

func (u User) GetPrivateKey() *rsa.PrivateKey

GetPrivateKey gets u's private key.

func (User) GetRegistration

func (u User) GetRegistration() *acme.RegistrationResource

GetRegistration gets u's registration resource.