| 1 | From time to time, experimental features may be added to Exim. |
| 2 | While a feature is experimental, there will be a build-time |
| 3 | option whose name starts "EXPERIMENTAL_" that must be set in |
| 4 | order to include the feature. This file contains information |
| 5 | about experimental features, all of which are unstable and |
| 6 | liable to incompatible change. |
| 7 | |
| 8 | |
| 9 | Brightmail AntiSpam (BMI) suppport |
| 10 | -------------------------------------------------------------- |
| 11 | |
| 12 | Brightmail AntiSpam is a commercial package. Please see |
| 13 | http://www.brightmail.com for more information on |
| 14 | the product. For the sake of clarity, we'll refer to it as |
| 15 | "BMI" from now on. |
| 16 | |
| 17 | |
| 18 | 0) BMI concept and implementation overview |
| 19 | |
| 20 | In contrast to how spam-scanning with SpamAssassin is |
| 21 | implemented in exiscan-acl, BMI is more suited for per |
| 22 | -recipient scanning of messages. However, each messages is |
| 23 | scanned only once, but multiple "verdicts" for multiple |
| 24 | recipients can be returned from the BMI server. The exiscan |
| 25 | implementation passes the message to the BMI server just |
| 26 | before accepting it. It then adds the retrieved verdicts to |
| 27 | the messages header file in the spool. These verdicts can then |
| 28 | be queried in routers, where operation is per-recipient |
| 29 | instead of per-message. To use BMI, you need to take the |
| 30 | following steps: |
| 31 | |
| 32 | 1) Compile Exim with BMI support |
| 33 | 2) Set up main BMI options (top section of Exim config file) |
| 34 | 3) Set up ACL control statement (ACL section of the config |
| 35 | file) |
| 36 | 4) Set up your routers to use BMI verdicts (routers section |
| 37 | of the config file). |
| 38 | 5) (Optional) Set up per-recipient opt-in information. |
| 39 | |
| 40 | These four steps are explained in more details below. |
| 41 | |
| 42 | 1) Adding support for BMI at compile time |
| 43 | |
| 44 | To compile with BMI support, you need to link Exim against |
| 45 | the Brighmail client SDK, consisting of a library |
| 46 | (libbmiclient_single.so) and a header file (bmi_api.h). |
| 47 | You'll also need to explicitly set a flag in the Makefile to |
| 48 | include BMI support in the Exim binary. Both can be achieved |
| 49 | with these lines in Local/Makefile: |
| 50 | |
| 51 | EXPERIMENTAL_BRIGHTMAIL=yes |
| 52 | CFLAGS=-I/path/to/the/dir/with/the/includefile |
| 53 | EXTRALIBS_EXIM=-L/path/to/the/dir/with/the/library -lbmiclient_single |
| 54 | |
| 55 | If you use other CFLAGS or EXTRALIBS_EXIM settings then |
| 56 | merge the content of these lines with them. |
| 57 | |
| 58 | Note for BMI6.x users: You'll also have to add -lxml2_single |
| 59 | to the EXTRALIBS_EXIM line. Users of 5.5x do not need to do |
| 60 | this. |
| 61 | |
| 62 | You should also include the location of |
| 63 | libbmiclient_single.so in your dynamic linker configuration |
| 64 | file (usually /etc/ld.so.conf) and run "ldconfig" |
| 65 | afterwards, or else the produced Exim binary will not be |
| 66 | able to find the library file. |
| 67 | |
| 68 | |
| 69 | 2) Setting up BMI support in the Exim main configuration |
| 70 | |
| 71 | To enable BMI support in the main Exim configuration, you |
| 72 | should set the path to the main BMI configuration file with |
| 73 | the "bmi_config_file" option, like this: |
| 74 | |
| 75 | bmi_config_file = /opt/brightmail/etc/brightmail.cfg |
| 76 | |
| 77 | This must go into section 1 of Exim's configuration file (You |
| 78 | can put it right on top). If you omit this option, it |
| 79 | defaults to /opt/brightmail/etc/brightmail.cfg. |
| 80 | |
| 81 | Note for BMI6.x users: This file is in XML format in V6.xx |
| 82 | and its name is /opt/brightmail/etc/bmiconfig.xml. So BMI |
| 83 | 6.x users MUST set the bmi_config_file option. |
| 84 | |
| 85 | |
| 86 | 3) Set up ACL control statement |
| 87 | |
| 88 | To optimize performance, it makes sense only to process |
| 89 | messages coming from remote, untrusted sources with the BMI |
| 90 | server. To set up a messages for processing by the BMI |
| 91 | server, you MUST set the "bmi_run" control statement in any |
| 92 | ACL for an incoming message. You will typically do this in |
| 93 | an "accept" block in the "acl_check_rcpt" ACL. You should |
| 94 | use the "accept" block(s) that accept messages from remote |
| 95 | servers for your own domain(s). Here is an example that uses |
| 96 | the "accept" blocks from Exim's default configuration file: |
| 97 | |
| 98 | |
| 99 | accept domains = +local_domains |
| 100 | endpass |
| 101 | verify = recipient |
| 102 | control = bmi_run |
| 103 | |
| 104 | accept domains = +relay_to_domains |
| 105 | endpass |
| 106 | verify = recipient |
| 107 | control = bmi_run |
| 108 | |
| 109 | If bmi_run is not set in any ACL during reception of the |
| 110 | message, it will NOT be passed to the BMI server. |
| 111 | |
| 112 | |
| 113 | 4) Setting up routers to use BMI verdicts |
| 114 | |
| 115 | When a message has been run through the BMI server, one or |
| 116 | more "verdicts" are present. Different recipients can have |
| 117 | different verdicts. Each recipient is treated individually |
| 118 | during routing, so you can query the verdicts by recipient |
| 119 | at that stage. From Exim's view, a verdict can have the |
| 120 | following outcomes: |
| 121 | |
| 122 | o deliver the message normally |
| 123 | o deliver the message to an alternate location |
| 124 | o do not deliver the message |
| 125 | |
| 126 | To query the verdict for a recipient, the implementation |
| 127 | offers the following tools: |
| 128 | |
| 129 | |
| 130 | - Boolean router preconditions. These can be used in any |
| 131 | router. For a simple implementation of BMI, these may be |
| 132 | all that you need. The following preconditions are |
| 133 | available: |
| 134 | |
| 135 | o bmi_deliver_default |
| 136 | |
| 137 | This precondition is TRUE if the verdict for the |
| 138 | recipient is to deliver the message normally. If the |
| 139 | message has not been processed by the BMI server, this |
| 140 | variable defaults to TRUE. |
| 141 | |
| 142 | o bmi_deliver_alternate |
| 143 | |
| 144 | This precondition is TRUE if the verdict for the |
| 145 | recipient is to deliver the message to an alternate |
| 146 | location. You can get the location string from the |
| 147 | $bmi_alt_location expansion variable if you need it. See |
| 148 | further below. If the message has not been processed by |
| 149 | the BMI server, this variable defaults to FALSE. |
| 150 | |
| 151 | o bmi_dont_deliver |
| 152 | |
| 153 | This precondition is TRUE if the verdict for the |
| 154 | recipient is NOT to deliver the message to the |
| 155 | recipient. You will typically use this precondition in a |
| 156 | top-level blackhole router, like this: |
| 157 | |
| 158 | # don't deliver messages handled by the BMI server |
| 159 | bmi_blackhole: |
| 160 | driver = redirect |
| 161 | bmi_dont_deliver |
| 162 | data = :blackhole: |
| 163 | |
| 164 | This router should be on top of all others, so messages |
| 165 | that should not be delivered do not reach other routers |
| 166 | at all. If the message has not been processed by |
| 167 | the BMI server, this variable defaults to FALSE. |
| 168 | |
| 169 | |
| 170 | - A list router precondition to query if rules "fired" on |
| 171 | the message for the recipient. Its name is "bmi_rule". You |
| 172 | use it by passing it a colon-separated list of rule |
| 173 | numbers. You can use this condition to route messages that |
| 174 | matched specific rules. Here is an example: |
| 175 | |
| 176 | # special router for BMI rule #5, #8 and #11 |
| 177 | bmi_rule_redirect: |
| 178 | driver = redirect |
| 179 | bmi_rule = 5:8:11 |
| 180 | data = postmaster@mydomain.com |
| 181 | |
| 182 | |
| 183 | - Expansion variables. Several expansion variables are set |
| 184 | during routing. You can use them in custom router |
| 185 | conditions, for example. The following variables are |
| 186 | available: |
| 187 | |
| 188 | o $bmi_base64_verdict |
| 189 | |
| 190 | This variable will contain the BASE64 encoded verdict |
| 191 | for the recipient being routed. You can use it to add a |
| 192 | header to messages for tracking purposes, for example: |
| 193 | |
| 194 | localuser: |
| 195 | driver = accept |
| 196 | check_local_user |
| 197 | headers_add = X-Brightmail-Verdict: $bmi_base64_verdict |
| 198 | transport = local_delivery |
| 199 | |
| 200 | If there is no verdict available for the recipient being |
| 201 | routed, this variable contains the empty string. |
| 202 | |
| 203 | o $bmi_base64_tracker_verdict |
| 204 | |
| 205 | This variable will contain a BASE64 encoded subset of |
| 206 | the verdict information concerning the "rules" that |
| 207 | fired on the message. You can add this string to a |
| 208 | header, commonly named "X-Brightmail-Tracker". Example: |
| 209 | |
| 210 | localuser: |
| 211 | driver = accept |
| 212 | check_local_user |
| 213 | headers_add = X-Brightmail-Tracker: $bmi_base64_tracker_verdict |
| 214 | transport = local_delivery |
| 215 | |
| 216 | If there is no verdict available for the recipient being |
| 217 | routed, this variable contains the empty string. |
| 218 | |
| 219 | o $bmi_alt_location |
| 220 | |
| 221 | If the verdict is to redirect the message to an |
| 222 | alternate location, this variable will contain the |
| 223 | alternate location string returned by the BMI server. In |
| 224 | its default configuration, this is a header-like string |
| 225 | that can be added to the message with "headers_add". If |
| 226 | there is no verdict available for the recipient being |
| 227 | routed, or if the message is to be delivered normally, |
| 228 | this variable contains the empty string. |
| 229 | |
| 230 | o $bmi_deliver |
| 231 | |
| 232 | This is an additional integer variable that can be used |
| 233 | to query if the message should be delivered at all. You |
| 234 | should use router preconditions instead if possible. |
| 235 | |
| 236 | $bmi_deliver is '0': the message should NOT be delivered. |
| 237 | $bmi_deliver is '1': the message should be delivered. |
| 238 | |
| 239 | |
| 240 | IMPORTANT NOTE: Verdict inheritance. |
| 241 | The message is passed to the BMI server during message |
| 242 | reception, using the target addresses from the RCPT TO: |
| 243 | commands in the SMTP transaction. If recipients get expanded |
| 244 | or re-written (for example by aliasing), the new address(es) |
| 245 | inherit the verdict from the original address. This means |
| 246 | that verdicts also apply to all "child" addresses generated |
| 247 | from top-level addresses that were sent to the BMI server. |
| 248 | |
| 249 | |
| 250 | 5) Using per-recipient opt-in information (Optional) |
| 251 | |
| 252 | The BMI server features multiple scanning "profiles" for |
| 253 | individual recipients. These are usually stored in a LDAP |
| 254 | server and are queried by the BMI server itself. However, |
| 255 | you can also pass opt-in data for each recipient from the |
| 256 | MTA to the BMI server. This is particularly useful if you |
| 257 | already look up recipient data in Exim anyway (which can |
| 258 | also be stored in a SQL database or other source). This |
| 259 | implementation enables you to pass opt-in data to the BMI |
| 260 | server in the RCPT ACL. This works by setting the |
| 261 | 'bmi_optin' modifier in a block of that ACL. If should be |
| 262 | set to a list of comma-separated strings that identify the |
| 263 | features which the BMI server should use for that particular |
| 264 | recipient. Ideally, you would use the 'bmi_optin' modifier |
| 265 | in the same ACL block where you set the 'bmi_run' control |
| 266 | flag. Here is an example that will pull opt-in data for each |
| 267 | recipient from a flat file called |
| 268 | '/etc/exim/bmi_optin_data'. |
| 269 | |
| 270 | The file format: |
| 271 | |
| 272 | user1@mydomain.com: <OPTIN STRING1>:<OPTIN STRING2> |
| 273 | user2@thatdomain.com: <OPTIN STRING3> |
| 274 | |
| 275 | |
| 276 | The example: |
| 277 | |
| 278 | accept domains = +relay_to_domains |
| 279 | endpass |
| 280 | verify = recipient |
| 281 | bmi_optin = ${lookup{$local_part@$domain}lsearch{/etc/exim/bmi_optin_data}} |
| 282 | control = bmi_run |
| 283 | |
| 284 | Of course, you can also use any other lookup method that |
| 285 | Exim supports, including LDAP, Postgres, MySQL, Oracle etc., |
| 286 | as long as the result is a list of colon-separated opt-in |
| 287 | strings. |
| 288 | |
| 289 | For a list of available opt-in strings, please contact your |
| 290 | Brightmail representative. |
| 291 | |
| 292 | |
| 293 | |
| 294 | |
| 295 | Sender Policy Framework (SPF) support |
| 296 | -------------------------------------------------------------- |
| 297 | |
| 298 | To learn more about SPF, visit http://www.openspf.org. This |
| 299 | document does not explain the SPF fundamentals, you should |
| 300 | read and understand the implications of deploying SPF on your |
| 301 | system before doing so. |
| 302 | |
| 303 | SPF support is added via the libspf2 library. Visit |
| 304 | |
| 305 | http://www.libspf2.org/ |
| 306 | |
| 307 | to obtain a copy, then compile and install it. By default, |
| 308 | this will put headers in /usr/local/include and the static |
| 309 | library in /usr/local/lib. |
| 310 | |
| 311 | To compile Exim with SPF support, set these additional flags in |
| 312 | Local/Makefile: |
| 313 | |
| 314 | EXPERIMENTAL_SPF=yes |
| 315 | CFLAGS=-DSPF -I/usr/local/include |
| 316 | EXTRALIBS_EXIM=-L/usr/local/lib -lspf2 |
| 317 | |
| 318 | This assumes that the libspf2 files are installed in |
| 319 | their default locations. |
| 320 | |
| 321 | You can now run SPF checks in incoming SMTP by using the "spf" |
| 322 | ACL condition in either the MAIL, RCPT or DATA ACLs. When |
| 323 | using it in the RCPT ACL, you can make the checks dependent on |
| 324 | the RCPT address (or domain), so you can check SPF records |
| 325 | only for certain target domains. This gives you the |
| 326 | possibility to opt-out certain customers that do not want |
| 327 | their mail to be subject to SPF checking. |
| 328 | |
| 329 | The spf condition takes a list of strings on its right-hand |
| 330 | side. These strings describe the outcome of the SPF check for |
| 331 | which the spf condition should succeed. Valid strings are: |
| 332 | |
| 333 | o pass The SPF check passed, the sending host |
| 334 | is positively verified by SPF. |
| 335 | o fail The SPF check failed, the sending host |
| 336 | is NOT allowed to send mail for the domain |
| 337 | in the envelope-from address. |
| 338 | o softfail The SPF check failed, but the queried |
| 339 | domain can't absolutely confirm that this |
| 340 | is a forgery. |
| 341 | o none The queried domain does not publish SPF |
| 342 | records. |
| 343 | o neutral The SPF check returned a "neutral" state. |
| 344 | This means the queried domain has published |
| 345 | a SPF record, but wants to allow outside |
| 346 | servers to send mail under its domain as well. |
| 347 | This should be treated like "none". |
| 348 | o permerror This indicates a syntax error in the SPF |
| 349 | record of the queried domain. You may deny |
| 350 | messages when this occurs. (Changed in 4.83) |
| 351 | o temperror This indicates a temporary error during all |
| 352 | processing, including Exim's SPF processing. |
| 353 | You may defer messages when this occurs. |
| 354 | (Changed in 4.83) |
| 355 | o err_temp Same as permerror, deprecated in 4.83, will be |
| 356 | removed in a future release. |
| 357 | o err_perm Same as temperror, deprecated in 4.83, will be |
| 358 | removed in a future release. |
| 359 | |
| 360 | You can prefix each string with an exclamation mark to invert |
| 361 | its meaning, for example "!fail" will match all results but |
| 362 | "fail". The string list is evaluated left-to-right, in a |
| 363 | short-circuit fashion. When a string matches the outcome of |
| 364 | the SPF check, the condition succeeds. If none of the listed |
| 365 | strings matches the outcome of the SPF check, the condition |
| 366 | fails. |
| 367 | |
| 368 | Here is an example to fail forgery attempts from domains that |
| 369 | publish SPF records: |
| 370 | |
| 371 | /* ----------------- |
| 372 | deny message = $sender_host_address is not allowed to send mail from ${if def:sender_address_domain {$sender_address_domain}{$sender_helo_name}}. \ |
| 373 | Please see http://www.openspf.org/Why?scope=${if def:sender_address_domain {mfrom}{helo}};identity=${if def:sender_address_domain {$sender_address}{$sender_helo_name}};ip=$sender_host_address |
| 374 | spf = fail |
| 375 | --------------------- */ |
| 376 | |
| 377 | You can also give special treatment to specific domains: |
| 378 | |
| 379 | /* ----------------- |
| 380 | deny message = AOL sender, but not from AOL-approved relay. |
| 381 | sender_domains = aol.com |
| 382 | spf = fail:neutral |
| 383 | --------------------- */ |
| 384 | |
| 385 | Explanation: AOL publishes SPF records, but is liberal and |
| 386 | still allows non-approved relays to send mail from aol.com. |
| 387 | This will result in a "neutral" state, while mail from genuine |
| 388 | AOL servers will result in "pass". The example above takes |
| 389 | this into account and treats "neutral" like "fail", but only |
| 390 | for aol.com. Please note that this violates the SPF draft. |
| 391 | |
| 392 | When the spf condition has run, it sets up several expansion |
| 393 | variables. |
| 394 | |
| 395 | $spf_header_comment |
| 396 | This contains a human-readable string describing the outcome |
| 397 | of the SPF check. You can add it to a custom header or use |
| 398 | it for logging purposes. |
| 399 | |
| 400 | $spf_received |
| 401 | This contains a complete Received-SPF: header that can be |
| 402 | added to the message. Please note that according to the SPF |
| 403 | draft, this header must be added at the top of the header |
| 404 | list. Please see section 10 on how you can do this. |
| 405 | |
| 406 | Note: in case of "Best-guess" (see below), the convention is |
| 407 | to put this string in a header called X-SPF-Guess: instead. |
| 408 | |
| 409 | $spf_result |
| 410 | This contains the outcome of the SPF check in string form, |
| 411 | one of pass, fail, softfail, none, neutral, permerror or |
| 412 | temperror. |
| 413 | |
| 414 | $spf_smtp_comment |
| 415 | This contains a string that can be used in a SMTP response |
| 416 | to the calling party. Useful for "fail". |
| 417 | |
| 418 | In addition to SPF, you can also perform checks for so-called |
| 419 | "Best-guess". Strictly speaking, "Best-guess" is not standard |
| 420 | SPF, but it is supported by the same framework that enables SPF |
| 421 | capability. Refer to http://www.openspf.org/FAQ/Best_guess_record |
| 422 | for a description of what it means. |
| 423 | |
| 424 | To access this feature, simply use the spf_guess condition in place |
| 425 | of the spf one. For example: |
| 426 | |
| 427 | /* ----------------- |
| 428 | deny message = $sender_host_address doesn't look trustworthy to me |
| 429 | spf_guess = fail |
| 430 | --------------------- */ |
| 431 | |
| 432 | In case you decide to reject messages based on this check, you |
| 433 | should note that although it uses the same framework, "Best-guess" |
| 434 | is NOT SPF, and therefore you should not mention SPF at all in your |
| 435 | reject message. |
| 436 | |
| 437 | When the spf_guess condition has run, it sets up the same expansion |
| 438 | variables as when spf condition is run, described above. |
| 439 | |
| 440 | Additionally, since Best-guess is not standardized, you may redefine |
| 441 | what "Best-guess" means to you by redefining spf_guess variable in |
| 442 | global config. For example, the following: |
| 443 | |
| 444 | /* ----------------- |
| 445 | spf_guess = v=spf1 a/16 mx/16 ptr ?all |
| 446 | --------------------- */ |
| 447 | |
| 448 | would relax host matching rules to a broader network range. |
| 449 | |
| 450 | |
| 451 | SRS (Sender Rewriting Scheme) Support |
| 452 | -------------------------------------------------------------- |
| 453 | |
| 454 | Exiscan currently includes SRS support via Miles Wilton's |
| 455 | libsrs_alt library. The current version of the supported |
| 456 | library is 0.5. |
| 457 | |
| 458 | In order to use SRS, you must get a copy of libsrs_alt from |
| 459 | |
| 460 | http://srs.mirtol.com/ |
| 461 | |
| 462 | Unpack the tarball, then refer to MTAs/README.EXIM |
| 463 | to proceed. You need to set |
| 464 | |
| 465 | EXPERIMENTAL_SRS=yes |
| 466 | |
| 467 | in your Local/Makefile. |
| 468 | |
| 469 | |
| 470 | DCC Support |
| 471 | -------------------------------------------------------------- |
| 472 | |
| 473 | *) Building exim |
| 474 | |
| 475 | In order to build exim with DCC support add |
| 476 | |
| 477 | EXPERIMENTAL_DCC=yes |
| 478 | |
| 479 | to your Makefile. (Re-)build/install exim. exim -d should show |
| 480 | EXPERIMENTAL_DCC under "Support for". |
| 481 | |
| 482 | |
| 483 | *) Configuration |
| 484 | |
| 485 | In the main section of exim.cf add at least |
| 486 | dccifd_address = /usr/local/dcc/var/dccifd |
| 487 | or |
| 488 | dccifd_address = <ip> <port> |
| 489 | |
| 490 | In the DATA ACL you can use the new condition |
| 491 | dcc = * |
| 492 | |
| 493 | After that "$dcc_header" contains the X-DCC-Header. |
| 494 | |
| 495 | Return values are: |
| 496 | fail for overall "R", "G" from dccifd |
| 497 | defer for overall "T" from dccifd |
| 498 | accept for overall "A", "S" from dccifd |
| 499 | |
| 500 | dcc = */defer_ok works as for spamd. |
| 501 | |
| 502 | The "$dcc_result" variable contains the overall result from DCC |
| 503 | answer. There will an X-DCC: header added to the mail. |
| 504 | |
| 505 | Usually you'll use |
| 506 | defer !dcc = * |
| 507 | to greylist with DCC. |
| 508 | |
| 509 | If you set, in the main section, |
| 510 | dcc_direct_add_header = true |
| 511 | then the dcc header will be added "in deep" and if the spool |
| 512 | file was already written it gets removed. This forces Exim to |
| 513 | write it again if needed. This helps to get the DCC Header |
| 514 | through to eg. SpamAssassin. |
| 515 | |
| 516 | If you want to pass even more headers in the middle of the |
| 517 | DATA stage you can set |
| 518 | $acl_m_dcc_add_header |
| 519 | to tell the DCC routines to add more information; eg, you might set |
| 520 | this to some results from ClamAV. Be careful. Header syntax is |
| 521 | not checked and is added "as is". |
| 522 | |
| 523 | In case you've troubles with sites sending the same queue items from several |
| 524 | hosts and fail to get through greylisting you can use |
| 525 | $acl_m_dcc_override_client_ip |
| 526 | |
| 527 | Setting $acl_m_dcc_override_client_ip to an IP address overrides the default |
| 528 | of $sender_host_address. eg. use the following ACL in DATA stage: |
| 529 | |
| 530 | warn set acl_m_dcc_override_client_ip = \ |
| 531 | ${lookup{$sender_helo_name}nwildlsearch{/etc/mail/multipleip_sites}{$value}{}} |
| 532 | condition = ${if def:acl_m_dcc_override_client_ip} |
| 533 | log_message = dbg: acl_m_dcc_override_client_ip set to \ |
| 534 | $acl_m_dcc_override_client_ip |
| 535 | |
| 536 | Then set something like |
| 537 | # cat /etc/mail/multipleip_sites |
| 538 | mout-xforward.gmx.net 82.165.159.12 |
| 539 | mout.gmx.net 212.227.15.16 |
| 540 | |
| 541 | Use a reasonable IP. eg. one the sending cluster acutally uses. |
| 542 | |
| 543 | DMARC Support |
| 544 | -------------------------------------------------------------- |
| 545 | |
| 546 | DMARC combines feedback from SPF, DKIM, and header From: in order |
| 547 | to attempt to provide better indicators of the authenticity of an |
| 548 | email. This document does not explain the fundamentals, you |
| 549 | should read and understand how it works by visiting the website at |
| 550 | http://www.dmarc.org/. |
| 551 | |
| 552 | DMARC support is added via the libopendmarc library. Visit: |
| 553 | |
| 554 | http://sourceforge.net/projects/opendmarc/ |
| 555 | |
| 556 | to obtain a copy, or find it in your favorite rpm package |
| 557 | repository. If building from source, this description assumes |
| 558 | that headers will be in /usr/local/include, and that the libraries |
| 559 | are in /usr/local/lib. |
| 560 | |
| 561 | 1. To compile Exim with DMARC support, you must first enable SPF. |
| 562 | Please read the above section on enabling the EXPERIMENTAL_SPF |
| 563 | feature. You must also have DKIM support, so you cannot set the |
| 564 | DISABLE_DKIM feature. Once both of those conditions have been met |
| 565 | you can enable DMARC in Local/Makefile: |
| 566 | |
| 567 | EXPERIMENTAL_DMARC=yes |
| 568 | LDFLAGS += -lopendmarc |
| 569 | # CFLAGS += -I/usr/local/include |
| 570 | # LDFLAGS += -L/usr/local/lib |
| 571 | |
| 572 | The first line sets the feature to include the correct code, and |
| 573 | the second line says to link the libopendmarc libraries into the |
| 574 | exim binary. The commented out lines should be uncommented if you |
| 575 | built opendmarc from source and installed in the default location. |
| 576 | Adjust the paths if you installed them elsewhere, but you do not |
| 577 | need to uncomment them if an rpm (or you) installed them in the |
| 578 | package controlled locations (/usr/include and /usr/lib). |
| 579 | |
| 580 | |
| 581 | 2. Use the following global settings to configure DMARC: |
| 582 | |
| 583 | Required: |
| 584 | dmarc_tld_file Defines the location of a text file of valid |
| 585 | top level domains the opendmarc library uses |
| 586 | during domain parsing. Maintained by Mozilla, |
| 587 | the most current version can be downloaded |
| 588 | from a link at http://publicsuffix.org/list/. |
| 589 | |
| 590 | Optional: |
| 591 | dmarc_history_file Defines the location of a file to log results |
| 592 | of dmarc verification on inbound emails. The |
| 593 | contents are importable by the opendmarc tools |
| 594 | which will manage the data, send out DMARC |
| 595 | reports, and expire the data. Make sure the |
| 596 | directory of this file is writable by the user |
| 597 | exim runs as. |
| 598 | |
| 599 | dmarc_forensic_sender The email address to use when sending a |
| 600 | forensic report detailing alignment failures |
| 601 | if a sender domain's dmarc record specifies it |
| 602 | and you have configured Exim to send them. |
| 603 | Default: do-not-reply@$default_hostname |
| 604 | |
| 605 | |
| 606 | 3. By default, the DMARC processing will run for any remote, |
| 607 | non-authenticated user. It makes sense to only verify DMARC |
| 608 | status of messages coming from remote, untrusted sources. You can |
| 609 | use standard conditions such as hosts, senders, etc, to decide that |
| 610 | DMARC verification should *not* be performed for them and disable |
| 611 | DMARC with a control setting: |
| 612 | |
| 613 | control = dmarc_disable_verify |
| 614 | |
| 615 | A DMARC record can also specify a "forensic address", which gives |
| 616 | exim an email address to submit reports about failed alignment. |
| 617 | Exim does not do this by default because in certain conditions it |
| 618 | results in unintended information leakage (what lists a user might |
| 619 | be subscribed to, etc). You must configure exim to submit forensic |
| 620 | reports to the owner of the domain. If the DMARC record contains a |
| 621 | forensic address and you specify the control statement below, then |
| 622 | exim will send these forensic emails. It's also advised that you |
| 623 | configure a dmarc_forensic_sender because the default sender address |
| 624 | construction might be inadequate. |
| 625 | |
| 626 | control = dmarc_forensic_enable |
| 627 | |
| 628 | (AGAIN: You can choose not to send these forensic reports by simply |
| 629 | not putting the dmarc_forensic_enable control line at any point in |
| 630 | your exim config. If you don't tell it to send them, it will not |
| 631 | send them.) |
| 632 | |
| 633 | There are no options to either control. Both must appear before |
| 634 | the DATA acl. |
| 635 | |
| 636 | |
| 637 | 4. You can now run DMARC checks in incoming SMTP by using the |
| 638 | "dmarc_status" ACL condition in the DATA ACL. You are required to |
| 639 | call the spf condition first in the ACLs, then the "dmarc_status" |
| 640 | condition. Putting this condition in the ACLs is required in order |
| 641 | for a DMARC check to actually occur. All of the variables are set |
| 642 | up before the DATA ACL, but there is no actual DMARC check that |
| 643 | occurs until a "dmarc_status" condition is encountered in the ACLs. |
| 644 | |
| 645 | The dmarc_status condition takes a list of strings on its |
| 646 | right-hand side. These strings describe recommended action based |
| 647 | on the DMARC check. To understand what the policy recommendations |
| 648 | mean, refer to the DMARC website above. Valid strings are: |
| 649 | |
| 650 | o accept The DMARC check passed and the library recommends |
| 651 | accepting the email. |
| 652 | o reject The DMARC check failed and the library recommends |
| 653 | rejecting the email. |
| 654 | o quarantine The DMARC check failed and the library recommends |
| 655 | keeping it for further inspection. |
| 656 | o none The DMARC check passed and the library recommends |
| 657 | no specific action, neutral. |
| 658 | o norecord No policy section in the DMARC record for this |
| 659 | sender domain. |
| 660 | o nofrom Unable to determine the domain of the sender. |
| 661 | o temperror Library error or dns error. |
| 662 | o off The DMARC check was disabled for this email. |
| 663 | |
| 664 | You can prefix each string with an exclamation mark to invert its |
| 665 | meaning, for example "!accept" will match all results but |
| 666 | "accept". The string list is evaluated left-to-right in a |
| 667 | short-circuit fashion. When a string matches the outcome of the |
| 668 | DMARC check, the condition succeeds. If none of the listed |
| 669 | strings matches the outcome of the DMARC check, the condition |
| 670 | fails. |
| 671 | |
| 672 | Of course, you can also use any other lookup method that Exim |
| 673 | supports, including LDAP, Postgres, MySQL, etc, as long as the |
| 674 | result is a list of colon-separated strings. |
| 675 | |
| 676 | Several expansion variables are set before the DATA ACL is |
| 677 | processed, and you can use them in this ACL. The following |
| 678 | expansion variables are available: |
| 679 | |
| 680 | o $dmarc_status |
| 681 | This is a one word status indicating what the DMARC library |
| 682 | thinks of the email. It is a combination of the results of |
| 683 | DMARC record lookup and the SPF/DKIM/DMARC processing results |
| 684 | (if a DMARC record was found). The actual policy declared |
| 685 | in the DMARC record is in a separate expansion variable. |
| 686 | |
| 687 | o $dmarc_status_text |
| 688 | This is a slightly longer, human readable status. |
| 689 | |
| 690 | o $dmarc_used_domain |
| 691 | This is the domain which DMARC used to look up the DMARC |
| 692 | policy record. |
| 693 | |
| 694 | o $dmarc_domain_policy |
| 695 | This is the policy declared in the DMARC record. Valid values |
| 696 | are "none", "reject" and "quarantine". It is blank when there |
| 697 | is any error, including no DMARC record. |
| 698 | |
| 699 | o $dmarc_ar_header |
| 700 | This is the entire Authentication-Results header which you can |
| 701 | add using an add_header modifier. |
| 702 | |
| 703 | |
| 704 | 5. How to enable DMARC advanced operation: |
| 705 | By default, Exim's DMARC configuration is intended to be |
| 706 | non-intrusive and conservative. To facilitate this, Exim will not |
| 707 | create any type of logging files without explicit configuration by |
| 708 | you, the admin. Nor will Exim send out any emails/reports about |
| 709 | DMARC issues without explicit configuration by you, the admin (other |
| 710 | than typical bounce messages that may come about due to ACL |
| 711 | processing or failure delivery issues). |
| 712 | |
| 713 | In order to log statistics suitable to be imported by the opendmarc |
| 714 | tools, you need to: |
| 715 | a. Configure the global setting dmarc_history_file. |
| 716 | b. Configure cron jobs to call the appropriate opendmarc history |
| 717 | import scripts and truncating the dmarc_history_file. |
| 718 | |
| 719 | In order to send forensic reports, you need to: |
| 720 | a. Configure the global setting dmarc_forensic_sender. |
| 721 | b. Configure, somewhere before the DATA ACL, the control option to |
| 722 | enable sending DMARC forensic reports. |
| 723 | |
| 724 | |
| 725 | 6. Example usage: |
| 726 | (RCPT ACL) |
| 727 | warn domains = +local_domains |
| 728 | hosts = +local_hosts |
| 729 | control = dmarc_disable_verify |
| 730 | |
| 731 | warn !domains = +screwed_up_dmarc_records |
| 732 | control = dmarc_enable_forensic |
| 733 | |
| 734 | warn condition = (lookup if destined to mailing list) |
| 735 | set acl_m_mailing_list = 1 |
| 736 | |
| 737 | (DATA ACL) |
| 738 | warn dmarc_status = accept : none : off |
| 739 | !authenticated = * |
| 740 | log_message = DMARC DEBUG: $dmarc_status $dmarc_used_domain |
| 741 | add_header = $dmarc_ar_header |
| 742 | |
| 743 | warn dmarc_status = !accept |
| 744 | !authenticated = * |
| 745 | log_message = DMARC DEBUG: '$dmarc_status' for $dmarc_used_domain |
| 746 | |
| 747 | warn dmarc_status = quarantine |
| 748 | !authenticated = * |
| 749 | set $acl_m_quarantine = 1 |
| 750 | # Do something in a transport with this flag variable |
| 751 | |
| 752 | deny condition = ${if eq{$dmarc_domain_policy}{reject}} |
| 753 | condition = ${if eq{$acl_m_mailing_list}{1}} |
| 754 | message = Messages from $dmarc_used_domain break mailing lists |
| 755 | |
| 756 | deny dmarc_status = reject |
| 757 | !authenticated = * |
| 758 | message = Message from $domain_used_domain failed sender's DMARC policy, REJECT |
| 759 | |
| 760 | |
| 761 | |
| 762 | Event Actions |
| 763 | -------------------------------------------------------------- |
| 764 | |
| 765 | (Renamed from TPDA, Transport post-delivery actions) |
| 766 | |
| 767 | An arbitrary per-transport string can be expanded upon various transport events. |
| 768 | Additionally a main-section configuration option can be expanded on some |
| 769 | per-message events. |
| 770 | This feature may be used, for example, to write exim internal log information |
| 771 | (not available otherwise) into a database. |
| 772 | |
| 773 | In order to use the feature, you must compile with |
| 774 | |
| 775 | EXPERIMENTAL_EVENT=yes |
| 776 | |
| 777 | in your Local/Makefile |
| 778 | |
| 779 | and define one or both of |
| 780 | - the event_action option in the transport |
| 781 | - the event_action main option |
| 782 | to be expanded when the event fires. |
| 783 | |
| 784 | A new variable, $event_name, is set to the event type when the |
| 785 | expansion is done. The current list of events is: |
| 786 | |
| 787 | msg:complete after main per message |
| 788 | msg:delivery after transport per recipient |
| 789 | msg:host:defer after transport per attempt |
| 790 | msg:fail:delivery after main per recipient |
| 791 | msg:fail:internal after main per recipient |
| 792 | tcp:connect before transport per connection |
| 793 | tcp:close after transport per connection |
| 794 | tls:cert before transport per certificate in verification chain |
| 795 | smtp:connect after transport per connection |
| 796 | |
| 797 | The expansion is called for all event types, and should use the $event_name |
| 798 | value to decide when to act. The variable data is a colon-separated |
| 799 | list, describing an event tree. |
| 800 | |
| 801 | There is an auxilary variable, $event_data, for which the |
| 802 | content is event_dependent: |
| 803 | |
| 804 | msg:delivery smtp confirmation mssage |
| 805 | msg:host:defer error string |
| 806 | tls:cert verification chain depth |
| 807 | smtp:connect smtp banner |
| 808 | |
| 809 | The msg:host:defer event populates one extra variable, $event_defer_errno. |
| 810 | |
| 811 | The following variables are likely to be useful depending on the event type: |
| 812 | |
| 813 | router_name, transport_name |
| 814 | local_part, domain |
| 815 | host, host_address, host_port |
| 816 | tls_out_peercert |
| 817 | lookup_dnssec_authenticated, tls_out_dane |
| 818 | sending_ip_address, sending_port |
| 819 | message_exim_id, verify_mode |
| 820 | |
| 821 | |
| 822 | An example might look like: |
| 823 | |
| 824 | event_action = ${if = {msg:delivery}{$event_name} \ |
| 825 | {${lookup pgsql {SELECT * FROM record_Delivery( \ |
| 826 | '${quote_pgsql:$sender_address_domain}',\ |
| 827 | '${quote_pgsql:${lc:$sender_address_local_part}}', \ |
| 828 | '${quote_pgsql:$domain}', \ |
| 829 | '${quote_pgsql:${lc:$local_part}}', \ |
| 830 | '${quote_pgsql:$host_address}', \ |
| 831 | '${quote_pgsql:${lc:$host}}', \ |
| 832 | '${quote_pgsql:$message_exim_id}')}} \ |
| 833 | } {}} |
| 834 | |
| 835 | The string is expanded when each of the supported events occur |
| 836 | and any side-effects of the expansion will happen. |
| 837 | Note that for complex operations an ACL expansion can be used. |
| 838 | |
| 839 | |
| 840 | The expansion of the event_action option should normally |
| 841 | return an empty string. Should it return anything else the |
| 842 | following will be forced: |
| 843 | |
| 844 | msg:delivery (ignored) |
| 845 | msg:host:defer (ignored) |
| 846 | msg:fail:delivery (ignored) |
| 847 | tcp:connect do not connect |
| 848 | tcp:close (ignored) |
| 849 | tls:cert refuse verification |
| 850 | smtp:connect close connection |
| 851 | |
| 852 | No other use is made of the result string. |
| 853 | |
| 854 | |
| 855 | |
| 856 | |
| 857 | Redis Lookup |
| 858 | -------------------------------------------------------------- |
| 859 | |
| 860 | Redis is open source advanced key-value data store. This document |
| 861 | does not explain the fundamentals, you should read and understand how |
| 862 | it works by visiting the website at http://www.redis.io/. |
| 863 | |
| 864 | Redis lookup support is added via the hiredis library. Visit: |
| 865 | |
| 866 | https://github.com/redis/hiredis |
| 867 | |
| 868 | to obtain a copy, or find it in your operating systems package repository. |
| 869 | If building from source, this description assumes that headers will be in |
| 870 | /usr/local/include, and that the libraries are in /usr/local/lib. |
| 871 | |
| 872 | 1. In order to build exim with Redis lookup support add |
| 873 | |
| 874 | EXPERIMENTAL_REDIS=yes |
| 875 | |
| 876 | to your Local/Makefile. (Re-)build/install exim. exim -d should show |
| 877 | Experimental_Redis in the line "Support for:". |
| 878 | |
| 879 | EXPERIMENTAL_REDIS=yes |
| 880 | LDFLAGS += -lhiredis |
| 881 | # CFLAGS += -I/usr/local/include |
| 882 | # LDFLAGS += -L/usr/local/lib |
| 883 | |
| 884 | The first line sets the feature to include the correct code, and |
| 885 | the second line says to link the hiredis libraries into the |
| 886 | exim binary. The commented out lines should be uncommented if you |
| 887 | built hiredis from source and installed in the default location. |
| 888 | Adjust the paths if you installed them elsewhere, but you do not |
| 889 | need to uncomment them if an rpm (or you) installed them in the |
| 890 | package controlled locations (/usr/include and /usr/lib). |
| 891 | |
| 892 | |
| 893 | 2. Use the following global settings to configure Redis lookup support: |
| 894 | |
| 895 | Required: |
| 896 | redis_servers This option provides a list of Redis servers |
| 897 | and associated connection data, to be used in |
| 898 | conjunction with redis lookups. The option is |
| 899 | only available if Exim is configured with Redis |
| 900 | support. |
| 901 | |
| 902 | For example: |
| 903 | |
| 904 | redis_servers = 127.0.0.1/10/ - using database 10 with no password |
| 905 | redis_servers = 127.0.0.1//password - to make use of the default database of 0 with a password |
| 906 | redis_servers = 127.0.0.1// - for default database of 0 with no password |
| 907 | |
| 908 | 3. Once you have the Redis servers defined you can then make use of the |
| 909 | experimental Redis lookup by specifying ${lookup redis{}} in a lookup query. |
| 910 | |
| 911 | 4. Example usage: |
| 912 | |
| 913 | (Host List) |
| 914 | hostlist relay_from_ips = <\n ${lookup redis{SMEMBERS relay_from_ips}} |
| 915 | |
| 916 | Where relay_from_ips is a Redis set which contains entries such as "192.168.0.0/24" "10.0.0.0/8" and so on. |
| 917 | The result set is returned as |
| 918 | 192.168.0.0/24 |
| 919 | 10.0.0.0/8 |
| 920 | .. |
| 921 | . |
| 922 | |
| 923 | (Domain list) |
| 924 | domainlist virtual_domains = ${lookup redis {HGET $domain domain}} |
| 925 | |
| 926 | Where $domain is a hash which includes the key 'domain' and the value '$domain'. |
| 927 | |
| 928 | (Adding or updating an existing key) |
| 929 | set acl_c_spammer = ${if eq{${lookup redis{SPAMMER_SET}}}{OK}} |
| 930 | |
| 931 | Where SPAMMER_SET is a macro and it is defined as |
| 932 | |
| 933 | "SET SPAMMER <some_value>" |
| 934 | |
| 935 | (Getting a value from Redis) |
| 936 | |
| 937 | set acl_c_spam_host = ${lookup redis{GET...}} |
| 938 | |
| 939 | |
| 940 | Proxy Protocol Support |
| 941 | -------------------------------------------------------------- |
| 942 | |
| 943 | Exim now has Experimental "Proxy Protocol" support. It was built on |
| 944 | specifications from: |
| 945 | http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt |
| 946 | Above URL revised May 2014 to change version 2 spec: |
| 947 | http://git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e |
| 948 | |
| 949 | The purpose of this function is so that an application load balancer, |
| 950 | such as HAProxy, can sit in front of several Exim servers and Exim |
| 951 | will log the IP that is connecting to the proxy server instead of |
| 952 | the IP of the proxy server when it connects to Exim. It resets the |
| 953 | $sender_address_host and $sender_address_port to the IP:port of the |
| 954 | connection to the proxy. It also re-queries the DNS information for |
| 955 | this new IP address so that the original sender's hostname and IP |
| 956 | get logged in the Exim logfile. There is no logging if a host passes or |
| 957 | fails Proxy Protocol negotiation, but it can easily be determined and |
| 958 | recorded in an ACL (example is below). |
| 959 | |
| 960 | 1. To compile Exim with Proxy Protocol support, put this in |
| 961 | Local/Makefile: |
| 962 | |
| 963 | EXPERIMENTAL_PROXY=yes |
| 964 | |
| 965 | 2. Global configuration settings: |
| 966 | |
| 967 | proxy_required_hosts = HOSTLIST |
| 968 | |
| 969 | The proxy_required_hosts option will require any IP in that hostlist |
| 970 | to use Proxy Protocol. The specification of Proxy Protocol is very |
| 971 | strict, and if proxy negotiation fails, Exim will not allow any SMTP |
| 972 | command other than QUIT. (See end of this section for an example.) |
| 973 | The option is expanded when used, so it can be a hostlist as well as |
| 974 | string of IP addresses. Since it is expanded, specifying an alternate |
| 975 | separator is supported for ease of use with IPv6 addresses. |
| 976 | |
| 977 | To log the IP of the proxy in the incoming logline, add: |
| 978 | log_selector = +proxy |
| 979 | |
| 980 | A default incoming logline (wrapped for appearance) will look like this: |
| 981 | |
| 982 | 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net |
| 983 | H=mail.example.net [1.2.3.4] P=esmtp S=433 |
| 984 | |
| 985 | With the log selector enabled, an email that was proxied through a |
| 986 | Proxy Protocol server at 192.168.1.2 will look like this: |
| 987 | |
| 988 | 2013-11-04 09:25:06 1VdNti-0001OY-1V <= me@example.net |
| 989 | H=mail.example.net [1.2.3.4] P=esmtp PRX=192.168.1.2 S=433 |
| 990 | |
| 991 | 3. In the ACL's the following expansion variables are available. |
| 992 | |
| 993 | proxy_host_address The (internal) src IP of the proxy server |
| 994 | making the connection to the Exim server. |
| 995 | proxy_host_port The (internal) src port the proxy server is |
| 996 | using to connect to the Exim server. |
| 997 | proxy_target_address The dest (public) IP of the remote host to |
| 998 | the proxy server. |
| 999 | proxy_target_port The dest port the remote host is using to |
| 1000 | connect to the proxy server. |
| 1001 | proxy_session Boolean, yes/no, the connected host is required |
| 1002 | to use Proxy Protocol. |
| 1003 | |
| 1004 | There is no expansion for a failed proxy session, however you can detect |
| 1005 | it by checking if $proxy_session is true but $proxy_host is empty. As |
| 1006 | an example, in my connect ACL, I have: |
| 1007 | |
| 1008 | warn condition = ${if and{ {bool{$proxy_session}} \ |
| 1009 | {eq{$proxy_host_address}{}} } } |
| 1010 | log_message = Failed required proxy protocol negotiation \ |
| 1011 | from $sender_host_name [$sender_host_address] |
| 1012 | |
| 1013 | warn condition = ${if and{ {bool{$proxy_session}} \ |
| 1014 | {!eq{$proxy_host_address}{}} } } |
| 1015 | # But don't log health probes from the proxy itself |
| 1016 | condition = ${if eq{$proxy_host_address}{$sender_host_address} \ |
| 1017 | {false}{true}} |
| 1018 | log_message = Successfully proxied from $sender_host_name \ |
| 1019 | [$sender_host_address] through proxy protocol \ |
| 1020 | host $proxy_host_address |
| 1021 | |
| 1022 | # Possibly more clear |
| 1023 | warn logwrite = Remote Source Address: $sender_host_address:$sender_host_port |
| 1024 | logwrite = Proxy Target Address: $proxy_target_address:$proxy_target_port |
| 1025 | logwrite = Proxy Internal Address: $proxy_host_address:$proxy_host_port |
| 1026 | logwrite = Internal Server Address: $received_ip_address:$received_port |
| 1027 | |
| 1028 | |
| 1029 | 4. Recommended ACL additions: |
| 1030 | - Since the real connections are all coming from your proxy, and the |
| 1031 | per host connection tracking is done before Proxy Protocol is |
| 1032 | evaluated, smtp_accept_max_per_host must be set high enough to |
| 1033 | handle all of the parallel volume you expect per inbound proxy. |
| 1034 | - With the smtp_accept_max_per_host set so high, you lose the ability |
| 1035 | to protect your server from massive numbers of inbound connections |
| 1036 | from one IP. In order to prevent your server from being DOS'd, you |
| 1037 | need to add a per connection ratelimit to your connect ACL. I |
| 1038 | suggest something like this: |
| 1039 | |
| 1040 | # Set max number of connections per host |
| 1041 | LIMIT = 5 |
| 1042 | # Or do some kind of IP lookup in a flat file or database |
| 1043 | # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}} |
| 1044 | |
| 1045 | defer message = Too many connections from this IP right now |
| 1046 | ratelimit = LIMIT / 5s / per_conn / strict |
| 1047 | |
| 1048 | |
| 1049 | 5. Runtime issues to be aware of: |
| 1050 | - The proxy has 3 seconds (hard-coded in the source code) to send the |
| 1051 | required Proxy Protocol header after it connects. If it does not, |
| 1052 | the response to any commands will be: |
| 1053 | "503 Command refused, required Proxy negotiation failed" |
| 1054 | - If the incoming connection is configured in Exim to be a Proxy |
| 1055 | Protocol host, but the proxy is not sending the header, the banner |
| 1056 | does not get sent until the timeout occurs. If the sending host |
| 1057 | sent any input (before the banner), this causes a standard Exim |
| 1058 | synchronization error (i.e. trying to pipeline before PIPELINING |
| 1059 | was advertised). |
| 1060 | - This is not advised, but is mentioned for completeness if you have |
| 1061 | a specific internal configuration that you want this: If the Exim |
| 1062 | server only has an internal IP address and no other machines in your |
| 1063 | organization will connect to it to try to send email, you may |
| 1064 | simply set the hostlist to "*", however, this will prevent local |
| 1065 | mail programs from working because that would require mail from |
| 1066 | localhost to use Proxy Protocol. Again, not advised! |
| 1067 | |
| 1068 | 6. Example of a refused connection because the Proxy Protocol header was |
| 1069 | not sent from a host configured to use Proxy Protocol. In the example, |
| 1070 | the 3 second timeout occurred (when a Proxy Protocol banner should have |
| 1071 | been sent), the banner was displayed to the user, but all commands are |
| 1072 | rejected except for QUIT: |
| 1073 | |
| 1074 | # nc mail.example.net 25 |
| 1075 | 220-mail.example.net, ESMTP Exim 4.82+proxy, Mon, 04 Nov 2013 10:45:59 |
| 1076 | 220 -0800 RFC's enforced |
| 1077 | EHLO localhost |
| 1078 | 503 Command refused, required Proxy negotiation failed |
| 1079 | QUIT |
| 1080 | 221 mail.example.net closing connection |
| 1081 | |
| 1082 | |
| 1083 | DSN Support |
| 1084 | -------------------------------------------------------------- |
| 1085 | |
| 1086 | DSN Support tries to add RFC 3461 support to Exim. It adds support for |
| 1087 | *) the additional parameters for MAIL FROM and RCPT TO |
| 1088 | *) RFC complient MIME DSN messages for all of |
| 1089 | success, failure and delay notifications |
| 1090 | *) dsn_advertise_hosts main option to select which hosts are able |
| 1091 | to use the extension |
| 1092 | *) dsn_lasthop router switch to end DSN processing |
| 1093 | |
| 1094 | In case of failure reports this means that the last three parts, the message body |
| 1095 | intro, size info and final text, of the defined template are ignored since there is no |
| 1096 | logical place to put them in the MIME message. |
| 1097 | |
| 1098 | All the other changes are made without changing any defaults |
| 1099 | |
| 1100 | Building exim: |
| 1101 | -------------- |
| 1102 | |
| 1103 | Define |
| 1104 | EXPERIMENTAL_DSN=YES |
| 1105 | in your Local/Makefile. |
| 1106 | |
| 1107 | Configuration: |
| 1108 | -------------- |
| 1109 | All DSNs are sent in MIME format if you built exim with EXPERIMENTAL_DSN=YES |
| 1110 | No option needed to activate it, and no way to turn it off. |
| 1111 | |
| 1112 | Failure and delay DSNs are triggered as usual except a sender used NOTIFY=... |
| 1113 | to prevent them. |
| 1114 | |
| 1115 | Support for Success DSNs is added and activated by NOTIFY=SUCCESS by clients. |
| 1116 | |
| 1117 | Add |
| 1118 | dsn_advertise_hosts = * |
| 1119 | or a more restrictive host_list to announce DSN in EHLO answers |
| 1120 | |
| 1121 | Those hosts can then use NOTIFY,ENVID,RET,ORCPT options. |
| 1122 | |
| 1123 | If a message is relayed to a DSN aware host without changing the envelope |
| 1124 | recipient the options are passed along and no success DSN is generated. |
| 1125 | |
| 1126 | A redirect router will always trigger a success DSN if requested and the DSN |
| 1127 | options are not passed any further. |
| 1128 | |
| 1129 | A success DSN always contains the recipient address as submitted by the |
| 1130 | client as required by RFC. Rewritten addresses are never exposed. |
| 1131 | |
| 1132 | If you used DSN patch up to 1.3 before remove all "dsn_process" switches from |
| 1133 | your routers since you don't need them anymore. There is no way to "gag" |
| 1134 | success DSNs anymore. Announcing DSN means answering as requested. |
| 1135 | |
| 1136 | You can prevent Exim from passing DSN options along to other DSN aware hosts by defining |
| 1137 | dsn_lasthop |
| 1138 | in a router. Exim will then send the success DSN himself if requested as if |
| 1139 | the next hop does not support DSN. |
| 1140 | Adding it to a redirect router makes no difference. |
| 1141 | |
| 1142 | |
| 1143 | Certificate name checking |
| 1144 | -------------------------------------------------------------- |
| 1145 | The X509 certificates used for TLS are supposed be verified |
| 1146 | that they are owned by the expected host. The coding of TLS |
| 1147 | support to date has not made these checks. |
| 1148 | |
| 1149 | If built with EXPERIMENTAL_CERTNAMES defined, code is |
| 1150 | included to do so, and a new smtp transport option |
| 1151 | "tls_verify_cert_hostname" supported which takes a list of |
| 1152 | names for which the checks must be made. The host must |
| 1153 | also be in "tls_verify_hosts". |
| 1154 | |
| 1155 | Both Subject and Subject-Alternate-Name certificate fields |
| 1156 | are supported, as are wildcard certificates (limited to |
| 1157 | a single wildcard being the initial component of a 3-or-more |
| 1158 | component FQDN). |
| 1159 | |
| 1160 | |
| 1161 | DANE |
| 1162 | ------------------------------------------------------------ |
| 1163 | DNS-based Authentication of Named Entities, as applied |
| 1164 | to SMTP over TLS, provides assurance to a client that |
| 1165 | it is actually talking to the server it wants to rather |
| 1166 | than some attacker operating a Man In The Middle (MITM) |
| 1167 | operation. The latter can terminate the TLS connection |
| 1168 | you make, and make another one to the server (so both |
| 1169 | you and the server still think you have an encrypted |
| 1170 | connection) and, if one of the "well known" set of |
| 1171 | Certificate Authorities has been suborned - something |
| 1172 | which *has* been seen already (2014), a verifiable |
| 1173 | certificate (if you're using normal root CAs, eg. the |
| 1174 | Mozilla set, as your trust anchors). |
| 1175 | |
| 1176 | What DANE does is replace the CAs with the DNS as the |
| 1177 | trust anchor. The assurance is limited to a) the possibility |
| 1178 | that the DNS has been suborned, b) mistakes made by the |
| 1179 | admins of the target server. The attack surface presented |
| 1180 | by (a) is thought to be smaller than that of the set |
| 1181 | of root CAs. |
| 1182 | |
| 1183 | It also allows the server to declare (implicitly) that |
| 1184 | connections to it should use TLS. An MITM could simply |
| 1185 | fail to pass on a server's STARTTLS. |
| 1186 | |
| 1187 | DANE scales better than having to maintain (and |
| 1188 | side-channel communicate) copies of server certificates |
| 1189 | for every possible target server. It also scales |
| 1190 | (slightly) better than having to maintain on an SMTP |
| 1191 | client a copy of the standard CAs bundle. It also |
| 1192 | means not having to pay a CA for certificates. |
| 1193 | |
| 1194 | DANE requires a server operator to do three things: |
| 1195 | 1) run DNSSEC. This provides assurance to clients |
| 1196 | that DNS lookups they do for the server have not |
| 1197 | been tampered with. The domain MX record applying |
| 1198 | to this server, its A record, its TLSA record and |
| 1199 | any associated CNAME records must all be covered by |
| 1200 | DNSSEC. |
| 1201 | 2) add TLSA DNS records. These say what the server |
| 1202 | certificate for a TLS connection should be. |
| 1203 | 3) offer a server certificate, or certificate chain, |
| 1204 | in TLS connections which is traceable to the one |
| 1205 | defined by (one of?) the TSLA records |
| 1206 | |
| 1207 | There are no changes to Exim specific to server-side |
| 1208 | operation of DANE. |
| 1209 | |
| 1210 | The TLSA record for the server may have "certificate |
| 1211 | usage" of DANE-TA(2) or DANE-EE(3). The latter specifies |
| 1212 | the End Entity directly, i.e. the certificate involved |
| 1213 | is that of the server (and should be the sole one transmitted |
| 1214 | during the TLS handshake); this is appropriate for a |
| 1215 | single system, using a self-signed certificate. |
| 1216 | DANE-TA usage is effectively declaring a specific CA |
| 1217 | to be used; this might be a private CA or a public, |
| 1218 | well-known one. A private CA at simplest is just |
| 1219 | a self-signed certificate which is used to sign |
| 1220 | cerver certificates, but running one securely does |
| 1221 | require careful arrangement. If a private CA is used |
| 1222 | then either all clients must be primed with it, or |
| 1223 | (probably simpler) the server TLS handshake must transmit |
| 1224 | the entire certificate chain from CA to server-certificate. |
| 1225 | If a public CA is used then all clients must be primed with it |
| 1226 | (losing one advantage of DANE) - but the attack surface is |
| 1227 | reduced from all public CAs to that single CA. |
| 1228 | DANE-TA is commonly used for several services and/or |
| 1229 | servers, each having a TLSA query-domain CNAME record, |
| 1230 | all of which point to a single TLSA record. |
| 1231 | |
| 1232 | The TLSA record should have a Selector field of SPKI(1) |
| 1233 | and a Matching Type field of SHA2-512(2). |
| 1234 | |
| 1235 | At the time of writing, https://www.huque.com/bin/gen_tlsa |
| 1236 | is useful for quickly generating TLSA records; and commands like |
| 1237 | |
| 1238 | openssl x509 -in -pubkey -noout <certificate.pem \ |
| 1239 | | openssl rsa -outform der -pubin 2>/dev/null \ |
| 1240 | | openssl sha512 \ |
| 1241 | | awk '{print $2}' |
| 1242 | |
| 1243 | are workable for 4th-field hashes. |
| 1244 | |
| 1245 | For use with the DANE-TA model, server certificates |
| 1246 | must have a correct name (SubjectName or SubjectAltName). |
| 1247 | |
| 1248 | The use of OCSP-stapling should be considered, allowing |
| 1249 | for fast revocation of certificates (which would otherwise |
| 1250 | be limited by the DNS TTL on the TLSA records). However, |
| 1251 | this is likely to only be usable with DANE-TA. NOTE: the |
| 1252 | default of requesting OCSP for all hosts is modified iff |
| 1253 | DANE is in use, to: |
| 1254 | |
| 1255 | hosts_request_ocsp = ${if or { {= {0}{$tls_out_tlsa_usage}} \ |
| 1256 | {= {4}{$tls_out_tlsa_usage}} } \ |
| 1257 | {*}{}} |
| 1258 | |
| 1259 | The (new) variable $tls_out_tlsa_usage is a bitfield with |
| 1260 | numbered bits set for TLSA record usage codes. |
| 1261 | The zero above means DANE was not in use, |
| 1262 | the four means that only DANE-TA usage TLSA records were |
| 1263 | found. If the definition of hosts_request_ocsp includes the |
| 1264 | string "tls_out_tlsa_usage", they are re-expanded in time to |
| 1265 | control the OCSP request. |
| 1266 | |
| 1267 | This modification of hosts_request_ocsp is only done if |
| 1268 | it has the default value of "*". Admins who change it, and |
| 1269 | those who use hosts_require_ocsp, should consider the interaction |
| 1270 | with DANE in their OCSP settings. |
| 1271 | |
| 1272 | |
| 1273 | For client-side DANE there are two new smtp transport options, |
| 1274 | hosts_try_dane and hosts_require_dane. They do the obvious thing. |
| 1275 | [ should they be domain-based rather than host-based? ] |
| 1276 | |
| 1277 | DANE will only be usable if the target host has DNSSEC-secured |
| 1278 | MX, A and TLSA records. |
| 1279 | |
| 1280 | A TLSA lookup will be done if either of the above options match |
| 1281 | and the host-lookup succeded using dnssec. |
| 1282 | If the TLSA lookup succeeds, a TLS connection will be required |
| 1283 | for the host. |
| 1284 | |
| 1285 | (TODO: specify when fallback happens vs. when the host is not used) |
| 1286 | |
| 1287 | If dane is in use the following transport options are ignored: |
| 1288 | hosts_require_tls |
| 1289 | tls_verify_hosts |
| 1290 | tls_try_verify_hosts |
| 1291 | tls_verify_certificates |
| 1292 | tls_crl |
| 1293 | tls_verify_cert_hostnames |
| 1294 | |
| 1295 | Currently dnssec_request_domains must be active (need to think about that) |
| 1296 | and dnssec_require_domains is ignored. |
| 1297 | |
| 1298 | If verification was successful using DANE then the "CV" item |
| 1299 | in the delivery log line will show as "CV=dane". |
| 1300 | |
| 1301 | There is a new variable $tls_out_dane which will have "yes" if |
| 1302 | verification succeeded using DANE and "no" otherwise (only useful |
| 1303 | in combination with EXPERIMENTAL_TPDA), and a new variable |
| 1304 | $tls_out_tlsa_usage (detailed above). |
| 1305 | |
| 1306 | |
| 1307 | -------------------------------------------------------------- |
| 1308 | End of file |
| 1309 | -------------------------------------------------------------- |