~ubuntu-branches/debian/sid/postfix/sid

"<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt". According to <a href="http://tools.ietf.org/html/rfc2487">RFC 2487</a> this

417

MUST NOT be applied in case

488

418

of a publicly-referenced Postfix SMTP server. This option is off

489

419

by default and should only seldom be used.

490

420

493

423

494

424

<pre>

495

425

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

496

# Postfix 2.3 and later

497

426

<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt

498

# Obsolete, but still supported

499

<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes

500

427

</pre>

501

428

</blockquote>

502

429

538

465

this option is "off" by default. You will however need the certificate

539

466

if you want to use certificate based relaying with, for example, the

540

467

<a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> feature. A server that wants client certificates

541

must first present its own certificate. While Postfix 2.3 by default

468

must first present its own certificate. While Postfix by default

542

469

offers anonymous ciphers to remote SMTP clients, these are automatically

543

470

suppressed

544

471

when the Postfix SMTP server is configured to ask for client

550

477

<pre>

551

478

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

552

479

<a href="postconf.5.html#smtpd_tls_ask_ccert">smtpd_tls_ask_ccert</a> = yes

553

# Postfix 2.3 and later

554

480

<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may

555

# Obsolete, but still supported

556

<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> = yes

557

481

</pre>

558

482

</blockquote>

559

483

570

494

<pre>

571

495

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

572

496

<a href="postconf.5.html#smtpd_tls_req_ccert">smtpd_tls_req_ccert</a> = yes

573

# Postfix 2.3 and later

574

497

<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt

575

# Obsolete, but still supported

576

<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes

577

498

</pre>

578

499

</blockquote>

579

500

604

525

605

526

Sending AUTH data over an unencrypted channel poses a security

606

527

risk. When TLS layer encryption is required

607

("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt" or the obsolete

608

"<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = yes"), the Postfix SMTP server will

528

("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = encrypt"), the Postfix SMTP server will

609

529

announce and accept AUTH only after the TLS layer has been activated

610

530

with STARTTLS. When TLS layer encryption is optional

611

("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may" or the obsolete

612

"<a href="postconf.5.html#smtpd_enforce_tls">smtpd_enforce_tls</a> = no"), it may however still be useful

531

("<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may"), it may however still be useful

613

532

to only offer AUTH when TLS is active. To maintain compatibility

614

533

with non-TLS clients, the default is to accept AUTH without encryption.

615

534

In order to change this behavior, set

693

612

694

613

<dl>

695

614

696

<dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> Allow the remote SMTP client

697

request if the client certificate fingerprint is listed in the

698

client certificate table (see <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below).

699

</dd>

615

<dt> <a href="postconf.5.html#permit_tls_clientcerts">permit_tls_clientcerts</a> </dt> <dd> Allow the remote SMTP

616

client request if the client certificate fingerprint or certificate

617

public key fingerprint (Postfix 2.9 and later) is listed in the

618

client certificate table (see <a href="postconf.5.html#relay_clientcerts">relay_clientcerts</a> discussion below).

619

</dd>

700

620

701

621

<dt> <a href="postconf.5.html#permit_tls_all_clientcerts">permit_tls_all_clientcerts</a> </dt> <dd> Allow the remote SMTP

702

622

client request if the client certificate passes trust chain verification.

703

623

Useful with private-label CAs that only issue certificates to trusted

704

624

clients (and not otherwise). </dd>

705

625

706

<dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> Use the remote SMTP

707

client

708

certificate fingerprint as the lookup key for the specified <a href="access.5.html">access(5)</a>

626

<dt> <a href="postconf.5.html#check_ccert_access">check_ccert_access</a> <a href="DATABASE_README.html">type:table</a></dt> <dd> Use the remote

627

SMTP client certificate fingerprint or public key fingerprint

628

(Postfix 2.9 and later) as the lookup key for the specified <a href="access.5.html">access(5)</a>

709

629

table. </dd>

710

630

711

631

</dl>

712

632

713

633

</blockquote>

714

634

715

The digest algorithm used to construct the client certificate

635

The digest algorithm used to compute the client certificate

716

636

fingerprints is specified with the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtpd_tls_fingerprint_digest">smtpd_tls_fingerprint_digest</a>

717

637

parameter. The default is "md5", for compatibility with Postfix

718

638

versions < 2.5.

759

679

760

680

<h3><a name="server_cipher">Server-side cipher controls</a> </h3>

761

681

762

The description below is for Postfix 2.3; for Postfix < 2.3 the

763

<a href="postconf.5.html#smtpd_tls_cipherlist">smtpd_tls_cipherlist</a> parameter specifies the acceptable ciphers as an

764

explicit OpenSSL cipherlist. The obsolete setting applies even when TLS

765

encryption is not enforced. Use of this control on public MX hosts is

766

strongly discouraged.

767

768

682

The Postfix SMTP server supports 5 distinct cipher security levels

769

683

as specified by the <a href="postconf.5.html#smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a> configuration parameter,

770

684

which determines the cipher grade with mandatory TLS encryption. The

796

710

corresponding <a href="postconf.5.html#smtpd_tls_protocols">smtpd_tls_protocols</a> parameter (Postfix ≥ 2.6)

797

711

controls the SSL/TLS protocols used with opportunistic TLS.

798

712

799

For a server that is not a public Internet MX host, Postfix (≥ 2.3)

713

For a server that is not a public Internet MX host, Postfix

800

714

supports configurations with no <a href="#server_cert_key">server

801

715

certificates</a> that use only the anonymous ciphers. This is

802

716

enabled by explicitly setting "<a href="postconf.5.html#smtpd_tls_cert_file">smtpd_tls_cert_file</a> = none"

921

835

922

836

<ul>

923

837

924

<li><a href="#client_lmtp_tls"> TLS support in the LMTP delivery agent </a>

838

<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>

839

840

<li><a href="#client_logging"> Client-side TLS activity logging </a>

925

841

926

842

<li><a href="#client_cert_key">Client-side certificate and private

927

843

key configuration </a>

928

844

929

<li><a href="#client_logging"> Client-side TLS activity logging

930

</a>

931

932

845

<li><a href="#client_tls_cache">Client-side TLS session cache</a>

933

846

934

847

<li><a href="#client_tls_limits"> Client TLS limitations </a>

935

848

936

<li><a href="#client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>

937

938

849

<li><a href="#client_tls_policy"> Per-destination TLS policy </a>

939

850

940

<li><a href="#client_tls_obs"> Obsolete per-site TLS policy support </a>

941

942

<li><a href="#client_tls_harden"> Closing a DNS loophole with obsolete per-site TLS policies </a>

943

944

851

<li><a href="#client_tls_discover"> Discovering servers that support TLS </a>

945

852

946

853

<li><a href="#client_vrfy_server">Server certificate verification depth</a>

953

860

954

861

</ul>

955

862

956

<h3><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a>

957

</h3>

958

959

The <a href="smtp.8.html">smtp(8)</a> and <a href="lmtp.8.html">lmtp(8)</a> delivery agents are implemented by a

960

single dual-purpose program. Specifically, all the TLS features

961

described below apply

962

equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each

963

parameter name with "lmtp_".

964

965

The Postfix LMTP delivery agent can communicate with LMTP servers

966

listening

967

on UNIX-domain sockets. When server certificate verification is enabled

968

and the server is listening on a UNIX-domain socket, the $<a href="postconf.5.html#myhostname">myhostname</a>

969

parameter is used to set the TLS verification nexthop and

970

hostname. Note, opportunistic encryption of LMTP traffic over

971

UNIX-domain sockets is futile. TLS is only useful in this context when

972

it is mandatory, typically to allow at least one of the server or the

973

client to authenticate the other. The "null" cipher grade may be

974

appropriate in this context, when available on both client and server.

975

The "null" ciphers provide authentication without encryption.

976

977

<h3><a name="client_cert_key">Client-side certificate and private

978

key configuration </a> </h3>

979

980

Do not configure Postfix SMTP client certificates unless you must

981

present

982

client TLS certificates to one or more servers. Client certificates are

983

not usually needed, and can cause problems in configurations that work

984

well without them. The recommended setting is to let the defaults stand:

985

986

987

<pre>

988

<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> =

989

<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> =

990

<a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> =

991

<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> =

992

# Postfix ≥ 2.6

993

<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> =

994

<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> =

995

</pre>

996

</blockquote>

997

998

The best way to use the default settings is to comment out the above

999

parameters in <a href="postconf.5.html">main.cf</a> if present.

1000

1001

During TLS startup negotiation the Postfix SMTP client may present

1002

a certificate to the remote SMTP server. The Netscape client is

1003

rather clever here and lets the user select between only those

1004

certificates that match CA certificates offered by the remote SMTP

1005

server. As the Postfix SMTP client uses the "SSL_connect()" function

1006

from the OpenSSL package, this is not possible and we have to choose

1007

just one certificate. So for now the default is to use _no_

1008

certificate and key unless one is explicitly specified here.

1009

1010

RSA, DSA and ECDSA (Postfix ≥ 2.6) certificates are supported.

1011

You can configure all three at the same time, in which case the

1012

cipher used determines which certificate is presented.

1013

1014

It is possible for the Postfix SMTP client to use the same

1015

key/certificate pair as the Postfix SMTP server. If a certificate

1016

is to be presented, it must be in "PEM" format. The private key

1017

must not be encrypted, meaning: it must be accessible without

1018

password. Both parts (certificate and private key) may be in the

1019

same file.

1020

1021

To enable remote SMTP servers to verify the Postfix SMTP client

1022

certificate, the issuing CA certificates must be made available to the

1023

server. You should include the required certificates in the client

1024

certificate file, the client certificate first, then the issuing

1025

CA(s) (bottom-up order).

1026

1027

Example: the certificate for "client.example.com" was issued by

1028

"intermediate CA" which itself has a certificate issued by "root CA".

1029

Create the client.pem file with:

1030

1031

1032

<pre>

1033

% cat client_cert.pem intermediate_CA.pem > client.pem

1034

</pre>

1035

</blockquote>

1036

1037

A Postfix SMTP client certificate supplied here must be usable

1038

as SSL client certificate and hence pass the "openssl verify -purpose

1039

sslclient ..." test.

1040

1041

A server that trusts the root CA has a local copy of the root

1042

CA certificate, so it is not necessary to include the root CA

1043

certificate here. Leaving it out of the "client.pem" file reduces

1044

the overhead of the TLS exchange.

1045

1046

If you want the Postfix SMTP client to accept remote SMTP server

1047

certificates issued by these CAs, append the root certificate to

1048

$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory.

1049

1050

RSA key and certificate examples:

1051

1052

1053

<pre>

1054

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1055

<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem

1056

1057

</pre>

1058

</blockquote>

1059

1060

Their DSA counterparts:

1061

1062

1063

<pre>

1064

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1065

<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem

1066

<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a>

1067

</pre>

1068

</blockquote>

1069

1070

Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9):

1071

1072

1073

<pre>

1074

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1075

<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem

1076

<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a>

1077

</pre>

1078

</blockquote>

1079

1080

To verify a remote SMTP server certificate, the Postfix SMTP

1081

client needs to trust the certificates of the issuing certification

1082

authorities. These certificates in "pem" format can be stored in a

1083

single $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in

1084

the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget

1085

to create the necessary "hash" links with:

1086

1087

1088

<pre>

1089

# $OPENSSL_HOME/bin/c_rehash /path/to/directory

1090

</pre>

1091

</blockquote>

1092

1093

The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> contains the CA certificates of one or more

1094

trusted CAs. The file is opened (with root privileges) before Postfix

1095

enters the optional chroot jail and so need not be accessible from inside the

1096

chroot jail.

1097

1098

Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>

1099

directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>

1100

privileges) from the files in the directory when the information

1101

is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible

1102

inside the optional chroot jail.

1103

1104

The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> is

1105

a space/time tradeoff. If there are many trusted CAs, the cost of

1106

preloading them all into memory may not pay off in reduced access time

1107

when the certificate is needed.

1108

1109

Example:

1110

1111

1112

<pre>

1113

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1114

<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem

1115

<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs

1116

</pre>

1117

</blockquote>

1118

1119

<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>

1120

1121

To get additional information about Postfix SMTP client TLS

1122

activity you can increase the loglevel from 0..4. Each logging

1123

level also includes the information that is logged at a lower

1124

logging level.

1125

1126

1127

1128

<table>

1129

1130

<tr> <td> 0 </td> <td> Disable logging of TLS activity.</td> </tr>

1131

1132

<tr> <td> 1 </td> <td> Log TLS handshake and certificate information.

1133

</td> </tr>

1134

1135

<tr> <td> 2 </td> <td> Log levels during TLS negotiation. </td>

1136

</tr>

1137

1138

<tr> <td> 3 </td> <td> Log hexadecimal and ASCII dump of TLS

1139

negotiation process </td> </tr>

1140

1141

<tr> <td> 4 </td> <td> Log hexadecimal and ASCII dump of complete

1142

transmission after STARTTLS </td> </tr>

1143

1144

</table>

1145

1146

</blockquote>

1147

1148

Example:

1149

1150

1151

<pre>

1152

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1153

<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0

1154

</pre>

1155

</blockquote>

1156

1157

<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>

1158

1159

The remote SMTP server and the Postfix SMTP client negotiate a

1160

session, which takes some computer time and network bandwidth. By

1161

default, this session information is cached only in the <a href="smtp.8.html">smtp(8)</a>

1162

process actually using this session and is lost when the process

1163

terminates. To share the session information between multiple

1164

<a href="smtp.8.html">smtp(8)</a> processes, a persistent session cache can be used. You

1165

can specify any database type that can store objects of several

1166

kbytes and that supports the sequence operator. DBM databases are

1167

not suitable because they can only store small objects. The cache

1168

is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with

1169

concurrent access. Session caching is highly recommended, because

1170

the cost of repeatedly negotiating TLS session keys is high. Future

1171

Postfix SMTP servers may limit the number of sessions that a client

1172

is allowed to negotiate per unit time.

1173

1174

1175

Example:

1176

1177

1178

<pre>

1179

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1180

<a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/var/lib/postfix/smtp_scache

1181

</pre>

1182

</blockquote>

1183

1184

Note: as of version 2.5, Postfix no longer uses root privileges

1185

when opening this file. The file should now be stored under the

1186

Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to

1187

open the file under a non-Postfix directory is redirected to the

1188

Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged.

1189

1190

Cached Postfix SMTP client session information expires after

1191

a certain amount of time. Postfix/TLS does not use the OpenSSL

1192

default of 300s, but a longer time of 3600s (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>

1193

recommends a maximum of 24 hours.

1194

1195

Example:

1196

1197

1198

<pre>

1199

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1200

<a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s

1201

</pre>

1202

</blockquote>

1203

1204

<h3><a name="client_tls_limits"> Client TLS limitations </a>

1205

</h3>

1206

1207

The security properties of TLS communication channels are

1208

application specific. While the TLS protocol can provide a confidential,

1209

tamper-resistant, mutually authenticated channel between client

1210

and server, not all of these security features are applicable to every

1211

communication.

1212

1213

For example, while mutual TLS authentication between browsers and web

1214

servers is possible, it is not practical, or even useful, for web-servers

1215

that serve the public to verify the identity of every potential user. In

1216

practice, most HTTPS transactions are asymmetric: the browser verifies

1217

the HTTPS server's identity, but the user remains anonymous. Much of

1218

the security policy is up to the client. If the client chooses to not

1219

verify the server's name, the server is not aware of this. There are many

1220

interesting browser security topics, but we shall not dwell

1221

on them here. Rather, our goal is to understand the security features

1222

of TLS in conjunction with SMTP.

1223

1224

An important SMTP-specific observation is that a public MX host is

1225

even more at the mercy of the SMTP client than is an HTTPS server. Not only

1226

can it not enforce due care in the client's use of TLS, but it cannot even

1227

enforce the use of TLS, because TLS support in SMTP clients is still the

1228

exception rather than the rule. One cannot, in practice, limit access to

1229

one's MX hosts to just TLS-enabled clients. Such a policy would result

1230

in a vast reduction in one's ability to communicate by email with the

1231

world at large.

1232

1233

One may be tempted to try enforcing TLS for mail from specific

1234

sending organizations, but this, too, runs into obstacles. One such

1235

obstacle is that we don't know who is (allegedly) sending mail until

1236

we see the "MAIL FROM:" SMTP command, and at that point, if TLS

1237

is not already in use, a potentially sensitive sender address (and

1238

with SMTP PIPELINING one or more of the recipients) has (have) already been

1239

leaked in the clear. Another obstacle is that mail from the sender to

1240

the recipient may be forwarded, and the forwarding organization may not

1241

have any security arrangements with the final destination. Bounces also

1242

need to be protected. These can only be identified by the IP address and

1243

HELO name of the connecting client, and it is difficult to keep track

1244

of all the potential IP addresses or HELO names of the outbound email

1245

servers of the sending organization.

1246

1247

Consequently, TLS security for mail delivery to public MX hosts is

1248

almost entirely the client's responsibility. The server is largely a

1249

passive enabler of TLS security, the rest is up to the client. While the

1250

server has a greater opportunity to mandate client security policy when

1251

it is a dedicated MSA that only handles outbound mail from trusted clients,

1252

below we focus on the client security policy.

1253

1254

On the SMTP client, there are further complications. When delivering

1255

mail to a given domain, in contrast to HTTPS, one rarely uses the domain

1256

name directly as the target host of the SMTP session. More typically,

1257

one uses MX lookups - these are usually unauthenticated - to obtain the domain's SMTP server

1258

hostname(s). When, as is current practice, the client verifies the

1259

insecurely obtained MX hostname, it is subject to a DNS man-in-the-middle

1260

attack.

1261

1262

If clients instead attempted to verify the recipient domain name,

1263

an SMTP server for multiple domains would need to

1264

list all its email domain names in its certificate, and generate a

1265

new certificate each time a new domain were added. At least some CAs set

1266

fairly low limits (20 for one prominent CA) on the number of names that

1267

server certificates can contain. This approach is not consistent with

1268

current practice and does not scale.

1269

1270

It is regrettably the case that TLS secure-channels

1271

(fully authenticated and immune to man-in-the-middle attacks) impose

1272

constraints on the sending and receiving sites that preclude ubiquitous

1273

deployment. One needs to manually configure this type of security for

1274

each destination domain, and in many cases implement non-default TLS

1275

<a href="#client_tls_policy">policy table</a> entries for additional

1276

domains hosted at a common secured destination. With Postfix 2.3, we

1277

make secure-channel configurations substantially easier to configure,

1278

but they will never be the norm. For the generic domain with which you

1279

have made no specific security arrangements, this security level is not

1280

a good fit.

1281

1282

Given that strong authentication is not generally possible, and that

1283

verifiable certificates cost time and money, many servers that implement

1284

TLS use self-signed certificates or private CAs. This further limits

1285

the applicability of verified TLS on the public Internet.

1286

1287

Historical note: while the documentation of these issues and many of the

1288

related features are new with Postfix 2.3, the issue was well

1289

understood before Postfix 1.0, when Lutz Jänicke was designing

1290

the first unofficial Postfix TLS patch. See his original post <a

1291

href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>

1292

and the first response <a

1293

href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.

1294

The problem is not even unique to SMTP or even TLS, similar issues exist

1295

for secure connections via aliases for HTTPS and Kerberos. SMTP merely

1296

uses indirect naming (via MX records) more frequently.

1297

1298

863

<h3><a name="client_tls_levels"> Configuring TLS in the SMTP/LMTP client </a>

1299

864

</h3>

1300

865

1317

882

<dd><a href="#client_tls_secure">Secure-channel TLS.</a>

1318

883

</dl>

1319

884

1320

<h3><a name="client_tls_none"> No TLS encryption </a>

1321

</h3>

885

<h4><a name="client_lmtp_tls"> TLS support in the LMTP delivery agent </a> </h4>

886

887

The <a href="smtp.8.html">smtp(8)</a> and <a href="lmtp.8.html">lmtp(8)</a> delivery agents are implemented by a

888

single dual-purpose program. Specifically, all the TLS features

889

described below apply

890

equally to SMTP and LMTP, after replacing the "smtp_" prefix of the each

891

parameter name with "lmtp_".

892

893

The Postfix LMTP delivery agent can communicate with LMTP servers

894

listening

895

on UNIX-domain sockets. When server certificate verification is enabled

896

and the server is listening on a UNIX-domain socket, the $<a href="postconf.5.html#myhostname">myhostname</a>

897

parameter is used to set the TLS verification nexthop and

898

hostname.

899

900

NOTE: Opportunistic encryption of LMTP traffic over UNIX-domain

901

sockets or loopback TCP connections is futile. TLS is only useful

902

in this context when

903

it is mandatory, typically to allow at least one of the server or the

904

client to authenticate the other. The "null" cipher grade may be

905

appropriate in this context, when available on both client and server.

906

The "null" ciphers provide authentication without encryption.

907

908

<h4><a name="client_tls_none"> No TLS encryption </a> </h4>

1322

909

1323

910

At the "none" TLS security level, TLS encryption is

1324

disabled. This is the default security level. With Postfix 2.3 and later,

1325

it can be configured explicitly by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = none".

1326

1327

With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is set to

1328

its default (backwards compatible) empty value, the appropriate configuration

1329

settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = no" and "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".

1330

With either approach, TLS is not used even if supported by the server.

1331

For LMTP, use the corresponding "lmtp_" parameters.

1332

1333

Per destination settings may override this default setting, in which case

911

disabled. This is the default security level, and

912

can be configured explicitly by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = none".

913

For LMTP, use the corresponding "lmtp_" parameter.

914

915

Per-destination settings may override this default setting, in which case

1334

916

TLS is used selectively, only with destinations explicitly configured

1335

917

for TLS.

1336

918

1337

919

You can disable TLS for a subset of destinations, while leaving

1338

it enabled for the rest. With the Postfix 2.3 and later TLS <a

920

it enabled for the rest. With the Postfix TLS <a

1339

921

href="#client_tls_policy">policy table</a>, specify the "none"

1340

security level. With the obsolete <a href="#client_tls_obs">per-site</a>

1341

table, specify the "NONE" keyword.

922

security level.

1342

923

1343

<h3><a name="client_tls_may"> Opportunistic TLS </a>

1344

</h3>

924

<h4><a name="client_tls_may"> Opportunistic TLS </a> </h4>

1345

925

1346

926

At the "may" TLS security level, TLS encryption is opportunistic.

1347

927

The SMTP transaction is encrypted if the STARTTLS ESMTP feature

1348

928

is supported by the server. Otherwise, messages are sent in the clear.

1349

With Postfix 2.3 and later, opportunistic TLS can be configured by

1350

setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may".

929

Opportunistic TLS can be configured by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may".

930

For LMTP, use the corresponding "lmtp_" parameter.

1351

931

1352

932

Since sending in the clear is acceptable, demanding stronger

1353

933

than default TLS security mostly reduces inter-operability. If you

1358

938

used with opportunistic TLS. With earlier releases the opportunistic TLS

1359

939

cipher grade is always "export" and no protocols are disabled.

1360

940

1361

With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> is

1362

set to its default (backwards compatible) empty value, the appropriate

1363

configuration settings are "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes" and

1364

"<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no".

1365

For LMTP use the corresponding "lmtp_" parameters.

1366

1367

941

With opportunistic TLS, mail delivery continues even if the

1368

server certificate is untrusted or bears the wrong name. Starting

1369

with Postfix 2.3, when the TLS handshake fails for an opportunistic

1370

TLS session, rather than give up on mail delivery, the transaction

1371

is retried with TLS disabled. Trying an unencrypted connection makes

942

server certificate is untrusted or bears the wrong name.

943

When the TLS handshake fails for an opportunistic

944

TLS session, rather than give up on mail delivery, the Postfix SMTP

945

client retries the transaction

946

with TLS disabled. Trying an unencrypted connection makes

1372

947

it possible to deliver mail to sites with non-interoperable server

1373

948

TLS implementations.

1374

949

1382

957

be ignored with a warning written to the mail logs.

1383

958

1384

959

You can enable opportunistic TLS just for selected destinations. With

1385

the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,

1386

specify the "may" security level. With the obsolete <a

1387

href="#client_tls_obs">per-site</a> table, specify the "MAY" keyword.

960

the Postfix TLS <a href="#client_tls_policy">policy table</a>,

961

specify the "may" security level.

1388

962

1389

963

This is the most common security level for TLS protected SMTP

1390

964

sessions, stronger security is not generally available and, if needed,

1400

974

</pre>

1401

975

</blockquote>

1402

976

1403

Postfix 2.2 syntax:

1404

1405

1406

<pre>

1407

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1408

<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes

1409

<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = no

1410

</pre>

1411

</blockquote>

1412

1413

<h3><a name="client_tls_encrypt"> Mandatory TLS encryption </a>

1414

</h3>

977

<h4><a name="client_tls_encrypt"> Mandatory TLS encryption </a> </h4>

1415

978

1416

979

At the "encrypt" TLS security level, messages are sent only

1417

980

over TLS encrypted sessions. The SMTP transaction is aborted unless

1418

981

the STARTTLS ESMTP feature is supported by the remote SMTP server.

1419

982

If no suitable

1420

servers are found, the message will be deferred. With Postfix 2.3

1421

and later, mandatory TLS encryption can be configured by setting

983

servers are found, the message will be deferred.

984

Mandatory TLS encryption can be configured by setting

1422

985

"<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = encrypt". Even though TLS

1423

986

encryption is always used, mail delivery continues even if the server

1424

certificate is untrusted or bears the wrong name.

987

certificate is untrusted or bears the wrong name.

988

For LMTP, use the corresponding "lmtp_" parameter.

1425

989

1426

990

At this security level and higher, the <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>

1427

991

and <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> configuration parameters determine

1431

995

parameters includes useful interoperability and security guidelines.

1432

996

1433

997

1434

With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>

1435

is set to its default (backwards compatible) empty value, the

1436

appropriate configuration settings are "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes"

1437

and "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = no". For LMTP use the corresponding

1438

"lmtp_" parameters.

1439

1440

998

Despite the potential for eliminating passive eavesdropping attacks,

1441

999

mandatory TLS encryption is not viable as a default security level for

1442

1000

mail delivery to the public Internet. Most MX hosts do not support TLS at

1445

1003

TLS encryption as the default security level.

1446

1004

1447

1005

You can enable mandatory TLS encryption just for specific destinations.

1448

With the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy

1449

table</a>, specify the "encrypt" security level. With the

1450

obsolete <a href="#client_tls_obs">per-site</a> table, specify the

1451

"MUST_NOPEERMATCH" keyword. While the obsolete approach still works

1452

with Postfix 2.3, it is strongly discouraged: users of Postfix 2.3 and later

1453

should use the new TLS policy settings.

1006

With the Postfix TLS <a href="#client_tls_policy">policy

1007

table</a>, specify the "encrypt" security level.

1008

1454

1009

1455

1010

Examples:

1456

1011

1472

1027

</pre>

1473

1028

</blockquote>

1474

1029

1475

Postfix 2.2 syntax (no support for sub-domains without resorting to

1476

regexp tables). With Postfix 2.3 and later, do not use the obsolete <a

1477

href="#client_tls_obs">per-site</a> table.

1478

1479

1480

<pre>

1481

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1482

<a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site

1483

1484

/etc/postfix/tls_per_site:

1485

example.com MUST_NOPEERMATCH

1486

</pre>

1487

</blockquote>

1488

1489

1030

In the next example, secure message submission is configured

1490

1031

via the MSA "<tt>[example.net]:587</tt>". TLS sessions are encrypted

1491

1032

without authentication, because this MSA does not possess an acceptable

1517

1058

</pre>

1518

1059

</blockquote>

1519

1060

1520

Postfix 2.2 syntax:

1521

1522

Note: Avoid policy lookups with the bare hostname (for

1523

example, "example.net"). Instead,

1524

use the destination (for example, "[example.net]:587"), as the <a

1525

href="#client_tls_obs">per-site</a> table lookup key (a recipient domain

1526

or MX-enabled transport nexthop with no port suffix may look like a bare

1527

hostname, but is still a suitable destination). With Postfix 2.3

1528

and later,

1529

do not use the obsolete <a href="#client_tls_obs">per-site</a> table;

1530

use the new <a href="#client_tls_policy">policy table</a> instead.

1531

1532

1533

<pre>

1534

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1535

<a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site

1536

1537

/etc/postfix/tls_per_site:

1538

[example.net]:587 MUST_NOPEERMATCH

1539

</pre>

1540

</blockquote>

1541

1542

<h3><a name="client_tls_fprint"> Certificate fingerprint verification </a>

1543

</h3>

1544

1545

Certificate fingerprint verification is available with Postfix 2.5 and

1546

later. At this security level ("<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = fingerprint"),

1547

no trusted certificate authorities are used or required. The certificate

1548

trust chain, expiration date, ... are not checked. Instead, the

1549

<a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter or the "match" attribute

1550

in the <a href="#client_tls_policy">policy</a> table lists the valid

1551

"fingerprints" of the remote SMTP server certificate.

1061

<h4><a name="client_tls_fprint"> Certificate fingerprint verification </a> </h4>

1062

1063

Certificate fingerprint verification is available with Postfix

1064

2.5 and later. At this security level ("<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> =

1065

fingerprint"), no trusted certificate authorities are used or

1066

required. The certificate trust chain, expiration date, ... are

1067

not checked. Instead, the <a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter

1068

or the "match" attribute in the <a href="#client_tls_policy">policy</a>

1069

table lists the remote SMTP server certificate fingerprint or

1070

public key fingerprint (Postfix 2.9 and later).

1552

1071

1553

1072

If certificate fingerprints are exchanged securely, this is the

1554

strongest, and least scalable security level. The administrator needs to

1555

securely collect the fingerprints of the X.509 certificates of each peer

1556

server, store them into a local file, and update this local file

1557

whenever the peer server's public certificate

1558

changes. This may be feasible for an SMTP "VPN" connecting a small

1559

number of branch offices over the Internet, or for secure connections

1560

to a central mail hub. It works poorly if the remote SMTP server is

1561

managed by a

1562

third party, and its public certificate changes periodically without

1563

prior coordination with the verifying site.

1073

strongest, and least scalable security level. The administrator needs

1074

to securely collect the fingerprints of the X.509 certificates of each

1075

peer server, store them into a local file, and update this local file

1076

whenever the peer server's public certificate changes. If public key

1077

fingerprints are used in place of fingerprints of the entire certificate,

1078

the fingerprints remain valid even after the certificate is renewed,

1079

provided that the same public/private keys are used to obtain

1080

the new certificate.

1081

1082

Fingerprint verification may be feasible for an SMTP "VPN" connecting

1083

a small number of branch offices over the Internet, or for secure

1084

connections to a central mail hub. It works poorly if the remote SMTP

1085

server is managed by a third party, and its public certificate changes

1086

periodically without prior coordination with the verifying site.

1564

1087

1565

1088

The digest algorithm used to calculate the fingerprint is

1566

1089

selected by the <a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> parameter. In the <a

1606

1129

</pre>

1607

1130

</blockquote>

1608

1131

1609

<h3><a name="client_tls_verify"> Mandatory server certificate verification </a>

1610

</h3>

1132

<h4><a name="client_tls_verify"> Mandatory server certificate verification </a> </h4>

1611

1133

1612

1134

At the "verify" TLS security level, messages are sent only over

1613

1135

TLS encrypted sessions if the remote SMTP server certificate is

1620

1142

<a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> parameter can override the default

1621

1143

"hostname" certificate name matching strategy. Fine-tuning the

1622

1144

matching strategy is generally only appropriate for <a

1623

href="#client_tls_secure">secure-channel</a> destinations.

1624

1625

With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>

1626

is set to its default (backwards compatible) empty value, the

1627

appropriate configuration settings are "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" and

1628

"<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes". For LMTP use the corresponding

1629

"lmtp_" parameters.

1145

href="#client_tls_secure">secure-channel</a> destinations.

1146

For LMTP use the corresponding "lmtp_" parameters.

1630

1147

1631

1148

If the server certificate chain is trusted (see <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a>

1632

1149

and <a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), any DNS names in the SubjectAlternativeName

1655

1172

1656

1173

1657

1174

You can enable mandatory server certificate verification just

1658

for specific destinations. With the Postfix 2.3 and later TLS <a

1175

for specific destinations. With the Postfix TLS <a

1659

1176

href="#client_tls_policy">policy table</a>, specify the "verify"

1660

security level. With the obsolete <a href="#client_tls_obs">per-site</a>

1661

table, specify the "MUST" keyword. While the obsolete approach

1662

still works with Postfix 2.3, it is strongly discouraged: users of

1663

Postfix 2.3 and later should use the new TLS policy settings.

1177

security level.

1664

1178

1665

1179

Example:

1666

1180

1681

1195

</pre>

1682

1196

</blockquote>

1683

1197

1684

Postfix 2.2 syntax:

1685

1686

<pre>

1687

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1688

indexed = ${<a href="postconf.5.html#default_database_type">default_database_type</a>}:${<a href="postconf.5.html#config_directory">config_directory</a>}/

1689

<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = ${<a href="postconf.5.html#config_directory">config_directory</a>}/CAfile.pem

1690

<a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = ${indexed}tls_per_site

1691

1692

/etc/postfix/tls_per_site:

1693

example.com MUST

1694

</pre>

1695

</blockquote>

1696

1697

<h3><a name="client_tls_secure"> Secure server certificate verification </a>

1698

</h3>

1198

<h4><a name="client_tls_secure"> Secure server certificate verification </a> </h4>

1699

1199

1700

1200

At the secure TLS security level, messages are sent only over

1701

1201

secure-channel TLS sessions where DNS forgery resistant server

1702

1202

certificate verification succeeds. If no suitable servers are found, the

1703

message will be deferred. With Postfix 2.3 and later, secure-channels

1203

message will be deferred. Postfix secure-channels

1704

1204

can be configured by setting "<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = secure".

1705

1205

The <a href="postconf.5.html#smtp_tls_secure_cert_match">smtp_tls_secure_cert_match</a> parameter can override the default

1706

"nexthop, dot-nexthop" certificate match strategy.

1707

1708

With Postfix 2.2 and earlier, or when <a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a>

1709

is set to its default (backwards compatible) empty value, the

1710

appropriate configuration settings are "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes"

1711

and "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes" with additional settings to

1712

<a href="#client_tls_harden">harden</a> peer certificate verification

1713

against forged DNS data. For LMTP, use the corresponding "lmtp_"

1714

parameters.

1206

"nexthop, dot-nexthop" certificate match strategy.

1207

For LMTP, use the corresponding "lmtp_" parameters.

1715

1208

1716

1209

If the server certificate chain is trusted (see <a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and

1717

1210

<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>), any DNS names in the SubjectAlternativeName certificate

1738

1231

STARTTLS support.

1739

1232

1740

1233

You can enable secure TLS verification just for specific destinations.

1741

With the Postfix 2.3 and later TLS <a href="#client_tls_policy">policy table</a>,

1742

specify the "secure" security level. With the obsolete

1743

<a href="#client_tls_obs">per-site</a> table, specify the "MUST"

1744

keyword and <a href="#client_tls_harden">harden</a> the certificate

1745

verification against DNS forgery. While the obsolete approach still

1746

works with Postfix 2.3, it is strongly discouraged: users of Postfix 2.3

1747

and later

1748

should use the new TLS policy settings.

1234

With the Postfix TLS <a href="#client_tls_policy">policy table</a>,

1235

specify the "secure" security level.

1749

1236

1750

1237

Examples:

1751

1238

1752

Secure-channel TLS without <a href="transport.5.html">transport(5)</a> table overrides:

1239

<ul>

1240

1241

<li> Secure-channel TLS without <a href="transport.5.html">transport(5)</a> table overrides:

1753

1242

1754

1243

The Postfix SMTP client will encrypt all traffic and verify the

1755

1244

destination name

1795

1284

</pre>

1796

1285

</blockquote>

1797

1286

1798

Secure-channel TLS with <a href="transport.5.html">transport(5)</a> table overrides:

1287

<li> Secure-channel TLS with <a href="transport.5.html">transport(5)</a> table overrides:

1799

1288

1800

1289

In this case traffic to example.com and its related domains

1801

1290

is sent to a single logical gateway (to avoid a single point of failure,

1802

1291

its name may resolve to one or more load-balancer addresses, or to the

1803

1292

combined addresses of multiple physical hosts). All the physical hosts

1804

1293

reachable via the gateway's IP addresses have the logical gateway name

1805

listed in their certificates. This secure-channel configuration can also

1806

be implemented via a <a href="#client_tls_harden">hardened</a> variant of

1807

the MUST policy in the obsolete <a href="#client_tls_obs">per-site</a>

1808

table. As stated above, this approach has the potential to mis-deliver

1809

email if the related domains change hands.

1294

listed in their certificates.

1810

1295

1811

1296

1812

1297

<pre>

1825

1310

</pre>

1826

1311

</blockquote>

1827

1312

1828

Postfix 2.2.9 and later syntax:

1829

1830

Note: Avoid policy lookups with the bare hostname (for

1831

example, "tls.example.com"). Instead, use the destination (for

1832

example, "[tls.example.com]") as the <a

1833

href="#client_tls_obs">per-site</a> table lookup key (a recipient domain

1834

or MX-enabled transport nexthop with no port suffix may look like a bare

1835

hostname, but is still a suitable destination). With Postfix 2.3

1836

and later,

1837

do not use the obsolete <a href="#client_tls_obs">per-site</a> table;

1838

use the new <a href="#client_tls_policy">policy table</a> instead.

1839

1840

1841

<pre>

1842

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1843

<a href="postconf.5.html#smtp_cname_overrides_servername">smtp_cname_overrides_servername</a> = no

1844

<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAfile.pem

1845

<a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport

1846

<a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> = hash:/etc/postfix/tls_per_site

1847

1848

/etc/postfix/transport:

1849

example.com <a href="smtp.8.html">smtp</a>:[tls.example.com]

1850

example.co.uk <a href="smtp.8.html">smtp</a>:[tls.example.com]

1851

example.co.jp <a href="smtp.8.html">smtp</a>:[tls.example.com]

1852

1853

/etc/postfix/tls_per_site:

1854

[tls.example.com] MUST

1855

</pre>

1856

</blockquote>

1313

</ul>

1314

1315

<h3><a name="client_logging"> Client-side TLS activity logging </a> </h3>

1316

1317

To get additional information about Postfix SMTP client TLS

1318

activity you can increase the loglevel from 0..4. Each logging

1319

level also includes the information that is logged at a lower

1320

logging level.

1321

1322

1323

1324

1325

1326

<tr> <th> Level </th> <th> Postfix 2.9 and later</th> <th> Earlier

1327

releases. </th> </tr>

1328

1329

<tr> <td valign="top"> 0 </td> <td valign="top"> Log only a summary

1330

message on TLS handshake completion — no logging of remote

1331

SMTP server certificate trust-chain verification errors if server

1332

certificate verification is not required. </td> <td valign="top">

1333

Disable logging of TLS activity.</td> </tr>

1334

1335

<tr> <td valign="top"> 1 </td> <td valign="top"> Also log remote

1336

SMTP server trust-chain verification errors and peer certificate

1337

summary information. </td> <td valign="top"> Also log TLS handshake

1338

and certificate information. </td> </tr>

1339

1340

<tr> <td valign="top"> 2 </td> <td valign="top" colspan="2"> Also

1341

log levels during TLS negotiation. </td> </tr>

1342

1343

<tr> <td valign="top"> 3 </td> <td valign="top" colspan="2"> Also

1344

log hexadecimal and ASCII dump of TLS negotiation process. </td>

1345

</tr>

1346

1347

<tr> <td valign="top"> 4 </td> <td valign="top" colspan="2"> Also

1348

log hexadecimal and ASCII dump of complete transmission after

1349

STARTTLS. </td> </tr>

1350

1351

</table>

1352

1353

</blockquote>

1354

1355

Example:

1356

1357

1358

<pre>

1359

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1360

<a href="postconf.5.html#smtp_tls_loglevel">smtp_tls_loglevel</a> = 0

1361

</pre>

1362

</blockquote>

1363

1364

<h3><a name="client_cert_key">Client-side certificate and private

1365

key configuration </a> </h3>

1366

1367

Do not configure Postfix SMTP client certificates unless you must

1368

present

1369

client TLS certificates to one or more servers. Client certificates are

1370

not usually needed, and can cause problems in configurations that work

1371

well without them. The recommended setting is to let the defaults stand:

1372

1373

1374

<pre>

1375

<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> =

1376

<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> =

1377

<a href="postconf.5.html#smtp_tls_key_file">smtp_tls_key_file</a> =

1378

<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> =

1379

# Postfix ≥ 2.6

1380

<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> =

1381

<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> =

1382

</pre>

1383

</blockquote>

1384

1385

The best way to use the default settings is to comment out the above

1386

parameters in <a href="postconf.5.html">main.cf</a> if present.

1387

1388

During TLS startup negotiation the Postfix SMTP client may present

1389

a certificate to the remote SMTP server. The Netscape client is

1390

rather clever here and lets the user select between only those

1391

certificates that match CA certificates offered by the remote SMTP

1392

server. As the Postfix SMTP client uses the "SSL_connect()" function

1393

from the OpenSSL package, this is not possible and we have to choose

1394

just one certificate. So for now the default is to use _no_

1395

certificate and key unless one is explicitly specified here.

1396

1397

RSA, DSA and ECDSA (Postfix ≥ 2.6) certificates are supported.

1398

You can configure all three at the same time, in which case the

1399

cipher used determines which certificate is presented.

1400

1401

It is possible for the Postfix SMTP client to use the same

1402

key/certificate pair as the Postfix SMTP server. If a certificate

1403

is to be presented, it must be in "PEM" format. The private key

1404

must not be encrypted, meaning: it must be accessible without

1405

password. Both parts (certificate and private key) may be in the

1406

same file.

1407

1408

To enable remote SMTP servers to verify the Postfix SMTP client

1409

certificate, the issuing CA certificates must be made available to the

1410

server. You should include the required certificates in the client

1411

certificate file, the client certificate first, then the issuing

1412

CA(s) (bottom-up order).

1413

1414

Example: the certificate for "client.example.com" was issued by

1415

"intermediate CA" which itself has a certificate issued by "root CA".

1416

Create the client.pem file with:

1417

1418

1419

<pre>

1420

% cat client_cert.pem intermediate_CA.pem > client.pem

1421

</pre>

1422

</blockquote>

1423

1424

A Postfix SMTP client certificate supplied here must be usable

1425

as SSL client certificate and hence pass the "openssl verify -purpose

1426

sslclient ..." test.

1427

1428

A server that trusts the root CA has a local copy of the root

1429

CA certificate, so it is not necessary to include the root CA

1430

certificate here. Leaving it out of the "client.pem" file reduces

1431

the overhead of the TLS exchange.

1432

1433

If you want the Postfix SMTP client to accept remote SMTP server

1434

certificates issued by these CAs, append the root certificate to

1435

$<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or install it in the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory.

1436

1437

RSA key and certificate examples:

1438

1439

1440

<pre>

1441

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1442

<a href="postconf.5.html#smtp_tls_cert_file">smtp_tls_cert_file</a> = /etc/postfix/client.pem

1443

1444

</pre>

1445

</blockquote>

1446

1447

Their DSA counterparts:

1448

1449

1450

<pre>

1451

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1452

<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a> = /etc/postfix/client-dsa.pem

1453

<a href="postconf.5.html#smtp_tls_dkey_file">smtp_tls_dkey_file</a> = $<a href="postconf.5.html#smtp_tls_dcert_file">smtp_tls_dcert_file</a>

1454

</pre>

1455

</blockquote>

1456

1457

Their ECDSA counterparts (Postfix ≥ 2.6 + OpenSSL ≥ 0.9.9):

1458

1459

1460

<pre>

1461

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1462

<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a> = /etc/postfix/client-ecdsa.pem

1463

<a href="postconf.5.html#smtp_tls_eckey_file">smtp_tls_eckey_file</a> = $<a href="postconf.5.html#smtp_tls_eccert_file">smtp_tls_eccert_file</a>

1464

</pre>

1465

</blockquote>

1466

1467

To verify a remote SMTP server certificate, the Postfix SMTP

1468

client needs to trust the certificates of the issuing certification

1469

authorities. These certificates in "pem" format can be stored in a

1470

single $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> or in multiple files, one CA per file in

1471

the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory. If you use a directory, don't forget

1472

to create the necessary "hash" links with:

1473

1474

1475

<pre>

1476

# $OPENSSL_HOME/bin/c_rehash /path/to/directory

1477

</pre>

1478

</blockquote>

1479

1480

The $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> contains the CA certificates of one or more

1481

trusted CAs. The file is opened (with root privileges) before Postfix

1482

enters the optional chroot jail and so need not be accessible from inside the

1483

chroot jail.

1484

1485

Additional trusted CAs can be specified via the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a>

1486

directory, in which case the certificates are read (with $<a href="postconf.5.html#mail_owner">mail_owner</a>

1487

privileges) from the files in the directory when the information

1488

is needed. Thus, the $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> directory needs to be accessible

1489

inside the optional chroot jail.

1490

1491

The choice between $<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> and $<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> is

1492

a space/time tradeoff. If there are many trusted CAs, the cost of

1493

preloading them all into memory may not pay off in reduced access time

1494

when the certificate is needed.

1495

1496

Example:

1497

1498

1499

<pre>

1500

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1501

<a href="postconf.5.html#smtp_tls_CAfile">smtp_tls_CAfile</a> = /etc/postfix/CAcert.pem

1502

<a href="postconf.5.html#smtp_tls_CApath">smtp_tls_CApath</a> = /etc/postfix/certs

1503

</pre>

1504

</blockquote>

1505

1506

<h3><a name="client_tls_cache">Client-side TLS session cache</a> </h3>

1507

1508

The remote SMTP server and the Postfix SMTP client negotiate a

1509

session, which takes some computer time and network bandwidth. By

1510

default, this session information is cached only in the <a href="smtp.8.html">smtp(8)</a>

1511

process actually using this session and is lost when the process

1512

terminates. To share the session information between multiple

1513

<a href="smtp.8.html">smtp(8)</a> processes, a persistent session cache can be used. You

1514

can specify any database type that can store objects of several

1515

kbytes and that supports the sequence operator. DBM databases are

1516

not suitable because they can only store small objects. The cache

1517

is maintained by the <a href="tlsmgr.8.html">tlsmgr(8)</a> process, so there is no problem with

1518

concurrent access. Session caching is highly recommended, because

1519

the cost of repeatedly negotiating TLS session keys is high. Future

1520

Postfix SMTP servers may limit the number of sessions that a client

1521

is allowed to negotiate per unit time.

1522

1523

1524

Example:

1525

1526

1527

<pre>

1528

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1529

<a href="postconf.5.html#smtp_tls_session_cache_database">smtp_tls_session_cache_database</a> = btree:/var/lib/postfix/smtp_scache

1530

</pre>

1531

</blockquote>

1532

1533

Note: as of version 2.5, Postfix no longer uses root privileges

1534

when opening this file. The file should now be stored under the

1535

Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>. As a migration aid, an attempt to

1536

open the file under a non-Postfix directory is redirected to the

1537

Postfix-owned <a href="postconf.5.html#data_directory">data_directory</a>, and a warning is logged.

1538

1539

Cached Postfix SMTP client session information expires after

1540

a certain amount of time. Postfix/TLS does not use the OpenSSL

1541

default of 300s, but a longer time of 3600s (=1 hour). <a href="http://tools.ietf.org/html/rfc2246">RFC 2246</a>

1542

recommends a maximum of 24 hours.

1543

1544

Example:

1545

1546

1547

<pre>

1548

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

1549

<a href="postconf.5.html#smtp_tls_session_cache_timeout">smtp_tls_session_cache_timeout</a> = 3600s

1550

</pre>

1551

</blockquote>

1552

1553

<h3><a name="client_tls_limits"> Client TLS limitations </a>

1554

</h3>

1555

1556

The security properties of TLS communication channels are

1557

application specific. While the TLS protocol can provide a confidential,

1558

tamper-resistant, mutually authenticated channel between client

1559

and server, not all of these security features are applicable to every

1560

communication.

1561

1562

For example, while mutual TLS authentication between browsers and web

1563

servers is possible, it is not practical, or even useful, for web-servers

1564

that serve the public to verify the identity of every potential user. In

1565

practice, most HTTPS transactions are asymmetric: the browser verifies

1566

the HTTPS server's identity, but the user remains anonymous. Much of

1567

the security policy is up to the client. If the client chooses to not

1568

verify the server's name, the server is not aware of this. There are many

1569

interesting browser security topics, but we shall not dwell

1570

on them here. Rather, our goal is to understand the security features

1571

of TLS in conjunction with SMTP.

1572

1573

An important SMTP-specific observation is that a public MX host is

1574

even more at the mercy of the SMTP client than is an HTTPS server. Not only

1575

can it not enforce due care in the client's use of TLS, but it cannot even

1576

enforce the use of TLS, because TLS support in SMTP clients is still the

1577

exception rather than the rule. One cannot, in practice, limit access to

1578

one's MX hosts to just TLS-enabled clients. Such a policy would result

1579

in a vast reduction in one's ability to communicate by email with the

1580

world at large.

1581

1582

One may be tempted to try enforcing TLS for mail from specific

1583

sending organizations, but this, too, runs into obstacles. One such

1584

obstacle is that we don't know who is (allegedly) sending mail until

1585

we see the "MAIL FROM:" SMTP command, and at that point, if TLS

1586

is not already in use, a potentially sensitive sender address (and

1587

with SMTP PIPELINING one or more of the recipients) has (have) already been

1588

leaked in the clear. Another obstacle is that mail from the sender to

1589

the recipient may be forwarded, and the forwarding organization may not

1590

have any security arrangements with the final destination. Bounces also

1591

need to be protected. These can only be identified by the IP address and

1592

HELO name of the connecting client, and it is difficult to keep track

1593

of all the potential IP addresses or HELO names of the outbound email

1594

servers of the sending organization.

1595

1596

Consequently, TLS security for mail delivery to public MX hosts is

1597

almost entirely the client's responsibility. The server is largely a

1598

passive enabler of TLS security, the rest is up to the client. While the

1599

server has a greater opportunity to mandate client security policy when

1600

it is a dedicated MSA that only handles outbound mail from trusted clients,

1601

below we focus on the client security policy.

1602

1603

On the SMTP client, there are further complications. When delivering

1604

mail to a given domain, in contrast to HTTPS, one rarely uses the domain

1605

name directly as the target host of the SMTP session. More typically,

1606

one uses MX lookups - these are usually unauthenticated - to obtain the domain's SMTP server

1607

hostname(s). When, as is current practice, the client verifies the

1608

insecurely obtained MX hostname, it is subject to a DNS man-in-the-middle

1609

attack.

1610

1611

If clients instead attempted to verify the recipient domain name,

1612

an SMTP server for multiple domains would need to

1613

list all its email domain names in its certificate, and generate a

1614

new certificate each time a new domain were added. At least some CAs set

1615

fairly low limits (20 for one prominent CA) on the number of names that

1616

server certificates can contain. This approach is not consistent with

1617

current practice and does not scale.

1618

1619

It is regrettably the case that TLS secure-channels

1620

(fully authenticated and immune to man-in-the-middle attacks) impose

1621

constraints on the sending and receiving sites that preclude ubiquitous

1622

deployment. One needs to manually configure this type of security for

1623

each destination domain, and in many cases implement non-default TLS

1624

<a href="#client_tls_policy">policy table</a> entries for additional

1625

domains hosted at a common secured destination. For these reasons

1626

secure-channel configurations

1627

will never be the norm. For the generic domain with which you

1628

have made no specific security arrangements, this security level is not

1629

a good fit.

1630

1631

Given that strong authentication is not generally possible, and that

1632

verifiable certificates cost time and money, many servers that implement

1633

TLS use self-signed certificates or private CAs. This further limits

1634

the applicability of verified TLS on the public Internet.

1635

1636

Historical note: while the documentation of these issues and many of the

1637

related features were new with Postfix 2.3, the issue was well

1638

understood before Postfix 1.0, when Lutz Jänicke was designing

1639

the first unofficial Postfix TLS patch. See his original post <a

1640

href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00304.html</a>

1641

and the first response <a

1642

href="http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html">http://www.imc.org/ietf-apps-tls/mail-archive/msg00305.html</a>.

1643

The problem is not even unique to SMTP or even TLS, similar issues exist

1644

for secure connections via aliases for HTTPS and Kerberos. SMTP merely

1645

uses indirect naming (via MX records) more frequently.

1857

1646

1858

1647

<h3> <a name="client_tls_policy"> TLS policy table </a>

1859

1648

</h3>

1860

1649

1861

The current TLS policy table was introduced with Postfix 2.3. For

1862

earlier releases, read the description of the obsolete Postfix 2.2 <a

1863

href="#client_tls_obs">per-site</a> table.

1864

1865

1650

A small fraction of servers offer STARTTLS but the negotiation

1866

consistently fails. With Postfix 2.3, so long as encryption is not

1867

enforced, the delivery is immediately retried with TLS disabled. You no

1868

longer need to explicitly disable TLS for the problem destinations.

1869

As soon as their TLS software or configuration is repaired, encryption

1870

will be used.

1651

consistently fails. As long as encryption is not mandatory, the

1652

Postfix SMTP client retries the delivery immediately with TLS

1653

disabled, without any need to explicitly disable TLS for the problem

1654

destinations.

1871

1655

1872

The new policy table is specified via the <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>

1656

The policy table is specified via the <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>

1873

1657

parameter. This lists optional lookup tables with the Postfix SMTP client

1874

TLS security policy by next-hop destination. When $<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a>

1875

is not empty, the obsolete <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> parameter is ignored

1876

(a warning is written to the logs if both parameter values are

1877

non-empty).

1658

TLS security policy by next-hop destination.

1878

1659

1879

1660

The TLS policy table is indexed by the full next-hop destination,

1880

1661

which is either the recipient domain, or the verbatim next-hop

1927

1708

later. At this security level, there are no trusted certificate

1928

1709

authorities. The certificate trust chain, expiration date, ... are

1929

1710

not checked. Instead, the optional match attribute, or else

1930

the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter,

1931

lists the valid fingerprints of the server certificate. The

1711

the <a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_fingerprint_cert_match">smtp_tls_fingerprint_cert_match</a> parameter, lists

1712

the server certificate fingerprints or public key fingerprints

1713

(Postfix 2.9 and later). The

1932

1714

digest algorithm used to calculate fingerprints is selected by the

1933

1715

<a href="postconf.5.html#smtp_tls_fingerprint_digest">smtp_tls_fingerprint_digest</a> parameter. Multiple fingerprints can

1934

1716

be combined with a "|" delimiter in a single match attribute, or multiple

2022

1804

the "hostname" strategy for <a href="#client_tls_secure">secure-channel</a>

2023

1805

configurations in environments where DNS security is not assured.

2024

1806

2025

<h3> <a name="client_tls_obs"> Obsolete per-site TLS policy support

2026

</a> </h3>

2027

2028

This section describes an obsolete per-site TLS policy mechanism.

2029

Unlike the Postfix 2.3 <a href="#client_tls_policy">policy table</a>

2030

mechanism, this uses as a policy lookup key a potentially untrusted

2031

server hostname, and lacks control over what names can appear in

2032

server certificates. Because of this, the obsolete mechanism is

2033

typically vulnerable to false DNS hostname information in MX or

2034

CNAME records. These attacks can be eliminated only with great

2035

difficulty. The new <a href="#client_tls_policy">policy table</a>

2036

makes <a href="#client_tls_secure">secure-channel</a> configurations

2037

easier and provides more control over the cipher and protocol selection

2038

for sessions with mandatory encryption.

2039

2040

Avoid policy lookups with the bare hostname. Instead, use the

2041

full destination nexthop (enclosed in [] with a possible ":port"

2042

suffix) as the per-site table lookup key (a recipient domain or

2043

MX-enabled transport nexthop with no port suffix may look like a bare

2044

hostname, but is still a suitable destination). With Postfix 2.3

2045

and later,

2046

use of the obsolete approach documented here is strongly discouraged:

2047

use the new <a href="#client_tls_policy">policy table</a> instead.

2048

2049

Starting with Postfix 2.3, the underlying TLS enforcement levels are

2050

common to the obsolete per-site table and the new policy table. The

2051

<a href="postconf.5.html">main.cf</a> <a href="postconf.5.html#smtp_tls_mandatory_ciphers">smtp_tls_mandatory_ciphers</a> and <a href="postconf.5.html#smtp_tls_mandatory_protocols">smtp_tls_mandatory_protocols</a>

2052

parameters control the TLS ciphers and protocols for mandatory

2053

encryption regardless of which table is used. The

2054

<a href="postconf.5.html#smtp_tls_verify_cert_match">smtp_tls_verify_cert_match</a> parameter determines the match strategy

2055

for the obsolete "MUST" keyword in the same way as for the "verify"

2056

level in the new policy.

2057

2058

With Postfix < 2.3, the obsolete <a href="postconf.5.html#smtp_tls_cipherlist">smtp_tls_cipherlist</a> parameter

2059

is also applied for opportunistic TLS sessions, and should be used with

2060

care, or not at all. Setting cipherlist restrictions that are incompatible

2061

with a remote SMTP server render that server unreachable, TLS handshakes

2062

are always attempted and always fail.

2063

2064

When <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> is empty (default) and <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a>

2065

is not empty, the per-site table is searched for a policy that matches

2066

the following information:

2067

2068

2069

2070

<dl>

2071

2072

<dt> remote SMTP server hostname </dt> <dd> This is simply the DNS

2073

name of the server that the Postfix SMTP client connects to; this

2074

name may be obtained from other DNS lookups, such as MX lookups or

2075

CNAME lookups. Use of the hostname lookup key is discouraged; always

2076

use the next-hop destination instead. </dd>

2077

2078

<dt> next-hop destination </dt> <dd> This is normally the domain portion

2079

of the recipient address, but it may be overridden by information from

2080

the <a href="transport.5.html">transport(5)</a> table, from the <a href="postconf.5.html#relayhost">relayhost</a> parameter setting, or from

2081

the <a href="postconf.5.html#relay_transport">relay_transport</a> setting. When it is not the recipient domain, the

2082

next-hop destination can have the Postfix-specific form "<tt>[name]</tt>",

2083

"<tt>[name]:port</tt>", "<tt>name</tt>" or "<tt>name:port</tt>". This is

2084

the recommended lookup key for per-site policy lookups (and incidentally

2085

for <a href="SASL_README.html#client_sasl">SASL password</a> lookups). </dd>

2086

2087

</dl>

2088

2089

</blockquote>

2090

2091

When both the hostname lookup and the next-hop lookup succeed,

2092

the host policy does not automatically override the next-hop policy.

2093

Instead, precedence is given to either the more specific or the

2094

more secure per-site policy as described below.

2095

2096

The <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table uses a simple "name whitespace

2097

value" format. Specify host names or next-hop destinations on

2098

the left-hand side; no wildcards are allowed. On the right hand

2099

side specify one of the following keywords:

2100

2101

2102

2103

<dl>

2104

2105

<dt> NONE </dt> <dd> No TLS. This overrides a less specific "MAY" lookup

2106

result from the alternate host or next-hop lookup key, and overrides

2107

the global <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>, <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>, and <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>

2108

settings. </dd>

2109

2110

<dt> MAY </dt> <dd> Opportunistic TLS. This has less precedence than

2111

a more specific result (including "NONE") from the alternate host or

2112

next-hop lookup key, and has less precedence than the more specific global

2113

"<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" or "<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes". </dd>

2114

2115

<dt> MUST_NOPEERMATCH </dt> <dd> Mandatory TLS encryption. This

2116

overrides a less secure "NONE" or a less specific "MAY" lookup result

2117

from the alternate host or next-hop lookup key, and overrides the global

2118

<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>, <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> and <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> settings.

2119

</dd>

2120

2121

<dt> MUST </dt> <dd> Mandatory server certificate verification.

2122

This overrides a less secure "NONE" and "MUST_NOPEERMATCH" or a

2123

less specific "MAY" lookup result from the alternate host or next-hop

2124

lookup key, and overrides the global <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>, <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>

2125

and <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> settings. </dd>

2126

2127

</dl>

2128

2129

</blockquote>

2130

2131

The precedences between global (<a href="postconf.5.html">main.cf</a>) and per-site TLS

2132

policies can be summarized as follows:

2133

2134

<ul>

2135

2136

<li> When neither the remote SMTP server hostname nor the

2137

next-hop destination are found in the <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> table, the

2138

policy is based on <a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a>, <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> and

2139

<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>. Note: "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" and

2140

"<a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a> = yes" imply "<a href="postconf.5.html#smtp_use_tls">smtp_use_tls</a> = yes".

2141

2142

<li> When both hostname and next-hop destination lookups produce

2143

a result, the more specific per-site policy (NONE, MUST, etc)

2144

overrides the less specific one (MAY), and the more secure per-site

2145

policy (MUST, etc) overrides the less secure one (NONE).

2146

2147

<li> After the per-site policy lookups are combined, the result

2148

generally overrides the global policy. The exception is the less

2149

specific "MAY" per-site policy, which is overruled by the more

2150

specific global "<a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a> = yes" with server certificate

2151

verification as specified with the <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>

2152

parameter.

2153

2154

</ul>

2155

2156

<h3> <a name="client_tls_harden"> Closing a DNS loophole with

2157

obsolete per-site TLS policies </a> </h3>

2158

2159

For a general discussion of TLS security for SMTP see <a

2160

href="#client_tls_limits">TLS limitations</a> above. What follows applies

2161

only to Postfix 2.2.9 and subsequent Postfix 2.2 patch levels. Do

2162

not use this approach with Postfix 2.3

2163

and later; instead see the instructions under <a

2164

href="#client_tls_secure">secure</a> server certificate verification.

2165

2166

As long as no secure DNS lookup mechanism is available, false

2167

hostnames in MX or CNAME responses can change Postfix's notion of the

2168

server hostname that is used for TLS policy lookup and server certificate

2169

verification. Even with a perfect match between the server hostname and

2170

the server certificate, there is no guarantee that Postfix is connected

2171

to the right server. To avoid this loophole, take all of the following

2172

steps:

2173

2174

<ol>

2175

2176

<li> Use a dedicated message delivery transport (for example,

2177

"securetls") as illustrated below.

2178

2179

<li> Eliminate MX lookups. Specify local <a href="transport.5.html">transport(5)</a> table

2180

entries for sensitive domains with explicit securetls:[mailhost]

2181

or securetls:[mailhost]:port destinations (you can

2182

assure security of this table unlike DNS). This prevents false

2183

hostname information in DNS MX records from changing Postfix's

2184

notion of the server hostname that is used for TLS policy lookup

2185

and server certificate verification. The "securetls" transport is

2186

configured to enforce TLS with peername verification, and to disable

2187

the SMTP connection cache which could interfere with enforcement

2188

of <a href="postconf.5.html#smtp_tls_per_site">smtp_tls_per_site</a> policies.

2189

2190

<li> Disallow CNAME hostname overrides. In <a href="postconf.5.html">main.cf</a>, specify

2191

"<a href="postconf.5.html#smtp_cname_overrides_servername">smtp_cname_overrides_servername</a> = no". This prevents false hostname

2192

information in DNS CNAME records from changing the server hostname

2193

that Postfix uses for TLS policy lookup and server certificate

2194

verification. This feature requires Postfix 2.2.9 or later. The

2195

default value is "no" starting with Postfix 2.3.

2196

2197

</ol>

2198

2199

Example:

2200

2201

We give the <a href="postconf.5.html#default_transport">non-default</a>

2202

"securetls" transport an explicit <a href="master.5.html">master.cf</a> process limit, so that we

2203

don't raise its process limit when raising $<a href="postconf.5.html#default_process_limit">default_process_limit</a>. The

2204

total process limit for *all* transports should stay somewhat under 1024

2205

(the typical select() file descriptor limit); otherwise transports may

2206

be throttled under steady high load, compounding congestion. It is not

2207

uncommon at high volume sites to set the default process limit to 500

2208

or more.

2209

2210

We also default the "securetls" transport TLS security level to

2211

<a href="#client_tls_verify">MUST</a>, obviating the need for <a

2212

href="#client_tls_obs">per-site</a> table entries for secure-channel

2213

destinations.

2214

2215

2216

<pre>

2217

/etc/postfix/<a href="postconf.5.html">main.cf</a>:

2218

<a href="postconf.5.html#transport_maps">transport_maps</a> = hash:/etc/postfix/transport

2219

2220

/etc/postfix/transport:

2221

example.com securetls:[tls.example.com]

2222

2223

/etc/postfix/<a href="master.5.html">master.cf</a>:

2224

securetls unix - - n - 100 smtp

2225

-o <a href="postconf.5.html#smtp_enforce_tls">smtp_enforce_tls</a>=yes

2226

-o <a href="postconf.5.html#smtp_tls_enforce_peername">smtp_tls_enforce_peername</a>=yes

2227

</pre>

2228

</blockquote>

2229

2230

1807

<h3> <a name="client_tls_discover"> Discovering servers that support

2231

1808

TLS </a> </h3>

2232

1809

2655

2232

<a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> =

2656

2233

btree:/var/lib/postfix/smtpd_tls_session_cache

2657

2234

<a href="postconf.5.html#tls_random_source">tls_random_source</a> = dev:/dev/urandom

2658

# Postfix 2.3 and later

2659

2235

<a href="postconf.5.html#smtpd_tls_security_level">smtpd_tls_security_level</a> = may

2660

# Obsolete, but still supported

2661

<a href="postconf.5.html#smtpd_use_tls">smtpd_use_tls</a> = yes

2662

</pre>

2663

</blockquote>

2664

2665

</ul>

2666

2236

</pre>

2237

</blockquote>

2238

2239

</ul>

2240

2241

2242

<h2><a name="build_tls">Building Postfix with TLS support</a></h2>

2243

2244

These instructions assume that you build Postfix from source

2245

code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may

2246

be required if you build Postfix from a vendor-specific source

2247

package.

2248

2249

To build Postfix with TLS support, first we need to generate

2250

the <tt>make(1)</tt> files with the necessary definitions. This is

2251

done by invoking the command "<tt>make makefiles</tt>" in the Postfix

2252

top-level directory and with arguments as shown next.

2253

2254

NOTE: Do not use Gnu TLS. It will spontaneously terminate

2255

a Postfix daemon process with exit status code 2, instead of allowing

2256

Postfix to 1) report the error to the maillog file, and to 2) provide

2257

plaintext service where this is appropriate.

2258

2259

<ul>

2260

2261

<li> If the OpenSSL include files (such as <tt>ssl.h</tt>) are

2262

in directory <tt>/usr/include/openssl</tt>, and the OpenSSL libraries

2263

(such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>) are in

2264

directory <tt>/usr/lib</tt>:

2265

2266

2267

<pre>

2268

% make tidy # if you have left-over files from a previous build

2269

% make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"

2270

</pre>

2271

</blockquote>

2272

2273

<li> If the OpenSSL include files (such as <tt>ssl.h</tt>) are

2274

in directory <tt>/usr/local/include/openssl</tt>, and the OpenSSL

2275

libraries (such as <tt>libssl.so</tt> and <tt>libcrypto.so</tt>)

2276

are in directory <tt>/usr/local/lib</tt>:

2277

2278

2279

<pre>

2280

% make tidy # if you have left-over files from a previous build

2281

% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \

2282

AUXLIBS="-L/usr/local/lib -lssl -lcrypto"

2283

</pre>

2284

</blockquote>

2285

2286

On Solaris, specify the <tt>-R</tt> option as shown below:

2287

2288

2289

<pre>

2290

% make tidy # if you have left-over files from a previous build

2291

% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \

2292

AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto"

2293

</pre>

2294

</blockquote>

2295

2296

</ul>

2297

2298

If you need to apply other customizations (such as Berkeley DB

2299

databases, MySQL, PostgreSQL, LDAP or SASL), see the respective

2300

Postfix README documents, and combine their "<tt>make makefiles</tt>"

2301

instructions with the instructions above:

2302

2303

2304

<pre>

2305

% make tidy # if you have left-over files from a previous build

2306

% make makefiles CCARGS="-DUSE_TLS \

2307

(other -D or -I options)" \

2308

AUXLIBS="-lssl -lcrypto \

2309

(other -l options for libraries in /usr/lib) \

2310

(-L/path/name + -l options for other libraries)"

2311

</pre>

2312

</blockquote>

2313

2314

To complete the build process, see the Postfix <a href="INSTALL.html">INSTALL</a>

2315

instructions. Postfix has TLS support turned off by default, so

2316

you can start using Postfix as soon as it is installed.

2667

2317

2668

2318

<h2> <a name="problems"> Reporting problems </a> </h2>

2669

2319

Older »