Merge pull request #324 from wneessen/better-godoc

Revision of the GoDoc documentation

README.md

@@ -52,7 +52,7 @@ Here are some highlights of go-mail's featureset:
 * [X] Support sending mails via a local sendmail command
 * [X] Support for requestng MDNs (RFC 8098) and DSNs (RFC 1891)
 * [X] DKIM signature support via [go-mail-middlware](https://github.com/wneessen/go-mail-middleware)
-* [X] Message object satisfies `io.WriteTo` and `io.Reader` interfaces
+* [X] Message object satisfies `io.WriterTo` and `io.Reader` interfaces
 * [X] Support for Go's `html/template` and `text/template` (as message body, alternative part or attachment/emebed)
 * [X] Output to file support which allows storing mail messages as e. g. `.eml` files to disk to open them in a MUA
 * [X] Debug logging of SMTP traffic

auth.go

@@ -6,69 +6,131 @@ package mail
 
 import "errors"
 
-// SMTPAuthType represents a string to any SMTP AUTH type
+// SMTPAuthType is a type wrapper for a string type. It represents the type of SMTP authentication
+// mechanism to be used.
 type SMTPAuthType string
 
-// Supported SMTP AUTH types
 const (
-	// SMTPAuthCramMD5 is the "CRAM-MD5" SASL authentication mechanism as described in RFC 4954
+	// SMTPAuthCramMD5 is the "CRAM-MD5" SASL authentication mechanism as described in RFC 4954.
+	// https://datatracker.ietf.org/doc/html/rfc4954/
+	//
+	// CRAM-MD5 is not secure by modern standards. The vulnerabilities of MD5 and the lack of
+	// advanced security features make it inappropriate for protecting sensitive communications
+	// today.
+	//
+	// It was recommended to deprecate the standard in 20 November 2008. As an alternative it
+	// recommends e.g. SCRAM or SASL Plain protected by TLS instead.
+	//
+	// https://datatracker.ietf.org/doc/html/draft-ietf-sasl-crammd5-to-historic-00.html
 	SMTPAuthCramMD5 SMTPAuthType = "CRAM-MD5"
 
-	// SMTPAuthLogin is the "LOGIN" SASL authentication mechanism
+	// SMTPAuthCustom is a custom SMTP AUTH mechanism provided by the user. If a user provides
+	// a custom smtp.Auth function to the Client, the Client will its smtpAuthType to this type.
+	//
+	// Do not use this SMTPAuthType without setting a custom smtp.Auth function on the Client.
+	SMTPAuthCustom SMTPAuthType = "CUSTOM"
+
+	// SMTPAuthLogin is the "LOGIN" SASL authentication mechanism. This authentication mechanism
+	// does not have an official RFC that could be followed. There is a spec by Microsoft and an
+	// IETF draft. The IETF draft is more lax than the MS spec, therefore we follow the I-D, which
+	// automatically matches the MS spec.
+	//
+	// Since the "LOGIN" SASL authentication mechansim transmits the username and password in
+	// plaintext over the internet connection, we only allow this mechanism over a TLS secured
+	// connection.
+	//
+	// https://msopenspecs.azureedge.net/files/MS-XLOGIN/%5bMS-XLOGIN%5d.pdf
+	//
+	// https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00
 	SMTPAuthLogin SMTPAuthType = "LOGIN"
 
 	// SMTPAuthNoAuth is equivalent to performing no authentication at all. It is a convenience
 	// option and should not be used. Instead, for mail servers that do no support/require
-	// authentication, the Client should not be used with the WithSMTPAuth option
+	// authentication, the Client should not be passed the WithSMTPAuth option at all.
 	SMTPAuthNoAuth SMTPAuthType = ""
 
-	// SMTPAuthPlain is the "PLAIN" authentication mechanism as described in RFC 4616
+	// SMTPAuthPlain is the "PLAIN" authentication mechanism as described in RFC 4616.
+	//
+	// Since the "PLAIN" SASL authentication mechansim transmits the username and password in
+	// plaintext over the internet connection, we only allow this mechanism over a TLS secured
+	// connection.
+	//
+	// https://datatracker.ietf.org/doc/html/rfc4616/
 	SMTPAuthPlain SMTPAuthType = "PLAIN"
 
 	// 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
+	// SMTPAuthSCRAMSHA1 is the "SCRAM-SHA-1" SASL authentication mechanism as described in RFC 5802.
+	//
+	// SCRAM-SHA-1 is still considered secure for certain applications, particularly when used as part
+	// of a challenge-response authentication mechanism (as we use it). However, it is generally
+	// recommended to prefer stronger alternatives like SCRAM-SHA-256(-PLUS), as SHA-1 has known
+	// vulnerabilities in other contexts, although it remains effective in HMAC constructions.
+	//
 	// https://datatracker.ietf.org/doc/html/rfc5802
 	SMTPAuthSCRAMSHA1 SMTPAuthType = "SCRAM-SHA-1"
 
-	// SMTPAuthSCRAMSHA1PLUS represents the "SCRAM-SHA-1-PLUS" authentication mechanism for SMTP.
+	// SMTPAuthSCRAMSHA1PLUS is the "SCRAM-SHA-1-PLUS" SASL authentication mechanism as described in RFC 5802.
+	//
+	// SCRAM-SHA-X-PLUS authentication require TLS channel bindings to protect against MitM attacks and
+	// to guarantee that the integrity of the transport layer is preserved throughout the authentication
+	// process. Therefore we only allow this mechansim over a TLS secured connection.
+	//
+	// SCRAM-SHA-1-PLUS is still considered secure for certain applications, particularly when used as part
+	// of a challenge-response authentication mechanism (as we use it). However, it is generally
+	// recommended to prefer stronger alternatives like SCRAM-SHA-256(-PLUS), as SHA-1 has known
+	// vulnerabilities in other contexts, although it remains effective in HMAC constructions.
+	//
 	// https://datatracker.ietf.org/doc/html/rfc5802
 	SMTPAuthSCRAMSHA1PLUS SMTPAuthType = "SCRAM-SHA-1-PLUS"
 
-	// SMTPAuthSCRAMSHA256 represents the SCRAM-SHA-256 authentication mechanism for SMTP.
+	// SMTPAuthSCRAMSHA256 is the "SCRAM-SHA-256" SASL authentication mechanism as described in RFC 7677.
+	//
 	// https://datatracker.ietf.org/doc/html/rfc7677
 	SMTPAuthSCRAMSHA256 SMTPAuthType = "SCRAM-SHA-256"
 
-	// SMTPAuthSCRAMSHA256PLUS represents the "SCRAM-SHA-256-PLUS" SMTP AUTH type.
+	// SMTPAuthSCRAMSHA256PLUS is the "SCRAM-SHA-256-PLUS" SASL authentication mechanism as described in RFC 7677.
+	//
+	// SCRAM-SHA-X-PLUS authentication require TLS channel bindings to protect against MitM attacks and
+	// to guarantee that the integrity of the transport layer is preserved throughout the authentication
+	// process. Therefore we only allow this mechansim over a TLS secured connection.
+	//
 	// https://datatracker.ietf.org/doc/html/rfc7677
 	SMTPAuthSCRAMSHA256PLUS SMTPAuthType = "SCRAM-SHA-256-PLUS"
 )
 
 // SMTP Auth related static errors
 var (
-	// ErrPlainAuthNotSupported should be used if the target server does not support the "PLAIN" schema
+	// ErrPlainAuthNotSupported is returned when the server does not support the "PLAIN" SMTP
+	// authentication type.
 	ErrPlainAuthNotSupported = errors.New("server does not support SMTP AUTH type: PLAIN")
 
-	// ErrLoginAuthNotSupported should be used if the target server does not support the "LOGIN" schema
+	// ErrLoginAuthNotSupported is returned when the server does not support the "LOGIN" SMTP
+	// authentication type.
 	ErrLoginAuthNotSupported = errors.New("server does not support SMTP AUTH type: LOGIN")
 
-	// ErrCramMD5AuthNotSupported should be used if the target server does not support the "CRAM-MD5" schema
+	// ErrCramMD5AuthNotSupported is returned when the server does not support the "CRAM-MD5" SMTP
+	// authentication type.
 	ErrCramMD5AuthNotSupported = errors.New("server does not support SMTP AUTH type: CRAM-MD5")
 
-	// ErrXOauth2AuthNotSupported should be used if the target server does not support the "XOAUTH2" schema
+	// ErrXOauth2AuthNotSupported is returned when the 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 is returned when the server does not support the "SCRAM-SHA-1" SMTP
+	// authentication type.
 	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 is returned when the server does not support the "SCRAM-SHA-1-PLUS" SMTP
+	// authentication type.
 	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 is returned when the server does not support the "SCRAM-SHA-256" SMTP
+	// authentication type.
 	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 is returned when the server does not support the "SCRAM-SHA-256-PLUS" SMTP
+	// authentication type.
 	ErrSCRAMSHA256PLUSAuthNotSupported = errors.New("server does not support SMTP AUTH type: SCRAM-SHA-256-PLUS")
 )

b64linebreaker.go

@@ -9,21 +9,39 @@ import (
 	"io"
 )
 
-// ErrNoOutWriter is an error message that should be used if a Base64LineBreaker has no out io.Writer set
+// newlineBytes is a byte slice representation of the SingleNewLine constant used for line breaking
+// in encoding processes.
+var newlineBytes = []byte(SingleNewLine)
+
+// ErrNoOutWriter is the error message returned when no io.Writer is set for Base64LineBreaker.
 const ErrNoOutWriter = "no io.Writer set for Base64LineBreaker"
 
-// Base64LineBreaker is a io.WriteCloser that writes Base64 encoded data streams
-// with line breaks at a given line length
+// Base64LineBreaker handles base64 encoding with the insertion of new lines after a certain number
+// of characters.
+//
+// This struct is used to manage base64 encoding while ensuring that new lines are inserted after
+// reaching a specific line length. It satisfies the io.WriteCloser interface.
+//
+// References:
+//   - https://datatracker.ietf.org/doc/html/rfc2045 (Base64 and line length limitations)
 type Base64LineBreaker struct {
 	line [MaxBodyLength]byte
 	used int
 	out  io.Writer
 }
 
-var newlineBytes = []byte(SingleNewLine)
-
-// Write writes the data stream and inserts a SingleNewLine when the maximum
-// line length is reached
+// Write writes data to the Base64LineBreaker, ensuring lines do not exceed MaxBodyLength.
+//
+// This method writes the provided data to the Base64LineBreaker. It ensures that the written
+// lines do not exceed the MaxBodyLength. If the data exceeds the limit, it handles the
+// continuation by splitting the data and writing new lines as necessary.
+//
+// Parameters:
+//   - data: A byte slice containing the data to be written.
+//
+// Returns:
+//   - numBytes: The number of bytes written.
+//   - err: An error if one occurred during the write operation.
 func (l *Base64LineBreaker) Write(data []byte) (numBytes int, err error) {
 	if l.out == nil {
 		err = errors.New(ErrNoOutWriter)
@@ -55,8 +73,14 @@ func (l *Base64LineBreaker) Write(data []byte) (numBytes int, err error) {
 	return l.Write(data[excess:])
 }
 
-// Close closes the Base64LineBreaker and writes any access data that is still
-// unwritten in memory
+// Close finalizes the Base64LineBreaker, writing any remaining buffered data and appending a newline.
+//
+// This method ensures that any remaining data in the buffer is written to the output and appends
+// a newline. It is used to finalize the Base64LineBreaker and should be called when no more data
+// is expected to be written.
+//
+// Returns:
+//   - err: An error if one occurred during the final write operation.
 func (l *Base64LineBreaker) Close() (err error) {
 	if l.used > 0 {
 		_, err = l.out.Write(l.line[0:l.used])