From 5dadf46dc8b3dbb80c433889edce621f4f051d08 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Tue, 10 Nov 2026 11:03:43 +0100 Subject: [PATCH] feat(outbound): TLS, STARTTLS and SMTP AUTH towards an external relay - Add relay TLS modes: none (default), starttls (required, never downgraded) and implicit tls - Verify the certificate (system roots, optional CA pool and server name), TLS 1.2 minimum - Add AUTH PLAIN, refused over a clear connection to a remote relay - Report a wrong password or a relay that wants authentication as a temporary error, so mail waits instead of failing for good - Add a configurable EHLO name, validated against line breaks - Arm the context watcher before EHLO so a silent relay cannot hang a send --- go.mod | 2 +- internal/outbound/outbound.go | 129 +++++++++-- internal/outbound/tls_test.go | 411 ++++++++++++++++++++++++++++++++++ 3 files changed, 526 insertions(+), 16 deletions(-) create mode 100644 internal/outbound/tls_test.go diff --git a/go.mod b/go.mod index f6bb60f..a8827ff 100644 --- a/go.mod +++ b/go.mod @@ -5,6 +5,7 @@ go 1.27.3 require ( github.com/emersion/go-message v0.18.2 github.com/emersion/go-msgauth v0.7.0 + github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 github.com/emersion/go-smtp v0.25.1 gopkg.in/yaml.v3 v3.0.1 modernc.org/sqlite v1.62.0 @@ -12,7 +13,6 @@ require ( require ( github.com/dustin/go-humanize v1.1.0 // indirect - github.com/emersion/go-sasl v0.0.0-20241020182733-b788ff22d5a6 // indirect github.com/google/uuid v1.6.0 // indirect github.com/mattn/go-isatty v0.0.24 // indirect github.com/ncruces/go-strftime v1.1.0 // indirect diff --git a/internal/outbound/outbound.go b/internal/outbound/outbound.go index 9b1e4fc..ffa2603 100644 --- a/internal/outbound/outbound.go +++ b/internal/outbound/outbound.go @@ -4,12 +4,16 @@ package outbound import ( "bytes" "context" + "crypto/tls" + "crypto/x509" "errors" "fmt" "net" + "strings" "sync" "time" + "github.com/emersion/go-sasl" "github.com/emersion/go-smtp" ) @@ -22,10 +26,24 @@ type Sender interface { // DefaultBatchSize is the number of recipients per SMTP transaction. const DefaultBatchSize = 50 -// SMTPRelay sends through a plain SMTP relay such as a local Postfix. +// TLS modes of SMTPRelay. +const ( + TLSNone = "none" // plain connection (a local Postfix); the default + TLSStartTLS = "starttls" // upgrade the connection; fail if the relay does not offer it + TLSImplicit = "tls" // encrypted from the first byte (port 465) +) + +// SMTPRelay sends through an SMTP relay: a local Postfix, or an external one such as SES. type SMTPRelay struct { Addr string // host:port BatchSize int // recipients per transaction; DefaultBatchSize if zero + + TLS string // TLSNone (default), TLSStartTLS or TLSImplicit + ServerName string // name the certificate must match; the host of Addr by default + RootCAs *x509.CertPool // trusted CAs; the system's by default + Username string // SMTP AUTH PLAIN; only over TLS or to a loopback address + Password string + Helo string // EHLO name; "localhost" by default } // Send splits recipients in batches and sends one transaction per batch. @@ -46,19 +64,46 @@ func (r *SMTPRelay) Send(ctx context.Context, from string, to []string, data []b return nil } -func (r *SMTPRelay) sendBatch(ctx context.Context, from string, to []string, data []byte) (err error) { - d := net.Dialer{Timeout: 10 * time.Second} - conn, err := d.DialContext(ctx, "tcp", r.Addr) +// dial opens the connection and speaks EHLO, TLS and AUTH as configured. +// The returned release function must be called when the client is done: until then the connection +// is closed if ctx is cancelled, even in the middle of EHLO, STARTTLS or AUTH with a silent relay. +func (r *SMTPRelay) dial(ctx context.Context) (c *smtp.Client, release func(), err error) { + host, _, err := net.SplitHostPort(r.Addr) if err != nil { - return err + return nil, nil, fmt.Errorf("relay address %q: %w", r.Addr, err) } - // A relay that stops answering must not hold us past the context: apply its - // deadline to the connection and close the connection if it is cancelled. + mode := r.TLS + if mode == "" { + mode = TLSNone + } + if r.Username != "" && mode == TLSNone && !isLoopback(host) { + return nil, nil, errors.New("refusing to send credentials in clear to a remote relay: set relay.tls to starttls or tls") + } + helo := r.Helo + if helo == "" { + helo = "localhost" + } + tlsConf := &tls.Config{ServerName: host, RootCAs: r.RootCAs, MinVersion: tls.VersionTLS12} + if r.ServerName != "" { + tlsConf.ServerName = r.ServerName + } + + d := &net.Dialer{Timeout: 10 * time.Second} + var conn net.Conn + if mode == TLSImplicit { + conn, err = (&tls.Dialer{NetDialer: d, Config: tlsConf}).DialContext(ctx, "tcp", r.Addr) + } else { + conn, err = d.DialContext(ctx, "tcp", r.Addr) + } + if err != nil { + return nil, nil, err + } + // A relay that stops answering must not hold us past the context: apply its deadline to the + // connection and close the connection if the context is cancelled. if dl, ok := ctx.Deadline(); ok { conn.SetDeadline(dl) } stop := make(chan struct{}) - defer close(stop) go func() { select { case <-ctx.Done(): @@ -66,19 +111,73 @@ func (r *SMTPRelay) sendBatch(ctx context.Context, from string, to []string, dat case <-stop: } }() + release = func() { close(stop) } + fail := func(err error) (*smtp.Client, func(), error) { + release() + conn.Close() + return nil, nil, err + } + + if mode == TLSStartTLS { + // go-smtp performs EHLO and STARTTLS itself and fails when STARTTLS is not offered, so a + // downgrade is impossible. Its first EHLO says "localhost"; ours follows over TLS below. + c, err = smtp.NewClientStartTLS(conn, tlsConf) + if err != nil { + return fail(err) + } + } else { + c = smtp.NewClient(conn) + } + if err := c.Hello(helo); err != nil { + c.Close() + return fail(err) + } + if r.Username != "" { + if err := c.Auth(sasl.NewPlainClient("", r.Username, r.Password)); err != nil { + c.Close() + return fail(authError(err)) + } + } + return c, release, nil +} + +func isLoopback(host string) bool { + if host == "localhost" { + return true + } + ip := net.ParseIP(host) + return ip != nil && ip.IsLoopback() +} + +// authError turns a refusal of our credentials into a temporary error. A wrong password or a +// relay that wants authentication is a configuration problem: if it were permanent every message +// would be failed for good, instead of waiting in the queue until the admin fixes it. +func authError(err error) error { + var se *smtp.SMTPError + if errors.As(err, &se) && (se.Code == 530 || se.Code == 534 || se.Code == 535 || se.Code == 538) { + return fmt.Errorf("relay authentication failed (%d %s)", se.Code, strings.TrimSpace(se.Message)) + } + return err +} + +func (r *SMTPRelay) sendBatch(ctx context.Context, from string, to []string, data []byte) (err error) { + c, release, err := r.dial(ctx) + if err != nil { + if ctx.Err() != nil { + err = ctx.Err() // report the cause, not "use of closed connection" + } + return err + } + defer release() + defer c.Close() defer func() { if err != nil && ctx.Err() != nil { - err = ctx.Err() // report the cause, not "use of closed connection" + err = ctx.Err() } }() - c := smtp.NewClient(conn) - defer c.Close() - if err := c.Hello("localhost"); err != nil { - return err - } if err := c.SendMail(from, to, bytes.NewReader(data)); err != nil { - return err + return authError(err) } return c.Quit() } diff --git a/internal/outbound/tls_test.go b/internal/outbound/tls_test.go new file mode 100644 index 0000000..bf33832 --- /dev/null +++ b/internal/outbound/tls_test.go @@ -0,0 +1,411 @@ +package outbound + +import ( + "context" + "crypto/ecdsa" + "crypto/elliptic" + "crypto/rand" + "crypto/tls" + "crypto/x509" + "crypto/x509/pkix" + "errors" + "io" + "math/big" + "net" + "strings" + "sync" + "testing" + "time" + + "github.com/emersion/go-sasl" + "github.com/emersion/go-smtp" +) + +// --- a throwaway CA and certificates ------------------------------------------------------- + +type pki struct { + pool *x509.CertPool + good tls.Certificate // valid for 127.0.0.1 and localhost + wrong tls.Certificate // signed by the CA but for another name + rogue tls.Certificate // valid for 127.0.0.1 but signed by an unknown CA +} + +func newPKI(t *testing.T) *pki { + t.Helper() + mk := func(parent *x509.Certificate, parentKey *ecdsa.PrivateKey, tmpl *x509.Certificate) (*x509.Certificate, *ecdsa.PrivateKey, []byte) { + key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader) + if err != nil { + t.Fatal(err) + } + if parent == nil { + parent, parentKey = tmpl, key + } + der, err := x509.CreateCertificate(rand.Reader, tmpl, parent, &key.PublicKey, parentKey) + if err != nil { + t.Fatal(err) + } + c, _ := x509.ParseCertificate(der) + return c, key, der + } + serial := int64(1) + tmpl := func(cn string, ca bool, dns []string, ips []net.IP) *x509.Certificate { + serial++ + return &x509.Certificate{ + SerialNumber: big.NewInt(serial), Subject: pkix.Name{CommonName: cn}, + NotBefore: time.Now().Add(-time.Hour), NotAfter: time.Now().Add(24 * time.Hour), + IsCA: ca, BasicConstraintsValid: true, + KeyUsage: x509.KeyUsageDigitalSignature | x509.KeyUsageCertSign, + ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth}, + DNSNames: dns, IPAddresses: ips, + } + } + ca, caKey, _ := mk(nil, nil, tmpl("test CA", true, nil, nil)) + rogueCA, rogueKey, _ := mk(nil, nil, tmpl("rogue CA", true, nil, nil)) + leaf := func(parent *x509.Certificate, pk *ecdsa.PrivateKey, dns []string, ips []net.IP) tls.Certificate { + _, key, der := mk(parent, pk, tmpl("relay", false, dns, ips)) + return tls.Certificate{Certificate: [][]byte{der}, PrivateKey: key} + } + pool := x509.NewCertPool() + pool.AddCert(ca) + loop := []net.IP{net.ParseIP("127.0.0.1")} + return &pki{ + pool: pool, + good: leaf(ca, caKey, []string{"localhost"}, loop), + wrong: leaf(ca, caKey, []string{"other.example"}, nil), + rogue: leaf(rogueCA, rogueKey, []string{"localhost"}, loop), + } +} + +// --- an SMTP server with TLS and AUTH -------------------------------------------------------- + +type relayOpts struct { + cert *tls.Certificate // nil: no TLS at all + implicit bool // TLS from the first byte (port 465 style) + user, pass string // when set, AUTH PLAIN must match + requireAuth bool // answer 530 to MAIL until authenticated +} + +type testRelay struct { + mu sync.Mutex + addr string + messages []captured + auths []string // "user:pass" seen + hellos []string // EHLO names seen at MAIL time + tlsSeen []bool // whether each message arrived over TLS +} + +type relayBackend struct { + r *testRelay + o relayOpts +} + +func (b *relayBackend) NewSession(c *smtp.Conn) (smtp.Session, error) { + return &relaySession{b: b, conn: c}, nil +} + +type relaySession struct { + b *relayBackend + conn *smtp.Conn + authed bool + from string + to []string +} + +func (s *relaySession) Reset() { s.from, s.to = "", nil } +func (s *relaySession) Logout() error { return nil } +func (s *relaySession) AuthMechanisms() []string { + if s.b.o.user == "" { + return nil + } + return []string{sasl.Plain} +} +func (s *relaySession) Auth(mech string) (sasl.Server, error) { + return sasl.NewPlainServer(func(identity, username, password string) error { + s.b.r.mu.Lock() + s.b.r.auths = append(s.b.r.auths, username+":"+password) + s.b.r.mu.Unlock() + if username != s.b.o.user || password != s.b.o.pass { + return &smtp.SMTPError{Code: 535, EnhancedCode: smtp.EnhancedCode{5, 7, 8}, Message: "Authentication credentials invalid"} + } + s.authed = true + return nil + }), nil +} +func (s *relaySession) Mail(from string, _ *smtp.MailOptions) error { + if s.b.o.requireAuth && !s.authed { + return &smtp.SMTPError{Code: 530, EnhancedCode: smtp.EnhancedCode{5, 7, 0}, Message: "Authentication required"} + } + s.from = from + s.b.r.mu.Lock() + s.b.r.hellos = append(s.b.r.hellos, s.conn.Hostname()) + s.b.r.mu.Unlock() + return nil +} +func (s *relaySession) Rcpt(to string, _ *smtp.RcptOptions) error { + s.to = append(s.to, to) + return nil +} +func (s *relaySession) Data(r io.Reader) error { + b, _ := io.ReadAll(r) + _, isTLS := s.conn.TLSConnectionState() + s.b.r.mu.Lock() + s.b.r.messages = append(s.b.r.messages, captured{s.from, s.to, string(b)}) + s.b.r.tlsSeen = append(s.b.r.tlsSeen, isTLS) + s.b.r.mu.Unlock() + return nil +} + +func startRelay(t *testing.T, o relayOpts) *testRelay { + t.Helper() + r := &testRelay{} + srv := smtp.NewServer(&relayBackend{r: r, o: o}) + srv.AllowInsecureAuth = false // credentials are only accepted over TLS + if o.cert != nil { + srv.TLSConfig = &tls.Config{Certificates: []tls.Certificate{*o.cert}} + } + ln, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { + t.Fatal(err) + } + r.addr = ln.Addr().String() + serveLn := ln + if o.implicit { + serveLn = nil + go srv.Serve(tls.NewListener(ln, srv.TLSConfig)) + } else { + go srv.Serve(ln) + } + _ = serveLn + t.Cleanup(func() { srv.Close() }) + return r +} + +func (r *testRelay) count() int { + r.mu.Lock() + defer r.mu.Unlock() + return len(r.messages) +} + +func send(r *SMTPRelay) error { + return r.Send(context.Background(), "bounce@example.org", []string{"a@x.com"}, []byte("Subject: hi\r\n\r\nbody\r\n")) +} + +// --- STARTTLS --------------------------------------------------------------------------------- + +func TestStartTLSDeliversOverAnEncryptedConnection(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good}) + r := &SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool} + if err := send(r); err != nil { + t.Fatal(err) + } + if srv.count() != 1 || !srv.tlsSeen[0] { + t.Fatalf("the message must arrive over TLS: %d %v", srv.count(), srv.tlsSeen) + } +} + +func TestStartTLSIsRequiredNotOptional(t *testing.T) { + srv := startRelay(t, relayOpts{}) // a server that does not offer STARTTLS + err := send(&SMTPRelay{Addr: srv.addr, TLS: "starttls"}) + if err == nil || !strings.Contains(err.Error(), "STARTTLS") { + t.Fatalf("want a STARTTLS error, got %v", err) + } + if srv.count() != 0 { + t.Fatal("a downgrade attack must not make us send the message in clear") + } + if IsPermanent(err) { + t.Fatalf("a relay that cannot do TLS is a configuration problem to fix, not a reason to drop mail: %v", err) + } +} + +func TestImplicitTLS(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good, implicit: true}) + if err := send(&SMTPRelay{Addr: srv.addr, TLS: "tls", RootCAs: p.pool}); err != nil { + t.Fatal(err) + } + if srv.count() != 1 || !srv.tlsSeen[0] { + t.Fatalf("%d %v", srv.count(), srv.tlsSeen) + } +} + +func TestCertificateProblemsAreRefusedAndAreNotPermanent(t *testing.T) { + p := newPKI(t) + for name, tc := range map[string]struct { + cert *tls.Certificate + mode string + impl bool + }{ + "wrong name, starttls": {&p.wrong, "starttls", false}, + "wrong name, implicit": {&p.wrong, "tls", true}, + "unknown CA, starttls": {&p.rogue, "starttls", false}, + "unknown CA, implicit": {&p.rogue, "tls", true}, + } { + srv := startRelay(t, relayOpts{cert: tc.cert, implicit: tc.impl}) + err := send(&SMTPRelay{Addr: srv.addr, TLS: tc.mode, RootCAs: p.pool}) + if err == nil { + t.Errorf("%s: an untrusted relay must be refused", name) + continue + } + if !strings.Contains(strings.ToLower(err.Error()), "certificate") { + t.Errorf("%s: say it is a certificate problem: %v", name, err) + } + if srv.count() != 0 { + t.Errorf("%s: nothing may be sent to an untrusted relay", name) + } + if IsPermanent(err) { + t.Errorf("%s: a certificate problem must not drop the mail: %v", name, err) + } + } +} + +func TestServerNameOverridesTheNameToVerify(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.wrong}) // the certificate is for other.example + if err := send(&SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool, ServerName: "other.example"}); err != nil { + t.Fatalf("server_name is the name the certificate must match: %v", err) + } +} + +// --- AUTH --------------------------------------------------------------------------------------- + +func TestAuthPlainOverStartTLS(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good, user: "ses-user", pass: "s3cret pass", requireAuth: true}) + r := &SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool, Username: "ses-user", Password: "s3cret pass"} + if err := send(r); err != nil { + t.Fatal(err) + } + if srv.count() != 1 || len(srv.auths) != 1 || srv.auths[0] != "ses-user:s3cret pass" { + t.Fatalf("messages=%d auths=%v", srv.count(), srv.auths) + } +} + +func TestAuthPlainOverImplicitTLS(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good, implicit: true, user: "u", pass: "p", requireAuth: true}) + if err := send(&SMTPRelay{Addr: srv.addr, TLS: "tls", RootCAs: p.pool, Username: "u", Password: "p"}); err != nil { + t.Fatal(err) + } + if srv.count() != 1 { + t.Fatal("not delivered") + } +} + +func TestCredentialsAreNeverSentInClearToARemoteRelay(t *testing.T) { + // 192.0.2.1 is reserved for documentation: the client must refuse before it even connects. + for _, mode := range []string{"", "none"} { + start := time.Now() + err := send(&SMTPRelay{Addr: "192.0.2.1:25", TLS: mode, Username: "u", Password: "p"}) + if err == nil || !strings.Contains(err.Error(), "clear") { + t.Fatalf("mode %q: want a refusal to send credentials in clear, got %v", mode, err) + } + if time.Since(start) > time.Second { + t.Fatalf("mode %q: the refusal must not wait for a connection", mode) + } + } + // A clear connection to a relay that does not offer AUTH without TLS: nothing reaches the server. + srv := startRelay(t, relayOpts{user: "u", pass: "p", requireAuth: true}) + if err := send(&SMTPRelay{Addr: srv.addr, TLS: "none", Username: "u", Password: "p"}); err == nil { + t.Fatal("the relay cannot authenticate us in clear") + } + if len(srv.auths) != 0 { + t.Fatalf("the password reached the server: %v", srv.auths) + } +} + +func TestAWrongPasswordKeepsTheMailQueuedAndLeaksNothing(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good, user: "u", pass: "right", requireAuth: true}) + err := send(&SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool, Username: "u", Password: "Wr0ngPassw0rd"}) + if err == nil { + t.Fatal("want an authentication error") + } + if IsPermanent(err) { + t.Fatalf("a wrong password must not fail every message for good: the admin fixes it and the mail goes out: %v", err) + } + if !strings.Contains(strings.ToLower(err.Error()), "authentication") { + t.Fatalf("say what went wrong: %v", err) + } + if strings.Contains(err.Error(), "Wr0ngPassw0rd") { + t.Fatal("never put the password in an error") + } + if srv.count() != 0 { + t.Fatal("nothing delivered") + } +} + +func TestARelayThatWantsAuthenticationIsATemporaryProblem(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good, user: "u", pass: "p", requireAuth: true}) + // We forgot to configure credentials: the relay answers 530 at MAIL FROM. + err := send(&SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool}) + if err == nil || IsPermanent(err) { + t.Fatalf("530 means credentials are missing: retry after the admin fixes it, got %v", err) + } + if !strings.Contains(strings.ToLower(err.Error()), "authentication") { + t.Fatalf("%v", err) + } +} + +// --- EHLO name ---------------------------------------------------------------------------------- + +func TestHeloNameIsUsed(t *testing.T) { + p := newPKI(t) + srv := startRelay(t, relayOpts{cert: &p.good}) + if err := send(&SMTPRelay{Addr: srv.addr, TLS: "starttls", RootCAs: p.pool, Helo: "lists.example.org"}); err != nil { + t.Fatal(err) + } + if len(srv.hellos) != 1 || srv.hellos[0] != "lists.example.org" { + t.Fatalf("EHLO names: %v", srv.hellos) + } + plain := startRelay(t, relayOpts{}) + if err := send(&SMTPRelay{Addr: plain.addr, Helo: "lists.example.org"}); err != nil { + t.Fatal(err) + } + if plain.hellos[0] != "lists.example.org" { + t.Fatalf("EHLO over a plain connection: %v", plain.hellos) + } +} + +func TestInvalidHeloNamesAreRejectedBeforeConnecting(t *testing.T) { + srv := startRelay(t, relayOpts{}) + if err := send(&SMTPRelay{Addr: srv.addr, Helo: "bad name\r\nMAIL FROM:"}); err == nil { + t.Fatal("a name with a line break must never reach the wire") + } +} + +// --- unchanged behaviour ------------------------------------------------------------------------- + +func TestPlainRelayStillWorksWithoutAnyTLSSetting(t *testing.T) { + srv := startRelay(t, relayOpts{}) + if err := send(&SMTPRelay{Addr: srv.addr}); err != nil { + t.Fatal(err) + } + if srv.count() != 1 || srv.tlsSeen[0] { + t.Fatalf("the default is the plain connection used so far: %v", srv.tlsSeen) + } +} + +func TestAuthOverPlainConnectionToLoopbackIsAllowedWhenTheServerOffersIt(t *testing.T) { + // A local Postfix with SASL on 127.0.0.1: no TLS needed to reach it. + srv := startPlainAuthRelay(t) + err := send(&SMTPRelay{Addr: srv, TLS: "none", Username: "u", Password: "p"}) + if err != nil { + t.Fatalf("%v", err) + } +} + +// startPlainAuthRelay is a loopback relay that accepts AUTH without TLS. +func startPlainAuthRelay(t *testing.T) string { + t.Helper() + r := &testRelay{} + srv := smtp.NewServer(&relayBackend{r: r, o: relayOpts{user: "u", pass: "p", requireAuth: true}}) + srv.AllowInsecureAuth = true + ln, _ := net.Listen("tcp", "127.0.0.1:0") + go srv.Serve(ln) + t.Cleanup(func() { srv.Close() }) + return ln.Addr().String() +} + +var _ = errors.New