22
<p> People who go to the trouble of installing Postfix may have
23
the expectation that Postfix is more secure than some other mailers.
24
The Cyrus SASL library is a lot of code. With SASL authentication
25
enabled in the Postfix SMTP client and SMTP server, Postfix becomes
22
<p> People who go to the trouble of installing Postfix may have the
23
expectation that Postfix is more secure than some other mailers.
24
The Cyrus SASL library is a lot of code. With this, Postfix becomes
26
25
as secure as other mail systems that use the Cyrus SASL library.
26
Dovecot provides an alternative that may be worth considering.
29
29
<h2><a name="intro">How Postfix uses SASL authentication information</a></h2>
37
37
optionally grants mail access via the <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
38
38
UCE restriction. </p>
40
<p> Postfix does not record the client's SASL authentication
41
information in message headers, and does not pass it on via SMTP
42
commands when forwarding mail, because it is no-one else's business
43
to know the client username and authentication method. People who
44
need to know can find the information in the local Postfix maillog
45
file. Some day, Postfix message headers will be configurable and
46
then one can record the SASL username without having to edit C
40
<p> When sending mail, Postfix can look up the server hostname or
41
destination domain (the address right-hand part) in a Postfix SASL password
42
table, and if a username/password is found, it will use that username
43
and password to authenticate to the server. And as of version 2.3,
44
Postfix can be configured to search its SASL password table by the
45
sender email address. </p>
49
47
<p>This document covers the following topics: </p>
53
<li><a href="#versions">What SASL versions are supported</a>
55
<li><a href="#build_sasl">Building the SASL library</a>
57
<li><a href="#build_postfix">Building Postfix with SASL authentication
51
<li><a href="#versions">What SASL implementations are supported</a>
53
<li><a href="#build_dovecot">Building Postfix with Dovecot SASL
56
<li><a href="#build_sasl">Building the Cyrus SASL library</a>
58
<li><a href="#build_postfix">Building Postfix with Cyrus SASL
60
61
<li><a href="#server_sasl">Enabling SASL authentication in the
61
62
Postfix SMTP server</a></li>
64
<li><a href="#server_dovecot">Dovecot SASL configuration for the Postfix
67
<li><a href="#server_cyrus">Cyrus SASL configuration for the Postfix
63
70
<li><a href="#server_test">Testing SASL authentication in the
64
71
Postfix SMTP server</a></li>
75
<p> When sending mail, Postfix can look up the server hostname or
76
destination domain (the address right-hand part) in a table, and if a
77
username/password is found, it will use that username and password
78
to authenticate to the server. </p>
80
<h2><a name="versions">What SASL versions are supported</a></h2>
82
<p> Postfix+SASL 1.5.5 was seen working on RedHat 6.1 (pwcheck_method
83
set to shadow or sasldb), Solaris 2.7 (pwcheck_method set to shadow
84
or sasldb), and FreeBSD 3.4 (pwcheck_method set to sasldb). On
85
RedHat 6.1, SASL 1.5.5 insisted on write access to /etc/sasldb.
86
Note that this seems to be related to the auto_transition switch
87
in SASL. Note also that the Cyrus SASL documentation says that it
88
is pointless to enable that if you use "sasldb" for "pwcheck_method".
89
Later versions of the SASL 1.5.x series should also work. </p>
91
<p> Postfix+SASL 2.1.1 appears to work on Mandrake Linux 8.1
92
(pwcheck_method set to saslauthd or auxprop). Note that the
93
'auxprop' pwcheck_method replaces the 'sasldb' method from SASL
94
1.5.x. Postfix may need write access to /etc/sasldb2 if you use
95
the auto_transition feature, or if you use an authentication
96
mechanism such as OTP (one-time passwords) that needs to update
97
secrets in the database. </p>
99
<h2><a name="build_sasl">Building the SASL library</a></h2>
82
<h2><a name="versions">What SASL implementations are supported</a></h2>
84
<p> This document describes Postfix with the following SASL
89
<li> <p> Cyrus SASL version 1 (client and server). </p>
91
<li> <p> Cyrus SASL version 2 (client and server). </p>
93
<li> <p> Dovecot protocol version 1 (server only, Postfix version
98
<p> Postfix version 2.3 introduces a plug-in mechanism that provides
99
support for multiple SASL implementations. To find out what
100
implementations are built into Postfix, use the following commands:
105
% postconf -a (SASL support in the SMTP server)
106
% postconf -A (SASL support in the SMTP+LMTP client)
110
<p> Needless to say, these commands are not available in earlier
111
Postfix versions. </p>
113
<h2><a name="build_dovecot">Building Postfix with Dovecot SASL
116
<p> Dovecot SASL support is available in Postfix 2.3 and later. The
117
Dovecot source code is available via <a href="http://www.dovecot.org/">http://www.dovecot.org/</a>. At
119
of writing, only server-side SASL support is available, so you can't
120
use it to authenticate to your network provider's server. Dovecot
121
uses its own daemon process for authentication. This keeps the
122
Postfix build process simple, because there is no need to link extra
123
libraries into Postfix. </p>
125
<p> To generate the necessary Makefiles, execute the following
126
in the Postfix top-level directory: </p>
130
% make makefiles CCARGS='-DUSE_SASL_AUTH -DDEF_SASL_SERVER_TYPE=\"dovecot\"'
134
<p> After this, proceed with "<tt>make</tt>" as described in the
135
<a href="INSTALL.html">INSTALL</a> document. </p>
141
<li> <p> The "-DDEF_SASL_SERVER_TYPE" stuff is not necessary; it just
142
makes Postfix configuration a little more convenient because you
143
don't have to specify the SASL plug-in type in the Postfix <a href="postconf.5.html">main.cf</a>
146
<li> <p> If you also want support for LDAP or TLS, you will have to merge
147
their CCARGS and AUXLIBS into the above command line. </p>
151
<h2><a name="build_sasl">Building the Cyrus SASL library</a></h2>
101
153
<p> Postfix appears to work with cyrus-sasl-1.5.5 or cyrus-sasl-2.1.1,
102
154
which are available from: </p>
106
<a href="ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/">ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/</a>.
158
<a href="ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/">ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/</a>
131
<dt> (for SASL version 1.5.5):
182
<dt> (for Cyrus SASL version 1.5.5):
134
185
% make tidy # if you have left-over files from a previous build
135
% make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include" \
136
AUXLIBS="-L/usr/local/lib -lsasl"
186
% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
187
-I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
139
<dt> (for SASL version 2.1.1):
190
<dt> (for Cyrus SASL version 2.1.1):
142
193
% make tidy # if you have left-over files from a previous build
143
% make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \
144
AUXLIBS="-L/usr/local/lib -lsasl2"
194
% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
195
-I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
154
<dt> (for SASL version 1.5.5):
205
<dt> (for Cyrus SASL version 1.5.5):
157
208
% make tidy # if you have left-over files from a previous build
158
% make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include" \
159
AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl"
209
% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
210
-I/usr/local/include" AUXLIBS="-L/usr/local/lib \
211
-R/usr/local/lib -lsasl"
162
<dt> (for SASL version 2.1.1):
214
<dt> (for Cyrus SASL version 2.1.1):
165
217
% make tidy # if you have left-over files from a previous build
166
% make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \
167
AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl2"
218
% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
219
-I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
220
-R/usr/local/lib -lsasl2"
188
/etc/postfix/main.cf:
241
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
189
242
<a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
190
243
<a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a> <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a> ...
194
<p> In /usr/local/lib/sasl/smtpd.conf (SASL version 1.5.5) or
195
/usr/local/lib/sasl2/smtpd.conf (SASL version 2.1.1) you need to
247
<p> To report SASL login names in Received: message headers
248
(Postfix version 2.3 and later): </p>
252
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
253
<a href="postconf.5.html#smtpd_sasl_authenticated_header">smtpd_sasl_authenticated_header</a> = yes
257
<p> Note: the SASL login names will be shared with the entire world.
260
<p> Older Microsoft SMTP client software implements a non-standard
261
version of the AUTH protocol syntax, and expects that the SMTP
262
server replies to EHLO with "250 AUTH=stuff" instead of "250 AUTH
263
stuff". To accommodate such clients (in addition to conformant
264
clients) use the following: </p>
268
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
269
<a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> = yes
273
<h2><a name="server_dovecot">Dovecot SASL configuration for the
274
Postfix SMTP server</a></h2>
276
<p> Dovecot SASL support is available in Postfix 2.3 and later. On
277
the Postfix side you need to specify the location of the
278
Dovecot authentication daemon socket. We use a pathname relative
279
to the Postfix queue directory, so that it will work whether or not
280
Postfix runs chrooted: </p>
284
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
285
<a href="postconf.5.html#smtpd_sasl_type">smtpd_sasl_type</a> = dovecot
286
<a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = private/auth
290
<p> On the Dovecot side you also need to specify the Dovecot
291
authentication daemon socket. In this case we specify an
292
absolute pathname. In the example we assume that the
293
Postfix queue is under /var/spool/postfix/. </p>
297
/some/where/dovecot.conf:
299
mechanisms = plain login
306
path = /var/spool/postfix/private/auth
316
<p> See the Dovecot documentation for how to configure and operate
317
the Dovecot authentication server. </p>
319
<h2><a name="server_cyrus">Cyrus SASL configuration for the Postfix
322
<p> In /usr/local/lib/sasl/smtpd.conf (Cyrus SASL version 1.5.5) or
323
/usr/local/lib/sasl2/smtpd.conf (Cyrus SASL version 2.1.1) you need to
196
324
specify how the server should validate client passwords. </p>
198
<p> In order to authenticate against the UNIX password database, try: </p>
326
<p> Note: some Postfix distributions are modified and look for
327
the smtpd.conf file in /etc/postfix. </p>
329
<p> Note: some Cyrus SASL distributions look for the smtpd.conf
330
file in /etc/sasl2. </p>
334
<li> <p> To authenticate against the UNIX password database, try: </p>
201
<dt> (SASL version 1.5.5)
337
<dt> (Cyrus SASL version 1.5.5)
204
340
/usr/local/lib/sasl/smtpd.conf:
232
370
permission for the /var/pwcheck directory, otherwise authentication
233
371
attempts will fail. </p>
235
<p> Alternately, in SASL 1.5.26 and later (including 2.1.1), try: </p>
373
<li> <p> Alternately, in Cyrus SASL 1.5.26 and later (including
239
<dt> (SASL version 1.5.26)
378
<dt> (Cyrus SASL version 1.5.26)
242
381
/usr/local/lib/sasl/smtpd.conf:
243
382
pwcheck_method: saslauthd
246
<dt> (SASL version 2.1.1)
385
<dt> (Cyrus SASL version 2.1.1)
249
388
/usr/local/lib/sasl2/smtpd.conf:
257
396
can authenticate against PAM and various other sources. To use PAM,
258
397
start saslauthd with "-a pam". </p>
260
<p> In order to authenticate against SASL's own password database: </p>
399
<li> <p> To authenticate against Cyrus SASL's own password database: </p>
263
<dt> (SASL version 1.5.5)
402
<dt> (Cyrus SASL version 1.5.5)
266
405
/usr/local/lib/sasl/smtpd.conf:
267
406
pwcheck_method: sasldb
270
<dt> (SASL version 2.1.1)
409
<dt> (Cyrus SASL version 2.1.1)
273
412
/usr/local/lib/sasl2/smtpd.conf:
279
<p> This will use the SASL password file (default: /etc/sasldb in
418
<p> This will use the Cyrus SASL password file (default: /etc/sasldb in
280
419
version 1.5.5, or /etc/sasldb2 in version 2.1.1), which is maintained
281
420
with the saslpasswd or saslpasswd2 command (part of the Cyrus SASL
282
421
software). On some poorly-supported systems the saslpasswd command needs
283
422
to be run multiple times before it stops complaining. The Postfix SMTP
284
423
server needs read access to the sasldb file - you may have to play games
285
424
with group access permissions. With the OTP authentication mechanism,
286
the SMTP server also needs write access to /etc/sasldb2 or /etc/sasldb
425
the SMTP server also needs WRITE access to /etc/sasldb2 or /etc/sasldb
287
426
(or the back end SQL database, if used). </p>
428
<p> IMPORTANT: To get sasldb running, make sure that you set the SASL
429
domain (realm) to a fully qualified domain name. </p>
434
<dt> (Cyrus SASL version 1.5.5)
437
% saslpasswd -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
440
<dt> (Cyrus SASL version 2.1.1)
443
% saslpasswd2 -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
448
<p> You can find out SASL's idea about the realms of the users
449
in sasldb with <i>sasldblistusers</i> (Cyrus SASL version 1.5.5) or
450
<i>sasldblistusers2</i> (Cyrus SASL version 2.1.1). </p>
452
<p> On the Postfix side, you can have only one realm per smtpd
453
instance, and only the users belonging to that realm would be able to
454
authenticate. The Postfix variable <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> controls the
455
realm used by smtpd: </p>
459
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
460
<a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
289
466
<p> IMPORTANT: all users must be able to authenticate using ALL
290
467
authentication mechanisms advertised by Postfix, otherwise the
291
468
negotiation might end up with an unsupported mechanism, and
323
<p> IMPORTANT: To get sasldb running, make sure that you set the SASL
324
domain (realm) to a fully qualified domain name. </p>
329
<dt> (SASL version 1.5.5)
332
% saslpasswd -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
335
<dt> (SASL version 2.1.1)
338
% saslpasswd2 -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
343
<p> You can find out SASL's idea about the realms of the users
344
in sasldb with <i>sasldblistusers</i> (SASL version 1.5.5) or
345
<i>sasldblistusers2</i> (SASL version 2.1.1). </p>
347
<p> On the Postfix side, you can have only one realm per smtpd
348
instance, and only the users belonging to that realm would be able to
349
authenticate. The Postfix variable <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> controls the
350
realm used by smtpd: </p>
354
/etc/postfix/main.cf:
355
<a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
359
517
<p> To run software chrooted with SASL support is an interesting
360
518
exercise. It probably is not worth the trouble. </p>
362
<p> Older Microsoft SMTP client software implements a non-standard
363
version of the AUTH protocol syntax, and expects that the SMTP
364
server replies to EHLO with "250 AUTH=stuff" instead of "250 AUTH
365
stuff". To accommodate such clients in addition to conformant
366
clients, set "<a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> = yes" in the main.cf file.
369
520
<h2><a name="server_test">Testing SASL authentication in the Postfix
370
521
SMTP server</a></h2>
437
589
<h2><a name="client_sasl">Enabling SASL authentication in the
438
590
Postfix SMTP client</a></h2>
440
<p> Turn on client-side SASL authentication, and specify a table with
441
per-host or per-destination username and password information.
442
Postfix first looks up the server hostname; if no entry is found,
443
then Postfix looks up the destination domain name (usually, the
444
right-hand part of an email address). </p>
448
/etc/postfix/main.cf:
449
<a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
450
<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
452
/etc/postfix/sasl_passwd:
453
foo.com username:password
592
<p> Turn on client-side SASL authentication, and specify a table
593
with per-host or per-destination username and password information.
594
Postfix first searches the table for an entry with the server
595
hostname; if no entry is found, then Postfix searches the table for
596
an entry with the next-hop destination. Usually, that is the
597
right-hand part of an email address, but it can also be the information
598
that is specified with the <a href="postconf.5.html#relayhost">relayhost</a> parameter or with a <a href="transport.5.html">transport(5)</a>
603
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
604
<a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
605
<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
606
<a href="postconf.5.html#smtp_sasl_type">smtp_sasl_type</a> = cyrus
608
/etc/postfix/sasl_passwd:
609
foo.com username:password
611
[mail.myisp.net] username:password
612
[mail.myisp.net]:submission username:password
616
<p> Postfix version 2.3 supports-per-sender SASL password
617
information. To search the Postfix SASL password by sender
618
before it searches by destination, specify: </p>
622
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
623
<a href="postconf.5.html#smtp_sender_dependent_authentication">smtp_sender_dependent_authentication</a> = yes
624
<a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
625
<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
627
/etc/postfix/sasl_passwd:
628
user@example.com username:password
630
[mail.myisp.net] username:password
631
[mail.myisp.net]:submission username:password
478
655
possess the appropriate credentials to authenticate to the server. It
479
656
is possible via the <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> parameter to further
480
657
restrict the list of server mechanisms that the <a href="smtp.8.html">smtp(8)</a> client will take
481
into consideration. </p>
658
into consideration: </p>
662
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
663
<a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = !gssapi, !external, static:all
667
<p> In the above example, Postfix will decline to use mechanisms
668
that require special infrastructure such as Kerberos. </p>
483
670
<p> The Postfix SMTP client is backwards compatible with SMTP
484
671
servers that use the non-standard "AUTH=method..." syntax in response
495
682
<li> Wietse trimmed down the code to only the bare necessities.
497
<li> Support for SASL version 2 was contributed by Jason Hoos.
684
<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
499
<li> Liviu Daia added <a href="postconf.5.html#smtpd_sasl_application_name">smtpd_sasl_application_name</a>, split
686
<li> Liviu Daia added smtpd_sasl_application_name, split
500
687
<a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a> into
501
688
<a href="postconf.5.html#reject_authenticated_sender_login_mismatch">reject_authenticated_sender_login_mismatch</a> and
502
689
<a href="postconf.5.html#reject_unauthenticated_sender_login_mismatch">reject_unauthenticated_sender_login_mismatch</a>, and revised the docs.
691
<li> Wietse made another iteration through the code to add plug-in
692
support for multiple SASL implementations, and changed
693
smtpd_sasl_application_name into <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a>.
695
<li> The Dovecot SMTP server-only plug-in was originally implemented by
696
Timo Sirainen of Procontrol, Finland.
added
removed
html/SASL_README.html
