[Emacs-diffs] master 1dc4d09 2/2: Document network-security-protocol-checks better

[Lars Ingebrigtsen]

branch: master
commit 1dc4d0909349121699bf5c623004c0edb481e9b6
Author: Lars Ingebrigtsen <address@hidden>
Commit: Lars Ingebrigtsen <address@hidden>

    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.
---
 doc/emacs/misc.texi | 57 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 35 insertions(+), 22 deletions(-)

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index 692f1fd..9665138 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.
 
address@hidden 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
address@hidden 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
address@hidden being called like thus:
address@hidden(nsm-protocol-check--rc4 host port status optional-parameter)}.
+The function should return address@hidden 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
address@hidden check in
address@hidden).
 
 @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
address@hidden 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
address@hidden 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
address@hidden).
 
 @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}.
 
address@hidden network-security-protocol-checks
address@hidden 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
address@hidden being called like thus:
address@hidden(nsm-protocol-check--rc4 host port status optional-parameter)}.
-The function should return address@hidden if the connection should
-proceed and @code{nil} otherwise.
-
 @end table