Merge pull request #3430 from tangix/mail-tls-fixes

Clearing up confusion with TLS and SSL in Email Library, fixes #3429
codeigniter4 · Aug 1, 2020 · 2364200 · 2364200
2 parents 906026e + d17657e
commit 2364200
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 4 deletions.
diff --git a/system/Email/Email.php b/system/Email/Email.php
@@ -1862,7 +1862,17 @@ protected function SMTPConnect()
 		{
 			return true;
 		}
-		$ssl               = ($this->SMTPCrypto === 'ssl') ? 'ssl://' : '';
+
+		$ssl = '';
+		if ($this->SMTPPort === 465)
+		{
+			$ssl = 'tls://';
+		}
+		elseif ($this->SMTPCrypto === 'ssl')
+		{
+			$ssl = 'ssl://';
+		}
+
 		$this->SMTPConnect = fsockopen(
 				$ssl . $this->SMTPHost, $this->SMTPPort, $errno, $errstr, $this->SMTPTimeout
 		);
@@ -1877,7 +1887,8 @@ protected function SMTPConnect()
 		{
 			$this->sendCommand('hello');
 			$this->sendCommand('starttls');
-			$crypto = stream_socket_enable_crypto($this->SMTPConnect, true, STREAM_CRYPTO_METHOD_TLS_CLIENT);
+			$crypto = stream_socket_enable_crypto($this->SMTPConnect, true, STREAM_CRYPTO_METHOD_TLSv1_0_CLIENT |
+				STREAM_CRYPTO_METHOD_TLSv1_1_CLIENT | STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT);
 			if ($crypto !== true)
 			{
 				$this->setErrorMessage(lang('Email.SMTPError', $this->getSMTPData()));

diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst
@@ -87,6 +87,33 @@ The settings used for the last successful send are available from the
 instance property ``$archive``. This is helpful for testing and debugging
 to determine that actual values at the time of the ``send()`` call.
 
+SSL versus TLS for SMTP Protocol
+================================
+
+To protect the username, password and email content while communicating with the SMTP server,
+encryption on the channel should be used. Two different standards are widely deployed and
+it is important to understand the differences when trying to troubleshoot email sending
+issues.
+
+Most SMTP servers allow connections on ports 465 or 587 when submitting emails. (The
+original port 25 is seldom used because of many ISPs have blocking rules in place and
+since the communication is entirely in clear-text).
+
+The key difference is that port 465 expects the communication channel to be secured using TLS
+from the start as per `RFC 8314 <https://tools.ietf.org/html/rfc8314>`_.
+A connection to port 587 allows clear-text connection and later
+will upgrade the channel to use encryption using the ``STARTTLS`` SMTP command.
+
+Upgrading a connection on port 465 may or may not be supported by the server, so the
+``STARTTLS`` SMTP command may fail if the server does not allow it. If you set the port to 465,
+you should try to leave the ``SMTPCrypto`` setting blank since the communication is
+secured using TLS from the start and the ``STARTTLS`` is not needed.
+
+If your configuration requires you to connect to port 587, you should most likely set
+``SMTPCrypto`` to ``tls`` as this will implement the ``STARTTLS`` command while communicating
+with the SMTP server to switch from clear-text to an encrypted channel. The initial communication
+will be made in clear-text and the channel will be upgraded to TLS with the ``STARTTLS`` command.
+
 Email Preferences
 =================
 
@@ -102,10 +129,14 @@ Preference          Default Value          Options                      Descript
 **SMTPHost**        No Default             None                         SMTP Server Address.
 **SMTPUser**        No Default             None                         SMTP Username.
 **SMTPPass**        No Default             None                         SMTP Password.
-**SMTPPort**        25                     None                         SMTP Port.
+**SMTPPort**        25                     None                         SMTP Port. (If set to 465, TLS will be used for the connection
+                                                                        regardless of SMTPCrypto setting.)
 **SMTPTimeout**     5                      None                         SMTP Timeout (in seconds).
 **SMTPKeepAlive**   FALSE                  TRUE or FALSE (boolean)      Enable persistent SMTP connections.
-**SMTPCrypto**      No Default             tls or ssl                   SMTP Encryption
+**SMTPCrypto**      No Default             tls or ssl                   SMTP Encryption. Setting this to "ssl" will create a secure
+                                                                        channel to the server using SSL and "tls" will issue a
+                                                                        ``STARTTLS`` command to the server. Connection on port 465 should
+                                                                        set this to blank.
 **wordWrap**        TRUE                   TRUE or FALSE (boolean)      Enable word-wrap.
 **wrapChars**       76                                                  Character count to wrap at.
 **mailType**        text                   text or html                 Type of mail. If you send HTML email you must send it as a complete web