Writing a Plugin: DNS Provider

This page is obsolete.

It is about Casket v1.

---

Join the Casket Community Forum to chat with other Casket developers!

Casket magically obtains TLS certificates for your site in 3 ways: HTTP, TLS-SNI, and DNS. The first two are used by default and can be completed without intervention by you. The third is more versatile in some environments where you cannot start a listener that can be accessed by external networks, etc. The problem is that doing it the DNS way requires custom code to interact with the DNS provider whom your domain's nameservers are pointed to.

Casket uses xenolf/lego to implement the ACME protocol and solve the domain challenges (lego was originally written for use in Casket). It supports pluggable DNS providers, but to use them in Casket they have to be adapted. It only requires a few lines of code.

If you want to add a new DNS provider, it must be built to work with lego (see that repository for instructions and documentation). Once that is working, you can adapt it for Casket very easily:

package myprovider

import (
	"errors"

	"github.com/mholt/casket/caskettls"
	"github.com/xenolf/lego/providers/dns/myprovider"
)

func init() {
	caskettls.RegisterDNSProvider("myprovider", NewDNSProvider)
}

// NewDNSProvider returns a new MyProvider DNS challenge provider.
// The credentials are interpreted as follows:
//
// len(0): use credentials from environment
// len(2): credentials[0] = API user
//         credentials[1] = API key
func NewDNSProvider(credentials ...string) (caskettls.ChallengeProvider, error) {
	switch len(credentials) {
	case 0:
		return myprovider.NewDNSProvider()
	case 2:
		return myprovider.NewDNSProviderCredentials(credentials[0], credentials[1])
	default:
		return nil, errors.New("invalid credentials length")
	}
}

Note that we do not plug the DNS provider directly into the casket package; we plug it into caskettls.

You can see all of the officially-supported adapters at casketserver/dnsproviders. If you've written a DNS provider, please feel free to submit a pull request to adapt it for use with Casket!

Once your provider is plugged in, you can use it in the Casketfile:

tls {
    dns myprovider
}

And that's all there is to it.