Merge branch 'master' of ssh://git.exim.org/home/git/exim
[exim.git] / doc / doc-txt / GnuTLS-FAQ.txt
CommitLineData
51fb80db
PP
1Using Exim 4.80+ with GnuTLS
2============================
3
4(1) I'm having problems building with GnuTLS 1, why?
5(2) What changed? Why?
6(3) I'm seeing:
7 "(gnutls_handshake): A TLS packet with unexpected length was received"
8 Why?
9(4) What's the deal with MD5?
10(5) What happened to gnutls_require_kx / gnutls_require_mac /
11 gnutls_require_protocols?
12(6) What's the deal with tls_dh_max_bits? What's DH?
13(7) What's a Priority String?
14(8) How do I use tls_require_ciphers?
15(9) How do I test STARTTLS support?
16
17
18
19(1): I'm having problems building with GnuTLS 1, why?
20-----------------------------------------------------
21
22GnuTLS's library interface has changed and Exim uses the more current
23interface. Since GnuTLS is security critical code, you should probably update
24to a supported release.
25
26If updating GnuTLS is not an option, then build Exim against OpenSSL instead.
27
28If neither is an option, then you might build Exim with the rule
29"SUPPORT_TLS=yes" commented out in "Local/Makefile", so that your Exim build
30no longer has TLS support.
31
32If you need to keep TLS support, and you can't use OpenSSL, then you'll have
33to update the GnuTLS you have installed. Sorry.
34
35We've tested the build of Exim back as far as GnuTLS 2.8.x; most development
36work is done with 2.12 and tested on 2.10 and 3.x.
37
38If you have to pick a version to upgrade to, use GnuTLS 3.x if available. The
39GnuTLS developers took advantage of the version bump to add an error code
40return value which makes debugging some problems a lot easier.
41
42
43
44(2): What changed? Why?
45------------------------
46
47The GnuTLS provider integration in Exim was overhauled, rewritten but with
48some copy/paste, because building Exim against more current releases of GnuTLS
49was issuing deprecation warnings from the compiler.
50
51When a library provider marks up the include files so that some function calls
52will cause the compiler/linker to emit deprecation warnings, it's time to pay
53serious attention. A future release might not work at all. Using the new
54APIs may mean that Exim will *stop* working with older releases of GnuTLS.
55The GnuTLS support in Exim was overhauled in Exim 4.80. In prior releases,
56Exim hard-coded a lot of algorithms and constrained what could happen. In
57Exim 4.79, we added to the hard-coded list just enough to let TLSv1.1 and
58TLSv1.2 be negotiated, but not actually support the mandatory algorithms of
59those protocol versions. When Exim's GnuTLS integration was originally
60written, there was no other choice than to make Exim responsible for a lot of
61this. In the meantime, GnuTLS has improved.
62
63With the rewrite, we started using the current API and leaving a lot more
64responsibility for TLS decisions to the library.
65
66The GnuTLS developers added "priority strings" (see Q7), which provide an
67interface exposed to the configuration file for a lot of the tuning.
68
69The GnuTLS policy is to no longer support MD5 in certificates. Exim had
70previously been immune to this policy, but no longer. See Q4.
71
72
73
74(3): I'm seeing "A TLS packet with unexpected length was received". Why?
75-------------------------------------------------------------------------
76
77The most likely reason is that the client dropped the connection during
78handshake, because their library disliked some aspect of the negotiation.
79
80In GnuTLS 2, an EOF on the connection is reported with an error code for
81packets being too large, and the above is the string returned by the library
82for that error code. In GnuTLS 3, there's a specific error code for EOF and
83the diagnostic will be less confusing.
84
85Most likely cause is an MD5 hash used in a certificate. See Q4 below.
86Alternatively, the client dislikes the size of the Diffie-Hellman prime
87offered by the server; if lowering the value of the "tls_dh_max_bits" Exim
88option fixes the problem, this was the cause. See Q6.
89
90
91
92(4): What's the deal with MD5?
93------------------------------
94
95MD5 is a hash algorithm. Hash algorithms are used to reduce a lot of data
96down to a fairly short value, which is supposed to be extremely hard to
97manipulate to get a value of someone's choosing. Signatures, used to attest
98to identity or integrity, rely upon this manipulation being effectively
99impossible, because the signature is the result of math upon the hash result.
100Without hash algorithms, signatures would be longer than the text being
101signed.
102
103MD5 was once very popular. It still is far too popular. Real world attacks
104have been proven possible against MD5. Including an attack against PKI
105(Public Key Infrastructure) certificates used for SSL/TLS. In that attack,
106the attackers got a certificate for one identity but we able to then public a
107certificate with the same signature but a different identity. This undermines
108the whole purpose of having certificates.
109
110So GnuTLS stopped trusting any certificate with an MD5-based hash used in it.
111The world has been hurriedly moving away from MD5 in certificates for a while.
112If you still have such a certificate, you should move too.
113
114If you paid someone for your certificate, they should be willing to reissue
115the certificate with a different algorithm, for no extra money. If they try
116to charge money to replace their defective product, buy from someone else
117instead. Part of the reason for paying money on a recurring basis is to cover
118the ongoing costs of proving a trust relationship, such as providing
119revocation protocols. This is just another of those ongoing costs you have
120already paid for.
121
122
123
124(5): ... gnutls_require_kx / gnutls_require_mac / gnutls_require_protocols?
125---------------------------------------------------------------------------
126
127These Exim options were used to provide fine-grained control over the TLS
128negotiation performed by GnuTLS. They required explicit protocol knowledge
129from Exim, which vastly limited what GnuTLS could do and involved the Exim
130maintainers in decisions which aren't part of their professional areas of
131expertise. The need for Exim to be able to do this went away when GnuTLS
132introduced Priority Strings (see Q7).
133
134If you were using these options before, then you're already an expert user and
135should be able to easily craft a priority string to accomplish your goals.
136Set the Exim "tls_require_ciphers" value accordingly. There is a main section
137option of this name, used for Exim receiving inbound connections, and an SMTP
138driver transport option of this name, used for Exim establishing outbound
139connections.
140
141
142
143(6): What's the deal with tls_dh_max_bits? What's DH?
144------------------------------------------------------
145
a799883d
PP
146You can avoid all of the tls_dh_max_bits issues if you leave "tls_dhparam"
147unset, so that you get one of the standard built-in primes used for DH.
148
149
51fb80db
PP
150DH, Diffie-Hellman (or Diffie-Hellman-Merkle, or something naming Williamson)
151is the common name for a way for two parties to a communication stream to
152exchange some private random data so that both end up with a shared secret
153which no evesdropper can get. It does not provide for proof of the identity
154of either party, so on its own is subject to man-in-the-middle attacks, but is
155often combined with systems which do provide such proof, improving them by
156separating the session key (the shared secret) from the long-term identity,
157and so protecting past communications from a break of the long-term identity.
158
159To do this, the server sends to the client a very large prime number; this is
160in the clear, an attacker can see it. This is not a problem; it's so not a
161problem, that there are standard named primes which applications can use, and
162which a future release of Exim will probably support.
163
164The size of the prime number affects how difficult it is to break apart the
165shared secret and decrypt the data. As time passes, the size required to
166provide protection against an adversary climbs: computers get more powerful,
167mathematical advances are made, and so on.
168
169Estimates of the size needed are published as recommendations by various
170groups; a good summary of sizes currently recommended, for various
171cryptographic primitives, is available at:
172
173 http://www.keylength.com/en/3/
174
175The GnuTLS folks think the ECRYPT II advice is good. They know far more of
176such matters than the Exim folks, we just say "er, what they said".
177
178One of the new pieces of the GnuTLS API is a means for an application to ask
179it for guidance and advice on how large some numbers should be. This is not
180entirely internal to GnuTLS since generating the numbers is slow, an
181application might want to use a standard prime, etc. So, in an attempt to get
182away from being involved in cryptographic policy, and to get rid of a
183hard-coded "1024" in Exim's source-code, we switched to asking GnuTLS how many
184bits should be in the prime number generated for use for Diffie-Hellman. To
185give back to GnuTLS for use We can ask for various sizes, and did not expose
186this to the administrator but instead just asked for "NORMAL" protection.
187Literally:
188
189 dh_bits = gnutls_sec_param_to_pk_bits(GNUTLS_PK_DH, GNUTLS_SEC_PARAM_NORMAL);
190
191This API is only available as of GnuTLS 2.12. Prior to that release, we stuck
192with the old value, for compatibility, so "1024" is still hard-coded.
193Reviewing the page above, you'll see that this is described as "Short-term
194protection against medium organizations, medium-term protection against small
195organizations."
196
197So if you are using an old release of GnuTLS, you can either add to
198Local/Makefile a different value of "EXIM_SERVER_DH_BITS_PRE2_12" or accept
199that your protection might not be adequate to your needs. We advise updating
200to a more current GnuTLS release and rebuilding Exim against that.
201
202Unfortunately, some TLS libraries have the client side bound how large a DH
203prime they will accept from the server. The larger the number, the more
204computation required to work with it and the slower that things get. So they
205pick what they believe to be reasonable upper bounds, and then typically
206forget about it for several years.
207
208Worse, in TLS the DH negotiation happens after a ciphersuite has been chosen,
209so if the client dislikes the value then a different ciphersuite avoiding DH
210can not be negotiated! The client typically drops the connection, resulting
211in errors to the user and errors in the Exim logs. With GnuTLS 3, you'll see
212the EOF (End-Of-File) error message in Exim's logs, reported as being part of
213"gnutls_handshake", but with GnuTLS 2 you'll see a log message about a packet
214with an unexpected size. Unless the client software is written intelligently
215enough to be able to adapt and reconnect forbidding DH, the client will never
216be able to negotiate TLS.
217
218This time around, we discovered that the NSS library used by various Mozilla
219products, Chrome, etc, and most particularly by the Thunderbird mail client,
220has the lowest cap. In fact, prior to recent updates, their upper limit was
221lower than the value returned by GnuTLS for "NORMAL". The most recent NSS
222library release raises this, but the most recent Thunderbird release still has
223the old limit.
224
225So Exim had to get involved in cryptography policy decisions again. We added
226the "tls_dh_max_bits" global option, to set a number used in both OpenSSL and
227GnuTLS bindings for Exim. In GnuTLS, it clamps the value returned by
228gnutls_sec_param_to_pk_bits(), so that if the returned value is larger than
229tls_dh_max_bits then tls_dh_max_bits would be used instead.
230
231Our policy decision was to default the value of tls_dh_max_bits to the maximum
232supported in the most recent Thunderbird release, and to make this an
233administrator-available option so that administrators can choose to trade off
234security versus compatibility by raising it.
235
236A future release of Exim may even let the administrator tell GnuTLS to ask for
237more or less than "NORMAL".
238
201f5254
PP
239To add to the fun, the size of the prime returned by GnuTLS when we call
240gnutls_dh_params_generate2() is not limited to be the requested size. GnuTLS
241has a tendency to overshoot. 2237 bit primes are common when 2236 is
242requested, and higher still have been observed. Further, there is no API to
243ask how large the prime bundled up inside the parameter is; the most we can do
244is ask how large the DH prime used in an active TLS session is. Since we're
245not able to use GnuTLS API calls (and exporting to PKCS3 and then calling
246OpenSSL routines would be undiplomatic, plus add a library dependency), we're
247left with no way to actually know the size of the freshly generated DH prime.
248
249Thus we check if the the value returned is at least 10 more than the minimum
250we'll accept as a client (EXIM_CLIENT_DH_MIN_BITS, see below, defaults to
bba74fc6 2511024) and if it is, we subtract 10. Then we reluctantly deploy a strategy
201f5254
PP
252called "hope". This is not guaranteed to be successful; in the first code
253pass on this logic, we subtracted 3, asked for 2233 bits and got 2240 in the
254first test.
255
256If you see Thunderbird clients still failing, then as a user who can see into
257Exim's spool directory, run:
258
259$ openssl dhparam -noout -text -in /path/to/spool/gnutls-params-2236 | head
260
261Ideally, the first line will read "PKCS#3 DH Parameters: (2236 bit)". If the
262count is more than 2236, then remove the file and let Exim regenerate it, or
263generate one yourself and move it into place. Ideally use "openssl dhparam"
264to generate it, and then wait a very long time; at least this way, the size
a799883d
PP
265will be correct.
266
267The use of "hope" as a strategy was felt to be unacceptable as a default, so
268late in the RC series for 4.80, the whole issue was side-stepped. The primes
269used for DH are publicly revealed; moreover, there are selection criteria for
270what makes a "good" DH prime. As it happens, there are *standard* primes
271which can be used, and are specified to be used for certain protocols. So
272these primes were built into Exim, and by default exim now uses a 2048 bit
273prime from section 2.2 of RFC 5114.
201f5254
PP
274
275
51fb80db
PP
276A TLS client does not get to choose the DH prime used, but can choose a
277minimum acceptable value. For Exim, this is a compile-time constant called
bba74fc6 278"EXIM_CLIENT_DH_MIN_BITS" of 1024, which can be overruled in "Local/Makefile".
51fb80db
PP
279
280
281
282(7): What's a Priority String?
283------------------------------
284
285A priority string is a way for a user of GnuTLS to tell GnuTLS how it should
286make decisions about what to do in TLS; it includes which algorithms to make
287available for various roles, what compatibility trade-offs to make, which
288features to enable or disable.
289
290It is exposed to the Mail Administrator in Exim's configuration file as the
291"tls_require_ciphers" option, which exists as a main section option for use in
292Exim as a server, accepting connections, and as an option on Transports using
293the SMTP driver, for use in Exim as a client. The main section option is
294*not* the default for the transport option, they are entirely independent.
295For both, the default value used by Exim is the string "NORMAL". (This is not
296the same NORMAL as for DH prime bit size selection in Q6, but a different
297NORMAL.) See Q8.
298
299The current documentation, for the most recent release of GnuTLS, is available
300online at:
301
302 http://www.gnu.org/software/gnutls/manual/html_node/Priority-Strings.html
303
304Beware that if you are not using the most recent GnuTLS release then this
305documentation will be wrong for you! You should find the "info" documentation
306which came with GnuTLS to review the available options. It's under "The TLS
307Handshake Protocol".
308
309$ pinfo --node="Priority Strings" gnutls
310
311(This author is unable to persuade the "info" command-line tool to jump
312straight to the required node, but "pinfo" works.)
313
314To trade off some security for more compatibility, you might set a value of
315"NORMAL:%COMPAT". See the documentation for more, including lowering security
316even further for more security, forcing clients to use the server's protocol
317suite, and ways to force selection of particular algorithms.
318
319
320
321(8): How do I use tls_require_ciphers?
322--------------------------------------
323
324This is the name of two options in Exim. One is a main section option, used
325by Exim as a server when a client initiates SSL/TLS negotiation, the other is
326an option on transports which use "driver = smtp", used when Exim initiates
327SSL/TLS as a client talking to a remote server.
328
329The option is expanded and so can take advantage of any variables which have
330been set. This includes the IP address of the remote side, the port upon
331which a connection was accepted (when a server), and more. Currently it does
332not have access to $tls_sni, whether as a client or as a server.
333
334This example, for the main section's option, will let the library defaults be
335permitted on the MX port, where there's probably no identity verification
336anyway, and lowers security further by increasing compatibility; but this ups
337the ante on the submission ports where the administrator might have some
338influence on the choice of clients used:
339
340tls_require_ciphers = ${if =={$received_port}{25}\
341 {NORMAL:%COMPAT}\
342 {SECURE128}}
343
344Note that during Exim start-up, when this option is sanity-checked, there will
345be no value of $received_port. In the above example, the checked value will
346thus be "SECURE128". Be careful to ensure that it always expands safely.
347
348
349
350(9): How do I test STARTTLS support?
351------------------------------------
352
353The best command-line client for debugging specifically SSL/TLS which this
354author has encountered is part of the GnuTLS suite, and is called
355"gnutls-cli". It's best because it's the only interactive tool which lets the
356user start TLS handshake exactly when they wish, so can choose to use the
357STARTTLS command.
358
359$ gnutls-cli --starttls --crlf --port 587 mail.example.org
360
361After EHLO, to see the capabilities, enter STARTTLS, wait for the response,
362then send EOF. Typically that's done by typing Ctrl-D at the start of a line.
363The "gnutls-cli" tool will take over, set up TLS (or fail) and by the time it
364returns to await more user input, you're using a secure connection and should
365type your second EHLO.
366
367The "--x509cafile" option may be helpful for checking certificates and
368"--priority" to pass a priority string to the client tool for configuring it.
369
370The --crlf is for strict protocol correctness, but Exim doesn't really need
371it, so "gnutls-cli -s -p 587 mail.example.org" is shorter.
372
373
374For debugging SMTP as a whole, we recommend swaks, "Swiss Army Knife SMTP", by
375John Jetmore (one of the Exim Maintainers). This has some TLS tuning options;
376it can be found at:
377
378 http://www.jetmore.org/john/code/swaks/
379
380
381For OpenSSL, the "openssl s_client" command helps; you can either set up Exim
382with a listening port which is SSL-on-connect or tell s_client to use
383STARTTLS.
384
385For the former, use the "tls_on_connect_ports" option and the
386"daemon_smtp_ports" option. Most clients for SSL-on-connect use the port
387which was briefly registered with IANA for this purpose, 465. So you would
388set something like:
389
390 daemon_smtp_ports = 25 : 465 : 587
391 tls_on_connect_ports = 465
392
393To use s_client with STARTTLS support, use "-starttls smtp" on the
394command-line. Beware that older versions of OpenSSL did not wait for the SMTP
395banner before sending EHLO, which will fall afoul of the protocol
396synchronisation checks in Exim (used to trip up pump-and-dump spammers); also
397you will not get control of the session until TLS is established. That said,
398this tool provides more tuning hooks for adjusting how TLS will be set up than
399most.
400
401*BEWARE* that by default, s_client will take any line starting with a capital
402letter "R" to be a request to initiate TLS renegotiation with the server and
403the line will not be sent. This may trip up "RCPT TO:<someone@example.org>"
404lines in SMTP. SMTP is not case-sensitive, so type "rcpt to" instead.
405Alternatively, invoke s_client with the "-ign_eof" option to disable this
406R-filtering and a few other features.
407
408
409# END OF FAQ