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 "log/slog"

59 "net"

60 "strings"

61 "time"

62

63 "github.com/mjl-/adns"

64

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

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

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

68)

69

70var (

71 MetricVerify stub.Counter = stub.CounterIgnore{}

72 MetricVerifyErrors stub.Counter = stub.CounterIgnore{}

73)

74

75var (

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

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

78

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

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

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

82

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

84 // the remote TLS certificate.

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

86)

87

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

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

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

91type VerifyError struct {

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

93 Record adns.TLSA // Cause of error.

94}

95

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

97// underlying error.

98func (e VerifyError) Error() string {

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

100}

101

102// Unwrap returns the underlying error.

103func (e VerifyError) Unwrap() error {

104 return e.Err

105}

106

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

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

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

110// succeeds, the verified record is returned.

111//

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

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

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

115// any others ignored.

116//

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

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

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

120// indicate DNSSEC errors.

121// - ErrInsecure

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

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

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

125

126 // Split host and port.

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

128 if err != nil {

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

130 }

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

132 if err != nil {

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

134 }

135

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

137 if err != nil {

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

139 }

140

141 // ../rfc/7671:1015

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

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

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

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

146 // DANE-EE).

147 cnameDom := hostDom

148 cnameAuthentic := true

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

150 if i == 10 {

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

152 }

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

154 cnameAuthentic = cnameAuthentic && cnameResult.Authentic

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

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

157 } else if dns.IsNotFound(err) {

158 break

159 } else if err != nil {

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

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

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

163 } else {

164 cnameDom = d

165 }

166 }

167

168 // We lookup the IP.

169 ipnetwork := "ip"

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

171 ipnetwork += "4"

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

173 ipnetwork += "6"

174 }

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

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

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

178 // can continue with regular DANE.

179 if err != nil {

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

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

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

183 }

184

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

186 // we try at the secure original domain.

187 baseDom := hostDom

188 if cnameAuthentic {

189 baseDom = cnameDom

190 }

191 var records []adns.TLSA

192 var result adns.Result

193 for {

194 var err error

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

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

197 // name, try at original name.

198 // ../rfc/7671:1015

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

200 baseDom = hostDom

201 continue

202 }

203 if !result.Authentic {

204 return nil, adns.TLSA{}, ErrInsecure

205 } else if dns.IsNotFound(err) {

206 return nil, adns.TLSA{}, ErrNoRecords

207 } else if err != nil {

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

209 }

210 break

211 }

212

213 // Keep only the allowed usages.

214 if allowedUsages != nil {

215 o := 0

216 for _, r := range records {

217 for _, usage := range allowedUsages {

218 if r.Usage == usage {

219 records[o] = r

220 o++

221 break

222 }

223 }

224 }

225 records = records[:o]

226 if len(records) == 0 {

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

228 // certificate.

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

230 }

231 }

232

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

234 // ../rfc/7671:1021

235 var moreAllowedHosts []dns.Domain

236 if baseDom != hostDom {

237 moreAllowedHosts = []dns.Domain{hostDom}

238 }

239

240 // Dial the remote host.

241 timeout := 30 * time.Second

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

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

244 }

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

246 var conn net.Conn

247 var dialErrs []error

248 for _, ip := range ips {

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

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

251 if err != nil {

252 dialErrs = append(dialErrs, err)

253 continue

254 }

255 conn = c

256 break

257 }

258 if conn == nil {

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

260 }

261

262 var verifiedRecord adns.TLSA

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

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

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

266 conn.Close()

267 return nil, adns.TLSA{}, err

268 }

269 return tlsConn, verifiedRecord, nil

270}

271

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

273// TLS connection with DANE verification.

274//

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

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

277//

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

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

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

281//

282// The TLS config uses allowedHost for SNI.

283//

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

285// verified, if any.

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

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

288 return tls.Config{

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

290 InsecureSkipVerify: true,

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

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

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

294 if verified {

295 if verifiedRecord != nil {

296 *verifiedRecord = record

297 }

298 return nil

299 } else if err == nil {

300 return ErrNoMatch

301 }

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

303 },

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

305 }

306}

307

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

309// records.

310//

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

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

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

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

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

316//

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

318// record and a nil error.

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

320// record value and a nil error.

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

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

323// (wrapped) errors of type VerifyError.

324//

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

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

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

328// separately.

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

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

331 MetricVerify.Inc()

332 if len(records) == 0 {

333 MetricVerifyErrors.Inc()

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

335 }

336 var errs []error

337 for _, r := range records {

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

339 if err != nil {

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

341 } else if ok {

342 return true, r, nil

343 }

344 }

345 MetricVerifyErrors.Inc()

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

347}

348

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

350//

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

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

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

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

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

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

357// is only returned when verified is false.

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

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

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

361 }

362

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

364 var buf []byte

365 switch tlsa.Selector {

366 case adns.TLSASelectorCert:

367 buf = cert.Raw

368 case adns.TLSASelectorSPKI:

369 buf = cert.RawSubjectPublicKeyInfo

370 default:

371 return false

372 }

373

374 switch tlsa.MatchType {

375 case adns.TLSAMatchTypeFull:

376 case adns.TLSAMatchTypeSHA256:

377 d := sha256.Sum256(buf)

378 buf = d[:]

379 case adns.TLSAMatchTypeSHA512:

380 d := sha512.Sum512(buf)

381 buf = d[:]

382 default:

383 return false

384 }

385

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

387 }

388

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

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

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

392 opts := x509.VerifyOptions{

393 DNSName: host.ASCII,

394 Intermediates: x509.NewCertPool(),

395 Roots: pkixRoots,

396 }

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

398 opts.Intermediates.AddCert(cert)

399 }

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

401 return chains, err

402 }

403

404 switch tlsa.Usage {

405 case adns.TLSAUsagePKIXTA:

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

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

408 // ca certificate.

409 var errs []error

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

411 chains, err := pkixVerify(host)

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

413 if err != nil {

414 errs = append(errs, err)

415 continue

416 }

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

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

419 for _, chain := range chains {

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

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

422 if match(chain[i]) {

423 return true, nil

424 }

425 }

426 }

427 }

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

429

430 case adns.TLSAUsagePKIXEE:

431 // Check for a certificate match.

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

433 return false, nil

434 }

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

436 var errs []error

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

438 _, err := pkixVerify(host)

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

440 if err == nil {

441 return true, nil

442 }

443 errs = append(errs, err)

444 }

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

446

447 case adns.TLSAUsageDANETA:

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

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

450 opts := x509.VerifyOptions{

451 Roots: x509.NewCertPool(),

452 }

453

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

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

456 var found bool

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

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

459 if err != nil {

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

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

462 } else {

463 opts.Roots.AddCert(cert)

464 found = true

465 }

466 }

467

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

469 if match(cert) {

470 opts.Roots.AddCert(cert)

471 found = true

472 break

473 }

474 }

475 if !found {

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

477 // verify.

478 return false, nil

479 }

480

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

482 var errs []error

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

484 opts.DNSName = host.ASCII

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

486 if err == nil {

487 return true, nil

488 }

489 errs = append(errs, err)

490 }

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

492

493 case adns.TLSAUsageDANEEE:

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

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

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

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

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

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

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

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

502

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

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

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

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

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

508

509 default:

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

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

512 return false, nil

513 }

514}

515