certmagic package - github.com/caddyserver/certmagic

certmagic package - github.com/caddyserver/certmagic - Go Packages

Package certmagic automates the obtaining and renewal of TLS certificates, including TLS & HTTPS best practices such as robust OCSP stapling, caching, HTTP->HTTPS redirects, and more.

Its high-level API serves your HTTP handlers over HTTPS if you simply give the domain name(s) and the http.Handler; CertMagic will create and run the HTTPS server for you, fully managing certificates during the lifetime of the server. Similarly, it can be used to start TLS listeners or return a ready-to-use tls.Config -- whatever layer you need TLS for, CertMagic makes it easy. See the HTTPS, Listen, and TLS functions for that.

If you need more control, create a Cache using NewCache() and then make a Config using New(). You can then call Manage() on the config. But if you use this lower-level API, you'll have to be sure to solve the HTTP and TLS-ALPN challenges yourself (unless you disabled them or use the DNS challenge) by using the provided Config.GetCertificate function in your tls.Config and/or Config.HTTPChallengeHandler in your HTTP handler.

See the package's README for more instruction.

HTTPS

View Source

const (
	LetsEncryptStagingCA    = "https://acme-staging-v02.api.letsencrypt.org/directory" 
	LetsEncryptProductionCA = "https://acme-v02.api.letsencrypt.org/directory"         
	ZeroSSLProductionCA     = "https://acme.zerossl.com/v2/DV90"                       
	GoogleTrustStagingCA    = "https://dv.acme-v02.test-api.pki.goog/directory"        
	GoogleTrustProductionCA = "https://dv.acme-v02.api.pki.goog/directory"             
)

Some well-known CA endpoints available to use. See the documentation for each service; some may require External Account Binding (EAB) and possibly payment. COMPATIBILITY NOTICE: These constants refer to external resources and are thus subject to change or removal without a major version bump.

View Source

const (
	
	
	UseFirstIssuer = "first"

	
	
	
	UseFirstRandomIssuer = "first_random"
)

Supported issuer policies. These are subject to change.

View Source

const (
	
	
	HTTPChallengePort = 80

	
	
	TLSALPNChallengePort = 443
)

View Source

const (
	ED25519 = KeyType("ed25519")
	P256    = KeyType("p256")
	P384    = KeyType("p384")
	RSA2048 = KeyType("rsa2048")
	RSA4096 = KeyType("rsa4096")
	RSA8192 = KeyType("rsa8192")
)

Constants for all key types we support.

View Source

const ClientHelloInfoCtxKey helloInfoCtxKey = "certmagic:ClientHelloInfo"

ClientHelloInfoCtxKey is the key by which the ClientHelloInfo can be extracted from a context.Context within a DecisionFunc. However, be advised that it is best practice that the decision whether to obtain a certificate is be based solely on the name, not other properties of the specific connection/client requesting the connection. For example, it is not advisable to use a client's IP address to decide whether to allow a certificate. Instead, the ClientHello can be useful for logging, etc.

These internal rate limits are designed to prevent accidentally firehosing a CA's ACME endpoints. They are not intended to replace or replicate the CA's actual rate limits.

Let's Encrypt's rate limits can be found here: https://letsencrypt.org/docs/rate-limits/

Currently (as of December 2019), Let's Encrypt's most relevant rate limit for large deployments is 300 new orders per account per 3 hours (on average, or best case, that's about 1 every 36 seconds, or 2 every 72 seconds, etc.); but it's not reasonable to try to assume that our internal state is the same as the CA's (due to process restarts, config changes, failed validations, etc.) and ultimately, only the CA's actual rate limiter is the authority. Thus, our own rate limiters do not attempt to enforce external rate limits. Doing so causes problems when the domains are not in our control (i.e. serving customer sites) and/or lots of domains fail validation: they clog our internal rate limiter and nearly starve out (or at least slow down) the other domains that need certificates. Failed transactions are already retried with exponential backoff, so adding in rate limiting can slow things down even more.

Instead, the point of our internal rate limiter is to avoid hammering the CA's endpoint when there are thousands or even millions of certificates under management. Our goal is to allow small bursts in a relatively short timeframe so as to not block any one domain for too long, without unleashing thousands of requests to the CA at once.

Some default values passed down to the underlying ACME client.

Port variables must remain their defaults unless you forward packets from the defaults to whatever these are set to; otherwise ACME challenges will fail.

AttemptsCtxKey is the context key for the value that holds the attempt counter. The value counts how many times the operation has been attempted. A value of 0 means first attempt.

View Source

var Default = Config{
	RenewalWindowRatio: DefaultRenewalWindowRatio,
	Storage:            defaultFileStorage,
	KeySource:          DefaultKeyGenerator,
	Logger:             defaultLogger,
}

Default contains the package defaults for the various Config fields. This is used as a template when creating your own Configs with New() or NewDefault(), and it is also used as the Config by all the high-level functions in this package that abstract away most configuration (HTTPS(), TLS(), Listen(), etc).

The fields of this value will be used for Config fields which are unset. Feel free to modify these defaults, but do not use this Config by itself: it is only a template. Valid configurations can be obtained by calling New() (if you have your own certificate cache) or NewDefault() (if you only need a single config and want to use the default cache).

Even if the Issuers or Storage fields are not set, defaults will be applied in the call to New().

DefaultACME specifies default settings to use for ACMEIssuers. Using this value is optional but can be convenient.

DefaultKeyGenerator is the default key source.

ErrNoOCSPServerSpecified indicates that OCSP information could not be stapled because the certificate does not support OCSP.

CleanStorage removes assets which are no longer useful, according to opts.

CleanUpOwnLocks immediately cleans up all current locks obtained by this process. Since this does not cancel the operations that the locks are synchronizing, this should be called only immediately before process exit. Errors are only reported if a logger is given.

FindZoneByFQDN determines the zone apex for the given fully-qualified domain name (FQDN) by recursing up the domain labels until the nameserver returns a SOA record in the answer section. The logger must be non-nil.

EXPERIMENTAL: This API was previously unexported, and may be changed or unexported again in the future. Do not rely on it at this time.

HTTPS serves mux for all domainNames using the HTTP and HTTPS ports, redirecting all HTTP requests to HTTPS. It uses the Default config and a background context.

This high-level convenience function is opinionated and applies sane defaults for production use, including timeouts for HTTP requests and responses. To allow very long-lived connections, you should make your own http.Server values and use this package's Listen(), TLS(), or Config.TLSConfig() functions to customize to your needs. For example, servers which need to support large uploads or downloads with slow clients may need to use longer timeouts, thus this function is not suitable.

Calling this function signifies your acceptance to the CA's Subscriber Agreement and/or Terms of Service.

This is the simplest way for HTTP servers to use this package. Call HTTPS() with your domain names and your handler (or nil for the http.DefaultMux), and CertMagic will do the rest.

http.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
	fmt.Fprintf(w, "Hello, HTTPS visitor!")
})

err := HTTPS([]string{"example.com", "www.example.com"}, nil)
if err != nil {
	log.Fatal(err)
}

Listen manages certificates for domainName and returns a TLS listener. It uses the Default config.

Because this convenience function returns only a TLS-enabled listener and does not presume HTTP is also being served, the HTTP challenge will be disabled. The package variable Default is modified so that the HTTP challenge is disabled.

Calling this function signifies your acceptance to the CA's Subscriber Agreement and/or Terms of Service.

LooksLikeHTTPChallenge returns true if r looks like an ACME HTTP challenge request from an ACME server.

LooksLikeZeroSSLHTTPValidation returns true if the request appears to be domain validation from a ZeroSSL/Sectigo CA. NOTE: This API is non-standard and is subject to change.

ManageAsync is the same as ManageSync, except that certificates are managed asynchronously. This means that the function will return before certificates are ready, and errors that occur during certificate obtain or renew operations are only logged. It is vital that you monitor the logs if using this method, which is only recommended for automated/non-interactive environments.

ManageSync obtains certificates for domainNames and keeps them renewed using the Default config.

This is a slightly lower-level function; you will need to wire up support for the ACME challenges yourself. You can obtain a Config to help you do that by calling NewDefault().

You will need to ensure that you use a TLS config that gets certificates from this Config and that the HTTP and TLS-ALPN challenges can be solved. The easiest way to do this is to use NewDefault().TLSConfig() as your TLS config and to wrap your HTTP handler with NewDefault().HTTPChallengeHandler(). If you don't have an HTTP server, you will need to disable the HTTP challenge.

If you already have a TLS config you want to use, you can simply set its GetCertificate field to NewDefault().GetCertificate.

Calling this function signifies your acceptance to the CA's Subscriber Agreement and/or Terms of Service.

MatchWildcard returns true if subject (a candidate DNS name) matches wildcard (a reference DNS name), mostly according to RFC 6125-compliant wildcard rules. See also RFC 2818 which states that IP addresses must match exactly, but this function does not attempt to distinguish IP addresses from internal or external DNS names that happen to look like IP addresses. It uses DNS wildcard matching logic and is case-insensitive. https://tools.ietf.org/html/rfc2818#section-3.1

PEMDecodePrivateKey loads a PEM-encoded ECC/RSA private key from an array of bytes. Borrowed from Go standard library, to handle various private key and PEM block types.

PEMEncodePrivateKey marshals a private key into a PEM-encoded block. The private key must be one of *ecdsa.PrivateKey, *rsa.PrivateKey, or *ed25519.PrivateKey.

RecursiveNameservers are used to pre-check DNS propagation. It picks user-configured nameservers (custom) OR the defaults obtained from resolv.conf and defaultNameservers if none is configured and ensures that all server addresses have a port value.

EXPERIMENTAL: This API was previously unexported, and may be be unexported again in the future. Do not rely on it at this time.

SolveHTTPChallenge solves the HTTP challenge. It should be used only on HTTP requests that are from ACME servers trying to validate an identifier (i.e. LooksLikeHTTPChallenge() == true). It returns true if the request criteria check out and it answered with key authentication, in which case no further handling of the request is necessary.

SubjectIsIP returns true if subj is an IP address.

SubjectIsInternal returns true if subj is an internal-facing hostname or address, including localhost/loopback hosts. Ports are ignored, if present.

SubjectQualifiesForCert returns true if subj is a name which, as a quick sanity check, looks like it could be the subject of a certificate. Requirements are: - must not be empty - must not start or end with a dot (RFC 1034; RFC 6066 section 3) - must not contain common accidental special characters

func SubjectQualifiesForPublicCert(subj string) bool

SubjectQualifiesForPublicCert returns true if the subject name appears eligible for automagic TLS with a public CA such as Let's Encrypt. For example: internal IP addresses and localhost are not eligible because we cannot obtain certs for those names with a public CA. Wildcard names are allowed, as long as they conform to CABF requirements (only one wildcard label, and it must be the left-most label).

TLS enables management of certificates for domainNames and returns a valid tls.Config. It uses the Default config.

Because this is a convenience function that returns only a tls.Config, it does not assume HTTP is being served on the HTTP port, so the HTTP challenge is disabled (no HTTPChallengeHandler is necessary). The package variable Default is modified so that the HTTP challenge is disabled.

Calling this function signifies your acceptance to the CA's Subscriber Agreement and/or Terms of Service.

ACMEIssuer gets certificates using ACME. It implements the PreChecker, Issuer, and Revoker interfaces.

It is NOT VALID to use an ACMEIssuer without calling NewACMEIssuer(). It fills in any default values from DefaultACME as well as setting up internal state that is necessary for valid use. Always call NewACMEIssuer() to get a valid ACMEIssuer value.

func NewACMEIssuer(cfg *Config, template ACMEIssuer) *ACMEIssuer

NewACMEIssuer constructs a valid ACMEIssuer based on a template configuration; any empty values will be filled in by defaults in DefaultACME, and if any required values are still empty, sensible defaults will be used.

Typically, you'll create the Config first with New() or NewDefault(), then call NewACMEIssuer(), then assign the return value to the Issuers field of the Config.

GetAccount first tries loading the account with the associated private key from storage. If it does not exist in storage, it will be retrieved from the ACME server and added to storage. The account must already exist; it does not create a new account.

GetRenewalInfo gets the ACME Renewal Information (ARI) for the certificate.

func (*ACMEIssuer) HTTPChallengeHandler ¶ added in v0.16.0

HTTPChallengeHandler wraps h in a handler that can solve the ACME HTTP challenge. cfg is required, and it must have a certificate cache backed by a functional storage facility, since that is where the challenge state is stored between initiation and solution.

If a request is not an ACME HTTP challenge, h will be invoked.

func (*ACMEIssuer) HandleHTTPChallenge ¶ added in v0.16.0

HandleHTTPChallenge uses am to solve challenge requests from an ACME server that were initiated by this instance or any other instance in this cluster (being, any instances using the same storage am does).

If the HTTP challenge is disabled, this function is a no-op.

If am is nil or if am does not have a certificate cache backed by usable storage, solving the HTTP challenge will fail.

It returns true if it handled the request; if so, the response has already been written. If false is returned, this call was a no-op and the request has not been handled.

Issue implements the Issuer interface. It obtains a certificate for the given csr using the ACME configuration am.

IssuerKey returns the unique issuer key for the configured CA endpoint.

PreCheck performs a few simple checks before obtaining or renewing a certificate with ACME, and returns whether this batch is eligible for certificates. It also ensures that an email address is available if possible.

IP certificates via ACME are defined in RFC 8738.

Revoke implements the Revoker interface. It revokes the given certificate.

Cache is a structure that stores certificates in memory. A Cache indexes certificates by name for quick access during TLS handshakes, and avoids duplicating certificates in memory. Generally, there should only be one per process. However, that is not a strict requirement; but using more than one is a code smell, and may indicate an over-engineered design.

An empty cache is INVALID and must not be used. Be sure to call NewCache to get a valid value.

These should be very long-lived values and must not be copied. Before all references leave scope to be garbage collected, ensure you call Stop() to stop maintenance on the certificates stored in this cache and release locks.

Caches are not usually manipulated directly; create a Config value with a pointer to a Cache, and then use the Config to interact with the cache. Caches are agnostic of any particular storage or ACME config, since each certificate may be managed and stored differently.

func NewCache(opts CacheOptions) *Cache

NewCache returns a new, valid Cache for efficiently accessing certificates in memory. It also begins a maintenance goroutine to tend to the certificates in the cache. Call Stop() when you are done with the cache so it can clean up locks and stuff.

Most users of this package will not need to call this because a default certificate cache is created for you. Only advanced use cases require creating a new cache.

This function panics if opts.GetConfigForCert is not set. The reason is that a cache absolutely needs to be able to get a Config with which to manage TLS assets, and it is not safe to assume that the Default config is always the correct one, since you have created the cache yourself.

See the godoc for Cache to use it properly. When no longer needed, caches should be stopped with Stop() to clean up resources even if the process is being terminated, so that it can clean up any locks for other processes to unblock!

func (certCache *Cache) AllMatchingCertificates(name string) []Certificate

AllMatchingCertificates returns a list of all certificates that could be used to serve the given SNI name, including exact SAN matches and wildcard matches.

func (certCache *Cache) Remove(hashes []string)

Remove removes certificates with the given hashes from the cache. This is effectively used to unload manually-loaded certificates.

func (certCache *Cache) RemoveManaged(subjects []SubjectIssuer)

RemoveManaged removes managed certificates for the given subjects from the cache. This effectively stops maintenance of those certificates. If an IssuerKey is specified alongside the subject, only certificates for that subject from the specified issuer will be removed.

RenewManagedCertificates renews managed certificates, including ones loaded on-demand. Note that this is done automatically on a regular basis; normally you will not need to call this. This method assumes non-interactive mode (i.e. operating in the background).

func (certCache *Cache) SetOptions(opts CacheOptions)

func (certCache *Cache) Stop()

Stop stops the maintenance goroutine for certificates in certCache. It blocks until stopping is complete. Once a cache is stopped, it cannot be reused.

CacheOptions is used to configure certificate caches. Once a cache has been created with certain options, those settings cannot be changed.

Certificate is a tls.Certificate with associated metadata tacked on. Even if the metadata can be obtained by parsing the certificate, we are more efficient by extracting the metadata onto this struct, but at the cost of slightly higher memory use.

DefaultCertificateSelector is the default certificate selection logic given a choice of certificates. If there is at least one certificate in choices, it always returns a certificate without error. It chooses the first non-expired certificate that the client supports if possible, otherwise it returns an expired certificate that the client supports, otherwise it just returns the first certificate in the list of choices.

Empty returns true if the certificate struct is not filled out; at least the tls.Certificate.Certificate field is expected to be set.

func (cert Certificate) Expired() bool

Expired returns true if the certificate has expired.

HasTag returns true if cert.Tags has tag.

Hash returns a checksum of the certificate chain's DER-encoded bytes.

Lifetime returns the duration of the certificate's validity.

func (cert Certificate) NeedsRenewal(cfg *Config) bool

NeedsRenewal returns true if the certificate is expiring soon (according to ARI and/or cfg) or has expired.

type CertificateResource struct {
	
	
	SANs []string `json:"sans,omitempty"`

	
	
	CertificatePEM []byte `json:"-"`

	
	PrivateKeyPEM []byte `json:"-"`

	
	
	IssuerData json.RawMessage `json:"issuer_data,omitempty"`
	
}

CertificateResource associates a certificate with its private key and other useful information, for use in maintaining the certificate.

NamesKey returns the list of SANs as a single string, truncated to some ridiculously long size limit. It can act as a key for the set of names on the resource.

CertificateSelector is a type which can select a certificate to use given multiple choices.

type ChainPreference struct {
	
	Smallest *bool

	
	
	RootCommonName []string

	
	
	AnyCommonName []string
}

ChainPreference describes the client's preferred certificate chain, useful if the CA offers alternate chains. The first matching chain will be selected.

Challenge is an ACME challenge, but optionally paired with data that can make it easier or more efficient to solve.

GetACMEChallenge returns an active ACME challenge for the given identifier, or false if no active challenge for that identifier is known.

CleanStorageOptions specifies how to clean up a storage unit.

Config configures a certificate manager instance. An empty Config is not valid: use New() to obtain a valid Config.

func New(certCache *Cache, cfg Config) *Config

New makes a new, valid config based on cfg and uses the provided certificate cache. certCache MUST NOT be nil or this function will panic.

Use this method when you have an advanced use case that requires a custom certificate cache and config that may differ from the Default. For example, if not all certificates are managed/renewed the same way, you need to make your own Cache value with a GetConfigForCert callback that returns the correct configuration for each certificate. However, for the vast majority of cases, there will be only a single Config, thus the default cache (which always uses the default Config) and default config will suffice, and you should use NewDefault() instead.

func NewDefault() *Config

NewDefault makes a valid config based on the package Default config. Most users will call this function instead of New() since most use cases require only a single config for any and all certificates.

If your requirements are more advanced (for example, multiple configs depending on the certificate), then use New() instead. (You will need to make your own Cache first.) If you only need a single Config to manage your certs (even if that config changes, as long as it is the only one), customize the Default package variable before calling NewDefault().

All calls to NewDefault() will return configs that use the same, default certificate cache. All configs returned by NewDefault() are based on the values of the fields of Default at the time it is called.

This is the only way to get a config that uses the default certificate cache.

CacheManagedCertificate loads the certificate for domain into the cache, from the TLS storage for managed certificates. It returns a copy of the Certificate that was put into the cache.

This is a lower-level method; normally you'll call Manage() instead.