{"thread":{"id":"58601","subject":"[PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption","startedAt":"2022-10-11T16:50:22Z","lastAt":"2022-10-11T17:42:07Z","messageCount":4,"participants":["sndanailov@wired4ever.net","Junio C Hamano","Sotir Danailov"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"464620","messageId":"20221011164927.1516-1-sndanailov@wired4ever.net","threadId":"58601","inReplyTo":null,"subject":"[PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption","fromName":"","fromEmail":"sndanailov@wired4ever.net","sentAt":"2022-10-11T16:49:27Z","receivedAt":"2022-10-11T16:50:22Z","isPatch":true,"sender":{"key":"sndanailov@wired4ever.net","avatar":null},"body":"From: Sotir Danailov \n\nNew explanation for the difference between these values.\nIt's hard to understand what they do based only on the names.\nNew description of used default ports.\n\nSigned-off-by: Sotir Danailov \n---\nChanges since v1: Expanded explanation, covering more terms.\nLink to v1: https://public-inbox.org/git/20221010172859.13832-1-sndanailov@wired4ever.net/\n\n Documentation/git-send-email.txt | 15 ++++++++++++---\n 1 file changed, 12 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 3290043053..d64a46fa87 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -178,9 +178,18 @@ Sending\n \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.\n \n --smtp-encryption=::\n-\tSpecify the encryption to use, either 'ssl' or 'tls'. Any other\n-\tvalue reverts to plain SMTP. Default is the value of\n-\t`sendemail.smtpEncryption`.\n+\tValid values are 'ssl' and 'tls'. Any other value reverts to plain\n+\t(unencrypted) SMTP, which defaults to port 25.\n+\tDespite the names, both values will use the same newer version of TLS,\n+\tbut for historic reasons have these names. The difference between the\n+\ttwo values for Git is the following. 'ssl' refers to \"implicit\"\n+\tencryption (sometimes called SMTPS), that uses port 465 by default.\n+\t'tls' refers to \"explicit\" encryption (often known as STARTTLS),\n+\tthat uses port 25 by default. Other ports might be used by the SMTP\n+\tserver, which are not the default. Commonly found alternative port for\n+\t'tls' and unencrypted is 587. You need to check your provider's\n+\tdocumentation or your server configuration to make sure\n+\tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n \n --smtp-domain=::\n \tSpecifies the Fully Qualified Domain Name (FQDN) used in the\n-- \n2.37.3\n\n"},{"id":"464624","messageId":"xmqqh70auvf3.fsf@gitster.g","threadId":"58601","inReplyTo":"20221011164927.1516-1-sndanailov@wired4ever.net","subject":"Re: [PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-11T17:22:56Z","receivedAt":"2022-10-11T17:23:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"sndanailov@wired4ever.net writes:\n\n> From: Sotir Danailov \n>\n> New explanation for the difference between these values.\n> It's hard to understand what they do based only on the names.\n> New description of used default ports.\n>\n> Signed-off-by: Sotir Danailov \n> ---\n> Changes since v1: Expanded explanation, covering more terms.\n> Link to v1: https://public-inbox.org/git/20221010172859.13832-1-sndanailov@wired4ever.net/\n>\n> Documentation/git-send-email.txt | 15 ++++++++++++---\n> 1 file changed, 12 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n> index 3290043053..d64a46fa87 100644\n> --- a/Documentation/git-send-email.txt\n> +++ b/Documentation/git-send-email.txt\n> @@ -178,9 +178,18 @@ Sending\n> \tfor `sendmail` in `/usr/sbin`, `/usr/lib` and $PATH.\n> \n> --smtp-encryption=::\n> -\tSpecify the encryption to use, either 'ssl' or 'tls'. Any other\n> -\tvalue reverts to plain SMTP. Default is the value of\n> -\t`sendemail.smtpEncryption`.\n> +\tValid values are 'ssl' and 'tls'. Any other value reverts to plain\n> +\t(unencrypted) SMTP, which defaults to port 25.\n\nPlease always start the description of a thing by explaining what\nthe thing is. After reading two lines, we learned what values to\nplug are valid, but we still do not know what good\ngiving --smtp-encryption= is supposed to give us.\n\n> +\tDespite the names, both values will use the same newer version of TLS,\n> +\tbut for historic reasons have these names. The difference between the\n> +\ttwo values for Git is the following. 'ssl' refers to \"implicit\"\n> +\tencryption (sometimes called SMTPS), that uses port 465 by default.\n\nAnd we still haven't said what the option is about at this point,\neven though the reader may be able to guess that this is about a\nmechanism to specify something about encryption after reading this\nmuch text.\n\nNone of what we see in the updated text may be wrong per-se, but the\nreaders need \"what it is about\" upfront to be motivated to read it\nthrough.\n\nPerhaps start the description like this?\n\n\tSpecify how SMTP connection should be entered into encrypted\n\tmode. The valid values are 'ssl' and 'tls'. Any other value ...\n\n> +\t'tls' refers to \"explicit\" encryption (often known as STARTTLS),\n> +\tthat uses port 25 by default. Other ports might be used by the SMTP\n> +\tserver, which are not the default. Commonly found alternative port for\n> +\t'tls' and unencrypted is 587. You need to check your provider's\n> +\tdocumentation or your server configuration to make sure\n> +\tfor your own case. Default is the value of `sendemail.smtpEncryption`.\n\nI think the updated text is otherwise good, but it would be better\nto remove \"The difference between ... is the following.\" The text\nis easier to read without that sentence.\n\nThanks.\n"},{"id":"464625","messageId":"f384d6b9-fb4c-cf22-ea88-8ab50f319a78@wired4ever.net","threadId":"58601","inReplyTo":"xmqqh70auvf3.fsf@gitster.g","subject":"Re: [PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption","fromName":"Sotir Danailov","fromEmail":"sndanailov@wired4ever.net","sentAt":"2022-10-11T17:31:43Z","receivedAt":"2022-10-11T17:39:56Z","isPatch":true,"sender":{"key":"sndanailov@wired4ever.net","avatar":null},"body":"On Tue 11 10 2022 19:22, Junio C Hamano wrote:\n> Please always start the description of a thing by explaining what\n> the thing is.\n\nWow I can't believe I missed that...sorry!\n\n> I think the updated text is otherwise good, but it would be better\n> to remove \"The difference between ... is the following.\" The text\n> is easier to read without that sentence.\n\nI just wanted to make it clear that this is how Git interprets these values.\nBut yeah, you're right, it's unnecessary.\n\nI will make a v3 tomorrow.\n"},{"id":"464626","messageId":"xmqqczayuujc.fsf@gitster.g","threadId":"58601","inReplyTo":"f384d6b9-fb4c-cf22-ea88-8ab50f319a78@wired4ever.net","subject":"Re: [PATCH v2] docs: git-send-email: difference between ssl and tls smtp-encryption","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-10-11T17:41:59Z","receivedAt":"2022-10-11T17:42:07Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sotir Danailov writes:\n\n> On Tue 11 10 2022 19:22, Junio C Hamano wrote:\n>> Please always start the description of a thing by explaining what\n>> the thing is.\n>\n> Wow I can't believe I missed that...sorry!\n>\n>> I think the updated text is otherwise good, but it would be better\n>> to remove \"The difference between ... is the following.\" The text\n>> is easier to read without that sentence.\n>\n> I just wanted to make it clear that this is how Git interprets these values.\n> But yeah, you're right, it's unnecessary.\n>\n> I will make a v3 tomorrow.\n\nThanks.\n"}]}