[PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[sndanailov]

From: Sotir Danailov <sndanailov@wired4ever.net>

New explanation for the difference between these values.
It's hard to understand what they do based only on the names.
New description of used default ports.

Signed-off-by: Sotir Danailov <sndanailov@wired4ever.net>
---
Changes since v1: Expanded explanation, covering more terms.
Link to v1: https://public-inbox.org/git/20221010172859.13832-1-sndanailov@wired4ever.net/

Changes since v2: Added a description of what the option actually does.
Link to v2: https://public-inbox.org/git/20221011164927.1516-1-sndanailov@wired4ever.net/

 Documentation/git-send-email.txt | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 3290043053..765b2df853 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -178,9 +178,18 @@ Sending
 	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
 
 --smtp-encryption=<encryption>::
-	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
-	value reverts to plain SMTP.  Default is the value of
-	`sendemail.smtpEncryption`.
+	Specify in what way encrypting begins for the SMTP connection.
+	Valid values are 'ssl' and 'tls'. Any other value reverts to plain
+	(unencrypted) SMTP, which defaults to port 25.
+	Despite the names, both values will use the same newer version of TLS,
+	but for historic reasons have these names. 'ssl' refers to "implicit"
+	encryption (sometimes called SMTPS), that uses port 465 by default.
+	'tls' refers to "explicit" encryption (often known as STARTTLS),
+	that uses port 25 by default. Other ports might be used by the SMTP
+	server, which are not the default. Commonly found alternative port for
+	'tls' and unencrypted is 587. You need to check your provider's
+	documentation or your server configuration to make sure
+	for your own case. Default is the value of `sendemail.smtpEncryption`.
 
 --smtp-domain=<FQDN>::
 	Specifies the Fully Qualified Domain Name (FQDN) used in the
-- 
2.37.3

Re: [PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[Philip Oakley]

Hi Sotir,

On 12/10/2022 16:06, sndanailov@wired4ever.net wrote:
> From: Sotir Danailov <sndanailov@wired4ever.net>
>
> New explanation for the difference between these values.
> It's hard to understand what they do based only on the names.
> New description of used default ports.
>
> Signed-off-by: Sotir Danailov <sndanailov@wired4ever.net>
> ---
> Changes since v1: Expanded explanation, covering more terms.
> Link to v1: https://public-inbox.org/git/20221010172859.13832-1-sndanailov@wired4ever.net/
>
> Changes since v2: Added a description of what the option actually does.
> Link to v2: https://public-inbox.org/git/20221011164927.1516-1-sndanailov@wired4ever.net/
>
>  Documentation/git-send-email.txt | 15 ++++++++++++---
>  1 file changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
> index 3290043053..765b2df853 100644
> --- a/Documentation/git-send-email.txt
> +++ b/Documentation/git-send-email.txt
> @@ -178,9 +178,18 @@ Sending
>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
>  
>  --smtp-encryption=<encryption>::
> -	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
> -	value reverts to plain SMTP.  Default is the value of
> -	`sendemail.smtpEncryption`.
> +	Specify in what way encrypting begins for the SMTP connection.
> +	Valid values are 'ssl' and 'tls'. Any other value reverts to plain
> +	(unencrypted) SMTP, which defaults to port 25.
> +	Despite the names, both values will use the same newer version of TLS,
> +	but for historic reasons have these names. 'ssl' refers to "implicit"
> +	encryption (sometimes called SMTPS), that uses port 465 by default.
> +	'tls' refers to "explicit" encryption (often known as STARTTLS),
> +	that uses port 25 by default. Other ports might be used by the SMTP
> +	server, which are not the default. Commonly found alternative port for
> +	'tls' and unencrypted is 587.

Can we insert a sentence something like "Use the `--smtp-server-port`
option to set non-default ports." to direct users that need it?


>  You need to check your provider's
> +	documentation or your server configuration to make sure
> +	for your own case. Default is the value of `sendemail.smtpEncryption`.
>  
>  --smtp-domain=<FQDN>::
>  	Specifies the Fully Qualified Domain Name (FQDN) used in the
--
Philip

Re: [PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 1583 bytes --]

On 2022-10-12 at 15:06:19, sndanailov@wired4ever.net wrote:
> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
> index 3290043053..765b2df853 100644
> --- a/Documentation/git-send-email.txt
> +++ b/Documentation/git-send-email.txt
> @@ -178,9 +178,18 @@ Sending
>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
>  
>  --smtp-encryption=<encryption>::
> -	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
> -	value reverts to plain SMTP.  Default is the value of
> -	`sendemail.smtpEncryption`.
> +	Specify in what way encrypting begins for the SMTP connection.
> +	Valid values are 'ssl' and 'tls'. Any other value reverts to plain
> +	(unencrypted) SMTP, which defaults to port 25.
> +	Despite the names, both values will use the same newer version of TLS,
> +	but for historic reasons have these names. 'ssl' refers to "implicit"
> +	encryption (sometimes called SMTPS), that uses port 465 by default.
> +	'tls' refers to "explicit" encryption (often known as STARTTLS),
> +	that uses port 25 by default. Other ports might be used by the SMTP
> +	server, which are not the default. Commonly found alternative port for
> +	'tls' and unencrypted is 587. You need to check your provider's
> +	documentation or your server configuration to make sure
> +	for your own case. Default is the value of `sendemail.smtpEncryption`.

I'm happy with this as it stands.  Thanks for taking my suggestions and
sending a patch to improve the docs.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

Re: [PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[Junio C Hamano]

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> On 2022-10-12 at 15:06:19, sndanailov@wired4ever.net wrote:
>> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
>> index 3290043053..765b2df853 100644
>> --- a/Documentation/git-send-email.txt
>> +++ b/Documentation/git-send-email.txt
>> @@ -178,9 +178,18 @@ Sending
>>  	for `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.
>>  
>>  --smtp-encryption=<encryption>::
>> -	Specify the encryption to use, either 'ssl' or 'tls'.  Any other
>> -	value reverts to plain SMTP.  Default is the value of
>> -	`sendemail.smtpEncryption`.
>> +	Specify in what way encrypting begins for the SMTP connection.
>> +	Valid values are 'ssl' and 'tls'. Any other value reverts to plain
>> +	(unencrypted) SMTP, which defaults to port 25.
>> +	Despite the names, both values will use the same newer version of TLS,
>> +	but for historic reasons have these names. 'ssl' refers to "implicit"
>> +	encryption (sometimes called SMTPS), that uses port 465 by default.
>> +	'tls' refers to "explicit" encryption (often known as STARTTLS),
>> +	that uses port 25 by default. Other ports might be used by the SMTP
>> +	server, which are not the default. Commonly found alternative port for
>> +	'tls' and unencrypted is 587. You need to check your provider's
>> +	documentation or your server configuration to make sure
>> +	for your own case. Default is the value of `sendemail.smtpEncryption`.
>
> I'm happy with this as it stands.  Thanks for taking my suggestions and
> sending a patch to improve the docs.

I marked it as "Expecting a reroll" in the latest issue of "What's
cooking" report, but I do not mind taking it to 'next' as-is,
without adding an extra reference to --smtp-server-port.  The
reference to port numbers here are there to help readers identify
which one is which, not because it is common to use randomly
numbered ports.

Thanks.

Re: [PATCH v3] docs: git-send-email: difference between ssl and tls smtp-encryption

[Sotir Danailov]

On Wed 12 Oct 2022 23:38, Junio C Hamano wrote:
> not because it is common to use randomly numbered ports.

Yes, good point! Also I feel the description might become
a bit too bloated if we squeeze in the reference.
Although I'm not against adding it as well, it will make
things a lot clearer for sure.

There's also the issue with the commonly found alternative
port 587, which I feel might be better fixed by making the
script test for it as well if the first default fails.

I don't mind making a v4, but from the responses it seems
there's no need?

Thanks everybody for the input, helping me with the
patches and for the fast responses, I really appreciate it!