Fix build with DISABLE_EVENT (proper spelling)

[exim.git] / doc / doc-txt / GnuTLS-FAQ.txt

diff --git a/doc/doc-txt/GnuTLS-FAQ.txt b/doc/doc-txt/GnuTLS-FAQ.txt
index 60f40200478a72cb1059216ae7626fd2c786b706..ab4e5aaa6a88e549304923d5d75c2a271feef939 100644 (file)
--- a/doc/doc-txt/GnuTLS-FAQ.txt
+++ b/doc/doc-txt/GnuTLS-FAQ.txt
@@ -6,7 +6,7 @@ Using Exim 4.80+ with GnuTLS
 (3) I'm seeing:
     "(gnutls_handshake): A TLS packet with unexpected length was received"
     Why?
 (3) I'm seeing:
     "(gnutls_handshake): A TLS packet with unexpected length was received"
     Why?

-(4) What's the deal with MD5?
+(4) What's the deal with MD5?  (And SHA-1?)

 (5) What happened to gnutls_require_kx / gnutls_require_mac /
     gnutls_require_protocols?
 (6) What's the deal with tls_dh_max_bits?  What's DH?
 (5) What happened to gnutls_require_kx / gnutls_require_mac /
     gnutls_require_protocols?
 (6) What's the deal with tls_dh_max_bits?  What's DH?


@@ -89,8 +89,8 @@ option fixes the problem, this was the cause.  See Q6.
 
 
 
 
 
 

-(4): What's the deal with MD5?
-------------------------------
+(4): What's the deal with MD5?  (And SHA-1?)
+--------------------------------------------

 
 MD5 is a hash algorithm.  Hash algorithms are used to reduce a lot of data
 down to a fairly short value, which is supposed to be extremely hard to
 
 MD5 is a hash algorithm.  Hash algorithms are used to reduce a lot of data
 down to a fairly short value, which is supposed to be extremely hard to


@@ -103,9 +103,9 @@ signed.
 MD5 was once very popular.  It still is far too popular.  Real world attacks
 have been proven possible against MD5.  Including an attack against PKI
 (Public Key Infrastructure) certificates used for SSL/TLS.  In that attack,
 MD5 was once very popular.  It still is far too popular.  Real world attacks
 have been proven possible against MD5.  Including an attack against PKI
 (Public Key Infrastructure) certificates used for SSL/TLS.  In that attack,

-the attackers got a certificate for one identity but we able to then public a
-certificate with the same signature but a different identity.  This undermines
-the whole purpose of having certificates.
+the attackers got a certificate for one identity but were able to then publish
+a certificate with the same signature but a different identity.  This
+undermines the whole purpose of having certificates.

 
 So GnuTLS stopped trusting any certificate with an MD5-based hash used in it.
 The world has been hurriedly moving away from MD5 in certificates for a while.
 
 So GnuTLS stopped trusting any certificate with an MD5-based hash used in it.
 The world has been hurriedly moving away from MD5 in certificates for a while.


@@ -119,6 +119,10 @@ the ongoing costs of proving a trust relationship, such as providing
 revocation protocols.  This is just another of those ongoing costs you have
 already paid for.
 
 revocation protocols.  This is just another of those ongoing costs you have
 already paid for.
 

+The same has happened to SHA-1: there are real-world collision attacks against
+SHA-1, so SHA-1 is mostly defunct in certificates.  GnuTLS no longer supports
+its use in TLS certificates.
+

 
 
 (5): ... gnutls_require_kx / gnutls_require_mac / gnutls_require_protocols?
 
 
 (5): ... gnutls_require_kx / gnutls_require_mac / gnutls_require_protocols?


@@ -143,10 +147,14 @@ connections.
 (6): What's the deal with tls_dh_max_bits?  What's DH?
 ------------------------------------------------------
 
 (6): What's the deal with tls_dh_max_bits?  What's DH?
 ------------------------------------------------------
 

+You can avoid all of the tls_dh_max_bits issues if you leave "tls_dhparam"
+unset, so that you get one of the standard built-in primes used for DH.
+
+

 DH, Diffie-Hellman (or Diffie-Hellman-Merkle, or something naming Williamson)
 is the common name for a way for two parties to a communication stream to
 exchange some private random data so that both end up with a shared secret
 DH, Diffie-Hellman (or Diffie-Hellman-Merkle, or something naming Williamson)
 is the common name for a way for two parties to a communication stream to
 exchange some private random data so that both end up with a shared secret

-which no evesdropper can get.  It does not provide for proof of the identity
+which no eavesdropper can get.  It does not provide for proof of the identity

 of either party, so on its own is subject to man-in-the-middle attacks, but is
 often combined with systems which do provide such proof, improving them by
 separating the session key (the shared secret) from the long-term identity,
 of either party, so on its own is subject to man-in-the-middle attacks, but is
 often combined with systems which do provide such proof, improving them by
 separating the session key (the shared secret) from the long-term identity,


@@ -155,7 +163,7 @@ and so protecting past communications from a break of the long-term identity.
 To do this, the server sends to the client a very large prime number; this is
 in the clear, an attacker can see it.  This is not a problem; it's so not a
 problem, that there are standard named primes which applications can use, and
 To do this, the server sends to the client a very large prime number; this is
 in the clear, an attacker can see it.  This is not a problem; it's so not a
 problem, that there are standard named primes which applications can use, and

-which a future release of Exim will probably support.
+which Exim now supports.

 
 The size of the prime number affects how difficult it is to break apart the
 shared secret and decrypt the data.  As time passes, the size required to
 
 The size of the prime number affects how difficult it is to break apart the
 shared secret and decrypt the data.  As time passes, the size required to


@@ -173,13 +181,14 @@ such matters than the Exim folks, we just say "er, what they said".
 
 One of the new pieces of the GnuTLS API is a means for an application to ask
 it for guidance and advice on how large some numbers should be.  This is not
 
 One of the new pieces of the GnuTLS API is a means for an application to ask
 it for guidance and advice on how large some numbers should be.  This is not

-entirely internal to GnuTLS since generating the numbers is slow, an
+entirely internal to GnuTLS, since generating the numbers is slow, an

 application might want to use a standard prime, etc.  So, in an attempt to get
 away from being involved in cryptographic policy, and to get rid of a
 hard-coded "1024" in Exim's source-code, we switched to asking GnuTLS how many
 application might want to use a standard prime, etc.  So, in an attempt to get
 away from being involved in cryptographic policy, and to get rid of a
 hard-coded "1024" in Exim's source-code, we switched to asking GnuTLS how many

-bits should be in the prime number generated for use for Diffie-Hellman.  To
-give back to GnuTLS for use  We can ask for various sizes, and did not expose
-this to the administrator but instead just asked for "NORMAL" protection.
+bits should be in the prime number generated for use for Diffie-Hellman.  We
+then give this number straight back to GnuTLS when generating a DH prime.
+We can ask for various sizes, and did not expose this to the administrator but
+instead just asked for "NORMAL" protection.

 Literally:
 
  dh_bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH, GNUTLS_SEC_PARAM_NORMAL);
 Literally:
 
  dh_bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH, GNUTLS_SEC_PARAM_NORMAL);


@@ -232,6 +241,43 @@ security versus compatibility by raising it.
 A future release of Exim may even let the administrator tell GnuTLS to ask for
 more or less than "NORMAL".
 
 A future release of Exim may even let the administrator tell GnuTLS to ask for
 more or less than "NORMAL".
 

+To add to the fun, the size of the prime returned by GnuTLS when we call
+gnutls_dh_params_generate2() is not limited to be the requested size.  GnuTLS
+has a tendency to overshoot.  2237 bit primes are common when 2236 is
+requested, and higher still have been observed.  Further, there is no API to
+ask how large the prime bundled up inside the parameter is; the most we can do
+is ask how large the DH prime used in an active TLS session is.  Since we're
+not able to use GnuTLS API calls (and exporting to PKCS3 and then calling
+OpenSSL routines would be undiplomatic, plus add a library dependency), we're
+left with no way to actually know the size of the freshly generated DH prime.
+
+Thus we check if the the value returned is at least 10 more than the minimum
+we'll accept as a client (EXIM_CLIENT_DH_MIN_BITS, see below, defaults to
+1024) and if it is, we subtract 10.  Then we reluctantly deploy a strategy
+called "hope".  This is not guaranteed to be successful; in the first code
+pass on this logic, we subtracted 3, asked for 2233 bits and got 2240 in the
+first test.
+
+If you see Thunderbird clients still failing, then as a user who can see into
+Exim's spool directory, run:
+
+$ openssl dhparam -noout -text -in /path/to/spool/gnutls-params-2236 | head
+
+Ideally, the first line will read "PKCS#3 DH Parameters: (2236 bit)".  If the
+count is more than 2236, then remove the file and let Exim regenerate it, or
+generate one yourself and move it into place.  Ideally use "openssl dhparam"
+to generate it, and then wait a very long time; at least this way, the size
+will be correct.
+
+The use of "hope" as a strategy was felt to be unacceptable as a default, so
+late in the RC series for 4.80, the whole issue was side-stepped.  The primes
+used for DH are publicly revealed; moreover, there are selection criteria for
+what makes a "good" DH prime.  As it happens, there are *standard* primes
+which can be used, and are specified to be used for certain protocols.  So
+these primes were built into Exim, and by default exim now uses a 2048 bit
+prime from section 2.2 of RFC 5114.
+
+

 A TLS client does not get to choose the DH prime used, but can choose a
 minimum acceptable value.  For Exim, this is a compile-time constant called
 "EXIM_CLIENT_DH_MIN_BITS" of 1024, which can be overruled in "Local/Makefile".
 A TLS client does not get to choose the DH prime used, but can choose a
 minimum acceptable value.  For Exim, this is a compile-time constant called
 "EXIM_CLIENT_DH_MIN_BITS" of 1024, which can be overruled in "Local/Makefile".


@@ -258,7 +304,7 @@ NORMAL.)  See Q8.
 The current documentation, for the most recent release of GnuTLS, is available
 online at:
 
 The current documentation, for the most recent release of GnuTLS, is available
 online at:
 

-  http://www.gnu.org/software/gnutls/manual/html_node/Priority-Strings.html
+  http://www.gnutls.org/manual/html_node/Priority-Strings.html

 
 Beware that if you are not using the most recent GnuTLS release then this
 documentation will be wrong for you!  You should find the "info" documentation
 
 Beware that if you are not using the most recent GnuTLS release then this
 documentation will be wrong for you!  You should find the "info" documentation