feat(app): send through the configured relay with TLS and authentication

- Read the relay password and CA file at startup; refuse to start on an unusable one
- Pass TLS mode, server name, CA pool, credentials and EHLO name to the SMTP relay
- Default the EHLO name to the host name
- Test an authenticating STARTTLS relay, a wrong password (mail stays queued) and the startup checks
- Document external relays in the README and the example config
This commit is contained in:
tgiachi 2026-11-10 11:05:24 +01:00
commit a6601caed7
4 changed files with 263 additions and 2 deletions

View file

@ -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.

View file

@ -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,
}

View file

@ -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 <alice@example.com>\r\nSubject: via a relay\r\nMessage-ID: <r1@x>\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()
}

View file

@ -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