<a href="https://pkg.go.dev/github.com/caddyserver/certmagic?tab=doc">
<img src="https://github.com/caddyserver/certmagic/raw/v0.25.4/docs/banner/certmagic-banner.png" alt="CertMagic" width="550">
</a>
The same library used by the Caddy Web Server
<a href="https://pkg.go.dev/github.com/caddyserver/certmagic?tab=doc"><img src="https://img.shields.io/badge/godoc-reference-blue.svg"></a>
<a href="https://github.com/caddyserver/certmagic/actions?query=workflow%3ATests"><img src="https://github.com/caddyserver/certmagic/workflows/Tests/badge.svg"></a>
<a href="https://sourcegraph.com/github.com/caddyserver/certmagic?badge"><img src="https://sourcegraph.com/github.com/caddyserver/certmagic/-/badge.svg"></a>
Caddy's automagic TLS features—now for your own Go programs—in one powerful and easy-to-use library!
CertMagic is the most mature, robust, and powerful ACME client integration for Go... and perhaps ever.
With CertMagic, you can add one line to your Go application to serve securely over TLS, without ever having to touch certificates.
Instead of:
// plaintext HTTP, gross 🤢
http.ListenAndServe(":80", mux)
Use CertMagic:
// encrypted HTTPS with HTTP->HTTPS redirects - yay! 🔒😍
certmagic.HTTPS([]string{"example.com"}, mux)
That line of code will serve your HTTP router mux over HTTPS, complete with HTTP->HTTPS redirects. It obtains and renews the TLS certificates. It staples OCSP responses for greater privacy and security. As long as your domain name points to your server, CertMagic will keep its connections secure.
Compared to other ACME client libraries for Go, only CertMagic supports the full suite of ACME features, and no other library matches CertMagic's maturity and reliability.
Before using this library, your domain names MUST be pointed (A/AAAA records) at your server (unless you use the DNS challenge)!
$ go get github.com/caddyserver/certmagic
This library uses Let's Encrypt by default, but you can use any certificate authority that conforms to the ACME specification. Known/common CAs are provided as consts in the package, for example LetsEncryptStagingCA and LetsEncryptProductionCA.
Config typeThe certmagic.Config struct is how you can wield the power of this fully armed and operational battle station. However, an empty/uninitialized Config is not a valid one! In time, you will learn to use the force of certmagic.NewDefault() as I have.
The default Config value is called certmagic.Default. Change its fields to suit your needs, then call certmagic.NewDefault() when you need a valid Config value. In other words, certmagic.Default is a template and is not valid for use directly.
You can set the default values easily, for example: certmagic.Default.Issuer = ....
Similarly, to configure ACME-specific defaults, use certmagic.DefaultACME.
The high-level functions in this package (HTTPS(), Listen(), ManageSync(), and ManageAsync()) use the default config exclusively. This is how most of you will interact with the package. This is suitable when all your certificates are managed the same way. However, if you need to manage certificates differently depending on their name, you will need to make your own cache and configs (keep reading).
Although not strictly required, this is highly recommended best practice. It allows you to receive expiration emails if your certificates are expiring for some reason, and also allows the CA's engineers to potentially get in touch with you if something is wrong. I recommend setting certmagic.DefaultACME.Email or always setting the Email field of a new Config struct.
To avoid firehosing the CA's servers, CertMagic has built-in rate limiting. Currently, its default limit is up to 10 transactions (obtain or renew) every 1 minute (sliding window). This can be changed by setting the RateLimitEvents and RateLimitEventsWindow variables, if desired.
The CA may still enforce their own rate limits, and there's nothing (well, nothing ethical) CertMagic can do to bypass them for you.
Additionally, CertMagic will retry failed validations with exponential backoff for up to 30 days, with a reasonable maximum interval between attempts (an "attempt" means trying each enabled challenge type once).
Note that Let's Encrypt imposes strict rate limits at its production endpoint, so using it while developing your application may lock you out for a few days if you aren't careful!
While developing your application and testing it, use their staging endpoint which has much higher rate limits. Even then, don't hammer it: but it's much safer for when you're testing. When deploying, though, use their production CA because their staging CA doesn't issue trusted certificates.
To use staging, set certmagic.DefaultACME.CA = certmagic.LetsEncryptStagingCA or set CA of every ACMEIssuer struct.
There are many ways to use this library. We'll start with the highest-level (simplest) and work down (more control).
All these high-level examples use certmagic.Default and certmagic.DefaultACME for the config and the default cache and storage for serving up certificates.
First, we'll follow best practices and do the following:
// read and agree to your CA's legal documents
certmagic.DefaultACME.Agreed = true
// provide an email address
certmagic.DefaultACME.Email = "you@yours.com"
// use the staging endpoint while we're developing
certmagic.DefaultACME.CA = certmagic.LetsEncryptStagingCA
For fully-functional program examples, check out this X thread (or read it unrolled into a single post). (Note that the package API has changed slightly since these posts.)
err := certmagic.HTTPS([]string{"example.com", "www.example.com"}, mux)
if err != nil {
return err
}
This starts HTTP and HTTPS listeners and redirects HTTP to HTTPS!
ln, err := certmagic.Listen([]string{"example.com"})
if err != nil {
return err
}
tlsConfig, err := certmagic.TLS([]string{"example.com"})
if err != nil {
return err
}
// be sure to customize NextProtos if serving a specific
// application protocol after the TLS handshake, for example:
tlsConfig.NextProtos = append([]string{"h2", "http/1.1"}, tlsConfig.NextProtos...)
For more control (particularly, if you need a different way of managing each certificate), you'll make and use a Cache and a Config like so:
// First make a pointer to a Cache as we need to reference the same Cache in
// GetConfigForCert below.
var cache *certmagic.Cache
cache = certmagic.NewCache(certmagic.CacheOptions{
GetConfigForCert: func(cert certmagic.Certificate) (*certmagic.Config, error) {
// Here we use New to get a valid Config associated with the same cache.
// The provided Config is used as a template and will be completed with
// any defaults that are set in the Default config.
return certmagic.New(cache, certmagic.Config{
// ...
}), nil
},
...
})
magic := certmagic.New(cache, certmagic.Config{
// any customizations you need go here
})
myACME := certmagic.NewACMEIssuer(magic, certmagic.ACMEIssuer{
CA: certmagic.LetsEncryptStagingCA,
Email: "you@yours.com",
Agreed: true,
// plus any other customizations you need
})
magic.Issuers = []certmagic.Issuer{myACME}
// this obtains certificates or renews them if necessary
err := magic.ManageSync(context.TODO(), []string{"example.com", "sub.example.com"})
if err != nil {
return err
}
// to use its certificates and solve the TLS-ALPN challenge,
// you can get a TLS config to use in a TLS listener!
tlsConfig := magic.TLSConfig()
// be sure to customize NextProtos if serving a specific
// application protocol after the TLS handshake, for example:
tlsConfig.NextProtos = append([]string{"h2", "http/1.1"}, tlsConfig.NextProtos...)
//// OR ////
// if you already have a TLS config you don't want to replace,
// we can simply set its GetCertificate field and append the
// TLS-ALPN challenge protocol to the NextProtos
myTLSConfig.GetCertificate = magic.GetCertificate
myTLSConfig.NextProtos = append(myTLSConfig.NextProtos, acmez.ACMETLS1Protocol)
// the HTTP challenge has to be handled by your HTTP server;
// if you don't have one, you should have disabled it earlier
// when you made the certmagic.Config
httpMux = myACME.HTTPChallengeHandler(httpMux)
Great! This example grants you much more flexibility for advanced programs. However, the vast majority of you will only use the high-level functions described earlier, especially since you can still customize them by setting the package-level Default config.
At time of writing (December 2018), Let's Encrypt only issues wildcard certificates with the DNS challe
$ claude mcp add certmagic \
-- python -m otcore.mcp_server <graph>