Improve SSL/TLS documentation, and rearrange manual

Move SSL subsection up under AUTHENTICATION and ENCRYPTION,
where it belongs.

1 files changed, 76 insertions, 73 deletions

diff --git a/fetchmail.man b/fetchmail.man
index 7846ace1..855bb00b 100644
--- a/fetchmail.man
+++ b/fetchmail.man
@@ -71,7 +71,8 @@ language, please use English.
 
 
 
-.SS CONCEPTS
+
+.SH CONCEPTS
 If \fBfetchmail\fP is used with a POP or an IMAP server (but not with
 ETRN or ODMR), it has two fundamental modes of operation for each user
 account from which it retrieves mail: \fIsingledrop\fP- and
@@ -1195,6 +1196,78 @@ On mailservers that do not provide ordinary user accounts, your user-id and
 password are usually assigned by the server administrator when you apply for
 a mailbox on the server.  Contact your server administrator if you don't know
 the correct user-id and password for your mailbox account.
+
+.SS Secure Socket Layers (SSL) and Transport Layer Security (TLS)
+.PP
+All retrieval protocols can use SSL or TLS wrapping for the
+transport. Additionally, POP3 and IMAP retrival can also negotiate
+SSL/TLS by means of STARTTLS (or STLS).
+.PP
+Note that fetchmail currently uses the OpenSSL library, which is
+severely underdocumented, so failures may occur just because the
+programmers are not aware of OpenSSL's requirement of the day.
+For instance, since v6.3.16, fetchmail calls
+OpenSSL_add_all_algorithms(), which is necessary to support certificates
+using SHA256 on OpenSSL 0.9.8 -- this information is deeply hidden in
+the documentation and not at all obvious.  Please do not hesitate to
+report subtle SSL failures.
+.PP
+You can access SSL encrypted services by specifying the options starting
+with \-\-ssl, such as \-\-ssl, \-\-sslproto, \-\-sslcertck, and others.
+You can also do this using the corresponding user options in the .fetchmailrc
+file.  Some services, such as POP3 and IMAP, have
+different well known ports defined for the SSL encrypted services.  The
+encrypted ports will be selected automatically when SSL is enabled and
+no explicit port is specified.   Also, the \-\-sslcertck command line or
+sslcertck run control file option should be used to force strict
+certificate checking with older fetchmail versions - see below.
+.PP
+If SSL is not configured, fetchmail will usually opportunistically try to use
+STARTTLS. STARTTLS can be enforced by using \-\-sslproto\~auto and
+defeated by using \-\-sslproto\~''.
+TLS connections use the same port as the unencrypted version of the
+protocol and negotiate TLS via special command. The \-\-sslcertck
+command line or sslcertck run control file option should be used to
+force strict certificate checking - see below.
+.PP
+.B \-\-sslcertck is recommended:
+When connecting to an SSL or TLS encrypted server, the
+server presents a certificate to the client for validation.  The
+certificate is checked to verify that the common name in the certificate
+matches the name of the server being contacted and that the effective
+and expiration dates in the certificate indicate that it is currently
+valid.  If any of these checks fail, a warning message is printed, but
+the connection continues.  The server certificate does not need to be
+signed by any specific Certifying Authority and may be a "self-signed"
+certificate. If the \-\-sslcertck command line option or sslcertck run
+control file option is used, fetchmail will instead abort if any of
+these checks fail, because it must assume that there is a
+man-in-the-middle attack in this scenario, hence fetchmail must not
+expose cleartext passwords. Use of the sslcertck or \-\-sslcertck option
+is therefore advised; it has become the default in fetchmail 6.4.0.
+.PP
+Some SSL encrypted servers may request a client side certificate.  A client
+side public SSL certificate and private SSL key may be specified.  If
+requested by the server, the client certificate is sent to the server for
+validation.  Some servers may require a valid client certificate and may
+refuse connections if a certificate is not provided or if the certificate
+is not valid.  Some servers may require client side certificates be signed
+by a recognized Certifying Authority.  The format for the key files and
+the certificate files is that required by the underlying SSL libraries
+(OpenSSL in the general case).
+.PP
+A word of care about the use of SSL: While above mentioned
+setup with self-signed server certificates retrieved over the wires
+can protect you from a passive eavesdropper, it doesn't help against an
+active attacker. It's clearly an improvement over sending the
+passwords in clear, but you should be aware that a man-in-the-middle
+attack is trivially possible (in particular with tools such as
+.URL "https://monkey.org/~dugsong/dsniff/" "dsniff" ,
+).  Use of strict certificate checking with a certification authority
+recognized by server and client, or perhaps of an SSH tunnel (see below
+for some examples) is preferable if you care seriously about the
+security of your mailbox and passwords.
+
 .SH POP3 VARIANTS
 .PP
 Early versions of POP3 (RFC1081, RFC1225) supported a crude form of
@@ -1218,6 +1291,7 @@ database.
 
 \fBNote that APOP is no longer considered resistant against
 man-in-the-middle attacks.\fP
+
 .SS RETR or TOP
 \fBfetchmail\fP makes some efforts to make the server believe messages
 had not been retrieved, by using the TOP command with a large number of
@@ -1242,7 +1316,7 @@ implies that in "keep" setups, "uidl" must be set if "TOP" is desired.
 fetchmail, but the behavior may change in future versions. In
 particular, fetchmail may prefer the RETR command because the TOP
 command causes much grief on some servers and is only optional.
-.SH ALTERNATE AUTHENTICATION FORMS
+.SH ALTERNATE AUTHENTICATION FORMS/METHODS
 .PP
 If your \fBfetchmail\fP was built with Kerberos support and you specify
 Kerberos authentication (either with \-\-auth or the \fI.fetchmailrc\fP
@@ -1291,77 +1365,6 @@ capability response. Specify a user option value that looks like
 \&'user@domain': the part to the left of the @ will be passed as the
 username and the part to the right as the NTLM domain.
 
-.SS Secure Socket Layers (SSL) and Transport Layer Security (TLS)
-.PP
-All retrieval protocols can use SSL or TLS wrapping for the
-transport. Additionally, POP3 and IMAP retrival can also negotiate
-SSL/TLS by means of STARTTLS (or STLS).
-.PP
-Note that fetchmail currently uses the OpenSSL library, which is
-severely underdocumented, so failures may occur just because the
-programmers are not aware of OpenSSL's requirement of the day.
-For instance, since v6.3.16, fetchmail calls
-OpenSSL_add_all_algorithms(), which is necessary to support certificates
-using SHA256 on OpenSSL 0.9.8 -- this information is deeply hidden in
-the documentation and not at all obvious.  Please do not hesitate to
-report subtle SSL failures.
-.PP
-You can access SSL encrypted services by specifying the options starting
-with \-\-ssl, such as \-\-ssl, \-\-sslproto, \-\-sslcertck, and others.
-You can also do this using the corresponding user options in the .fetchmailrc
-file.  Some services, such as POP3 and IMAP, have
-different well known ports defined for the SSL encrypted services.  The
-encrypted ports will be selected automatically when SSL is enabled and
-no explicit port is specified.   Also, the \-\-sslcertck command line or
-sslcertck run control file option should be used to force strict
-certificate checking with older fetchmail versions - see below.
-.PP
-If SSL is not configured, fetchmail will usually opportunistically try to use
-STARTTLS. STARTTLS can be enforced by using \-\-sslproto\~auto and
-defeated by using \-\-sslproto\~''.
-TLS connections use the same port as the unencrypted version of the
-protocol and negotiate TLS via special command. The \-\-sslcertck
-command line or sslcertck run control file option should be used to
-force strict certificate checking - see below.
-.PP
-.B \-\-sslcertck is recommended:
-When connecting to an SSL or TLS encrypted server, the
-server presents a certificate to the client for validation.  The
-certificate is checked to verify that the common name in the certificate
-matches the name of the server being contacted and that the effective
-and expiration dates in the certificate indicate that it is currently
-valid.  If any of these checks fail, a warning message is printed, but
-the connection continues.  The server certificate does not need to be
-signed by any specific Certifying Authority and may be a "self-signed"
-certificate. If the \-\-sslcertck command line option or sslcertck run
-control file option is used, fetchmail will instead abort if any of
-these checks fail, because it must assume that there is a
-man-in-the-middle attack in this scenario, hence fetchmail must not
-expose cleartext passwords. Use of the sslcertck or \-\-sslcertck option
-is therefore advised; it has become the default in fetchmail 6.4.0.
-.PP
-Some SSL encrypted servers may request a client side certificate.  A client
-side public SSL certificate and private SSL key may be specified.  If
-requested by the server, the client certificate is sent to the server for
-validation.  Some servers may require a valid client certificate and may
-refuse connections if a certificate is not provided or if the certificate
-is not valid.  Some servers may require client side certificates be signed
-by a recognized Certifying Authority.  The format for the key files and
-the certificate files is that required by the underlying SSL libraries
-(OpenSSL in the general case).
-.PP
-A word of care about the use of SSL: While above mentioned
-setup with self-signed server certificates retrieved over the wires
-can protect you from a passive eavesdropper, it doesn't help against an
-active attacker. It's clearly an improvement over sending the
-passwords in clear, but you should be aware that a man-in-the-middle
-attack is trivially possible (in particular with tools such as
-.URL "https://monkey.org/~dugsong/dsniff/" "dsniff" ,
-).  Use of strict certificate checking with a certification authority
-recognized by server and client, or perhaps of an SSH tunnel (see below
-for some examples) is preferable if you care seriously about the
-security of your mailbox and passwords.
-
 .SS ESMTP AUTH
 .PP
 \fBfetchmail\fP also supports authentication to the ESMTP server on the