Document network-security-protocol-checks better

* doc/emacs/misc.texi (Network Security): Rearrange the
network-security-protocol-checks documentation and try to explain
more what this all means and what checks are triggered.

1 files changed, 35 insertions, 22 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 692f1fd6504..96651381962 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -314,6 +314,26 @@ You can decide to register a permanent security exception for an
 unverified connection, a temporary exception, or refuse the connection
 entirely.
 
+@vindex network-security-protocol-checks
+In addition to the basic certificate corrections checks,
+several @acronym{TLS} algorithm checks are available.  Some encryption
+technologies that were previously thought to be secure have shown
+themselves to be fragile, and Emacs will (by default) warn the users
+about some of these problems.
+
+The protocol network checks is controlled via the
+@code{network-security-protocol-checks} variable.
+
+It's an alist where the first element is the name of the check,
+the second is the security level where the check kicks in, and the
+optional third element is a parameter supplied to the check.
+
+An element like @code{(rc4 medium)} will result in the function
+@code{nsm-protocol-check--rc4} being called like thus:
+@code{(nsm-protocol-check--rc4 host port status optional-parameter)}.
+The function should return non-@code{nil} if the connection should
+proceed and @code{nil} otherwise.
+
 Below is a list of the checks done on the @code{medium} level.
 
 @table @asis
@@ -353,24 +373,30 @@ connection to be encrypted.  If the connection isn't encrypted,
 @acronym{NSM} will warn you.
 
 @item Diffie-Hellman low prime bits
-When doing the public key exchange, the number of prime bits
-should be high to ensure that the channel can't be eavesdropped on by
-third parties.  If this number is too low, you will be warned.
+When doing the public key exchange, the number of prime bits should be
+high to ensure that the channel can't be eavesdropped on by third
+parties.  If this number is too low, you will be warned.  (This is the
+@code{diffie-hellman-prime-bits} check in
+@code{network-security-protocol-checks}).
 
 @item @acronym{RC4} stream cipher
 The @acronym{RC4} stream cipher is believed to be of low quality and
-may allow eavesdropping by third parties.
+may allow eavesdropping by third parties.  (This is the @code{rc4}
+check in @code{network-security-protocol-checks}).
 
 @item @acronym{SHA1} in the host certificate or in intermediate certificates
-It is believed that if an intermediate certificate uses
-the @acronym{SHA1} hashing algorithm, then third parties can issue
+It is believed that if an intermediate certificate uses the
+@acronym{SHA1} hashing algorithm, then third parties can issue
 certificates pretending to be that issuing instance.  These
 connections are therefore vulnerable to man-in-the-middle attacks.
+(These are the @code{signature-sha1} and @code{intermediate-sha1}
+checks in @code{network-security-protocol-checks}).
 
 @item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3}
 The protocols older than @acronym{TLS1.0} are believed to be
 vulnerable to a variety of attacks, and you may want to avoid using
-these if what you're doing requires higher security.
+these if what you're doing requires higher security.  (This is the
+@code{ssl} check in @code{network-security-protocol-checks}).
 
 @end table
 
@@ -381,6 +407,8 @@ will be made, in addition to the above:
 @item @acronym{3DES} cipher
 The @acronym{3DES} stream cipher provides at most 112 bits of
 effective security, which is considered to be towards the low end.
+(This is the @code{3des} check in
+@code{network-security-protocol-checks}).
 
 @item a validated certificate changes the public key
 Servers change their keys occasionally, and that is normally nothing
@@ -414,21 +442,6 @@ servers the user has connected to.  If this variable is @code{t},
 @acronym{NSM} will also save host names in the
 @code{nsm-settings-file}.
 
-@item network-security-protocol-checks
-@vindex network-security-protocol-checks
-The protocol network checks (mostly for @acronym{TLS} weaknesses) is
-controlled via the @code{network-security-protocol-checks} variable.
-
-It's an alist where the first element is the name of the check,
-the second is the security level where the check kicks in, and the
-optional third element is a parameter supplied to the check.
-
-An element like @code{(rc4 medium)} will result in the function
-@code{nsm-protocol-check--rc4} being called like thus:
-@code{(nsm-protocol-check--rc4 host port status optional-parameter)}.
-The function should return non-@code{nil} if the connection should
-proceed and @code{nil} otherwise.
-
 @end table