1// Package autotls automatically configures TLS (for SMTP, IMAP, HTTP) by

2// requesting certificates with ACME, typically from Let's Encrypt.

3package autotls

4

5// We do tls-alpn-01, and also http-01. For DNS we would need a third party tool

6// with an API that can make the DNS changes, as we don't want to link in dozens of

7// bespoke API's for DNS record manipulation into mox.

8

9import (

10 "bytes"

11 "context"

12 "crypto"

13 "crypto/ecdsa"

14 "crypto/elliptic"

15 cryptorand "crypto/rand"

16 "crypto/rsa"

17 "crypto/tls"

18 "crypto/x509"

19 "encoding/pem"

20 "errors"

21 "fmt"

22 "io"

23 "log/slog"

24 "net"

25 "os"

26 "path/filepath"

27 "sort"

28 "strings"

29 "sync"

30 "time"

31

32 "golang.org/x/crypto/acme"

33

34 "github.com/prometheus/client_golang/prometheus"

35 "github.com/prometheus/client_golang/prometheus/promauto"

36

37 "github.com/mjl-/autocert"

38

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

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

41 "github.com/mjl-/mox/moxvar"

42)

43

44var (

45 metricMissingServerName = promauto.NewCounter(

46 prometheus.CounterOpts{

47 Name: "mox_autotls_missing_servername_total",

48 Help: "Number of failed TLS connection attempts with missing SNI where no fallback hostname was configured.",

49 },

50 )

51 metricUnknownServerName = promauto.NewCounter(

52 prometheus.CounterOpts{

53 Name: "mox_autotls_unknown_servername_total",

54 Help: "Number of failed TLS connection attempts with an unrecognized SNI name where no fallback hostname was configured.",

55 },

56 )

57 metricCertRequestErrors = promauto.NewCounter(

58 prometheus.CounterOpts{

59 Name: "mox_autotls_cert_request_errors_total",

60 Help: "Number of errors trying to retrieve a certificate for a hostname, possibly ACME verification errors.",

61 },

62 )

63 metricCertput = promauto.NewCounter(

64 prometheus.CounterOpts{

65 Name: "mox_autotls_certput_total",

66 Help: "Number of certificate store puts.",

67 },

68 )

69)

70

71// Manager is in charge of a single ACME identity, and automatically requests

72// certificates for allowlisted hosts.

73type Manager struct {

74 ACMETLSConfig *tls.Config // For serving HTTPS on port 443, which is required for certificate requests to succeed.

75 Manager *autocert.Manager

76

77 shutdown <-chan struct{}

78

79 sync.Mutex

80 hosts map[dns.Domain]struct{}

81}

82

83// Load returns an initialized autotls manager for "name" (used for the ACME key

84// file and requested certs and their keys). All files are stored within acmeDir.

85//

86// contactEmail must be a valid email address to which notifications about ACME can

87// be sent. directoryURL is the ACME starting point.

88//

89// eabKeyID and eabKey are for external account binding when making a new account,

90// which some ACME providers require.

91//

92// getPrivateKey is called to get the private key for the host and key type. It

93// can be used to deliver a specific (e.g. always the same) private key for a

94// host, or a newly generated key.

95//

96// When shutdown is closed, no new TLS connections can be created.

97func Load(log mlog.Log, name, acmeDir, contactEmail, directoryURL string, eabKeyID string, eabKey []byte, getPrivateKey func(host string, keyType autocert.KeyType) (crypto.Signer, error), shutdown <-chan struct{}) (*Manager, error) {

98 if directoryURL == "" {

99 return nil, fmt.Errorf("empty ACME directory URL")

100 }

101 if contactEmail == "" {

102 return nil, fmt.Errorf("empty contact email")

103 }

104

105 // Load identity key if it exists. Otherwise, create a new key.

106 p := filepath.Join(acmeDir, name+".key")

107 var key crypto.Signer

108 f, err := os.Open(p)

109 if f != nil {

110 defer func() {

111 err := f.Close()

112 log.Check(err, "closing identify key file")

113 }()

114 }

115 if err != nil && os.IsNotExist(err) {

116 key, err = ecdsa.GenerateKey(elliptic.P256(), cryptorand.Reader)

117 if err != nil {

118 return nil, fmt.Errorf("generating ecdsa identity key: %s", err)

119 }

120 der, err := x509.MarshalPKCS8PrivateKey(key)

121 if err != nil {

122 return nil, fmt.Errorf("marshal identity key: %s", err)

123 }

124 block := &pem.Block{

125 Type: "PRIVATE KEY",

126 Headers: map[string]string{

127 "Note": fmt.Sprintf("PEM PKCS8 ECDSA private key generated for ACME provider %s by mox", name),

128 },

129 Bytes: der,

130 }

131 b := &bytes.Buffer{}

132 if err := pem.Encode(b, block); err != nil {

133 return nil, fmt.Errorf("pem encode: %s", err)

134 } else if err := os.WriteFile(p, b.Bytes(), 0660); err != nil {

135 return nil, fmt.Errorf("writing identity key: %s", err)

136 }

137 } else if err != nil {

138 return nil, fmt.Errorf("open identity key file: %s", err)

139 } else {

140 var privKey any

141 if buf, err := io.ReadAll(f); err != nil {

142 return nil, fmt.Errorf("reading identity key: %s", err)

143 } else if p, _ := pem.Decode(buf); p == nil {

144 return nil, fmt.Errorf("no pem data")

145 } else if p.Type != "PRIVATE KEY" {

146 return nil, fmt.Errorf("got PEM block %q, expected \"PRIVATE KEY\"", p.Type)

147 } else if privKey, err = x509.ParsePKCS8PrivateKey(p.Bytes); err != nil {

148 return nil, fmt.Errorf("parsing PKCS8 private key: %s", err)

149 }

150 switch k := privKey.(type) {

151 case *ecdsa.PrivateKey:

152 key = k

153 case *rsa.PrivateKey:

154 key = k

155 default:

156 return nil, fmt.Errorf("unsupported private key type %T", key)

157 }

158 }

159

160 m := &autocert.Manager{

161 Cache: dirCache(filepath.Join(acmeDir, "keycerts", name)),

162 Prompt: autocert.AcceptTOS,

163 Email: contactEmail,

164 Client: &acme.Client{

165 DirectoryURL: directoryURL,

166 Key: key,

167 UserAgent: "mox/" + moxvar.Version,

168 },

169 GetPrivateKey: getPrivateKey,

170 // HostPolicy set below.

171 }

172 // If external account binding key is provided, use it for registering a new account.

173 // todo: ideally the key and its id are provided temporarily by the admin when registering a new account. but we don't do that interactive setup yet. in the future, an interactive setup/quickstart would ask for the key once to register a new acme account.

174 if eabKeyID != "" {

175 m.ExternalAccountBinding = &acme.ExternalAccountBinding{

176 KID: eabKeyID,

177 Key: eabKey,

178 }

179 }

180

181 a := &Manager{

182 Manager: m,

183 shutdown: shutdown,

184 hosts: map[dns.Domain]struct{}{},

185 }

186 m.HostPolicy = a.HostPolicy

187 acmeTLSConfig := *m.TLSConfig()

188 acmeTLSConfig.GetCertificate = func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {

189 return a.loggingGetCertificate(hello, dns.Domain{}, false, false)

190 }

191 a.ACMETLSConfig = &acmeTLSConfig

192 return a, nil

193}

194

195// loggingGetCertificate is a helper to implement crypto/tls.Config.GetCertificate,

196// optionally falling back to a certificate for fallbackHostname in case SNI is

197// absent or for an unknown hostname.

198func (m *Manager) loggingGetCertificate(hello *tls.ClientHelloInfo, fallbackHostname dns.Domain, fallbackNoSNI, fallbackUnknownSNI bool) (*tls.Certificate, error) {

199 log := mlog.New("autotls", nil).WithContext(hello.Context()).With(

200 slog.Any("localaddr", hello.Conn.LocalAddr()),

201 slog.Any("supportedprotos", hello.SupportedProtos),

202 slog.String("servername", hello.ServerName),

203 )

204

205 // If we can't find a certificate (depending on fallback parameters), we return a

206 // nil certificate and nil error, which crypto/tls turns into a TLS alert

207 // "unrecognized name", which can be interpreted by clients as a hint that they are

208 // using the wrong hostname, or a certificate is missing. ../rfc/9325:578

209

210 // IP addresses for ServerName are not allowed, but happen in practice. If we

211 // should be lenient (fallbackUnknownSNI), we switch to the fallback hostname,

212 // otherwise we return an error. We don't want to pass IP addresses to

213 // GetCertificate because it will return an error for IPv6 addresses.

214 // ../rfc/6066:367 ../rfc/4366:535

215 if net.ParseIP(hello.ServerName) != nil {

216 if fallbackUnknownSNI {

217 hello.ServerName = fallbackHostname.ASCII

218 log = log.With(slog.String("servername", hello.ServerName))

219 } else {

220 log.Debug("tls request with ip for server name, rejecting")

221 return nil, fmt.Errorf("invalid ip address for sni server name")

222 }

223 }

224

225 if hello.ServerName == "" && fallbackNoSNI {

226 hello.ServerName = fallbackHostname.ASCII

227 log = log.With(slog.String("servername", hello.ServerName))

228 }

229

230 // Handle missing SNI to prevent logging an error below.

231 if hello.ServerName == "" {

232 metricMissingServerName.Inc()

233 log.Debug("tls request without sni server name, rejecting")

234 return nil, nil

235 }

236

237 cert, err := m.Manager.GetCertificate(hello)

238 if err != nil && errors.Is(err, errHostNotAllowed) {

239 if !fallbackUnknownSNI {

240 metricUnknownServerName.Inc()

241 log.Debugx("requesting certificate", err)

242 return nil, nil

243 }

244

245 // Some legitimate email deliveries over SMTP use an unknown SNI, e.g. a bare

246 // domain instead of the MX hostname. We "should" return an error, but that would

247 // break email delivery, so we use the fallback name if it is configured.

248 // ../rfc/9325:589

249

250 log = log.With(slog.String("servername", hello.ServerName))

251 log.Debug("certificate for unknown hostname, using fallback hostname")

252 hello.ServerName = fallbackHostname.ASCII

253 cert, err = m.Manager.GetCertificate(hello)

254 if err != nil {

255 metricCertRequestErrors.Inc()

256 log.Errorx("requesting certificate for fallback hostname", err)

257 } else {

258 log.Debug("using certificate for fallback hostname")

259 }

260 return cert, err

261 } else if err != nil {

262 metricCertRequestErrors.Inc()

263 log.Errorx("requesting certificate", err)

264 }

265 return cert, err

266}

267

268// TLSConfig returns a TLS server config that optionally returns a certificate for

269// fallbackHostname if no SNI was done, or for an unknown hostname.

270//

271// If fallbackNoSNI is set, TLS connections without SNI will use a certificate for

272// fallbackHostname. Otherwise, connections without SNI will fail with a message

273// that no TLS certificate is available.

274//

275// If fallbackUnknownSNI is set, TLS connections with an SNI hostname that is not

276// allowlisted will instead use a certificate for fallbackHostname. Otherwise, such

277// TLS connections will fail.

278func (m *Manager) TLSConfig(fallbackHostname dns.Domain, fallbackNoSNI, fallbackUnknownSNI bool) *tls.Config {

279 return &tls.Config{

280 GetCertificate: func(hello *tls.ClientHelloInfo) (*tls.Certificate, error) {

281 return m.loggingGetCertificate(hello, fallbackHostname, fallbackNoSNI, fallbackUnknownSNI)

282 },

283 }

284}

285

286// CertAvailable checks whether a non-expired ECDSA certificate is available in the

287// cache for host. No other checks than expiration are done.

288func (m *Manager) CertAvailable(ctx context.Context, log mlog.Log, host dns.Domain) (bool, error) {

289 ck := host.ASCII // Would be "+rsa" for rsa keys.

290 data, err := m.Manager.Cache.Get(ctx, ck)

291 if err != nil && errors.Is(err, autocert.ErrCacheMiss) {

292 return false, nil

293 } else if err != nil {

294 return false, fmt.Errorf("attempt to get certificate from cache: %v", err)

295 }

296

297 // The cached keycert is of the form: private key, leaf certificate, intermediate certificates...

298 privb, rem := pem.Decode(data)

299 if privb == nil {

300 return false, fmt.Errorf("missing private key in cached keycert file")

301 }

302 pubb, _ := pem.Decode(rem)

303 if pubb == nil {

304 return false, fmt.Errorf("missing certificate in cached keycert file")

305 } else if pubb.Type != "CERTIFICATE" {

306 return false, fmt.Errorf("second pem block is %q, expected CERTIFICATE", pubb.Type)

307 }

308 cert, err := x509.ParseCertificate(pubb.Bytes)

309 if err != nil {

310 return false, fmt.Errorf("parsing certificate from cached keycert file: %v", err)

311 }

312 // We assume the certificate has a matching hostname, and is properly CA-signed. We

313 // only check the expiration time.

314 if time.Until(cert.NotBefore) > 0 || time.Since(cert.NotAfter) > 0 {

315 return false, nil

316 }

317 return true, nil

318}

319

320// SetAllowedHostnames sets a new list of allowed hostnames for automatic TLS.

321// After setting the host names, a goroutine is start to check that new host names

322// are fully served by publicIPs (only if non-empty and there is no unspecified

323// address in the list). If no, log an error with a warning that ACME validation

324// may fail.

325func (m *Manager) SetAllowedHostnames(log mlog.Log, resolver dns.Resolver, hostnames map[dns.Domain]struct{}, publicIPs []string, checkHosts bool) {

326 m.Lock()

327 defer m.Unlock()

328

329 // Log as slice, sorted.

330 l := make([]dns.Domain, 0, len(hostnames))

331 for d := range hostnames {

332 l = append(l, d)

333 }

334 sort.Slice(l, func(i, j int) bool {

335 return l[i].Name() < l[j].Name()

336 })

337

338 log.Debug("autotls setting allowed hostnames", slog.Any("hostnames", l), slog.Any("publicips", publicIPs))

339 var added []dns.Domain

340 for h := range hostnames {

341 if _, ok := m.hosts[h]; !ok {

342 added = append(added, h)

343 }

344 }

345 m.hosts = hostnames

346

347 if checkHosts && len(added) > 0 && len(publicIPs) > 0 {

348 for _, ip := range publicIPs {

349 if net.ParseIP(ip).IsUnspecified() {

350 return

351 }

352 }

353 go func() {

354 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)

355 defer cancel()

356

357 publicIPstrs := map[string]struct{}{}

358 for _, ip := range publicIPs {

359 publicIPstrs[ip] = struct{}{}

360 }

361

362 log.Debug("checking ips of hosts configured for acme tls cert validation")

363 for _, h := range added {

364 ips, _, err := resolver.LookupIP(ctx, "ip", h.ASCII+".")

365 if err != nil {

366 log.Warnx("acme tls cert validation for host may fail due to dns lookup error", err, slog.Any("host", h))

367 continue

368 }

369 for _, ip := range ips {

370 if _, ok := publicIPstrs[ip.String()]; !ok {

371 log.Warn("acme tls cert validation for host is likely to fail because not all its ips are being listened on",

372 slog.Any("hostname", h),

373 slog.Any("listenedips", publicIPs),

374 slog.Any("hostips", ips),

375 slog.Any("missingip", ip))

376 }

377 }

378 }

379 }()

380 }

381}

382

383// Hostnames returns the allowed host names for use with ACME.

384func (m *Manager) Hostnames() []dns.Domain {

385 m.Lock()

386 defer m.Unlock()

387 var l []dns.Domain

388 for h := range m.hosts {

389 l = append(l, h)

390 }

391 return l

392}

393

394var errHostNotAllowed = errors.New("autotls: host not in allowlist")

395

396// HostPolicy decides if a host is allowed for use with ACME, i.e. whether a

397// certificate will be returned if present and/or will be requested if not yet

398// present. Only hosts added with SetAllowedHostnames are allowed. During shutdown,

399// no new connections are allowed.

400func (m *Manager) HostPolicy(ctx context.Context, host string) (rerr error) {

401 log := mlog.New("autotls", nil).WithContext(ctx)

402 defer func() {

403 log.Debugx("autotls hostpolicy result", rerr, slog.String("host", host))

404 }()

405

406 // Don't request new TLS certs when we are shutting down.

407 select {

408 case <-m.shutdown:

409 return fmt.Errorf("shutting down")

410 default:

411 }

412

413 xhost, _, err := net.SplitHostPort(host)

414 if err == nil {

415 // For http-01, host may include a port number.

416 host = xhost

417 }

418

419 d, err := dns.ParseDomain(host)

420 if err != nil {

421 return fmt.Errorf("invalid host: %v", err)

422 }

423

424 m.Lock()

425 defer m.Unlock()

426 if _, ok := m.hosts[d]; !ok {

427 return fmt.Errorf("%w: %q", errHostNotAllowed, d)

428 }

429 return nil

430}

431

432type dirCache autocert.DirCache

433

434func (d dirCache) Delete(ctx context.Context, name string) (rerr error) {

435 log := mlog.New("autotls", nil).WithContext(ctx)

436 defer func() {

437 log.Debugx("dircache delete result", rerr, slog.String("name", name))

438 }()

439 err := autocert.DirCache(d).Delete(ctx, name)

440 if err != nil {

441 log.Errorx("deleting cert from dir cache", err, slog.String("name", name))

442 } else if !strings.HasSuffix(name, "+token") {

443 log.Info("autotls cert delete", slog.String("name", name))

444 }

445 return err

446}

447

448func (d dirCache) Get(ctx context.Context, name string) (rbuf []byte, rerr error) {

449 log := mlog.New("autotls", nil).WithContext(ctx)

450 defer func() {

451 log.Debugx("dircache get result", rerr, slog.String("name", name))

452 }()

453 buf, err := autocert.DirCache(d).Get(ctx, name)

454 if err != nil && errors.Is(err, autocert.ErrCacheMiss) {

455 log.Infox("getting cert from dir cache", err, slog.String("name", name))

456 } else if err != nil {

457 log.Errorx("getting cert from dir cache", err, slog.String("name", name))

458 } else if !strings.HasSuffix(name, "+token") {

459 log.Debug("autotls cert get", slog.String("name", name))

460 }

461 return buf, err

462}

463

464func (d dirCache) Put(ctx context.Context, name string, data []byte) (rerr error) {

465 log := mlog.New("autotls", nil).WithContext(ctx)

466 defer func() {

467 log.Debugx("dircache put result", rerr, slog.String("name", name))

468 }()

469 metricCertput.Inc()

470 err := autocert.DirCache(d).Put(ctx, name, data)

471 if err != nil {

472 log.Errorx("storing cert in dir cache", err, slog.String("name", name))

473 } else if !strings.HasSuffix(name, "+token") {

474 log.Info("autotls cert store", slog.String("name", name))

475 }

476 return err

477}

478