Remove $ssl_starttls check for IMAP PREAUTH.

Checking $ssl_starttls provides no real protection, because an
attacker can just as easily spoof "* OK" and strip the STARTTLS
capability as it can spoof "* PREAUTH".  The only way to really
protect again the MITM is through $ssl_force_tls.

Add documentation about STARTTLS, $tunnel, and the current PREAUTH
exception when using $tunnel.

The behavior of Mutt about $tunnel is somewhat inconsistent: is it
considered secure or not?  For PREAUTH, to avoid breaking
configurations, we assume it is secure.  But at the same time, Mutt is
still negotiating STARTTLS for other $tunnel connections.

This will be resolved in master for the next release; probably by
adding a $tunnel_is_secure config variable defaulting "yes" and
removing the STARTTLS negotiation in that case.

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/manual.xml.head b/doc/manual.xml.head
index 908e62aa..52769530 100644
--- a/doc/manual.xml.head
+++ b/doc/manual.xml.head
@@ -8672,6 +8672,57 @@ are suffixed with <quote>s</quote> for <quote>secure
 communication</quote>.
 </para>
 
+<sect2 id="starttls">
+  <title>STARTTLS</title>
+  <para>
+    When non-secure URL protocols <literal>imap://</literal>,
+    <literal>pop://</literal>, and <literal>smtp://</literal> are
+    used, the initial connection to the server will be unencrypted.
+    <literal>STARTTLS</literal> can be used to negotiate an encrypted
+    connection after the initial unencrypted connection and exchange.
+  </para>
+  <para>
+    Two configuration variables control Mutt's behavior with
+    <literal>STARTTLS</literal>.  <link
+    linkend="ssl-starttls">$ssl_starttls</link> will initiate
+    <literal>STARTTLS</literal> if the server advertises support for
+    it.  <link linkend="ssl-force-tls">$ssl_force_tls</link> will
+    always try to initiate it, whether the server advertises support
+    or not.
+  </para>
+  <para>
+    Mutt <emphasis>highly recommends</emphasis> setting <link
+    linkend="ssl-force-tls">$ssl_force_tls</link> unless you need to
+    connect to an unencrypted server.  It's possible for an attacker
+    to spoof interactions during the initial connection and hide
+    support for <literal>STARTTLS</literal>.  The only way to prevent
+    these attacks is by forcing <literal>STARTTLS</literal> with the
+    <link linkend="ssl-force-tls">$ssl_force_tls</link> configuration
+    variable.
+  </para>
+</sect2>
+
+<sect2 id="secure-tunnel">
+  <title>Tunnel</title>
+  <para>
+    Mutt generally assumes a connection through <link
+    linkend="tunnel">$tunnel</link> is secure: either using a direct
+    pipe or a <literal>ssh</literal> connection.  However, Mutt will
+    still attempt to negotiate <literal>STARTTLS</literal> subject to
+    <link linkend="ssl-starttls">$ssl_starttls</link> and <link
+    linkend="ssl-force-tls">$ssl_force_tls</link>.
+  </para>
+  <para>
+    An IMAP server configured for preauthentication
+    (<literal>PREAUTH</literal>) does not allow
+    <literal>STARTTLS</literal> negotation.  If using <link
+    linkend="tunnel">$tunnel</link>, Mutt allows the connection to go
+    through.  Outside of a tunnel, setting <link
+    linkend="ssl-force-tls">$ssl_force_tls</link> will abort the
+    connection.
+  </para>
+</sect2>
+
 </sect1>
 
 <sect1 id="pop">