Merge pull request #310 from wneessen/feature/242_support-scram-sha

SCRAM-SHA-1(-PLUS) / SCRAM-SHA-256(-PLUS) support

README.md

@@ -18,33 +18,34 @@ SPDX-License-Identifier: CC0-1.0
 
 <p align="center"><img src="./assets/gopher2.svg" width="250" alt="go-mail logo"/></p>
 
-The main idea of this library was to provide a simple interface to sending mails for
+The main idea of this library was to provide a simple interface for sending mails to
 my [JS-Mailer](https://github.com/wneessen/js-mailer) project. It quickly evolved into a full-fledged mail library.
 
-go-mail follows idiomatic Go style and best practice. It's only dependency is the Go Standard Library. It combines a lot
-of functionality from the standard library to give easy and convenient access to mail and SMTP related tasks.
+go-mail follows idiomatic Go style and best practice. It has a small dependency footprint by mainly relying on the
+Go Standard Library and the Go extended packages. It combines a lot of functionality from the standard library to 
+give easy and convenient access to mail and SMTP related tasks.
 
-Parts of this library (especially some parts of [msgwriter.go](msgwriter.go)) have been forked/ported from the
-[go-mail/mail](https://github.com/go-mail/mail) respectively [go-gomail/gomail](https://github.com/go-gomail/gomail)
-which both seems to not be maintained anymore.
+In the early days, parts of this library (especially some parts of [msgwriter.go](msgwriter.go)) had been 
+forked/ported from [go-mail/mail](https://github.com/go-mail/mail) and respectively [go-gomail/gomail](https://github.com/go-gomail/gomail). Today
+most of the ported code has been refactored.
 
-The smtp package of go-mail is forked from the original Go stdlib's `net/smtp` and then extended by the go-mail
-team.
+The `smtp` package of go-mail has been forked from the original Go stdlib's `net/smtp` package and has then been extended 
+by the go-mail team to fit the packages needs (more SMTP Auth methods, logging, concurrency-safety, etc.).
 
 ## Features
 
-Some of the features of this library:
+Here are some highlights of go-mail's featureset:
 
-* [X] Only Standard Library dependant
+* [X] Very small dependency footprint (mainly Go Stdlib and Go extended packages)
 * [X] Modern, idiomatic Go
 * [X] Sane and secure defaults
 * [X] Explicit SSL/TLS support
 * [X] Implicit StartTLS support with different policies
 * [X] Makes use of contexts for a better control flow and timeout/cancelation handling
-* [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD, XOAUTH2)
+* [X] SMTP Auth support (LOGIN, PLAIN, CRAM-MD, XOAUTH2, SCRAM-SHA-1(-PLUS), SCRAM-SHA-256(-PLUS))
 * [X] RFC5322 compliant mail address validation
 * [X] Support for common mail header field generation (Message-ID, Date, Bulk-Precedence, Priority, etc.)
-* [X] Reusing the same SMTP connection to send multiple mails
+* [X] Concurrency-safe reusing the same SMTP connection to send multiple mails
 * [X] Support for attachments and inline embeds (from file system, `io.Reader` or `embed.FS`)
 * [X] Support for different encodings
 * [X] Middleware support for 3rd-party libraries to alter mail messages
@@ -99,15 +100,18 @@ We provide example code in both our GoDocs as well as on our official Website (s
 check out our [Getting started](https://go-mail.dev/getting-started/introduction/) guide.
 
 ## Authors/Contributors
-go-mail was initially authored and developed by [Winni Neessen](https://github.com/wneessen/).
-
-Big thanks to the following people, for contributing to the go-mail project (either in form of code or by 
-reviewing code, writing documenation or helping to translate the website):
-* [Christian Vette](https://github.com/cvette)
-* [Dhia Gharsallaoui](https://github.com/dhia-gharsallaoui)
-* [inliquid](https://github.com/inliquid) 
-* [iwittkau](https://github.com/iwittkau)
-* [James Elliott](https://github.com/james-d-elliott)
-* [Maria Letta](https://github.com/MariaLetta) (designed the go-mail logo)
-* [Nicola Murino](https://github.com/drakkan)
-* [sters](https://github.com/sters)
+go-mail was initially created and developed by [Winni Neessen](https://github.com/wneessen/), but over time a lot of amazing people 
+contributed ot the project. Big thanks to all of them for improving the go-mail project (be it writing code, testing
+code, reviewing code, writing documenation or helping to translate the website):
+
+<a href="https://github.com/wneessen/go-mail/graphs/contributors">
+ <img src="https://contrib.rocks/image?repo=wneessen/go-mail" />
+</a>
+
+A huge thank you also goes to [Maria Letta](https://github.com/MariaLetta) for designing our super cool go-mail logo!
+
+## Sponsors
+We sincerely thank our amazing sponsors for their generous support! Your contributions do not go unnoticed and helps
+keeping up the project!
+
+* [kolaente](https://github.com/kolaente)

REUSE.toml

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: Copyright (c) 2022-2024 The go-mail Authors
+#
+# SPDX-License-Identifier: MIT
+
+version = 1
+SPDX-PackageName = "go-mail"
+SPDX-PackageSupplier = "Winni Neessen <winni@neessen.dev>"
+SPDX-PackageDownloadLocation = "https://github.com/wneessen/go-mail"
+annotations = []

auth.go

@@ -28,6 +28,22 @@ const (
  // SMTPAuthXOAUTH2 is the "XOAUTH2" SASL authentication mechanism.
  // https://developers.google.com/gmail/imap/xoauth2-protocol
  SMTPAuthXOAUTH2 SMTPAuthType = "XOAUTH2"
+
+ // SMTPAuthSCRAMSHA1 represents the SCRAM-SHA-1 SMTP authentication mechanism
+ // https://datatracker.ietf.org/doc/html/rfc5802
+ SMTPAuthSCRAMSHA1 SMTPAuthType = "SCRAM-SHA-1"
+
+ // SMTPAuthSCRAMSHA1PLUS represents the "SCRAM-SHA-1-PLUS" authentication mechanism for SMTP.
+ // https://datatracker.ietf.org/doc/html/rfc5802
+ SMTPAuthSCRAMSHA1PLUS SMTPAuthType = "SCRAM-SHA-1-PLUS"
+
+ // SMTPAuthSCRAMSHA256 represents the SCRAM-SHA-256 authentication mechanism for SMTP.
+ // https://datatracker.ietf.org/doc/html/rfc7677
+ SMTPAuthSCRAMSHA256 SMTPAuthType = "SCRAM-SHA-256"
+
+ // SMTPAuthSCRAMSHA256PLUS represents the "SCRAM-SHA-256-PLUS" SMTP AUTH type.
+ // https://datatracker.ietf.org/doc/html/rfc7677
+ SMTPAuthSCRAMSHA256PLUS SMTPAuthType = "SCRAM-SHA-256-PLUS"
 )
 
 // SMTP Auth related static errors
@@ -43,4 +59,16 @@ var (
 
  // ErrXOauth2AuthNotSupported should be used if the target server does not support the "XOAUTH2" schema
  ErrXOauth2AuthNotSupported = errors.New("server does not support SMTP AUTH type: XOAUTH2")
+
+ // ErrSCRAMSHA1AuthNotSupported should be used if the target server does not support the "SCRAM-SHA-1" schema
+ ErrSCRAMSHA1AuthNotSupported = errors.New("server does not support SMTP AUTH type: SCRAM-SHA-1")
+
+ // ErrSCRAMSHA1PLUSAuthNotSupported should be used if the target server does not support the "SCRAM-SHA-1-PLUS" schema
+ ErrSCRAMSHA1PLUSAuthNotSupported = errors.New("server does not support SMTP AUTH type: SCRAM-SHA-1-PLUS")
+
+ // ErrSCRAMSHA256AuthNotSupported should be used if the target server does not support the "SCRAM-SHA-256" schema
+ ErrSCRAMSHA256AuthNotSupported = errors.New("server does not support SMTP AUTH type: SCRAM-SHA-256")
+
+ // ErrSCRAMSHA256PLUSAuthNotSupported should be used if the target server does not support the "SCRAM-SHA-256-PLUS" schema
+ ErrSCRAMSHA256PLUSAuthNotSupported = errors.New("server does not support SMTP AUTH type: SCRAM-SHA-256-PLUS")
 )

client.go

@@ -578,6 +578,7 @@ func (c *Client) SetPassword(password string) {
 // SetSMTPAuth overrides the current SMTP AUTH type setting with the given value
 func (c *Client) SetSMTPAuth(authtype SMTPAuthType) {
  c.smtpAuthType = authtype
+ c.smtpAuth = nil
 }
 
 // SetSMTPAuthCustom overrides the current SMTP AUTH setting with the given custom smtp.Auth
@@ -748,7 +749,17 @@ func (c *Client) tls() error {
  return err
  }
  }
- _, c.isEncrypted = c.smtpClient.TLSConnectionState()
+ tlsConnState, err := c.smtpClient.GetTLSConnectionState()
+ if err != nil {
+ switch {
+ case errors.Is(err, smtp.ErrNonTLSConnection):
+ c.isEncrypted = false
+ return nil
+ default:
+ return fmt.Errorf("failed to get TLS connection state: %w", err)
+ }
+ }
+ c.isEncrypted = tlsConnState.HandshakeComplete
  }
  return nil
 }
@@ -785,6 +796,34 @@ func (c *Client) auth() error {
  return ErrXOauth2AuthNotSupported
  }
  c.smtpAuth = smtp.XOAuth2Auth(c.user, c.pass)
+ case SMTPAuthSCRAMSHA1:
+ if !strings.Contains(smtpAuthType, string(SMTPAuthSCRAMSHA1)) {
+ return ErrSCRAMSHA1AuthNotSupported
+ }
+ c.smtpAuth = smtp.ScramSHA1Auth(c.user, c.pass)
+ case SMTPAuthSCRAMSHA256:
+ if !strings.Contains(smtpAuthType, string(SMTPAuthSCRAMSHA256)) {
+ return ErrSCRAMSHA256AuthNotSupported
+ }
+ c.smtpAuth = smtp.ScramSHA256Auth(c.user, c.pass)
+ case SMTPAuthSCRAMSHA1PLUS:
+ if !strings.Contains(smtpAuthType, string(SMTPAuthSCRAMSHA1PLUS)) {
+ return ErrSCRAMSHA1PLUSAuthNotSupported
+ }
+ tlsConnState, err := c.smtpClient.GetTLSConnectionState()
+ if err != nil {
+ return err
+ }
+ c.smtpAuth = smtp.ScramSHA1PlusAuth(c.user, c.pass, tlsConnState)
+ case SMTPAuthSCRAMSHA256PLUS:
+ if !strings.Contains(smtpAuthType, string(SMTPAuthSCRAMSHA256PLUS)) {
+ return ErrSCRAMSHA256PLUSAuthNotSupported
+ }
+ tlsConnState, err := c.smtpClient.GetTLSConnectionState()
+ if err != nil {
+ return err
+ }
+ c.smtpAuth = smtp.ScramSHA256PlusAuth(c.user, c.pass, tlsConnState)
  default:
  return fmt.Errorf("unsupported SMTP AUTH type %q", c.smtpAuthType)
  }