dane

Documentation

Overview

Package dane verifies TLS certificates through DNSSEC-verified TLSA records.

On the internet, TLS certificates are commonly verified by checking if they are signed by one of many commonly trusted Certificate Authorities (CAs). This is PKIX or WebPKI. With DANE, TLS certificates are verified through DNSSEC-protected DNS records of type TLSA. These TLSA records specify the rules for verification ("usage") and whether a full certificate ("selector" cert) is checked or only its "subject public key info" ("selector" spki). The (hash of) the certificate or "spki" is included in the TLSA record ("matchtype").

DANE SMTP connections have two allowed "usages" (verification rules):

• DANE-EE, which only checks if the certificate or spki match, without the WebPKI verification of expiration, name or signed-by-trusted-party verification.
• DANE-TA, which does verification similar to PKIX/WebPKI, but verifies against a certificate authority ("trust anchor", or "TA") specified in the TLSA record instead of the CA pool.

DANE has two more "usages", that may be used with protocols other than SMTP:

• PKIX-EE, which matches the certificate or spki, and also verifies the certificate against the CA pool.
• PKIX-TA, which verifies the certificate or spki against a "trust anchor" specified in the TLSA record, that also has to be trusted by the CA pool.

TLSA records are looked up for a specific port number, protocol (tcp/udp) and host name. Each port can have different TLSA records. TLSA records must be signed and verified with DNSSEC before they can be trusted and used.

TLSA records are looked up under "TLSA candidate base domains". The domain where the TLSA records are found is the "TLSA base domain". If the host to connect to is a CNAME that can be followed with DNSSEC protection, it is the first TLSA candidate base domain. If no protected records are found, the original host name is the second TLSA candidate base domain.

For TLS connections, the TLSA base domain is used with SNI during the handshake.

For TLS certificate verification that requires PKIX/WebPKI/trusted-anchor verification (all except DANE-EE), the potential second TLSA candidate base domain name is also a valid hostname. With SMTP, additionally for hosts found in MX records for a "next-hop domain", the "original next-hop domain" (domain of an email address to deliver to) is also a valid name, as is the "CNAME-expanded original next-hop domain", bringing the potential total allowed names to four (if CNAMEs are followed for the MX hosts).

Index

• Variables
• func Dial(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, ...) (net.Conn, adns.TLSA, error)
• func TLSClientConfig(elog *slog.Logger, records []adns.TLSA, allowedHost dns.Domain, ...) tls.Config
• func Verify(elog *slog.Logger, records []adns.TLSA, cs tls.ConnectionState, ...) (verified bool, matching adns.TLSA, rerr error)
• type VerifyError
  • func (e VerifyError) Error() string
  • func (e VerifyError) Unwrap() error

Examples

• Dial

Variables

var (
	MetricVerify       stub.Counter = stub.CounterIgnore{}
	MetricVerifyErrors stub.Counter = stub.CounterIgnore{}
)

var (
	// ErrNoRecords means no TLSA records were found and host has not opted into DANE.
	ErrNoRecords = errors.New("dane: no tlsa records")

	// ErrInsecure indicates insecure DNS responses were encountered while looking up
	// the host, CNAME records, or TLSA records.
	ErrInsecure = errors.New("dane: dns lookups insecure")

	// ErrNoMatch means some TLSA records were found, but none can be verified against
	// the remote TLS certificate.
	ErrNoMatch = errors.New("dane: no match between certificate and tlsa records")
)

Functions

func Dial

func Dial(ctx context.Context, elog *slog.Logger, resolver dns.Resolver, network, address string, allowedUsages []adns.TLSAUsage, pkixRoots *x509.CertPool) (net.Conn, adns.TLSA, error)

Dial looks up DNSSEC-protected DANE TLSA records for the domain name and port/service in address, checks for allowed usages, makes a network connection and verifies the remote certificate against the TLSA records. If verification succeeds, the verified record is returned.

Different protocols require different usages. For example, SMTP with STARTTLS for delivery only allows usages DANE-TA and DANE-EE. If allowedUsages is non-nil, only the specified usages are taken into account when verifying, and any others ignored.

Errors that can be returned, possibly in wrapped form:

• ErrNoRecords, also in case the DNS response indicates "not found".
• adns.DNSError, potentially wrapping adns.ExtendedError of which some can indicate DNSSEC errors.
• ErrInsecure
• VerifyError, potentially wrapping errors from crypto/x509.

Example

package main

import (
	"context"
	"crypto/x509"
	"log"
	"log/slog"

	"github.com/mjl-/adns"

	"github.com/mjl-/mox/dane"
	"github.com/mjl-/mox/dns"
)

func main() {
	ctx := context.Background()
	resolver := dns.StrictResolver{}
	usages := []adns.TLSAUsage{adns.TLSAUsageDANETA, adns.TLSAUsageDANEEE}
	pkixRoots, err := x509.SystemCertPool()
	if err != nil {
		log.Fatalf("system pkix roots: %v", err)
	}

	// Connect to SMTP server, use STARTTLS, and verify TLS certificate with DANE.
	conn, verifiedRecord, err := dane.Dial(ctx, slog.Default(), resolver, "tcp", "mx.example.com", usages, pkixRoots)
	if err != nil {
		log.Fatalf("dial: %v", err)
	}
	defer conn.Close()

	log.Printf("connected, conn %v, verified record %s", conn, verifiedRecord)
}

func TLSClientConfig

func TLSClientConfig(elog *slog.Logger, records []adns.TLSA, allowedHost dns.Domain, moreAllowedHosts []dns.Domain, verifiedRecord *adns.TLSA, pkixRoots *x509.CertPool) tls.Config

TLSClientConfig returns a tls.Config to be used for dialing/handshaking a TLS connection with DANE verification.

Callers should only pass records that are allowed for the intended use. DANE with SMTP only allows DANE-EE and DANE-TA usages, not the PKIX-usages.

The config has InsecureSkipVerify set to true, with a custom VerifyConnection function for verifying DANE. Its VerifyConnection can return ErrNoMatch and additionally one or more (wrapped) errors of type VerifyError.

The TLS config uses allowedHost for SNI.

If verifiedRecord is not nil, it is set to the record that was successfully verified, if any.

func Verify

func Verify(elog *slog.Logger, records []adns.TLSA, cs tls.ConnectionState, allowedHost dns.Domain, moreAllowedHosts []dns.Domain, pkixRoots *x509.CertPool) (verified bool, matching adns.TLSA, rerr error)

Verify checks if the TLS connection state can be verified against DANE TLSA records.

allowedHost along with the optional moreAllowedHosts are the host names that are allowed during certificate verification (as used by PKIX-TA, PKIX-EE, DANE-TA, but not DANE-EE). A typical connection would allow just one name, but some uses of DANE allow multiple, like SMTP which allow up to four valid names for a TLS certificate based on MX/CNAME/TLSA/DNSSEC lookup results.

When one of the records matches, Verify returns true, along with the matching record and a nil error. If there is no match, then in the typical case Verify returns: false, a zero record value and a nil error. If an error is encountered while verifying a record, e.g. for x509 trusted-anchor verification, an error may be returned, typically one or more (wrapped) errors of type VerifyError.

Verify is useful when DANE verification and its results has to be done separately from other validation, e.g. for MTA-STS. The caller can create a tls.Config with a VerifyConnection function that checks DANE and MTA-STS separately.

Types

type VerifyError

type VerifyError struct {
	Err    error     // Underlying error, possibly from crypto/x509.
	Record adns.TLSA // Cause of error.
}

VerifyError is an error encountered while verifying a DANE TLSA record. For example, an error encountered with x509 certificate trusted-anchor verification. A TLSA record that does not match a TLS certificate is not a VerifyError.

func (VerifyError) Error

func (e VerifyError) Error() string

Error returns a string explaining this is a dane verify error along with the underlying error.

func (VerifyError) Unwrap

func (e VerifyError) Unwrap() error

Unwrap returns the underlying error.