v5, 3 partsImprove checks for valid_fqdn in send-email and update documentation

Hi all

This series of patches mainly has two changes:

1. Improve the checks for valid_fqdn in send-email to be more strict and
   compliant with RFC1035.
2. Update the documentation for send-email to include examples of using
   OAuth2.0 with Gmail and Outlook, as well as links to the credential
   helpers for these services.

P.S. I have used `git-credential-outlook` linked in the second and third patch for this email!

v2: - Improve grammar and add missing "" in second patch.
    - Separate footnotes and the trailer block with a blank line in the first
      patch.

v3: - Change link for email helpers since old one was too long.

v4: - Improve log message of first and second patch.
    - Update valid_fqdn check in first patch to allow one or more <upto 63
      octet run of alnum or hyphen that does not begin or end with hyphen>,
      separated by a single dot in between each.
    - Revert the documentation regarding sending patches to a mailing list
      in the second patch.

v5: - Simplify the regex in the first patch to check for valid FQDN.
    - Fix formatting in the second patch to make it more readable.

Aditya Garg (3):
  send-mail: improve checks for valid_fqdn
  docs: improve send-email documentation
  docs: add credential helper for outlook and gmail in OAuth list of
    helpers

 Documentation/git-send-email.adoc | 63 +++++++++++++++++++++++++++----
 Documentation/gitcredentials.adoc |  4 ++
 git-send-email.perl               |  4 +-
 3 files changed, 62 insertions(+), 9 deletions(-)

The current implementation of a valid Fully Qualified Domain Name is not that strict. It just checks whether it has a dot (.) and if using macOS, it should not end with .local. As per RFC1035[1], from what I understood, the following checks need to be done:

- The domain must contain atleast one dot
- Each label (separated by dots) must be 1-63 characters long
- Labels must start and end with an alphanumeric character
- Labels can contain alphanumeric characters and hyphens

Here are some examples of valid and invalid labels:

'example.com', # Valid 'sub.example.com', # Valid 'my-domain.org', # Valid 'localhost', # Invalid (no dot) 'MacBook..', # Invalid (double dots) '-example.com', # Invalid (starts with a hyphen) 'example-.com', # Invalid (ends with a hyphen) 'example..com', # Invalid (double dots) 'example', # Invalid (no TLD) 'example.local', # Invalid on macOS 'valid-domain.co.uk', # Valid '123.example.com', # Valid 'example.com.', # Invalid (trailing dot) 'toolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabeltoolonglabel.com', # Invalid (label > 63 chars)

Due to current implementation, I was not able to send emails from Ubuntu. Upon debugging, I found that the SMTP domain being passed to Outlook's servers was not valid.

Net::SMTP=GLOB(0x5db4351225f8)>>> EHLO MacBook.. Net::SMTP=GLOB(0x5db4351225f8)<<< 501 5.5.4 Invalid domain name Net::SMTP=GLOB(0x5db4351225f8)>>> HELO MacBook..

Notice that an invalid domain name "MacBook.." is sent by git-send-email. We have a fallback code that checks output from Net::Domain::domainname() or asking domain method of an Net::SMTP instance to detect a misconfigured hostname and replace it with fallback "localhost.localdomain", but the valid_fqdn apparently is failing to say "MacBook.." is not a valid fqdn.

With this patch, the rule used in valid_fqdn is tightened, the beginning part of the SMTP exchange looked like this:

Net::SMTP=GLOB(0x58c8af71e930)>>> EHLO localhost.localdomain Net::SMTP=GLOB(0x58c8af71e930)<<< 250-PN4P287CA0064.outlook.office365.com Hello

[1]: https://datatracker.ietf.org/doc/html/rfc1035

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 git-send-email.perl | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

OAuth2.0 is a new authentication method that is being used by many email providers, including Outlook and Gmail. Recently, the Authen::SASL perl module has been updated to support OAuth2.0 authentication, thus making the git-send-email script be able to use this authentication method as well. So lets improve the documentation to reflect this change.

I also had a hard time finding a reliable OAuth2.0 access token generator for Outlook and Gmail. So I added a link to the such generators which I developed myself after seaching through lots of code and API documentation to make things easier for others.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/git-send-email.adoc | 63 +++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 8 deletions(-)

This commit adds the `git-credential-outlook` and `git-credential-gmail` helpers to the list of OAuth helpers.

Signed-off-by: Aditya Garg <gargaditya08@live.com>
---
 Documentation/gitcredentials.adoc | 4 ++++
 1 file changed, 4 insertions(+)

Aditya Garg <gargaditya08@live.com> writes:

;-)

I didn't know if the $subdomain variable thing would actually work, so it is great to see you took it and tested it.

Thanks for an update.  Will queue.