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 ConfigQualifies(cfg server.Config) bool
• func Deactivate() (err error)
• func EnableTLS(configs []server.Config)
• func HostQualifies(hostname string) bool
• func MakePlaintextRedirects(allConfigs []server.Config) []server.Config
• func MarkQualified(configs []server.Config)
• func ObtainCerts(configs []server.Config, altPort string) error
• func RequestCallback(w http.ResponseWriter, r *http.Request) bool
• func Revoke(host string) error
• func StapleOCSP(configs []server.Config) 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 (
	// AlternatePort is the port on which the acme client will open a
	// listener and solve the CA's challenges. If this alternate port
	// is used instead of the default port (80 or 443), then the
	// default port for the challenge must be forwarded to this one.
	AlternatePort = "5033"

	// RenewInterval is how often to check certificates for renewal.
	RenewInterval = 24 * time.Hour

	// OCSPInterval is how often to check if OCSP stapling needs updating.
	OCSPInterval = 1 * time.Hour
)

Some essential values related to the Let's Encrypt process

const (
	Ecc224  KeySize = 224
	Ecc256          = 256
	Rsa2048         = 2048
	Rsa4096         = 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; this consists of acquiring and maintaining certificates and keys for qualifying configs and enabling OCSP stapling for all TLS-enabled configs.

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 ConfigQualifies

func ConfigQualifies(cfg server.Config) bool

ConfigQualifies returns true if cfg qualifies for fully managed TLS. It does NOT check to see if a cert and key already exist for the config. If the config does qualify, you should set cfg.TLS.Managed to true and use that instead, because the process of setting up the config may make it look like it doesn't qualify even though it originally did.

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 EnableTLS

func EnableTLS(configs []server.Config)

EnableTLS configures each config to use TLS according to default settings. It will only change configs that are marked as managed, and assumes that certificates and keys are already on disk.

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 MakePlaintextRedirects

func MakePlaintextRedirects(allConfigs []server.Config) []server.Config

MakePlaintextRedirects sets up redirects from port 80 to the relevant HTTPS hosts. You must pass in all configs, not just configs that qualify, since we must know whether the same host already exists on port 80, and those would not be in a list of configs that qualify for automatic HTTPS. This function will only set up redirects for configs that qualify. It returns the updated list of all configs.

func MarkQualified

func MarkQualified(configs []server.Config)

MarkQualified scans each config and, if it qualifies for managed TLS, it sets the Marked field of the TLSConfig to true.

func ObtainCerts

func ObtainCerts(configs []server.Config, altPort string) error

ObtainCerts obtains certificates for all these configs as long as a certificate does not already exist on disk. It does not modify the configs at all; it only obtains and stores certificates and keys to the disk.

func RequestCallback

func RequestCallback(w http.ResponseWriter, r *http.Request) bool

RequestCallback proxies challenge requests to ACME client if the request path starts with challengeBasePath. It returns true if it handled the request and no more needs to be done; it returns false if this call was a no-op and the request still needs handling.

func Revoke

func Revoke(host string) error

Revoke revokes the certificate for host via ACME protocol.

func StapleOCSP

func StapleOCSP(configs []server.Config) error

StapleOCSP staples OCSP responses to each config according to their certificate. This should work for any TLS-enabled config, not just Let's Encrypt ones.

Types

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.