diff --git a/README.md b/README.md index 0b8337a..8e850ac 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,36 @@ Use `db: /data/parsimony.db` in the config. Do not publish the LMTP port (2424): shared with the container, and `lmtp.allow` should list that network's range (see Security notes). A new named volume gets the right ownership by itself; for a bind mount, make the host directory writable by uid 65532. +## Sending through an external relay + +By default parsimony hands mail to an SMTP server on the same machine (`relay.addr: 127.0.0.1:25`). It can also send through +an external relay such as Amazon SES, Mailgun or a company smarthost: + +```yaml +relay: + addr: email-smtp.eu-west-1.amazonaws.com:587 + tls: starttls # none (default), starttls or tls (port 465) + username: AKIAEXAMPLE + password_file: /run/secrets/relay-password # the password is never in the config + helo: lists.example.org # EHLO name; this machine's host name by default + # ca_file: /etc/parsimony/private-ca.pem # to trust a private CA + # server_name: smtp.example.com # when the certificate is for another name than the host in addr +``` + +- **TLS is required, never silently skipped.** With `starttls` a relay that does not offer it makes the send fail; the + certificate is always verified (TLS 1.2 or later; system roots, or `ca_file`). +- **Credentials only travel encrypted.** SMTP AUTH PLAIN is refused over a clear connection to a remote relay, at load + time and again at send time. A local relay (127.0.0.1, `::1`, `localhost`) may be used without TLS. +- **A wrong password does not lose mail.** A refused login (or a relay that wants authentication) is treated as a temporary + error: the deliveries stay queued, retry with backoff, and show the reason in the queue (without the password). Fix the + password and restart; the mail goes out. A missing or empty password file, or an unreadable CA file, stops the daemon at + startup. +- With `starttls`, the very first EHLO before the upgrade says `localhost` (the SMTP library offers no way to set it + earlier); the configured `helo` is used right after, over TLS. +- Keep SPF and DKIM right for the path your mail takes (for SES, `include:amazonses.com` in SPF), and check that the provider + accepts the list's per-recipient return addresses (`list+bounce-ID-MAC@domain`) as envelope sender. Bounces come back + to those addresses, so they reach parsimony only if the domain's MX delivers them to its LMTP. + ## Delivery and the queue LMTP answers `250` when the post is in the queue, so a down relay never bounces mail back to Postfix. diff --git a/internal/app/app.go b/internal/app/app.go index 2caeb5f..8909328 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -29,6 +29,17 @@ import ( // nowFunc is the clock of the store (queue schedules, token expiry). Tests move it. var nowFunc = time.Now +// heloName is the EHLO name: the configured one, else this machine's host name. +func heloName(configured string) string { + if configured != "" { + return configured + } + if h, err := os.Hostname(); err == nil && h != "" { + return h + } + return "localhost" +} + // allowListener drops connections from clients that are not in the allow list, // before the LMTP greeting: LMTP has no authentication of its own. type allowListener struct { @@ -123,6 +134,16 @@ func Start(cfg config.Config, apiToken string) (*App, error) { sign = signer.Sign } + // Same for the relay secrets: read them now, not at the first send. + relayPassword, err := cfg.RelayPassword() + if err != nil { + return nil, err + } + relayCAs, err := cfg.RelayRootCAs() + if err != nil { + return nil, err + } + st, err := store.Open(cfg.DB) if err != nil { return nil, fmt.Errorf("store: %w", err) @@ -133,8 +154,11 @@ func Start(cfg config.Config, apiToken string) (*App, error) { rt := router.New(st) rt.BaseURL = cfg.BaseURL worker := &queue.Worker{ - Store: st, - Sender: &outbound.SMTPRelay{Addr: cfg.Relay.Addr}, + Store: st, + Sender: &outbound.SMTPRelay{ + Addr: cfg.Relay.Addr, TLS: cfg.Relay.TLS, ServerName: cfg.Relay.ServerName, RootCAs: relayCAs, + Username: cfg.Relay.Username, Password: relayPassword, Helo: heloName(cfg.Relay.Helo), + }, Concurrency: cfg.Relay.Concurrency, Sign: sign, } diff --git a/internal/app/app_test.go b/internal/app/app_test.go index 6866c03..d600c17 100644 --- a/internal/app/app_test.go +++ b/internal/app/app_test.go @@ -2,14 +2,19 @@ package app import ( "bytes" + "crypto/ecdsa" + "crypto/elliptic" "crypto/rand" "crypto/rsa" + "crypto/tls" "crypto/x509" + "crypto/x509/pkix" "encoding/base64" "encoding/pem" "errors" "io" "log" + "math/big" "net" "net/http" "os" @@ -21,6 +26,7 @@ import ( "time" "github.com/emersion/go-msgauth/dkim" + "github.com/emersion/go-sasl" "github.com/emersion/go-smtp" "codeberg.org/squidd/parsimony/internal/config" @@ -728,3 +734,199 @@ func TestStartWarnsAboutAnOpenLMTPPort(t *testing.T) { } } } + +// --- an external relay: TLS and authentication ------------------------------------------------ + +type tlsRelay struct { + sink *sink + addr string + caFile string + mu sync.Mutex + auths []string +} + +type tlsRelayBackend struct { + r *tlsRelay + user, pass string +} + +func (b *tlsRelayBackend) NewSession(c *smtp.Conn) (smtp.Session, error) { + return &tlsRelaySession{b: b, conn: c}, nil +} + +type tlsRelaySession struct { + b *tlsRelayBackend + conn *smtp.Conn + authed bool + from string + to []string +} + +func (s *tlsRelaySession) Reset() { s.from, s.to = "", nil } +func (s *tlsRelaySession) Logout() error { return nil } +func (s *tlsRelaySession) AuthMechanisms() []string { return []string{sasl.Plain} } +func (s *tlsRelaySession) Auth(string) (sasl.Server, error) { + return sasl.NewPlainServer(func(_, user, pass string) error { + s.b.r.mu.Lock() + s.b.r.auths = append(s.b.r.auths, user+":"+pass) + s.b.r.mu.Unlock() + if user != s.b.user || pass != s.b.pass { + return &smtp.SMTPError{Code: 535, EnhancedCode: smtp.EnhancedCode{5, 7, 8}, Message: "bad credentials"} + } + s.authed = true + return nil + }), nil +} +func (s *tlsRelaySession) Mail(from string, _ *smtp.MailOptions) error { + if !s.authed { + return &smtp.SMTPError{Code: 530, EnhancedCode: smtp.EnhancedCode{5, 7, 0}, Message: "authenticate first"} + } + if _, ok := s.conn.TLSConnectionState(); !ok { + return errors.New("the relay was reached without TLS") + } + s.from = from + return nil +} +func (s *tlsRelaySession) Rcpt(to string, _ *smtp.RcptOptions) error { + s.to = append(s.to, to) + return nil +} +func (s *tlsRelaySession) Data(r io.Reader) error { + b, _ := io.ReadAll(r) + s.b.r.sink.mu.Lock() + s.b.r.sink.msgs = append(s.b.r.sink.msgs, sunk{s.from, s.to, string(b)}) + s.b.r.sink.mu.Unlock() + return nil +} + +// startTLSRelay starts an authenticating STARTTLS relay and writes the CA that signed its certificate. +func startTLSRelay(t *testing.T, user, pass string) *tlsRelay { + t.Helper() + caKey, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + caTmpl := &x509.Certificate{SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: "test CA"}, NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), IsCA: true, BasicConstraintsValid: true, KeyUsage: x509.KeyUsageCertSign} + caDER, _ := x509.CreateCertificate(rand.Reader, caTmpl, caTmpl, &caKey.PublicKey, caKey) + ca, _ := x509.ParseCertificate(caDER) + key, _ := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + leaf := &x509.Certificate{SerialNumber: big.NewInt(2), Subject: pkix.Name{CommonName: "relay"}, NotBefore: time.Now().Add(-time.Hour), + NotAfter: time.Now().Add(time.Hour), IPAddresses: []net.IP{net.ParseIP("127.0.0.1")}, ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}} + der, _ := x509.CreateCertificate(rand.Reader, leaf, ca, &key.PublicKey, caKey) + + r := &tlsRelay{sink: &sink{}} + r.caFile = filepath.Join(t.TempDir(), "ca.pem") + os.WriteFile(r.caFile, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: caDER}), 0o600) + srv := smtp.NewServer(&tlsRelayBackend{r: r, user: user, pass: pass}) + srv.TLSConfig = &tls.Config{Certificates: []tls.Certificate{{Certificate: [][]byte{der}, PrivateKey: key}}} + ln, _ := net.Listen("tcp", "127.0.0.1:0") + r.addr = ln.Addr().String() + go srv.Serve(ln) + t.Cleanup(func() { srv.Close() }) + return r +} + +func relayConfig(t *testing.T, r *tlsRelay, password string) config.Config { + t.Helper() + pwFile := filepath.Join(t.TempDir(), "relay-password") + os.WriteFile(pwFile, []byte(password+"\n"), 0o600) + cfg := testConfig(t, r.addr) + cfg.Relay.TLS = "starttls" + cfg.Relay.CAFile = r.caFile + cfg.Relay.Username = "ses-user" + cfg.Relay.PasswordFile = pwFile + cfg.Relay.Helo = "lists.example.org" + return cfg +} + +func postOne(t *testing.T, a *App) { + t.Helper() + call(t, a, "POST", "/api/v1/lists", `{"name":"dev","domain":"example.org"}`, "tok") + call(t, a, "POST", "/api/v1/lists/1/members", `{"address":"alice@example.com"}`, "tok") + msg := "From: Alice \r\nSubject: via a relay\r\nMessage-ID: \r\n\r\nbody\r\n" + if err := lmtpSend(t, a.LMTPAddr, "alice@example.com", "dev@example.org", msg); err != nil { + t.Fatal(err) + } +} + +func TestMailGoesThroughAnAuthenticatingTLSRelay(t *testing.T) { + relay := startTLSRelay(t, "ses-user", "p@ss word") + a, err := Start(relayConfig(t, relay, "p@ss word"), "tok") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { a.Close() }) + postOne(t, a) + relay.sink.waitCount(t, 1) + if !strings.Contains(relay.sink.all()[0].data, "Subject: via a relay") { + t.Fatalf("%q", relay.sink.all()[0].data) + } + relay.mu.Lock() + defer relay.mu.Unlock() + if len(relay.auths) == 0 || relay.auths[0] != "ses-user:p@ss word" { + t.Fatalf("the password comes from the file, without its line ending: %v", relay.auths) + } +} + +func TestAWrongRelayPasswordKeepsTheMailQueued(t *testing.T) { + relay := startTLSRelay(t, "ses-user", "right") + cfg := relayConfig(t, relay, "wrong") + a, err := Start(cfg, "tok") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { a.Close() }) + postOne(t, a) + + peek, err := store.Open(cfg.DB) + if err != nil { + t.Fatal(err) + } + defer peek.Close() + deadline := time.Now().Add(5 * time.Second) + for { + st, _ := peek.OutboxStats() + if st.Pending == 1 && st.Retrying == 1 && st.Failed == 0 { + break + } + if time.Now().After(deadline) { + t.Fatalf("the delivery must stay queued and retry, not fail for good: %+v", st) + } + time.Sleep(10 * time.Millisecond) + } + list, _ := peek.ListOutbox(10) + if !strings.Contains(list[0].LastError, "authentication") || strings.Contains(list[0].LastError, "wrong") { + t.Fatalf("the admin sees what is wrong, without the password: %q", list[0].LastError) + } + if relay.sink.count() != 0 { + t.Fatal("nothing was delivered") + } +} + +func TestStartFailsOnUnusableRelaySecrets(t *testing.T) { + relay := startTLSRelay(t, "ses-user", "p") + for name, mutate := range map[string]func(*config.Config){ + "missing password file": func(c *config.Config) { c.Relay.PasswordFile = "/nonexistent/pw" }, + "empty password file": func(c *config.Config) { os.WriteFile(c.Relay.PasswordFile, []byte("\n"), 0o600) }, + "missing CA file": func(c *config.Config) { c.Relay.CAFile = "/nonexistent/ca.pem" }, + "CA file without cert": func(c *config.Config) { os.WriteFile(c.Relay.CAFile, []byte("nope"), 0o600) }, + } { + cfg := relayConfig(t, relay, "p") + mutate(&cfg) + if a, err := Start(cfg, "tok"); err == nil { + a.Close() + t.Errorf("%s: the daemon must refuse to start rather than fail at the first send", name) + } else if !strings.Contains(err.Error(), "relay") { + t.Errorf("%s: the error names the relay setting: %v", name, err) + } + } +} + +func TestTheRelayAddressIsNotDialledAtStartup(t *testing.T) { + // Starting must not depend on the relay being reachable: mail waits in the queue. + cfg := testConfig(t, deadAddr(t)) + cfg.Relay.TLS = "starttls" + a, err := Start(cfg, "tok") + if err != nil { + t.Fatalf("an unreachable relay is a runtime condition, not a startup error: %v", err) + } + a.Close() +} diff --git a/parsimony.example.yaml b/parsimony.example.yaml index 78a6234..aff42fd 100644 --- a/parsimony.example.yaml +++ b/parsimony.example.yaml @@ -6,6 +6,11 @@ lmtp: allow: [172.16.0.0/12] # LMTP has no authentication: list who may connect (here: the Docker networks) relay: addr: postfix:25 + # To send through an external relay (SES, Mailgun, a smarthost) instead: + # addr: smtp.example.com:587 + # tls: starttls + # username: user + # password_file: /run/secrets/relay-password concurrency: 4 # simultaneous deliveries web: listen: 0.0.0.0:8081 # public archive and unsubscribe pages; "" disables them