1<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" 2 "http://www.w3.org/TR/html4/loose.dtd"> 3 4<head> 5 6<title>Postfix SASL Howto</title> 7 8<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 9<link rel='stylesheet' type='text/css' href='postfix-doc.css'> 10 11</head> 12 13<body> 14 15<h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix SASL Howto</h1> 16 17<hr> 18 19<h2><a name="intro">How Postfix uses SASL authentication</a></h2> 20 21<p> SMTP servers need to decide whether an SMTP client is authorized 22to send mail to remote destinations, or only to destinations that 23the server itself is responsible for. Usually, SMTP servers accept 24mail to remote destinations when the client's IP address is in the 25"same network" as the server's IP address. </p> 26 27<p> SMTP clients outside the SMTP server's network need a different 28way to get "same network" privileges. To address this need, Postfix 29supports SASL authentication (RFC 4954, formerly RFC 2554). With 30this a remote SMTP client can authenticate to the Postfix SMTP 31server, and the Postfix SMTP client can authenticate to a remote 32SMTP server. Once a client is authenticated, a server can give it 33"same network" privileges. </p> 34 35<p> Postfix does not implement SASL itself, but instead uses existing 36implementations as building blocks. This means that some SASL-related 37configuration files will belong to Postfix, while other 38configuration files belong to the specific SASL 39implementation that Postfix will use. This document covers both the 40Postfix and non-Postfix configuration. </p> 41 42<p> NOTE: People who go to the trouble of installing Postfix may 43have the expectation that Postfix is more secure than some other 44mailers. The Cyrus SASL library contains a lot of code. With this, 45Postfix becomes as secure as other mail systems that use the Cyrus 46SASL library. Dovecot provides an alternative that may be worth 47considering. </p> 48 49<p> You can read more about the following topics: </p> 50 51<ul> 52 53<li><a href="#server_sasl">Configuring SASL authentication in the 54Postfix SMTP server</a></li> 55 56<li><a href="#client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></li> 57 58<li><a href="#postfix_build">Building Postfix with SASL support</a></li> 59 60<li><a href="#cyrus_legacy">Using Cyrus SASL version 1.5.x</a></li> 61 62<li><a href="#credits">Credits</a></li> 63 64</ul> 65 66<h2><a name="server_sasl">Configuring SASL authentication in the 67Postfix SMTP server</a></h2> 68 69<p> As mentioned earlier, SASL is implemented separately from 70Postfix. For this reason, configuring SASL authentication in the 71Postfix SMTP server involves two different steps: </p> 72 73<ul> 74 75<li> <p> Configuring the SASL implementation to offer a list of 76mechanisms that are suitable for SASL authentication and, depending 77on the SASL implementation used, configuring authentication backends 78that verify the remote SMTP client's authentication data against 79the system password file or some other database. </p> </li> 80 81<li> <p> Configuring the Postfix SMTP server to enable SASL 82authentication, and to authorize clients to relay mail or to control 83what envelope sender addresses the client may use. </p> </li> 84 85</ul> 86 87<p> Successful authentication in the Postfix SMTP server requires 88a functional SASL framework. Configuring SASL should therefore 89always be the first step, before configuring Postfix. </p> 90 91<p> You can read more about the following topics: </p> 92 93<ul> 94 95<li><a href="#server_which">Which SASL Implementations are 96supported?</a></li> 97 98<li><a href="#server_dovecot">Configuring Dovecot SASL</a> 99 100<ul> 101 102<li><a href="#server_dovecot_comm">Postfix to Dovecot SASL 103communication</a></li> 104 105</ul> </li> 106 107<li><a href="#server_cyrus">Configuring Cyrus SASL</a> 108 109<ul> 110 111<li><a href="#server_cyrus_name">Cyrus SASL configuration file 112name</a></li> 113 114<li><a href="#server_cyrus_location">Cyrus SASL configuration 115file location</a></li> 116 117<li><a href="#server_cyrus_comm">Postfix to Cyrus SASL 118communication</a></li> 119 120</ul> </li> 121 122<li><a href="#server_sasl_enable">Enabling SASL authentication and 123authorization in the Postfix SMTP server</a> 124 125<ul> 126 127<li><a href="#server_sasl_authc">Enabling SASL authentication in 128the Postfix SMTP server</a></li> 129 130<li><a href="#smtpd_sasl_security_options">Postfix SMTP Server 131policy - SASL mechanism properties</a></li> 132 133<li><a href="#server_sasl_authz">Enabling SASL authorization in the 134Postfix SMTP server</a></li> 135 136<li><a href="#server_sasl_other">Additional SMTP Server SASL 137options</a></li> 138 139</ul></li> 140 141<li><a href="#server_test">Testing SASL authentication in the Postfix 142SMTP server</a></li> 143 144</ul> 145 146 147<h3><a name="server_which">Which SASL Implementations are 148supported?</a></h3> 149 150<p> Currently the Postfix SMTP server supports the Cyrus SASL and 151Dovecot SASL implementations. </p> 152 153<blockquote> 154 155<strong>Note</strong> 156 157<p> Current Postfix versions have a plug-in architecture that can 158support multiple SASL implementations. Before Postfix version 2.3, 159Postfix had support only for Cyrus SASL. </p> 160 161</blockquote> 162 163<p> To find out what SASL implementations are compiled into Postfix, 164use the following commands: </p> 165 166<blockquote> 167<pre> 168% <strong><code>postconf -a</code></strong> (SASL support in the SMTP server) 169% <strong><code>postconf -A</code></strong> (SASL support in the SMTP+LMTP client) 170</pre> 171</blockquote> 172 173<p> These commands are available only with Postfix version 2.3 and 174later. </p> 175 176<h3><a name="server_dovecot">Configuring Dovecot SASL</a></h3> 177 178<p> Dovecot is a POP/IMAP server that has its own configuration to 179authenticate POP/IMAP clients. When the Postfix SMTP server uses 180Dovecot SASL, it reuses parts of this configuration. Consult the 181<a href="http://wiki.dovecot.org">Dovecot documentation</a> for how 182to configure and operate the Dovecot authentication server. </p> 183 184<h4><a name="server_dovecot_comm">Postfix to Dovecot SASL communication</a></h4> 185 186<p> Communication between the Postfix SMTP server and Dovecot SASL 187happens over a UNIX-domain socket or over a TCP socket. We will 188be using a UNIX-domain socket for better privacy. </p> 189 190<p> The following fragment for Dovecot version 2 assumes that the 191Postfix queue is under <code>/var/spool/postfix/</code>. </p> 192 193<blockquote> 194<pre> 195 1 conf.d/10-master.conf: 196 2 service auth { 197 3 ... 198 4 unix_listener /var/spool/postfix/private/auth { 199 5 mode = 0660 200 6 # Assuming the default Postfix user and group 201 7 user = postfix 202 8 group = postfix 203 9 } 20410 ... 20511 } 20612 20713 conf.d/10-auth.conf 20814 auth_mechanisms = plain login 209</pre> 210</blockquote> 211 212<p> Line 4 places the Dovecot SASL socket in 213<code>/var/spool/postfix/private/auth</code>, lines 5-8 limit 214read+write permissions to user and group <code>postfix</code> only, 215and line 14 provides <code>plain</code> and <code>login</code> as 216mechanisms for the Postfix SMTP server. </p> 217 218<p> Proceed with the section "<a href="#server_sasl_enable">Enabling 219SASL authentication and authorization in the Postfix SMTP server</a>" 220to turn on and use SASL in the Postfix SMTP server. </p> 221 222<h3><a name="server_cyrus">Configuring Cyrus SASL</a></h3> 223 224<p> The Cyrus SASL framework supports a wide variety of applications 225(POP, IMAP, SMTP, etc.). Different applications may require different 226configurations. As a consequence each application may have its own 227configuration file. </p> 228 229<p> The first step configuring Cyrus SASL is to determine name and 230location of a configuration file that describes how the Postfix 231SMTP server will use the SASL framework. </p> 232 233<h4><a name="server_cyrus_name">Cyrus SASL configuration file name</a></h4> 234 235<p> The name of the configuration file (default: <code>smtpd.conf</code>) 236is configurable. It is a concatenation from a value that the Postfix 237SMTP server sends to the Cyrus SASL library, and the suffix 238<code>.conf</code>, added by Cyrus SASL. </p> 239 240<p> The value sent by Postfix is the name of the server component 241that will use Cyrus SASL. It defaults to <code>smtpd</code> and 242is configured with one of the following variables: </p> 243 244<blockquote> 245<pre> 246/etc/postfix/main.cf: 247 # Postfix 2.3 and later 248 smtpd_sasl_path = smtpd 249 250 # Postfix < 2.3 251 smtpd_sasl_application_name = smtpd 252</pre> 253</blockquote> 254 255<h4><a name="server_cyrus_location">Cyrus SASL configuration file 256location</a></h4> 257 258<p> The location where Cyrus SASL searches for the named file depends 259on the Cyrus SASL version and the OS/distribution used. </p> 260 261<p> You can read more about the following topics: </p> 262 263<ul> 264 265<li> <p> Cyrus SASL version 2.x searches for the configuration file 266in <code>/usr/lib/sasl2/</code>. </p> </li> 267 268<li> <p> Cyrus SASL version 2.1.22 and newer additionally search 269in <code>/etc/sasl2/</code>. </p> </li> 270 271<li> <p> With Postfix 2.5 and later you can explicitly configure the 272search path via the <code>cyrus_sasl_config_path</code> configuration 273parameter. Specify zero or more colon-separated directories. If 274set empty (the default value) the search path is the one compiled 275into the Cyrus SASL library. </p> </li> 276 277<li> <p> Some Postfix distributions employ a non-empty default value 278for <code>cyrus_sasl_config_path</code> to look for the Cyrus SASL 279configuration file in <code>/etc/postfix/sasl/</code>, 280<code>/var/lib/sasl2/</code> etc. See the output of <code>postconf 281cyrus_sasl_config_path</code> and/or the distribution-specific 282documentation to determine the expected location. </p> </li> 283 284<li> <p> Some Debian-based Postfix distributions patch Postfix to 285hardcode a non-default search path, making it impossible to set an 286alternate search path via the "cyrus_sasl_config_path" parameter. This 287is likely to be the case when the distribution documents a 288Postfix-specific path (e.g. <code>/etc/postfix/sasl/</code>) that is 289different from the default value of "cyrus_sasl_config_path" (which 290then is likely to be empty). </p> </li> 291 292</ul> 293 294<blockquote> 295 296<strong>Note</strong> 297 298<p> Cyrus SASL searches <code>/usr/lib/sasl2/</code> first. If it 299finds the specified configuration file there, it will not examine 300other locations. </p> 301 302</blockquote> 303 304<h4><a name="server_cyrus_comm">Postfix to Cyrus SASL communication</a></h4> 305 306<p> As the Postfix SMTP server is linked with the Cyrus SASL library 307<code>libsasl</code>, communication between Postfix and Cyrus SASL 308takes place by calling functions in the SASL library. </p> 309 310<p> The SASL library may use an external password verification 311service, or an internal plugin to connect to authentication backends 312and verify the SMTP client's authentication data against the system 313password file or other databases. </p> 314 315<p> The following table shows typical combinations discussed in 316this document: </p> 317 318<blockquote> 319 320<table border="1"> 321 322<tr> 323 324<th align="center">authentication backend</th> 325 326<th align="center">password verification service / plugin</th> 327 328</tr> 329 330<tr> 331 332<td>/etc/shadow</td> 333 334<td><a href="#saslauthd">saslauthd</a></td> 335 336</tr> 337 338<tr> 339 340<td>PAM</td> 341 342<td><a href="#saslauthd">saslauthd</a></td> 343 344</tr> 345 346<tr> 347 348<td>IMAP server</td> 349 350<td><a href="#saslauthd">saslauthd</a></td> 351 352</tr> 353 354<tr> 355 356<td>sasldb</td> 357 358<td><a href="#auxprop_sasldb">sasldb</a></td> 359 360</tr> 361 362<tr> 363 364<td>MySQL, PostgreSQL, SQLite</td> 365 366<td><a href="#auxprop_sql">sql</a></td> 367 368</tr> 369 370<tr> 371 372<td>LDAP</td> 373 374<td><a href="#auxprop_ldapdb">ldapdb</a></td> 375 376</tr> 377 378</table> 379 380</blockquote> 381 382<blockquote> 383 384<strong>Note</strong> 385 386<p> Read the Cyrus SASL documentation for other backends it can 387use. </p> 388 389</blockquote> 390 391<h4><a name="saslauthd">saslauthd - Cyrus SASL password verification service</a></h4> 392 393<p> Communication between the Postfix SMTP server (read: Cyrus SASL's 394<code>libsasl</code>) and the <code>saslauthd</code> server takes 395place over a UNIX-domain socket. </p> 396 397<p> <code>saslauthd</code> usually establishes the UNIX domain 398socket in <code>/var/run/saslauthd/</code> and waits for authentication 399requests. The Postfix SMTP server must have read+execute permission 400to this directory or authentication attempts will fail. </p> 401 402<blockquote> 403 404<strong>Important</strong> 405 406<p> Some distributions require the user <code>postfix</code> to be 407member of a special group e.g. <code>sasl</code>, otherwise it 408will not be able to access the <code>saslauthd</code> socket 409directory. </p> 410 411</blockquote> 412 413<p> The following example configures the Cyrus SASL library to 414contact <code>saslauthd</code> as its password verification service: 415</p> 416 417<blockquote> 418<pre> 419/etc/sasl2/smtpd.conf: 420 pwcheck_method: saslauthd 421 mech_list: PLAIN LOGIN 422</pre> 423</blockquote> 424 425<blockquote> 426 427<strong>Important</strong> 428 429<p> Do not specify any other mechanisms in <code>mech_list</code> 430than <code>PLAIN</code> or <code>LOGIN</code> when using 431<code>saslauthd</code>! It can only handle these two mechanisms, 432and authentication will fail if clients are allowed to choose other 433mechanisms. </p> 434 435</blockquote> 436 437<blockquote> 438 439<strong>Important</strong> 440 441<p> Plaintext mechanisms (<code>PLAIN</code>, <code>LOGIN</code>) 442send credentials unencrypted. This information should be protected 443by an additional security layer such as a TLS-encrypted SMTP session 444(see: TLS_README). </p> 445 446</blockquote> 447 448<p> Additionally the <code>saslauthd</code> server itself must be 449configured. It must be told which authentication backend to turn 450to for password verification. The backend is selected with a 451<code>saslauthd</code> command-line option and will be shown in the 452following examples. </p> 453 454<blockquote> 455 456<strong>Note</strong> 457 458<p> Some distributions use a configuration file to provide saslauthd 459command line options to set e.g. the authentication backend. Typical 460locations are <code>/etc/sysconfig/saslauthd</code> or 461<code>/etc/default/saslauthd</code>. </p> 462 463</blockquote> 464 465<h4><a name="saslauthd_shadow">Using saslauthd with /etc/shadow</a></h4> 466 467<p> Access to the <code>/etc/shadow</code> system password file 468requires <code>root</code> privileges. The Postfix SMTP server 469(and in consequence <code>libsasl</code> linked to the server) runs 470with the least privilege possible. Direct access to 471<code>/etc/shadow</code> would not be possible without breaking the 472Postfix security architecture. </p> 473 474<p> The <code>saslauthd</code> socket builds a safe bridge. Postfix, 475running as limited user <code>postfix</code>, can access the 476UNIX-domain socket that <code>saslauthd</code> receives commands 477on; <code>saslauthd</code>, running as privileged user <code>root</code>, 478has the privileges required to access the shadow file. </p> 479 480<p> The <code>saslauthd</code> server verifies passwords against the 481authentication backend <code>/etc/shadow</code> if started like this: </p> 482 483<blockquote> 484<pre> 485% <strong><code>saslauthd -a shadow</code></strong> 486</pre> 487</blockquote> 488 489<p> See section "<a href="#testing_saslauthd">Testing saslauthd 490authentication</a>" for test instructions. </p> 491 492<h4><a name="saslauthd_pam">Using saslauthd with PAM</a></h4> 493 494<p> Cyrus SASL can use the PAM framework to authenticate credentials. 495<code>saslauthd</code> uses the PAM framework when started like 496this: </p> 497 498<blockquote> 499<pre> 500% <strong><code>saslauthd -a pam</code></strong> 501</pre> 502</blockquote> 503 504<blockquote> 505 506<strong>Note</strong> 507 508<p> PAM configuration for the Postfix SMTP server is usually given 509in <code>/etc/pam.d/smtp</code> and is beyond the scope of this 510document. </p> 511 512</blockquote> 513 514<p> See section "<a href="#testing_saslauthd">Testing saslauthd 515authentication</a>" for test instructions. </p> 516 517<h4><a name="saslauthd_imap">Using saslauthd with an IMAP server</a></h4> 518 519<p> <code>saslauthd</code> can verify the SMTP client credentials 520by using them to log into an IMAP server. If the login succeeds, 521SASL authentication also succeeds. <code>saslauthd</code> contacts 522an IMAP server when started like this: </p> 523 524<blockquote> 525<pre> 526% <strong><code>saslauthd -a rimap -O imap.example.com</code></strong> 527</pre> 528</blockquote> 529 530<blockquote> 531 532<strong>Note</strong> 533 534<p> The option "<code>-O imap.example.com</code>" specifies the 535IMAP server <code>saslauthd</code> should contact when it verifies 536credentials. </p> 537 538</blockquote> 539 540<blockquote> 541 542<strong>Important</strong> 543 544<p> <code>saslauthd</code> sends IMAP login information unencrypted. 545Any IMAP session leaving the local host should be protected by an 546additional security layer such as an SSL tunnel. </p> 547 548</blockquote> 549 550<p> See section "<a href="#testing_saslauthd">Testing saslauthd 551authentication</a>" for test instructions. </p> 552 553<h4><a name="testing_saslauthd">Testing saslauthd authentication</a></h4> 554 555<p> Cyrus SASL provides the <code>testsaslauthd</code> utility to 556test <code>saslauthd</code> authentication. The username and password 557are given as command line arguments. The example shows the response 558when authentication is successful: </p> 559 560<blockquote> 561<pre> 562% <strong><code>testsaslauthd -u <em>username</em> -p <em>password</em></code></strong> 5630: OK "Success." 564</pre> 565</blockquote> 566 567<blockquote> 568 569<strong>Note</strong> 570 571<p> Sometimes the <code>testsaslauthd</code> program is not distributed 572with a the Cyrus SASL main package. In that case, it may be 573distributed with <code>-devel</code>, <code>-dev</code> or 574<code>-debug</code> packages. </p> 575 576</blockquote> 577 578<p> Specify an additional "<code>-s smtp</code>" if <code>saslauthd</code> 579was configured to contact the PAM authentication framework, and 580specify an additional "<code>-f <em>/path/to/socketdir/mux</em></code>" 581if <code>saslauthd</code> establishes the UNIX-domain socket in a 582non-default location. </p> 583 584<p> If authentication succeeds, proceed with the section "<a 585href="#server_sasl_enable">Enabling SASL authentication and authorization 586in the Postfix SMTP server</a>". </p> 587 588<h4><a name="auxprop">Cyrus SASL Plugins - auxiliary property 589plugins</a></h4> 590 591<p> Cyrus SASL uses a plugin infrastructure (called <code>auxprop</code>) 592to expand <code>libsasl</code>'s capabilities. Currently Cyrus 593SASL sources provide three authentication plugins. </p> 594 595<blockquote> 596 597<table border="1"> 598 599<tr> <th>Plugin </th> <th>Description </th> </tr> 600 601<tr> <td><a href="#auxprop_sasldb">sasldb</a></td> <td> Accounts 602are stored stored in a Cyrus SASL Berkeley DB database </td> </tr> 603 604<tr> <td><a href="#auxprop_sql">sql</a></td> <td> Accounts are 605stored in a SQL database </td> </tr> 606 607<tr> <td><a href="#auxprop_ldapdb">ldapdb</a></td> <td> Accounts 608are stored stored in an LDAP database </td> </tr> 609 610</table> 611 612</blockquote> 613 614<blockquote> 615 616<strong>Important</strong> 617 618<p> These three plugins support shared-secret mechanisms i.e. 619CRAM-MD5, DIGEST-MD5 and NTLM. These mechanisms send credentials 620encrypted but their verification process requires the password to 621be available in plaintext. Consequently passwords cannot (!) be 622stored in encrypted form. </p> 623 624</blockquote> 625 626<h4><a name="auxprop_sasldb">The sasldb plugin</a></h4> 627 628<p> The sasldb auxprop plugin authenticates SASL clients against 629credentials that are stored in a Berkeley DB database. The database 630schema is specific to Cyrus SASL. The database is usually located 631at <code>/etc/sasldb2</code>. </p> 632 633<blockquote> 634 635<strong>Note</strong> 636 637<p> The <code>sasldb2</code> file contains passwords in 638plaintext, and should have read+write access only to user 639<code>postfix</code> or a group that <code>postfix</code> is member 640of. </p> 641 642</blockquote> 643 644<p> The <code>saslpasswd2</code> command-line utility creates 645and maintains the database: </p> 646 647<blockquote> 648<pre> 649% <strong>saslpasswd2 -c -u <em>example.com</em> <em>username</em></strong> 650Password: 651Again (for verification): 652</pre> 653</blockquote> 654 655<p> This command creates an account 656<code><em>username@example.com</em></code>. </p> 657 658<blockquote> 659 660<strong>Important</strong> 661 662<p> users must specify <code><em>username@example.com</em></code> 663as login name, not <code><em>username</em></code>. </p> 664 665</blockquote> 666 667<p> Run the following command to reuse the Postfix <code>mydomain</code> 668parameter value as the login domain: </p> 669 670<blockquote> 671<pre> 672% <strong>saslpasswd2 -c -u `postconf -h mydomain` <em>username</em></strong> 673Password: 674Again (for verification): 675</pre> 676</blockquote> 677 678<blockquote> 679 680<strong>Note</strong> 681 682<p> Run <code>saslpasswd2</code> without any options for further 683help on how to use the command. </p> 684 685</blockquote> 686 687<p> The <code>sasldblistusers2</code> command lists all existing 688users in the sasldb database: </p> 689 690<blockquote> 691<pre> 692% <strong>sasldblistusers2</strong> 693username1@example.com: password1 694username2@example.com: password2 695</pre> 696</blockquote> 697 698<p> Configure libsasl to use sasldb with the following instructions: </p> 699 700<blockquote> 701<pre> 702/etc/sasl2/smtpd.conf: 703 pwcheck_method: auxprop 704 auxprop_plugin: sasldb 705 mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM 706</pre> 707</blockquote> 708 709<blockquote> 710 711<strong>Note</strong> 712 713<p> In the above example adjust <code>mech_list</code> to the 714mechanisms that are applicable for your environment. </p> 715 716</blockquote> 717 718<h4><a name="auxprop_sql">The sql plugin</a></h4> 719 720<p> The sql auxprop plugin is a generic SQL plugin. It provides 721access to credentials stored in a MySQL, PostgreSQL or SQLite 722database. This plugin requires that SASL client passwords are 723stored as plaintext. </p> 724 725<blockquote> 726 727<strong>Tip</strong> 728 729<p> If you must store encrypted passwords, you cannot use the sql 730auxprop plugin. Instead, see section "<a href="#saslauthd_pam">Using 731saslauthd with PAM</a>", and configure PAM to look up the encrypted 732passwords with, for example, the <code>pam_mysql</code> module. 733You will not be able to use any of the methods that require access 734to plaintext passwords, such as the shared-secret methods CRAM-MD5 735and DIGEST-MD5. </p> 736 737</blockquote> 738 739<p> The following example configures libsasl to use the sql plugin 740and connects it to a PostgreSQL server: </p> 741 742<blockquote> 743<pre> 744/etc/sasl2/smtpd.conf: 745 pwcheck_method: auxprop 746 auxprop_plugin: sql 747 mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM 748 sql_engine: pgsql 749 sql_hostnames: 127.0.0.1, 192.0.2.1 750 sql_user: username 751 sql_passwd: secret 752 sql_database: dbname 753 sql_select: SELECT password FROM users WHERE user = '%u@%r' 754</pre> 755</blockquote> 756 757<blockquote> 758 759<strong>Note</strong> 760 761<p> Set appropriate permissions if <code>smtpd.conf</code> contains 762a password. The file should be readable by the <code>postfix</code> 763user. </p> 764 765</blockquote> 766 767<blockquote> 768 769<strong>Note</strong> 770 771<p> In the above example, adjust <code>mech_list</code> to the 772mechanisms that are applicable for your environment. </p> 773 774</blockquote> 775 776<p> The sql plugin has the following configuration options: </p> 777 778<blockquote> 779 780<dl> 781 782<dt>sql_engine</dt> 783 784<dd> 785 786<p> Specify <code>mysql</code> to connect to a MySQL server, 787<code>pgsql</code> for a PostgreSQL server or <code>sqlite</code> 788for an SQLite database </p> 789 790</dd> 791 792<dt>sql_hostnames</dt> 793 794<dd> 795 796<p> Specify one or more servers (hostname or hostname:port) separated 797by commas. </p> 798 799<blockquote> 800 801<strong>Note</strong> 802 803<p> With MySQL servers, specify <code>localhost</code> to connect 804over a UNIX-domain socket, and specify <code>127.0.0.1</code> to 805connect over a TCP socket. </p> 806 807</blockquote> 808 809</dd> 810 811<dt>sql_user</dt> 812 813<dd> 814 815<p> The login name to gain access to the database. </p> 816 817</dd> 818 819<dt>sql_passwd</dt> 820 821<dd> 822 823<p> The password to gain access to the database. </p> 824 825</dd> 826 827<dt>sql_database</dt> 828 829<dd> 830 831<p> The name of the database to connect to. </p> 832 833</dd> 834 835<dt>sql_select</dt> 836 837<dd> 838 839<p> The SELECT statement that should retrieve the plaintext password 840from a database table. </p> 841 842<blockquote> 843 844<strong>Important</strong> 845 846<p> Do not enclose the statement in quotes! Use single quotes to 847escape macros! </p> 848 849</blockquote> 850 851</dd> 852 853</dl> 854 855</blockquote> 856 857<p> The sql plugin provides macros to build <code>sql_select</code> 858statements. They will be replaced with arguments sent from the client. The 859following macros are available: </p> 860 861<blockquote> 862 863<dl> 864 865<dt>%u</dt> 866 867<dd> 868 869<p> The name of the user whose properties are being selected. </p> 870 871</dd> 872 873<dt>%p</dt> 874 875<dd> 876 877<p> The name of the property being selected. While this could technically be 878anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME (where 879MECHNAME is the name of a SASL mechanism). </p> 880 881</dd> 882 883<dt>%r</dt> 884 885<dd> 886 887<p> The name of the realm to which the user belongs. This could be 888the KERBEROS realm, the fully-qualified domain name of the computer 889the SASL application is running on, or the domain after the "@" in a 890username. </p> 891 892</dd> 893 894</dl> 895 896</blockquote> 897 898<h4><a name="auxprop_ldapdb">The ldapdb plugin</a></h4> 899 900<p> The ldapdb auxprop plugin provides access to credentials stored 901in an LDAP server. This plugin requires that SASL client passwords are 902stored as plaintext. </p> 903 904<blockquote> 905 906<strong>Tip</strong> 907 908<p> If you must store encrypted passwords, you cannot use the ldapdb 909auxprop plugin. Instead, you can use "<code>saslauthd -a ldap</code>" 910to query the LDAP database directly, with appropriate configuration 911in <code>saslauthd.conf</code>, <a 912href="http://git.cyrusimap.org/cyrus-sasl/tree/saslauthd/LDAP_SASLAUTHD">as 913described here</a>. You will not be able to use any of the 914methods that require access to plaintext passwords, such as the 915shared-secret methods CRAM-MD5 and DIGEST-MD5. </p> 916 917</blockquote> 918 919<p> The ldapdb plugin implements proxy authorization. This means 920that the ldapdb plugin uses its own username and password to 921authenticate with the LDAP server, before it asks the LDAP server 922for the remote SMTP client's password. The LDAP server then decides 923if the ldapdb plugin is authorized to read the remote SMTP client's 924password. </p> 925 926<p> In a nutshell: Configuring ldapdb means authentication and 927authorization must be configured twice - once in the Postfix SMTP 928server to authenticate and authorize the remote SMTP client, and 929once in the LDAP server to authenticate and authorize the ldapdb 930plugin. </p> 931 932<p> This example configures libsasl to use the ldapdb plugin and 933the plugin to connect to an LDAP server: </p> 934 935<blockquote> 936<pre> 937/etc/sasl2/smtpd.conf: 938 pwcheck_method: auxprop 939 auxprop_plugin: ldapdb 940 mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5 941 ldapdb_uri: ldap://localhost 942 ldapdb_id: proxyuser 943 ldapdb_pw: password 944 ldapdb_mech: DIGEST-MD5 945</pre> 946</blockquote> 947 948<blockquote> 949 950<strong>Important</strong> 951 952<p> Set appropriate permissions if <code>smtpd.conf</code> contains a 953password. The file should be readable by the <code>postfix</code> 954user. </p> 955 956</blockquote> 957 958<blockquote> 959 960<strong>Note</strong> 961 962<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the 963SASL client passwords are stored as plaintext. </p> 964 965</blockquote> 966 967<p> The following is a summary of applicable <code>smtpd.conf</code> 968file entries: </p> 969 970<blockquote> 971 972<dl> 973 974<dt>auxprop_plugin</dt> 975 976<dd> <p> Specify <code>ldapdb</code> to enable the plugin. </p> </dd> 977 978<dt>ldapdb_uri</dt> 979 980<dd> <p> Specify either <code>ldapi://</code> to connect over 981a UNIX-domain socket, <code>ldap://</code> for an unencrypted TCP 982connection, or <code>ldaps://</code> for an encrypted TCP connection. 983</p> </dd> 984 985<dt>ldapdb_id</dt> 986 987<dd> <p> The login name to authenticate the ldapdb plugin to the 988LDAP server (proxy authorization). </p> </dd> 989 990<dt>ldapdb_pw</dt> 991 992<dd> <p> The password (in plaintext) to authenticate the ldapdb 993plugin to the LDAP server (proxy authorization). </p> </dd> 994 995<dt>ldapdb_mech</dt> 996 997<dd> <p> The mechanism to authenticate the ldapdb plugin to the 998LDAP server. </p> 999 1000<blockquote> 1001 1002<strong>Note</strong> 1003 1004<p> Specify a mechanism here that is supported by the LDAP server. 1005</p> 1006 1007</blockquote> 1008 1009</dd> 1010 1011<dt>ldapdb_rc (optional)</dt> 1012 1013<dd> <p> The path to a file containing individual configuration 1014options for the ldapdb LDAP client (libldap). This allows to specify 1015a TLS client certificate which in turn can be used to use the SASL 1016EXTERNAL mechanism. </p> 1017 1018<blockquote> 1019 1020<strong>Note</strong> 1021 1022<p> This mechanism supports authentication over an encrypted transport 1023layer, which is recommended if the plugin must connect to an OpenLDAP 1024server on a remote machine. </p> 1025 1026</blockquote> 1027 1028</dd> 1029 1030<dt>ldapdb_starttls (optional)</dt> 1031 1032<dd> <p> The TLS policy for connecting to the LDAP server. Specify 1033either <code>try</code> or <code>demand</code>. If the option is 1034<code>try</code> the plugin will attempt to establish a TLS-encrypted 1035connection with the LDAP server, and will fallback to an unencrypted 1036connection if TLS fails. If the policy is <code>demand</code> and 1037a TLS-encrypted connection cannot be established, the connection 1038fails immediately. </p> </dd> 1039 1040</dl> 1041 1042</blockquote> 1043 1044<p> When the ldapdb plugin connects to the OpenLDAP server and 1045successfully authenticates, the OpenLDAP server decides if the 1046plugin user is authorized to read SASL account information. </p> 1047 1048<p> The following configuration gives an example of authorization configuration 1049in the OpenLDAP slapd server: </p> 1050 1051<blockquote> 1052<pre> 1053/etc/openldap/slapd.conf: 1054 authz-regexp 1055 uid=(.*),cn=.*,cn=auth 1056 ldap:///dc=example,dc=com??sub?cn=$1 1057 authz-policy to 1058</pre> 1059</blockquote> 1060 1061<p> Here, the <code>authz-regexp</code> option serves for authentication 1062of the ldapdb user. It maps its login name to a DN in the LDAP 1063directory tree where <code>slapd</code> can look up the SASL account 1064information. The <code>authz-policy</code> options defines the 1065authentication policy. In this case it grants authentication 1066privileges "<code>to</code>" the ldapdb plugin. </p> 1067 1068<p> The last configuration step is to tell the OpenLDAP <code>slapd</code> 1069server where ldapdb may search for usernames matching the one given 1070by the mail client. The example below adds an additional attribute 1071ldapdb user object (here: <code>authzTo</code> because the authz-policy 1072is "<code>to</code>") and configures the scope where the login name 1073"proxyuser" may search: </p> 1074 1075<blockquote> 1076<pre> 1077dn: cn=proxyuser,dc=example,dc=com 1078changetype: modify 1079add: authzTo 1080authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com 1081</pre> 1082</blockquote> 1083 1084<p> Use the <code>ldapmodify</code> or <code>ldapadd</code> command 1085to add the above attribute. </p> 1086 1087<blockquote> 1088 1089<strong>Note</strong> 1090 1091<p> Read the chapter "Using SASL" in the <a 1092href="http://www.openldap.org/doc/admin">OpenLDAP Admin Guide</a> 1093for more detailed instructions to set up SASL authentication in 1094OpenLDAP. </p> 1095 1096</blockquote> 1097 1098<h3><a name="server_sasl_enable">Enabling SASL authentication and 1099authorization in the Postfix SMTP server</a></h3> 1100 1101<p> By default the Postfix SMTP server uses the Cyrus SASL 1102implementation. If the Dovecot SASL implementation should be used, 1103specify an <code>smtpd_sasl_type</code> value of <code>dovecot</code> 1104instead of <code>cyrus</code>: </p> 1105 1106<blockquote> 1107<pre> 1108/etc/postfix/main.cf: 1109 smtpd_sasl_type = dovecot 1110</pre> 1111</blockquote> 1112 1113<p> Additionally specify how Postfix SMTP server can find the Dovecot 1114authentication server. This depends on the settings that you have 1115selected in the section "<a href="#server_dovecot_comm">Postfix to 1116Dovecot SASL communication</a>". </p> 1117 1118<ul> 1119 1120<li> <p> If you configured Dovecot for UNIX-domain socket communication, 1121configure Postfix as follows: </p> 1122 1123<pre> 1124/etc/postfix/main.cf: 1125 smtpd_sasl_path = private/auth 1126</pre> 1127 1128<strong>Note</strong> 1129 1130<p> This example uses a pathname relative to the Postfix queue 1131directory, so that it will work whether or not the Postfix SMTP 1132server runs chrooted. </p> 1133 1134<li> <p> If you configured Dovecot for TCP socket communication, 1135configure Postfix as follows. If Dovecot runs on a different machine, 1136replace 127.0.0.1 by that machine's IP address. </p> 1137 1138<pre> 1139/etc/postfix/main.cf: 1140 smtpd_sasl_path = inet:127.0.0.1:12345 1141</pre> 1142 1143<strong>Note</strong> 1144 1145<p> If you specify a remote IP address, information 1146will be sent as plaintext over the network. </p> 1147 1148</ul> 1149 1150<h4><a name="server_sasl_authc">Enabling SASL authentication 1151in the Postfix SMTP server</a></h4> 1152 1153<p> Regardless of the SASL implementation type, enabling SMTP 1154authentication in the Postfix SMTP server always requires setting 1155the <code>smtpd_sasl_auth_enable</code> option: </p> 1156 1157<blockquote> 1158<pre> 1159/etc/postfix/main.cf: 1160 smtpd_sasl_auth_enable = yes 1161</pre> 1162</blockquote> 1163 1164<p> After a "postfix reload", SMTP clients will see the additional 1165capability AUTH in an SMTP session, followed by a list of 1166authentication mechanisms the server supports: </p> 1167 1168<blockquote> 1169<pre> 1170% <strong>telnet server.example.com 25</strong> 1171... 1172220 server.example.com ESMTP Postfix 1173<strong>EHLO client.example.com</strong> 1174250-server.example.com 1175250-PIPELINING 1176250-SIZE 10240000 1177250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 1178... 1179</pre> 1180</blockquote> 1181 1182<p> However not all clients recognize the AUTH capability as defined 1183by the SASL authentication RFC. Some historical implementations expect the 1184server to send an "<code>=</code>" as separator between the AUTH 1185verb and the list of mechanisms that follows it. </p> 1186 1187<p> The <code>broken_sasl_auth_clients</code> configuration option 1188lets Postfix repeat the AUTH statement in a form that these broken 1189clients understand: </p> 1190 1191<blockquote> 1192<pre> 1193/etc/postfix/main.cf: 1194 broken_sasl_auth_clients = yes 1195</pre> 1196</blockquote> 1197 1198<blockquote> 1199 1200<strong>Note</strong> 1201 1202<p> Enable this option for Outlook up to and including version 2003 1203and Outlook Express up to version 6. This option does not hurt other 1204clients. </p> 1205 1206</blockquote> 1207 1208<p> After "postfix reload", the Postfix SMTP server will propagate 1209the AUTH capability twice - once for compliant and once for broken 1210clients: </p> 1211 1212<blockquote> 1213<pre> 1214% <strong>telnet server.example.com 25</strong> 1215... 1216220 server.example.com ESMTP Postfix 1217<strong>EHLO client.example.com</strong> 1218250-server.example.com 1219250-PIPELINING 1220250-SIZE 10240000 1221250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 1222250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5 1223... 1224</pre> 1225</blockquote> 1226 1227<h4><a name="smtpd_sasl_security_options">Postfix SMTP Server policy 1228- SASL mechanism properties</a></h4> 1229 1230<p> The Postfix SMTP server supports policies that limit the SASL 1231mechanisms that it makes available to clients, based on the properties 1232of those mechanisms. The next two sections give examples of how 1233these policies are used. </p> 1234 1235<blockquote> 1236 1237<table border="1"> 1238 1239<tr> <th>Property</th> <th>Description</th> </tr> 1240 1241<tr> <td>noanonymous</td> <td> Don't use mechanisms that permit 1242anonymous authentication. </td> </tr> 1243 1244<tr> <td>noplaintext</td> <td> Don't use mechanisms that transmit 1245unencrypted username and password information. </td> </tr> 1246 1247<tr> <td>nodictionary</td> <td> Don't use mechanisms that are 1248vulnerable to dictionary attacks. </td> </tr> 1249 1250<tr> <td>forward_secrecy</td> <td> Require forward secrecy between 1251sessions (breaking one session does not break earlier sessions). 1252</td> </tr> 1253 1254<tr> <td>mutual_auth</td> <td> Use only mechanisms that authenticate 1255both the client and the server to each other. </td> </tr> 1256 1257</table> 1258 1259</blockquote> 1260 1261<h4><a name="id396877">Unencrypted SMTP session</a></h4> 1262 1263<p> The default policy is to allow any mechanism in the Postfix SMTP server 1264except for those based on anonymous authentication: </p> 1265 1266<blockquote> 1267<pre> 1268/etc/postfix/main.cf: 1269 # Specify a list of properties separated by comma or whitespace 1270 smtpd_sasl_security_options = noanonymous 1271</pre> 1272</blockquote> 1273 1274<blockquote> 1275 1276<strong>Important</strong> 1277 1278<p> Always set at least the <code>noanonymous</code> option. 1279Otherwise, the Postfix SMTP server can give strangers the same 1280authorization as a properly-authenticated client. </p> 1281 1282</blockquote> 1283 1284<h4><a name="id396969">Encrypted SMTP session (TLS)</a></h4> 1285 1286<p> A separate parameter controls Postfix SASL mechanism policy 1287during a TLS-encrypted SMTP session. The default is to copy the 1288settings from the unencrypted session: </p> 1289 1290<blockquote> 1291<pre> 1292/etc/postfix/main.cf: 1293 smtpd_sasl_tls_security_options = $smtpd_sasl_security_options 1294</pre> 1295</blockquote> 1296 1297<p> A more sophisticated policy allows plaintext mechanisms, but 1298only over a TLS-encrypted connection: </p> 1299 1300<blockquote> 1301<pre> 1302/etc/postfix/main.cf: 1303 smtpd_sasl_security_options = noanonymous, noplaintext 1304 smtpd_sasl_tls_security_options = noanonymous 1305</pre> 1306</blockquote> 1307 1308<p> To offer SASL authentication only after a TLS-encrypted session has been 1309established specify this: </p> 1310 1311<blockquote> 1312<pre> 1313/etc/postfix/main.cf: 1314 smtpd_tls_auth_only = yes 1315</pre> 1316</blockquote> 1317 1318<h4><a name="server_sasl_authz">Enabling SASL authorization in the Postfix 1319SMTP server</a></h4> 1320 1321<p> After the client has authenticated with SASL, the Postfix SMTP 1322server decides what the remote SMTP client will be authorized 1323for. Examples of possible SMTP clients authorizations are: </p> 1324 1325<ul> 1326 1327<li> <p> Send a message to a remote recipient. </p> </li> 1328 1329<li> <p> Use a specific envelope sender in the MAIL FROM command. </p> </li> 1330 1331</ul> 1332 1333<p> These permissions are not enabled by default. </p> 1334 1335<h4><a name="server_sasl_authz_relay">Mail relay authorization</a></h4> 1336 1337<p> With <code>permit_sasl_authenticated</code> the Postfix SMTP 1338server can allow 1339SASL-authenticated SMTP clients to send mail to remote destinations. 1340Examples: 1341</p> 1342 1343<blockquote> 1344<pre> 1345# With Postfix 2.10 and later, the mail relay policy is 1346# preferably specified under smtpd_relay_restrictions. 1347/etc/postfix/main.cf: 1348 smtpd_relay_restrictions = 1349 permit_mynetworks 1350 <strong>permit_sasl_authenticated</strong> 1351 reject_unauth_destination 1352</pre> 1353 1354<pre> 1355# Older configurations combine relay control and spam control under 1356# smtpd_recipient_restrictions. To use this example with Postfix ≥ 1357# 2.10 specify "smtpd_relay_restrictions=". 1358/etc/postfix/main.cf: 1359 smtpd_recipient_restrictions = 1360 permit_mynetworks 1361 <strong>permit_sasl_authenticated</strong> 1362 reject_unauth_destination 1363 ...other rules... 1364</pre> 1365</blockquote> 1366 1367<h4><a name="server_sasl_authz_envelope">Envelope sender address 1368authorization</a></h4> 1369 1370<p> By default an SMTP client may specify any envelope sender address 1371in the MAIL FROM command. That is because the Postfix SMTP server 1372only knows the remote SMTP client hostname and IP address, but not 1373the user who controls the remote SMTP client. </p> 1374 1375<p> This changes the moment an SMTP client uses SASL authentication. 1376Now, the Postfix SMTP server knows who the sender is. Given a table 1377of envelope sender addresses and SASL login names, the Postfix SMTP 1378server can decide if the SASL authenticated client is allowed to 1379use a particular envelope sender address: </p> 1380 1381<blockquote> 1382<pre> 1383/etc/postfix/main.cf: 1384 <strong>smtpd_sender_login_maps = hash:/etc/postfix/controlled_envelope_senders</strong> 1385 1386 smtpd_recipient_restrictions = 1387 ... 1388 <strong>reject_sender_login_mismatch</strong> 1389 permit_sasl_authenticated 1390 ... 1391</pre> 1392</blockquote> 1393 1394<p> The <code>controlled_envelope_senders</code> table specifies 1395the binding between a sender envelope address and the SASL login 1396names that own that address: </p> 1397 1398<blockquote> 1399<pre> 1400/etc/postfix/controlled_envelope_senders 1401 # envelope sender owners (SASL login names) 1402 john@example.com john@example.com 1403 helpdesk@example.com john@example.com, mary@example.com 1404 postmaster admin@example.com 1405 @example.net barney, fred, john@example.com, mary@example.com 1406</pre> 1407</blockquote> 1408 1409<p> With this, the <code>reject_sender_login_mismatch</code> 1410restriction above will reject the sender address in the MAIL FROM 1411command if <code>smtpd_sender_login_maps</code> does not specify 1412the SMTP client's login name as an owner of that address. </p> 1413 1414<p> See also <code>reject_authenticated_sender_login_mismatch</code>, 1415<code>reject_known_sender_login_mismatch</code>, and 1416<code>reject_unauthenticated_sender_login_mismatch</code> for additional 1417control over the SASL login name and the envelope sender. </p> 1418 1419<h4><a name="server_sasl_other">Additional SMTP Server SASL options</a></h4> 1420 1421<p> Postfix provides a wide range of SASL authentication configuration 1422options. The next section lists a few that are discussed frequently. 1423See postconf(5) for a complete list. </p> 1424 1425<h4><a name="sasl_access">Per-account access control</a></h4> 1426 1427<p> Postfix can implement policies that depend on the SASL login 1428name (Postfix 2.11 and later). Typically this is used to HOLD or 1429REJECT mail from accounts whose credentials have been compromised. 1430</p> 1431 1432<blockquote> 1433<pre> 1434/etc/postfix/main.cf: 1435 smtpd_recipient_restrictions = 1436 permit_mynetworks 1437 check_sasl_access hash:/etc/postfix/sasl_access 1438 permit_sasl_authenticated 1439 ... 1440 1441/etc/postfix/sasl_access: 1442 # Use this when smtpd_sasl_local_domain is empty. 1443 username HOLD 1444 # Use this when smtpd_sasl_local_domain=example.com. 1445 username@example.com HOLD 1446</pre> 1447</blockquote> 1448 1449<h4><a name="id397172">Default authentication domain</a></h4> 1450 1451<p> Postfix can append a domain name (or any other string) to a 1452SASL login name that does not have a domain part, e.g. "<code>john</code>" 1453instead of "<code>john@example.com</code>": </p> 1454 1455<blockquote> 1456<pre> 1457/etc/postfix/main.cf: 1458 smtpd_sasl_local_domain = example.com 1459</pre> 1460</blockquote> 1461 1462<p> This is useful as a default setting and safety net for misconfigured 1463clients, or during a migration to an authentication method/backend 1464that requires an authentication REALM or domain name, before all 1465SMTP clients are configured to send such information. </p> 1466 1467<h4><a name="id397205">Hiding SASL authentication from clients or 1468networks</a></h4> 1469 1470<p> Some clients insist on using SASL authentication if it is offered, even 1471when they are not configured to send credentials - and therefore 1472they will always fail and disconnect. </p> 1473 1474<p> Postfix can hide the AUTH capability from these clients/networks: </p> 1475 1476<blockquote> 1477<pre> 1478/etc/postfix/main.cf: 1479 smtpd_sasl_exceptions_networks = !192.0.2.171/32, 192.0.2.0/24 1480</pre> 1481</blockquote> 1482 1483<h4><a name="id397226">Adding the SASL login name to mail headers</a></h4> 1484 1485<p> To report SASL login names in Received: message headers (Postfix 1486version 2.3 and later): </p> 1487 1488<blockquote> 1489<pre> 1490/etc/postfix/main.cf: 1491 smtpd_sasl_authenticated_header = yes 1492</pre> 1493</blockquote> 1494 1495<blockquote> 1496 1497<strong>Note</strong> 1498 1499<p> The SASL login names will be shared with the entire world. </p> 1500 1501</blockquote> 1502 1503<h3><a name="server_test">Testing SASL authentication in the Postfix SMTP Server</a></h3> 1504 1505<p> To test the server side, connect (for example, with 1506<code>telnet</code>) to the Postfix SMTP server port and you should 1507be able to have a conversation as shown below. Information sent by 1508the client (that is, you) is shown in <strong>bold</strong> font. 1509</p> 1510 1511<blockquote> 1512<pre> 1513% <strong>telnet server.example.com 25</strong> 1514... 1515220 server.example.com ESMTP Postfix 1516<strong>EHLO client.example.com</strong> 1517250-server.example.com 1518250-PIPELINING 1519250-SIZE 10240000 1520250-ETRN 1521250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 1522250 8BITMIME 1523<strong>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</strong> 1524235 Authentication successful 1525</pre> 1526</blockquote> 1527 1528<p> To test this over a connection that is encrypted with TLS, use 1529<code>openssl s_client</code> instead of <code>telnet</code>: 1530 1531<blockquote> 1532<pre> 1533% <strong>openssl s_client -connect server.example.com:25 -starttls smtp</strong> 1534... 1535220 server.example.com ESMTP Postfix 1536<strong>EHLO client.example.com</strong> 1537...see above example for more... 1538</pre> 1539</blockquote> 1540 1541<p> Instead of <code>AHRlc3QAdGVzdHBhc3M=</code>, specify the 1542base64-encoded form of <code>\0username\0password</code> (the \0 1543is a null byte). The example above is for a user named `<code>test</code>' 1544with password `<code>testpass</code>'. </p> 1545<blockquote> 1546 1547<strong>Caution</strong> 1548 1549<p> When posting logs of the SASL negotiations to public lists, 1550please keep in mind that username/password information is trivial 1551to recover from the base64-encoded form. </p> 1552 1553</blockquote> 1554 1555<p> You can use one of the following commands to generate base64 1556encoded authentication information: </p> 1557 1558<ul> 1559 1560<li> <p> Using a recent version of the <b>bash</b> shell: </p> 1561 1562<blockquote> 1563<pre> 1564% <strong>echo -ne '\000username\000password' | openssl base64</strong> 1565</pre> 1566</blockquote> 1567 1568<p> Some other shells support similar syntax. </p> 1569 1570<li> <p> Using the <b>printf</b> command: </p> 1571 1572<blockquote> 1573<pre> 1574% <strong>printf '\0%s\0%s' '<em>username</em>' '<em>password</em>' | openssl base64</strong> 1575% <strong>printf '\0%s\0%s' '<em>username</em>' '<em>password</em>' | mmencode</strong> 1576</pre> 1577</blockquote> 1578 1579<p> The <strong>mmencode</strong> command is part of the metamail 1580software. </p> 1581 1582<li> <p> Using Perl <b>MIME::Base64</b> (from http://www.cpan.org/): </p> 1583 1584<blockquote> 1585<pre> 1586% <strong>perl -MMIME::Base64 -e \ 1587 'print encode_base64("\0<em>username</em>\0<em>password</em>");'</strong> 1588</pre> 1589</blockquote> 1590 1591<p> If the username or password contain "@", you must specify "\@". </p> 1592 1593<li> <p> Using the <b>gen-auth</b> script: </p> 1594 1595<blockquote> 1596<pre> 1597% <strong>gen-auth plain</strong> 1598username: <strong><em>username</em></strong> 1599password: 1600</pre> 1601</blockquote> 1602 1603<p> The <strong>gen-auth</strong> Perl script was written by John 1604Jetmore and can be found at http://jetmore.org/john/code/gen-auth. </p> 1605 1606</ul> 1607 1608<h2><a name="client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></h2> 1609 1610<p> The Postfix SMTP and the LMTP client can authenticate with a 1611remote SMTP server via the Cyrus SASL framework. At this time, the 1612Dovecot SASL implementation does not provide client functionality. 1613</p> 1614 1615<blockquote> 1616 1617<strong>Note</strong> 1618 1619<p> The examples in this section discuss only the SMTP client. 1620Replace <code>smtp_</code> with <code>lmtp_</code> to get the 1621corresponding LMTP client configuration. </p> 1622 1623</blockquote> 1624 1625<p> You can read more about the following topics: </p> 1626 1627<ul> 1628 1629<li><a href="#client_sasl_enable">Enabling SASL authentication in 1630the Postfix SMTP/LMTP client</a></li> 1631 1632<li><a href="#client_sasl_sender">Configuring sender-dependent SASL 1633authentication</a></li> 1634 1635<li><a href="#client_sasl_policy">Postfix SMTP/LMTP client policy 1636- SASL mechanism <em>properties</em></a></li> 1637 1638<li><a href="#client_sasl_filter">Postfix SMTP/LMTP client policy 1639- SASL mechanism <em>names</em></a></li> 1640 1641</ul> 1642 1643<h3><a name="client_sasl_enable">Enabling SASL authentication in the 1644Postfix SMTP/LMTP client</a></h3> 1645 1646<p> This section shows a typical scenario where the Postfix SMTP 1647client sends all messages via a mail gateway server that requires 1648SASL authentication. </p> 1649 1650<blockquote> 1651 1652<strong> Trouble solving tips: </strong> 1653 1654<ul> 1655 1656<li> <p> If your SASL logins fail with "SASL authentication failure: 1657No worthy mechs found" in the mail logfile, then see the section 1658"<a href="SASL_README.html#client_sasl_policy">Postfix SMTP/LMTP 1659client policy - SASL mechanism <em>properties</em></a>". 1660 1661<li> <p> For a solution to a more obscure class of SASL authentication 1662failures, see "<a href="SASL_README.html#client_sasl_filter">Postfix 1663SMTP/LMTP client policy - SASL mechanism <em>names</em></a>". 1664 1665</ul> 1666 1667</blockquote> 1668 1669<p> To make the example more readable we introduce it in two parts. 1670The first part takes care of the basic configuration, while the 1671second part sets up the username/password information. </p> 1672 1673<blockquote> 1674<pre> 1675/etc/postfix/main.cf: 1676 smtp_sasl_auth_enable = yes 1677 smtp_tls_security_level = encrypt 1678 smtp_sasl_tls_security_options = noanonymous 1679 relayhost = [mail.isp.example] 1680 # Alternative form: 1681 # relayhost = [mail.isp.example]:submission 1682 smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd 1683</pre> 1684</blockquote> 1685 1686<ul> 1687 1688<li> <p> The <code>smtp_sasl_auth_enable</code> setting enables 1689client-side authentication. We will configure the client's username 1690and password information in the second part of the example. </p> 1691</li> 1692 1693<li> <p> The <code>smtp_tls_security_level</code> setting ensures 1694that the connection to the remote smtp server will be encrypted, and 1695<code>smtp_sasl_tls_security_options</code> removes the prohibition on 1696plaintext passwords. </p> 1697 1698<li> <p> The <code>relayhost</code> setting forces the Postfix SMTP 1699to send all remote messages to the specified mail server instead 1700of trying to deliver them directly to their destination. </p> </li> 1701 1702<li> <p> In the <code>relayhost</code> setting, the "<code>[</code>" 1703and "<code>]</code>" prevent the Postfix SMTP client from looking 1704up MX (mail exchanger) records for the enclosed name. </p> </li> 1705 1706<li> <p> The <code>relayhost</code> destination may also specify a 1707non-default TCP port. For example, the alternative form 1708<code>[mail.isp.example]:submission</code> tells Postfix to connect 1709to TCP network port 587, which is reserved for email client 1710applications. </p> </li> 1711 1712<li> <p> The Postfix SMTP client is compatible with SMTP servers 1713that use the non-standard "<code>AUTH=<em>method.</em>...</code>" 1714syntax in response to the EHLO command; this requires no additional 1715Postfix client configuration. </p> </li> 1716 1717<li> <p> With the setting "smtp_tls_wrappermode = yes", the Postfix 1718SMTP client supports the "wrappermode" protocol, which uses TCP 1719port 465 on the SMTP server (Postfix 3.0 and later). </p> </li> 1720 1721<li> <p> With the <code>smtp_sasl_password_maps</code> parameter, 1722we configure the Postfix SMTP client to send username and password 1723information to the mail gateway server. As discussed in the next 1724section, the Postfix SMTP client supports multiple ISP accounts. 1725For this reason the username and password are stored in a table 1726that contains one username/password combination for each mail gateway 1727server. </p> 1728 1729</ul> 1730 1731<blockquote> 1732<pre> 1733/etc/postfix/sasl_passwd: 1734 # destination credentials 1735 [mail.isp.example] username:password 1736 # Alternative form: 1737 # [mail.isp.example]:submission username:password 1738</pre> 1739</blockquote> 1740 1741<blockquote> 1742 1743<strong>Important</strong> 1744 1745<p> Keep the SASL client password file in <code>/etc/postfix</code>, 1746and make the file read+write only for <code>root</code> to protect 1747the username/password combinations against other users. The Postfix 1748SMTP client will still be able to read the SASL client passwords. 1749It opens the file as user <code>root</code> before it drops privileges, 1750and before entering an optional chroot jail. </p> 1751 1752</blockquote> 1753 1754<ul> 1755 1756<li> <p> Use the <code>postmap</code> command whenever you 1757change the <code>/etc/postfix/sasl_passwd</code> file. </p> </li> 1758 1759<li> <p> If you specify the "<code>[</code>" and "<code>]</code>" 1760in the <code>relayhost</code> destination, then you must use the 1761same form in the <code>smtp_sasl_password_maps</code> file. </p> 1762</li> 1763 1764<li> <p> If you specify a non-default TCP Port (such as 1765"<code>:submission</code>" or "<code>:587</code>") in the 1766<code>relayhost</code> destination, then you must use the same form 1767in the <code>smtp_sasl_password_maps</code> file. </p> </li> 1768 1769</ul> 1770 1771<h3><a name="client_sasl_sender">Configuring Sender-Dependent SASL 1772authentication</a></h3> 1773 1774<p> Postfix supports different ISP accounts for different sender 1775addresses (version 2.3 and later). This can be useful when one 1776person uses the same machine for work and for personal use, or when 1777people with different ISP accounts share the same Postfix server. 1778</p> 1779 1780<p> To make this possible, Postfix supports per-sender SASL passwords 1781and per-sender relay hosts. In the example below, the Postfix SMTP 1782client will search the SASL password file by sender address before 1783it searches that same file by destination. Likewise, the Postfix 1784trivial-rewrite(8) daemon will search the per-sender relayhost file, 1785and use the default <code>relayhost</code> setting only as a final 1786resort. </p> 1787 1788<blockquote> 1789<pre> 1790/etc/postfix/main.cf: 1791 smtp_sender_dependent_authentication = yes 1792 sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay 1793 smtp_sasl_auth_enable = yes 1794 smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd 1795 relayhost = [mail.isp.example] 1796 # Alternative form: 1797 # relayhost = [mail.isp.example]:submission 1798</pre> 1799</blockquote> 1800 1801<blockquote> 1802<pre> 1803/etc/postfix/sasl_passwd: 1804 # Per-sender authentication; see also /etc/postfix/sender_relay. 1805 user1@example.com username1:password1 1806 user2@example.net username2:password2 1807 # Login information for the default relayhost. 1808 [mail.isp.example] username:password 1809 # Alternative form: 1810 # [mail.isp.example]:submission username:password 1811</pre> 1812</blockquote> 1813 1814<blockquote> 1815<pre> 1816/etc/postfix/sender_relay: 1817 # Per-sender provider; see also /etc/postfix/sasl_passwd. 1818 user1@example.com [mail.example.com]:submission 1819 user2@example.net [mail.example.net] 1820</pre> 1821</blockquote> 1822 1823<ul> 1824 1825<li> <p> If you are creative, then you can try to combine the two 1826tables into one single MySQL database, and configure different 1827Postfix queries to extract the appropriate information. </p> 1828 1829<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system uses 1830<b>dbm</b> files instead of <b>db</b> files. To find out what lookup 1831tables Postfix supports, use the command "<b>postconf -m</b>". </p> 1832 1833<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>" 1834whenever you change the sasl_passwd table. </p> 1835 1836<li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>" 1837whenever you change the sender_relay table. </p> 1838 1839</ul> 1840 1841<h3><a name="client_sasl_policy">Postfix SMTP/LMTP client policy - 1842SASL mechanism <em>properties</em></a></h3> 1843 1844<p> Just like the Postfix SMTP server, the SMTP client has a policy 1845that determines which SASL mechanisms are acceptable, based on their 1846properties. The next two sections give examples of how these policies 1847are used. </p> 1848 1849<blockquote> 1850 1851<table border="1"> 1852 1853<tr> <th>Property</th> <th>Description</th> </tr> 1854 1855<tr> <td>noanonymous</td> <td> Don't use mechanisms that permit 1856anonymous authentication. </td> </tr> 1857 1858<tr> <td>noplaintext</td> <td> Don't use mechanisms that transmit 1859unencrypted username and password information. </td> </tr> 1860 1861<tr> <td>nodictionary</td> <td> Don't use mechanisms that are 1862vulnerable to dictionary attacks. </td> </tr> 1863 1864<tr> <td>mutual_auth</td> <td> Use only mechanisms that authenticate 1865both the client and the server to each other. </td> </tr> 1866 1867</table> 1868 1869</blockquote> 1870 1871<h4>Unencrypted SMTP session</h4> 1872 1873<p> The default policy is stricter than that of the Postfix SMTP 1874server - plaintext mechanisms are not allowed (nor is any anonymous 1875mechanism): </p> 1876 1877<blockquote> 1878<pre> 1879/etc/postfix/main.cf: 1880 smtp_sasl_security_options = noplaintext, noanonymous 1881</pre> 1882</blockquote> 1883 1884<p> This default policy, which allows no plaintext passwords, leads 1885to authentication failures if the remote server only offers plaintext 1886authentication mechanisms (the SMTP server announces "<code>AUTH 1887PLAIN LOGIN</code>"). In such cases the SMTP client will log the 1888following error message: </p> 1889 1890<blockquote> 1891<pre> 1892SASL authentication failure: No worthy mechs found 1893</pre> 1894</blockquote> 1895 1896<blockquote> 1897 1898<strong>Note</strong> 1899 1900<p> This same error message will also be logged when the 1901<code>libplain.so</code> or <code>liblogin.so</code> modules are 1902not installed in the <code>/usr/lib/sasl2</code> directory. </p> 1903 1904</blockquote> 1905 1906<p> The insecure approach is to lower the security standards and 1907permit plaintext authentication mechanisms: </p> 1908 1909<blockquote> 1910<pre> 1911/etc/postfix/main.cf: 1912 smtp_sasl_security_options = noanonymous 1913</pre> 1914</blockquote> 1915 1916<p> The more secure approach is to protect the plaintext username 1917and password with TLS session encryption. To find out if the remote 1918SMTP server supports TLS, connect to the server and see if it 1919announces STARTTLS support as shown in the example. Information 1920sent by the client (that is, you) is shown in <strong>bold</strong> 1921font. </p> 1922 1923<blockquote> 1924<pre> 1925% <strong>telnet server.example.com 25</strong> 1926... 1927220 server.example.com ESMTP Postfix 1928<strong>EHLO client.example.com</strong> 1929250-server.example.com 1930250-PIPELINING 1931250-SIZE 10240000 1932250-STARTTLS 1933... 1934</pre> 1935</blockquote> 1936 1937<p> Instead of port 25 (smtp), specify port 587 (submission) where 1938appropriate. </p> 1939 1940<h4>Encrypted SMTP session (TLS)</h4> 1941 1942<p> To turn on TLS in the Postfix SMTP client, see TLS_README for 1943configuration details. </p> 1944 1945<p> The smtp_sasl_tls_security_options parameter controls Postfix 1946SASL mechanism policy during a TLS-encrypted SMTP session. The 1947default is to copy the settings from the unencrypted session: </p> 1948 1949<blockquote> 1950<pre> 1951/etc/postfix/main.cf: 1952 smtp_sasl_tls_security_options = $smtp_sasl_security_options 1953</pre> 1954</blockquote> 1955 1956<p> A more sophisticated policy allows plaintext mechanisms, but 1957only over a TLS-encrypted connection: </p> 1958 1959<blockquote> 1960<pre> 1961/etc/postfix/main.cf: 1962 smtp_sasl_security_options = noanonymous, noplaintext 1963 smtp_sasl_tls_security_options = noanonymous 1964</pre> 1965</blockquote> 1966 1967<h3><a name="client_sasl_filter">Postfix SMTP/LMTP client policy - 1968SASL mechanism <em>names</em></a></h3> 1969 1970<p> Given the SASL security options of the previous section, the 1971Cyrus SASL library will choose the most secure authentication 1972mechanism that both the SMTP client and server implement. Unfortunately, 1973that authentication mechanism may fail because the client or server 1974is not configured to use that mechanism.</p> 1975 1976<p> To prevent this, the Postfix SMTP client can filter the names 1977of the authentication mechanisms from the remote SMTP server. Used 1978correctly, the filter hides unwanted mechanisms from the Cyrus SASL 1979library, forcing the library to choose from the mechanisms the 1980Postfix SMTP client filter passes through. </p> 1981 1982<p> The following example filters out everything but the mechanisms 1983<code>PLAIN</code> and <code>LOGIN</code>: </p> 1984 1985<blockquote> 1986<pre> 1987/etc/postfix/main.cf: 1988 smtp_sasl_mechanism_filter = plain, login 1989</pre> 1990</blockquote> 1991 1992<blockquote> 1993 1994<strong>Note</strong> 1995 1996<p> If the remote server does not offer any of the mechanisms on 1997the filter list, authentication will fail. </p> 1998 1999</blockquote> 2000 2001<p> We close this section with an example that passes every mechanism 2002except for <code>GSSAPI</code> and <code>LOGIN</code>: </p> 2003 2004<blockquote> 2005<pre> 2006/etc/postfix/main.cf: 2007 smtp_sasl_mechanism_filter = !gssapi, !login, static:all 2008</pre> 2009</blockquote> 2010 2011<h2><a name="postfix_build">Building Postfix with SASL support</a></h2> 2012 2013<p> As mentioned elsewhere, Postfix supports two SASL implementations: 2014Cyrus SASL (SMTP client and server) and Dovecot SASL (SMTP server 2015only). Both implementations can be built into Postfix simultaneously. 2016</p> 2017 2018<ul> 2019 2020<li><a href="#build_dovecot">Building Dovecot SASL support</a></li> 2021 2022<li><a href="#sasl_support">Building Cyrus SASL support</a></li> 2023 2024</ul> 2025 2026<h3><a name="build_dovecot">Building Dovecot SASL support</a></h3> 2027 2028<p> These instructions assume that you build Postfix from source 2029code as described in the INSTALL document. Some modification may 2030be required if you build Postfix from a vendor-specific source 2031package. </p> 2032 2033<p> Support for the Dovecot version 1 SASL protocol is available 2034in Postfix 2.3 and later. At the time of writing, only server-side 2035SASL support is available, so you can't use it to authenticate the 2036Postfix SMTP client to your network provider's server. </p> 2037 2038<p> Dovecot uses its own daemon process for authentication. This 2039keeps the Postfix build process simple, because there is no need 2040to link extra libraries into Postfix. </p> 2041 2042<p> To generate the necessary Makefiles, execute the following in 2043the Postfix top-level directory: </p> 2044 2045<blockquote> 2046<pre> 2047% <strong>make tidy</strong> # if you have left-over files from a previous build 2048% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH \ 2049 -DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\""</strong> 2050</pre> 2051</blockquote> 2052 2053<p> After this, proceed with "<code>make</code>" as described in 2054the INSTALL document. </p> 2055 2056<strong>Note</strong> 2057 2058<ul> 2059 2060<li> 2061 2062<p> The <code>-DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\"</code> is not 2063necessary; it just makes Postfix configuration a little more 2064convenient because you don't have to specify the SASL plug-in type 2065in the Postfix main.cf file (but this may cause surprises when you 2066switch to a later Postfix version that is built with the default 2067SASL type of <code>cyrus</code>). </p> 2068 2069</li> 2070 2071<li> 2072 2073<p> If you also want support for LDAP or TLS (or for Cyrus SASL), 2074you need to merge their <code>CCARGS</code> and <code>AUXLIBS</code> 2075options into the above command line; see the LDAP_README and 2076TLS_README for details. </p> 2077 2078<blockquote> 2079<pre> 2080% <strong>make tidy</strong> # if you have left-over files from a previous build 2081% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH \ 2082 -DDEF_SERVER_SASL_TYPE=\\\"dovecot\\\" \ 2083 ...<i>CCARGS options for LDAP or TLS etc.</i>..." \ 2084 AUXLIBS="...<i>AUXLIBS options for LDAP or TLS etc.</i>..."</strong> 2085</pre> 2086</blockquote> 2087 2088</li> 2089 2090</ul> 2091 2092<h3><a name="sasl_support">Building Cyrus SASL support</a></h3> 2093 2094<h4><a name="build_sasl">Building the Cyrus SASL library</a></h4> 2095 2096<p> Postfix works with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are 2097available from https://github.com/cyrusimap/cyrus-sasl/releases. </p> 2098 2099<blockquote> 2100 2101<strong>Important</strong> 2102 2103<p> If you install the Cyrus SASL libraries as per the default, you will have 2104to create a symlink <code>/usr/lib/sasl</code> -> 2105<code>/usr/local/lib/sasl</code> for version 1.5.x or 2106<code>/usr/lib/sasl2</code> -> <code>/usr/local/lib/sasl2</code> 2107for version 2.1.x. </p> 2108 2109</blockquote> 2110 2111<p> Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN 2112and/or NTLM authentication mechanism. To enable these authentication 2113mechanisms, build the Cyrus SASL libraries with: </p> 2114 2115<blockquote> 2116<pre> 2117% <strong>./configure --enable-login --enable-ntlm</strong> 2118</pre> 2119</blockquote> 2120 2121<h4><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h4> 2122 2123<p> These instructions assume that you build Postfix from source 2124code as described in the INSTALL document. Some modification may 2125be required if you build Postfix from a vendor-specific source 2126package. </p> 2127 2128<p> The following assumes that the Cyrus SASL include files are in 2129<code>/usr/local/include</code>, and that the Cyrus SASL libraries are in 2130<code>/usr/local/lib</code>. </p> 2131 2132<p> On some systems this generates the necessary <code>Makefile</code> 2133definitions: </p> 2134 2135<dl> 2136 2137<dt>Cyrus SASL version 2.1.x</dt> 2138 2139<dd> 2140 2141<pre> 2142% <strong>make tidy</strong> # if you have left-over files from a previous build 2143% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ 2144 -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"</strong> 2145</pre> 2146 2147<p> If your Cyrus SASL shared library is in a directory that the RUN-TIME 2148linker does not know about, add a "-Wl,-R,/path/to/directory" option after 2149"-lsasl2". </p> 2150 2151</dd> 2152 2153<dt>Cyrus SASL version 1.5.x</dt> 2154 2155<dd> 2156 2157<pre> 2158% <strong>make tidy</strong> # if you have left-over files from a previous build 2159% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ 2160 -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"</strong> 2161</pre> 2162 2163</dd> 2164 2165</dl> 2166 2167<p> On Solaris 2.x you need to specify run-time link information, 2168otherwise the ld.so run-time linker will not find the SASL shared 2169library: </p> 2170 2171<dl> 2172 2173<dt>Cyrus SASL version 2.1.x</dt> 2174 2175<dd> 2176 2177<pre> 2178% <strong>make tidy</strong> # remove left-over files from a previous build 2179% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ 2180 -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \ 2181 -R/usr/local/lib -lsasl2"</strong> 2182</pre> 2183 2184</dd> 2185 2186<dt>Cyrus SASL version 1.5.x</dt> 2187 2188<dd> 2189 2190<pre> 2191% <strong>make tidy</strong> # if you have left-over files from a previous build 2192% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \ 2193 -I/usr/local/include" AUXLIBS="-L/usr/local/lib \ 2194 -R/usr/local/lib -lsasl"</strong> 2195</pre> 2196 2197</dd> 2198 2199</dl> 2200 2201<h2><a name="cyrus_legacy">Using Cyrus SASL version 1.5.x</a></h2> 2202 2203<p> Postfix supports Cyrus SASL version 1.x, but you shouldn't use 2204it unless you are forced to. The makers of Cyrus SASL write: </p> 2205 2206<blockquote> <i> This library is being deprecated and applications 2207should transition to using the SASLv2 library</i> (source: <a 2208href="http://www.cyrusimap.org/download.html">Project Cyrus: 2209Downloads</a>). </blockquote> 2210 2211<p> If you still need to set it up, here's a quick rundown: </p> 2212 2213<p> Read the regular section on SMTP server configurations for the 2214Cyrus SASL framework. The differences are: </p> 2215 2216<ul> 2217 2218<li> <p> Cyrus SASL version 1.5.x searches for configuration 2219(<code>smtpd.conf</code>) in <code>/usr/lib/sasl/</code> only. You 2220must place the configuration in that directory. Some systems may 2221have modified Cyrus SASL and put the files into e.g. 2222<code>/var/lib/sasl/</code>. </p> </li> 2223 2224<li> <p> Use the <code>saslpasswd</code> command instead of 2225<code>saslpasswd2</code> to create users in <code>sasldb</code>. 2226</p> </li> 2227 2228<li> <p> Use the <code>sasldblistusers</code> command instead of 2229<code>sasldblistusers2</code> to find users in <code>sasldb</code>. 2230</p> </li> 2231 2232<li> <p> In the <code>smtpd.conf</code> file you can't use 2233<code>mech_list</code> to limit the range of mechanisms offered. 2234Instead, remove their libraries from <code>/usr/lib/sasl/</code> 2235(and remember remove those files again when a system update 2236re-installs new versions). </p> </li> 2237 2238</ul> 2239 2240<h2><a name="credits">Credits</a></h2> 2241 2242<ul> 2243 2244<li> Postfix SASL support was originally implemented by Till Franke 2245of SuSE Rhein/Main AG. </li> 2246 2247<li> Wietse trimmed down the code to only the bare necessities. 2248 </li> 2249 2250<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos. 2251</li> 2252 2253<li> Liviu Daia added smtpd_sasl_application_name, separated 2254reject_sender_login_mismatch into 2255reject_authenticated_sender_login_mismatch and 2256reject_unauthenticated_sender_login_mismatch, and revised the docs. 2257 </li> 2258 2259<li> Wietse made another iteration through the code to add plug-in 2260support for multiple SASL implementations, and for reasons that 2261have been lost, also changed smtpd_sasl_application_name into 2262smtpd_sasl_path. </li> 2263 2264<li> The Dovecot SMTP server-only plug-in was originally implemented 2265by Timo Sirainen of Procontrol, Finland. </li> 2266 2267<li> Patrick Ben Koetter revised this document for Postfix 2.4 and 2268made much needed updates. </li> 2269 2270<li> Patrick Ben Koetter revised this document again for Postfix 22712.7 and made much needed updates. </li> 2272 2273</ul> 2274 2275</body> 2276 2277</html> 2278 2279
