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

2//

3// On the internet, TLS certificates are commonly verified by checking if they are

4// signed by one of many commonly trusted Certificate Authorities (CAs). This is

5// PKIX or WebPKI. With DANE, TLS certificates are verified through

6// DNSSEC-protected DNS records of type TLSA. These TLSA records specify the rules

7// for verification ("usage") and whether a full certificate ("selector" cert) is

8// checked or only its "subject public key info" ("selector" spki). The (hash of)

9// the certificate or "spki" is included in the TLSA record ("matchtype").

10//

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

12// - DANE-EE, which only checks if the certificate or spki match, without the

13// WebPKI verification of expiration, name or signed-by-trusted-party verification.

14// - DANE-TA, which does verification similar to PKIX/WebPKI, but verifies against

15// a certificate authority ("trust anchor", or "TA") specified in the TLSA record

16// instead of the CA pool.

17//

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

19// - PKIX-EE, which matches the certificate or spki, and also verifies the

20// certificate against the CA pool.

21// - PKIX-TA, which verifies the certificate or spki against a "trust anchor"

22// specified in the TLSA record, that also has to be trusted by the CA pool.

23//

24// TLSA records are looked up for a specific port number, protocol (tcp/udp) and

25// host name. Each port can have different TLSA records. TLSA records must be

26// signed and verified with DNSSEC before they can be trusted and used.

27//

28// TLSA records are looked up under "TLSA candidate base domains". The domain

29// where the TLSA records are found is the "TLSA base domain". If the host to

30// connect to is a CNAME that can be followed with DNSSEC protection, it is the

31// first TLSA candidate base domain. If no protected records are found, the

32// original host name is the second TLSA candidate base domain.

33//

34// For TLS connections, the TLSA base domain is used with SNI during the

35// handshake.

36//

37// For TLS certificate verification that requires PKIX/WebPKI/trusted-anchor

38// verification (all except DANE-EE), the potential second TLSA candidate base

39// domain name is also a valid hostname. With SMTP, additionally for hosts found in

40// MX records for a "next-hop domain", the "original next-hop domain" (domain of an

41// email address to deliver to) is also a valid name, as is the "CNAME-expanded

42// original next-hop domain", bringing the potential total allowed names to four

43// (if CNAMEs are followed for the MX hosts).

44package dane

45

46// todo: why is https://datatracker.ietf.org/doc/html/draft-barnes-dane-uks-00 not in use? sounds reasonable.

47// todo: add a DialSRV function that accepts a domain name, looks up srv records, dials the service, verifies dane certificate and returns the connection. for ../rfc/7673

48

49import (

50 "bytes"

51 "context"

52 "crypto/sha256"

53 "crypto/sha512"

54 "crypto/tls"

55 "crypto/x509"

56 "errors"

57 "fmt"

58 "net"

59 "strings"

60 "time"

61

62 "golang.org/x/exp/slog"

63

64 "github.com/mjl-/adns"

65

66 "github.com/mjl-/mox/dns"

67 "github.com/mjl-/mox/mlog"

68 "github.com/mjl-/mox/stub"

69)

70

71var (

72 MetricVerify stub.Counter = stub.CounterIgnore{}

73 MetricVerifyErrors stub.Counter = stub.CounterIgnore{}

74)

75

76var (

77 // ErrNoRecords means no TLSA records were found and host has not opted into DANE.

78 ErrNoRecords = errors.New("dane: no tlsa records")

79

80 // ErrInsecure indicates insecure DNS responses were encountered while looking up

81 // the host, CNAME records, or TLSA records.

82 ErrInsecure = errors.New("dane: dns lookups insecure")

83

84 // ErrNoMatch means some TLSA records were found, but none can be verified against

85 // the remote TLS certificate.

86 ErrNoMatch = errors.New("dane: no match between certificate and tlsa records")

87)

88

89// VerifyError is an error encountered while verifying a DANE TLSA record. For

90// example, an error encountered with x509 certificate trusted-anchor verification.

91// A TLSA record that does not match a TLS certificate is not a VerifyError.

92type VerifyError struct {

93 Err error // Underlying error, possibly from crypto/x509.

94 Record adns.TLSA // Cause of error.

95}

96

97// Error returns a string explaining this is a dane verify error along with the

98// underlying error.

99func (e VerifyError) Error() string {

100 return fmt.Sprintf("dane verify error: %s", e.Err)

101}

102

103// Unwrap returns the underlying error.

104func (e VerifyError) Unwrap() error {

105 return e.Err

106}

107

108// Dial looks up DNSSEC-protected DANE TLSA records for the domain name and

109// port/service in address, checks for allowed usages, makes a network connection

110// and verifies the remote certificate against the TLSA records. If verification

111// succeeds, the verified record is returned.

112//

113// Different protocols require different usages. For example, SMTP with STARTTLS

114// for delivery only allows usages DANE-TA and DANE-EE. If allowedUsages is

115// non-nil, only the specified usages are taken into account when verifying, and

116// any others ignored.

117//

118// Errors that can be returned, possibly in wrapped form:

119// - ErrNoRecords, also in case the DNS response indicates "not found".

120// - adns.DNSError, potentially wrapping adns.ExtendedError of which some can

121// indicate DNSSEC errors.

122// - ErrInsecure

123// - VerifyError, potentially wrapping errors from crypto/x509.

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

125 log := mlog.New("dane", elog)

126

127 // Split host and port.

128 host, portstr, err := net.SplitHostPort(address)

129 if err != nil {

130 return nil, adns.TLSA{}, fmt.Errorf("parsing address: %w", err)

131 }

132 port, err := resolver.LookupPort(ctx, network, portstr)

133 if err != nil {

134 return nil, adns.TLSA{}, fmt.Errorf("parsing port: %w", err)

135 }

136

137 hostDom, err := dns.ParseDomain(strings.TrimSuffix(host, "."))

138 if err != nil {

139 return nil, adns.TLSA{}, fmt.Errorf("parsing host: %w", err)

140 }

141

142 // ../rfc/7671:1015

143 // First follow CNAMEs for host. If the path to the final name is secure, we must

144 // lookup TLSA there first, then fallback to the original name. If the final name

145 // is secure that's also the SNI server name we must use, with the original name as

146 // allowed host during certificate name checks (for all TLSA usages other than

147 // DANE-EE).

148 cnameDom := hostDom

149 cnameAuthentic := true

150 for i := 0; ; i += 1 {

151 if i == 10 {

152 return nil, adns.TLSA{}, fmt.Errorf("too many cname lookups")

153 }

154 cname, cnameResult, err := resolver.LookupCNAME(ctx, cnameDom.ASCII+".")

155 cnameAuthentic = cnameAuthentic && cnameResult.Authentic

156 if !cnameResult.Authentic && i == 0 {

157 return nil, adns.TLSA{}, fmt.Errorf("%w: cname lookup insecure", ErrInsecure)

158 } else if dns.IsNotFound(err) {

159 break

160 } else if err != nil {

161 return nil, adns.TLSA{}, fmt.Errorf("resolving cname %s: %w", cnameDom, err)

162 } else if d, err := dns.ParseDomain(strings.TrimSuffix(cname, ".")); err != nil {

163 return nil, adns.TLSA{}, fmt.Errorf("parsing cname: %w", err)

164 } else {

165 cnameDom = d

166 }

167 }

168

169 // We lookup the IP.

170 ipnetwork := "ip"

171 if strings.HasSuffix(network, "4") {

172 ipnetwork += "4"

173 } else if strings.HasSuffix(network, "6") {

174 ipnetwork += "6"

175 }

176 ips, _, err := resolver.LookupIP(ctx, ipnetwork, cnameDom.ASCII+".")

177 // note: For SMTP with opportunistic DANE we would stop here with an insecure

178 // response. But as long as long as we have a verified original tlsa base name, we

179 // can continue with regular DANE.

180 if err != nil {

181 return nil, adns.TLSA{}, fmt.Errorf("resolving ips: %w", err)

182 } else if len(ips) == 0 {

183 return nil, adns.TLSA{}, &adns.DNSError{Err: "no ips for host", Name: cnameDom.ASCII, IsNotFound: true}

184 }

185

186 // Lookup TLSA records. If resolving CNAME was secure, we try that first. Otherwise

187 // we try at the secure original domain.

188 baseDom := hostDom

189 if cnameAuthentic {

190 baseDom = cnameDom

191 }

192 var records []adns.TLSA

193 var result adns.Result

194 for {

195 var err error

196 records, result, err = resolver.LookupTLSA(ctx, port, network, baseDom.ASCII+".")

197 // If no (secure) records can be found at the final cname, and there is an original

198 // name, try at original name.

199 // ../rfc/7671:1015

200 if baseDom != hostDom && (dns.IsNotFound(err) || !result.Authentic) {

201 baseDom = hostDom

202 continue

203 }

204 if !result.Authentic {

205 return nil, adns.TLSA{}, ErrInsecure

206 } else if dns.IsNotFound(err) {

207 return nil, adns.TLSA{}, ErrNoRecords

208 } else if err != nil {

209 return nil, adns.TLSA{}, fmt.Errorf("lookup dane tlsa records: %w", err)

210 }

211 break

212 }

213

214 // Keep only the allowed usages.

215 if allowedUsages != nil {

216 o := 0

217 for _, r := range records {

218 for _, usage := range allowedUsages {

219 if r.Usage == usage {

220 records[o] = r

221 o++

222 break

223 }

224 }

225 }

226 records = records[:o]

227 if len(records) == 0 {

228 // No point in dialing when we know we won't be able to verify the remote TLS

229 // certificate.

230 return nil, adns.TLSA{}, fmt.Errorf("no usable tlsa records remaining: %w", ErrNoMatch)

231 }

232 }

233

234 // We use the base domain for SNI, allowing the original domain as well.

235 // ../rfc/7671:1021

236 var moreAllowedHosts []dns.Domain

237 if baseDom != hostDom {

238 moreAllowedHosts = []dns.Domain{hostDom}

239 }

240

241 // Dial the remote host.

242 timeout := 30 * time.Second

243 if deadline, ok := ctx.Deadline(); ok && len(ips) > 0 {

244 timeout = time.Until(deadline) / time.Duration(len(ips))

245 }

246 dialer := &net.Dialer{Timeout: timeout}

247 var conn net.Conn

248 var dialErrs []error

249 for _, ip := range ips {

250 addr := net.JoinHostPort(ip.String(), portstr)

251 c, err := dialer.DialContext(ctx, network, addr)

252 if err != nil {

253 dialErrs = append(dialErrs, err)

254 continue

255 }

256 conn = c

257 break

258 }

259 if conn == nil {

260 return nil, adns.TLSA{}, errors.Join(dialErrs...)

261 }

262

263 var verifiedRecord adns.TLSA

264 config := TLSClientConfig(log.Logger, records, baseDom, moreAllowedHosts, &verifiedRecord, pkixRoots)

265 tlsConn := tls.Client(conn, &config)

266 if err := tlsConn.HandshakeContext(ctx); err != nil {

267 conn.Close()

268 return nil, adns.TLSA{}, err

269 }

270 return tlsConn, verifiedRecord, nil

271}

272

273// TLSClientConfig returns a tls.Config to be used for dialing/handshaking a

274// TLS connection with DANE verification.

275//

276// Callers should only pass records that are allowed for the intended use. DANE

277// with SMTP only allows DANE-EE and DANE-TA usages, not the PKIX-usages.

278//

279// The config has InsecureSkipVerify set to true, with a custom VerifyConnection

280// function for verifying DANE. Its VerifyConnection can return ErrNoMatch and

281// additionally one or more (wrapped) errors of type VerifyError.

282//

283// The TLS config uses allowedHost for SNI.

284//

285// If verifiedRecord is not nil, it is set to the record that was successfully

286// verified, if any.

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

288 log := mlog.New("dane", elog)

289 return tls.Config{

290 ServerName: allowedHost.ASCII, // For SNI.

291 InsecureSkipVerify: true,

292 VerifyConnection: func(cs tls.ConnectionState) error {

293 verified, record, err := Verify(log.Logger, records, cs, allowedHost, moreAllowedHosts, pkixRoots)

294 log.Debugx("dane verification", err, slog.Bool("verified", verified), slog.Any("record", record))

295 if verified {

296 if verifiedRecord != nil {

297 *verifiedRecord = record

298 }

299 return nil

300 } else if err == nil {

301 return ErrNoMatch

302 }

303 return fmt.Errorf("%w, and error(s) encountered during verification: %w", ErrNoMatch, err)

304 },

305 MinVersion: tls.VersionTLS12, // ../rfc/8996:31 ../rfc/8997:66

306 }

307}

308

309// Verify checks if the TLS connection state can be verified against DANE TLSA

310// records.

311//

312// allowedHost along with the optional moreAllowedHosts are the host names that are

313// allowed during certificate verification (as used by PKIX-TA, PKIX-EE, DANE-TA,

314// but not DANE-EE). A typical connection would allow just one name, but some uses

315// of DANE allow multiple, like SMTP which allow up to four valid names for a TLS

316// certificate based on MX/CNAME/TLSA/DNSSEC lookup results.

317//

318// When one of the records matches, Verify returns true, along with the matching

319// record and a nil error.

320// If there is no match, then in the typical case Verify returns: false, a zero

321// record value and a nil error.

322// If an error is encountered while verifying a record, e.g. for x509

323// trusted-anchor verification, an error may be returned, typically one or more

324// (wrapped) errors of type VerifyError.

325//

326// Verify is useful when DANE verification and its results has to be done

327// separately from other validation, e.g. for MTA-STS. The caller can create a

328// tls.Config with a VerifyConnection function that checks DANE and MTA-STS

329// separately.

330func 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) {

331 log := mlog.New("dane", elog)

332 MetricVerify.Inc()

333 if len(records) == 0 {

334 MetricVerifyErrors.Inc()

335 return false, adns.TLSA{}, fmt.Errorf("verify requires at least one tlsa record")

336 }

337 var errs []error

338 for _, r := range records {

339 ok, err := verifySingle(log, r, cs, allowedHost, moreAllowedHosts, pkixRoots)

340 if err != nil {

341 errs = append(errs, VerifyError{err, r})

342 } else if ok {

343 return true, r, nil

344 }

345 }

346 MetricVerifyErrors.Inc()

347 return false, adns.TLSA{}, errors.Join(errs...)

348}

349

350// verifySingle verifies the TLS connection against a single DANE TLSA record.

351//

352// If the remote TLS certificate matches with the TLSA record, true is

353// returned. Errors may be encountered while verifying, e.g. when checking one

354// of the allowed hosts against a TLSA record. A typical non-matching/verified

355// TLSA record returns a nil error. But in some cases, e.g. when encountering

356// errors while verifying certificates against a trust-anchor, an error can be

357// returned with one or more underlying x509 verification errors. A nil-nil error

358// is only returned when verified is false.

359func verifySingle(log mlog.Log, tlsa adns.TLSA, cs tls.ConnectionState, allowedHost dns.Domain, moreAllowedHosts []dns.Domain, pkixRoots *x509.CertPool) (verified bool, rerr error) {

360 if len(cs.PeerCertificates) == 0 {

361 return false, fmt.Errorf("no server certificate")

362 }

363

364 match := func(cert *x509.Certificate) bool {

365 var buf []byte

366 switch tlsa.Selector {

367 case adns.TLSASelectorCert:

368 buf = cert.Raw

369 case adns.TLSASelectorSPKI:

370 buf = cert.RawSubjectPublicKeyInfo

371 default:

372 return false

373 }

374

375 switch tlsa.MatchType {

376 case adns.TLSAMatchTypeFull:

377 case adns.TLSAMatchTypeSHA256:

378 d := sha256.Sum256(buf)

379 buf = d[:]

380 case adns.TLSAMatchTypeSHA512:

381 d := sha512.Sum512(buf)

382 buf = d[:]

383 default:

384 return false

385 }

386

387 return bytes.Equal(buf, tlsa.CertAssoc)

388 }

389

390 pkixVerify := func(host dns.Domain) ([][]*x509.Certificate, error) {

391 // Default Verify checks for expiration. We pass the host name to check. And we

392 // configure the intermediates. The roots are filled in by the x509 package.

393 opts := x509.VerifyOptions{

394 DNSName: host.ASCII,

395 Intermediates: x509.NewCertPool(),

396 Roots: pkixRoots,

397 }

398 for _, cert := range cs.PeerCertificates[1:] {

399 opts.Intermediates.AddCert(cert)

400 }

401 chains, err := cs.PeerCertificates[0].Verify(opts)

402 return chains, err

403 }

404

405 switch tlsa.Usage {

406 case adns.TLSAUsagePKIXTA:

407 // We cannot get at the system trusted ca certificates to look for the trusted

408 // anchor. So we just ask Go to verify, then see if any of the chains include the

409 // ca certificate.

410 var errs []error

411 for _, host := range append([]dns.Domain{allowedHost}, moreAllowedHosts...) {

412 chains, err := pkixVerify(host)

413 log.Debugx("pkix-ta verify", err)

414 if err != nil {

415 errs = append(errs, err)

416 continue

417 }

418 // The chains by x509's Verify should include the longest possible match, so it is

419 // sure to include the trusted anchor. ../rfc/7671:835

420 for _, chain := range chains {

421 // If pkix verified, check if any of the certificates match.

422 for i := len(chain) - 1; i >= 0; i-- {

423 if match(chain[i]) {

424 return true, nil

425 }

426 }

427 }

428 }

429 return false, errors.Join(errs...)

430

431 case adns.TLSAUsagePKIXEE:

432 // Check for a certificate match.

433 if !match(cs.PeerCertificates[0]) {

434 return false, nil

435 }

436 // And do regular pkix checks, ../rfc/7671:799

437 var errs []error

438 for _, host := range append([]dns.Domain{allowedHost}, moreAllowedHosts...) {

439 _, err := pkixVerify(host)

440 log.Debugx("pkix-ee verify", err)

441 if err == nil {

442 return true, nil

443 }

444 errs = append(errs, err)

445 }

446 return false, errors.Join(errs...)

447

448 case adns.TLSAUsageDANETA:

449 // We set roots, so the system defaults don't get used. Verify checks the host name

450 // (set below) and checks for expiration.

451 opts := x509.VerifyOptions{

452 Roots: x509.NewCertPool(),

453 }

454

455 // If the full certificate was included, we must add it to the valid roots, the TLS

456 // server may not send it. ../rfc/7671:692

457 var found bool

458 if tlsa.Selector == adns.TLSASelectorCert && tlsa.MatchType == adns.TLSAMatchTypeFull {

459 cert, err := x509.ParseCertificate(tlsa.CertAssoc)

460 if err != nil {

461 log.Debugx("parsing full exact certificate from tlsa record to use as root for usage dane-trusted-anchor", err)

462 // Continue anyway, perhaps the servers sends it again in a way that the tls package can parse? (unlikely)

463 } else {

464 opts.Roots.AddCert(cert)

465 found = true

466 }

467 }

468

469 for _, cert := range cs.PeerCertificates {

470 if match(cert) {

471 opts.Roots.AddCert(cert)

472 found = true

473 break

474 }

475 }

476 if !found {

477 // Trusted anchor was not found in TLS certificates so we won't be able to

478 // verify.

479 return false, nil

480 }

481

482 // Trusted anchor was found, still need to verify.

483 var errs []error

484 for _, host := range append([]dns.Domain{allowedHost}, moreAllowedHosts...) {

485 opts.DNSName = host.ASCII

486 _, err := cs.PeerCertificates[0].Verify(opts)

487 if err == nil {

488 return true, nil

489 }

490 errs = append(errs, err)

491 }

492 return false, errors.Join(errs...)

493

494 case adns.TLSAUsageDANEEE:

495 // ../rfc/7250 is about raw public keys instead of x.509 certificates in tls

496 // handshakes. Go's crypto/tls does not implement the extension (see

497 // crypto/tls/common.go, the extensions values don't appear in the

498 // rfc, but have values 19 and 20 according to

499 // https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#tls-extensiontype-values-1

500 // ../rfc/7671:1148 mentions the raw public keys are allowed. It's still

501 // questionable that this is commonly implemented. For now the world can probably

502 // live with an ignored certificate wrapped around the subject public key info.

503

504 // We don't verify host name in certificate, ../rfc/7671:489

505 // And we don't check for expiration. ../rfc/7671:527

506 // The whole point of this type is to have simple secure infrastructure that

507 // doesn't automatically expire (at the most inconvenient times).

508 return match(cs.PeerCertificates[0]), nil

509

510 default:

511 // Unknown, perhaps defined in the future. Not an error.

512 log.Debug("unrecognized tlsa usage, skipping", slog.Any("tlsausage", tlsa.Usage))

513 return false, nil

514 }

515}

516