acmedns

README

Acmedns implements automatic ACME-based TLS certificate renewal via a standalone DNS server. Documentation can be found at https://godoc.org/github.com/tsavola/acmedns.

This codebase includes a modified copy of https://golang.org/x/crypto/acme/autocert. Its copyright is held by The Go Authors. All code is released using similar license terms.

Documentation

Overview

Package acmedns and its subpackages implement automatic ACME-based TLS certificate renewal (Let's Encrypt) via a standalone DNS server. The purpose is to support wildcard certificates, which requires DNS verification.

This top-level package provides some reusable primitives, built on https://golang.org/x/crypto/acme.

Subpackages

The autocert subpackage is modeled after https://golang.org/x/crypto/acme/autocert. It can obtain and renew TLS certificates behind the scenes, during the normal operation of a TLS listener. A DNS backend must be plugged in to help it fulfill ACME's DNS challenges.

The dns/dnsserver subpackage implements an simple, authoritative DNS server. It expects a zone database to be plugged in.

The dns/dnszone subpackage implements just such a zone container. The autocert, dnszone, and dnsserver subsystems can be combined to implement the whole certificate renewal process in one Go program.

Those subsystems can also be combined with custom components, e.g. if the TLS listener and DNS server need to run in different processes or hosts, or to use a cloud DNS service.

DNS configuration

The idea is that there are fewer moving parts if the TLS server and its name server are the same server (e.g. 192.0.2.0). We just need some domain names: one for the name server (example.net), and one for the TLS server with wildcard needs (example.org). One could also be a subdomain of the other, but that would be messier to illustrate.

1. Zone “example.net” is hosted somewhere.

2. Name “ns.example.net” is configured with address 192.0.2.0.

3. A server program using acmedns is running at 192.0.2.0.

4. It configures dnsserver as “ns.example.net”.

5. It configures dnszone “example.org” with address 192.0.2.0 for all names.

6. “ns.example.net” is registered as the primary name server of the “example.org” domain.

7. Some slave name server mirroring “ns.example.net” should be registered as a secondary name server of the “example.org” domain (but the setup works also without one).

No fancy cloud DNS provider API adapters, just good *ahem* old DNS protocol!

Steps 3, 4, and 5 as code:

package main

import (
	"context"
	"net"

	"github.com/tsavola/acmedns/dns"
	"github.com/tsavola/acmedns/dns/dnsserver"
	"github.com/tsavola/acmedns/dns/dnszone"
)

func main() {
	// Step 4
	config := &dnsserver.Config{
		SOA: dnsserver.SOA{
			NS:   "ns.example.net.",
			Mbox: "hostmaster.example.net.",
		},
	}

	// Step 5
	zones := dnszone.Init(&dnszone.Zone{
		Domain: "example.org.",
		Nodes: map[string]*dns.Records{
			dns.Wildcard: &dns.Records{
				Addr: dns.AddrRecord{
					A:   net.ParseIP("192.0.2.0"),
					TTL: 7200,
				},
			},
		},
	})

	// Step 3
	panic(dnsserver.Serve(context.Background(), zones, config))
}

Index

• func AcquireAuthorization(ctx context.Context, client *acme.Client, authz *acme.Authorization, dns DNS, ...) (*acme.Authorization, error)
• func FulfillChallenge(ctx context.Context, client *acme.Client, chal *acme.Challenge, dns DNS, ...) error
• func Verify(ctx context.Context, client *acme.Client, dns DNS, serverName, zone string) (err error)
• type DNS

Functions

func AcquireAuthorization

func AcquireAuthorization(ctx context.Context, client *acme.Client, authz *acme.Authorization, dns DNS, zone string) (*acme.Authorization, error)

func FulfillChallenge

func FulfillChallenge(ctx context.Context, client *acme.Client, chal *acme.Challenge, dns DNS, zone string) error

func Verify

func Verify(ctx context.Context, client *acme.Client, dns DNS, serverName, zone string) (err error)

Types

type DNS

type DNS interface {
	ModifyTXTRecord(ctx context.Context, zone, node string, values []string, ttl uint32) error
}

DNS can create/update TXT records on name servers. It doesn't have to be instantaneous.