From c9e081a9dcdd8c33eba3f97970a76b1afcfbea7c Mon Sep 17 00:00:00 2001 From: Wietse Venema Date: Fri, 29 Dec 2006 00:00:00 -0500 Subject: [PATCH] postfix-2.4-20061229 --- postfix/HISTORY | 11 + postfix/README_FILES/AAAREADME | 1 + postfix/README_FILES/TLS_LEGACY_README | 1111 +++++++++++++++++ postfix/README_FILES/TLS_README | 45 +- postfix/html/TLS_LEGACY_README.html | 1596 ++++++++++++++++++++++++ postfix/html/TLS_README.html | 58 +- postfix/html/index.html | 2 + postfix/proto/Makefile.in | 10 +- postfix/proto/TLS_LEGACY_README.html | 1596 ++++++++++++++++++++++++ postfix/proto/TLS_README.html | 58 +- postfix/src/dns/dns_lookup.c | 6 + postfix/src/global/mail_version.h | 2 +- postfix/src/smtpd/smtpd_check.c | 24 +- 13 files changed, 4364 insertions(+), 156 deletions(-) create mode 100644 postfix/README_FILES/TLS_LEGACY_README create mode 100644 postfix/html/TLS_LEGACY_README.html create mode 100644 postfix/proto/TLS_LEGACY_README.html diff --git a/postfix/HISTORY b/postfix/HISTORY index 51a92d9bf..977239ad2 100644 --- a/postfix/HISTORY +++ b/postfix/HISTORY @@ -13047,6 +13047,17 @@ Apologies for any names omitted. Feature: time unit suffix support in _command_time_limit. Files: pipe/pipe.c, spawn/spawn.c. +20061227 + + Bugfix: the MX hostname syntax check was accidentally skipped + with reject_unknown_helo_hostname/sender_domain/recipient_domain. + File: smtpd/smtpd_check.c. + +20061229 + + Cleanup: use separate TLS_LEGACY_README to document the old + TLS user interface. This will simplify TLS_README dramatically. + Wish list: Update MILTER_README with Martinec info. diff --git a/postfix/README_FILES/AAAREADME b/postfix/README_FILES/AAAREADME index 86046121e..4a317e155 100644 --- a/postfix/README_FILES/AAAREADME +++ b/postfix/README_FILES/AAAREADME @@ -9,6 +9,7 @@ GGeenneerraall ccoonnffiigguurraattiioonn * VIRTUAL_README: Virtual domain hosting * SASL_README: SASL Authentication * TLS_README: TLS Encryption and authentication + * TLS_LEGACY_README: Legacy TLS support * IPV6_README: IP Version 6 Support * INSTALL: Installation from source code diff --git a/postfix/README_FILES/TLS_LEGACY_README b/postfix/README_FILES/TLS_LEGACY_README new file mode 100644 index 000000000..c534beb48 --- /dev/null +++ b/postfix/README_FILES/TLS_LEGACY_README @@ -0,0 +1,1111 @@ +PPoossttffiixx lleeggaaccyy TTLLSS SSuuppppoorrtt + +------------------------------------------------------------------------------- + +NNOOTTEE + +This document describes an old TLS user interface that is based on a third- +party TLS patch by Lutz Jänicke. As of Postfix version 2.3, the old user +interface still exists to allow migration from earlier Postfix releases, but +its functionality is frozen. + +WWhhaatt PPoossttffiixx TTLLSS ssuuppppoorrtt ddooeess ffoorr yyoouu + +Transport Layer Security (TLS, formerly called SSL) provides certificate-based +authentication and encrypted sessions. An encrypted session protects the +information that is transmitted with SMTP mail or with SASL authentication. + +Postfix version 2.2 introduces support for TLS as described in RFC 3207. TLS +Support for older Postfix versions was available as an add-on patch. The +section "Compatibility with Postfix < 2.2 TLS support" below discusses the +differences between these implementations. + +Topics covered in this document: + + * How Postfix TLS support works + * Building Postfix with TLS support + * SMTP Server specific settings + * SMTP Client specific settings + * TLS manager specific settings + * Reporting problems + * Compatibility with Postfix < 2.2 TLS support + * Credits + +And last but not least, for the impatient: + + * Getting started, quick and dirty + +HHooww PPoossttffiixx TTLLSS ssuuppppoorrtt wwoorrkkss + +The diagram below shows the main elements of the Postfix TLS architecture and +their relationships. Colored boxes with numbered names represent Postfix daemon +programs. Other colored boxes represent storage elements. + + * The smtpd(8) server implements the SMTP over TLS server side. + + * The smtp(8) client implements the SMTP over TLS client side. + + * The tlsmgr(8) server maintains the pseudo-random number generator (PRNG) + that seeds the TLS engines in the smtpd(8) server and smtp(8) client + processes, and maintains the TLS session key cache files. + + <---seed--- ---seed---> +Network-> smtpd(8) tlsmgr(8) smtp(8) ->Network + <-session-> <-session-> + + / | \ + | + / \ + + smtpd PRNG smtp + session state session + key cache file key cache + +BBuuiillddiinngg PPoossttffiixx wwiitthh TTLLSS ssuuppppoorrtt + +To build Postfix with TLS support, first we need to generate the make(1) files +with the necessary definitions. This is done by invoking the command "make +makefiles" in the Postfix top-level directory and with arguments as shown next. + +NNOOTTEE:: DDoo nnoott uussee GGnnuu TTLLSS.. IItt wwiillll ssppoonnttaanneeoouussllyy tteerrmmiinnaattee aa PPoossttffiixx ddaaeemmoonn +pprroocceessss wwiitthh eexxiitt ssttaattuuss ccooddee 22,, iinnsstteeaadd ooff aalllloowwiinngg PPoossttffiixx ttoo 11)) rreeppoorrtt tthhee +eerrrroorr ttoo tthhee mmaaiilllloogg ffiillee,, aanndd ttoo 22)) pprroovviiddee ppllaaiinntteexxtt sseerrvviiccee wwhheerree tthhiiss iiss +aapppprroopprriiaattee.. + + * If the OpenSSL include files (such as ssl.h) are in directory /usr/include/ + openssl, and the OpenSSL libraries (such as libssl.so and libcrypto.so) are + in directory /usr/lib: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS"" AAUUXXLLIIBBSS==""--llssssll --llccrryyppttoo"" + + * If the OpenSSL include files (such as ssl.h) are in directory /usr/local/ + include/openssl, and the OpenSSL libraries (such as libssl.so and + libcrypto.so) are in directory /usr/local/lib: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS --II//uussrr//llooccaall//iinncclluuddee"" \\ + AAUUXXLLIIBBSS==""--LL//uussrr//llooccaall//lliibb --llssssll --llccrryyppttoo"" + + On Solaris, specify the -R option as shown below: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS --II//uussrr//llooccaall//iinncclluuddee"" \\ + AAUUXXLLIIBBSS==""--RR//uussrr//llooccaall//lliibb --LL//uussrr//llooccaall//lliibb --llssssll --llccrryyppttoo"" + +If you need to apply other customizations (such as Berkeley DB databases, +MySQL, PosgreSQL, LDAP or SASL), see the respective Postfix README documents, +and combine their "make makefiles" instructions with the instructions above: + + % mmaakkee ttiiddyy # if you have left-over files from a previous build + % mmaakkee mmaakkeeffiilleess CCCCAARRGGSS==""--DDUUSSEE__TTLLSS \\ + ((ootthheerr --DD oorr --II ooppttiioonnss))"" \\ + AAUUXXLLIIBBSS==""--llssssll --llccrryyppttoo \\ + ((ootthheerr --ll ooppttiioonnss ffoorr lliibbrraarriieess iinn //uussrr//lliibb)) \\ + ((--LL//ppaatthh//nnaammee ++ --ll ooppttiioonnss ffoorr ootthheerr lliibbrraarriieess))"" + +To complete the build process, see the Postfix INSTALL instructions. Postfix +has TLS support turned off by default, so you can start using Postfix as soon +as it is installed. + +SSMMTTPP SSeerrvveerr ssppeecciiffiicc sseettttiinnggss + +Topics covered in this section: + + * Server-side certificate and private key configuration + * Server-side TLS activity logging + * Enabling TLS in the Postfix SMTP server + * Client certificate verification + * Supporting AUTH over TLS only + * Server-side TLS session cache + * Server access control + * Server-side cipher controls + * Miscellaneous server controls + +SSeerrvveerr--ssiiddee cceerrttiiffiiccaattee aanndd pprriivvaattee kkeeyy ccoonnffiigguurraattiioonn + +In order to use TLS, the Postfix SMTP server needs a certificate and a private +key. Both must be in "pem" format. The private key must not be encrypted, +meaning: the key must be accessible without password. Both certificate and +private key may be in the same file. + +Both RSA and DSA certificates are supported. Typically you will only have RSA +certificates issued by a commercial CA. In addition, the tools supplied with +OpenSSL will by default issue RSA certificates. You can have both at the same +time, in which case the cipher used determines which certificate is presented. +For Netscape and OpenSSL clients without special cipher choices, the RSA +certificate is preferred. + +In order for remote SMTP clients to check the Postfix SMTP server certificates, +the CA certificate (in case of a certificate chain, all CA certificates) must +be available. You should add these certificates to the server certificate, the +server certificate first, then the issuing CA(s). + +Example: the certificate for "server.dom.ain" was issued by "intermediate CA" +which itself has a certificate issued by "root CA". Create the server.pem file +with: + + % ccaatt sseerrvveerr__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> sseerrvveerr..ppeemm + +A Postfix SMTP server certificate supplied here must be usable as SSL server +certificate and hence pass the "openssl verify -purpose sslserver ..." test. + +A client that trusts the root CA has a local copy of the root CA certificate, +so it is not necessary to include the root CA certificate here. Leaving it out +of the "server.pem" file reduces the overhead of the TLS exchange. + +If you want the Postfix SMTP server to accept remote SMTP client certificates +issued by these CAs, append the root certificate to $smtpd_tls_CAfile or +install it in the $smtpd_tls_CApath directory. When you configure trust in a +root CA, it is not necessary to explicitly trust intermediary CAs signed by the +root CA, unless $smtpd_tls_ccert_verifydepth is less than the number of CAs in +the certificate chain for the clients of interest. With a verify depth of 1 you +can only verify certificates directly signed by a trusted CA, and all trusted +intermediary CAs need to be configured explicitly. With a verify depth of 2 you +can verify clients signed by a root CA or a direct intermediary CA (so long as +the client is correctly configured to supply its intermediate CA certificate). + +RSA key and certificate examples: + + /etc/postfix/main.cf: + smtpd_tls_cert_file = /etc/postfix/server.pem + smtpd_tls_key_file = $smtpd_tls_cert_file + +Their DSA counterparts: + + /etc/postfix/main.cf: + smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem + smtpd_tls_dkey_file = $smtpd_tls_dcert_file + +To verify a remote SMTP client certificate, the Postfix SMTP server needs to +trust the certificates of the issuing certification authorities. These +certificates in "pem" format can be stored in a single $smtpd_tls_CAfile or in +multiple files, one CA per file in the $smtpd_tls_CApath directory. If you use +a directory, don't forget to create the necessary "hash" links with: + + # $$OOPPEENNSSSSLL__HHOOMMEE//bbiinn//cc__rreehhaasshh //ppaatthh//ttoo//ddiirreeccttoorryy + +The $smtpd_tls_CAfile contains the CA certificates of one or more trusted CAs. +The file is opened (with root privileges) before Postfix enters the optional +chroot jail and so need not be accessible from inside the chroot jail. + +Additional trusted CAs can be specified via the $smtpd_tls_CApath directory, in +which case the certificates are read (with $mail_owner privileges) from the +files in the directory when the information is needed. Thus, the +$smtpd_tls_CApath directory needs to be accessible inside the optional chroot +jail. + +When you configure Postfix to request client certificates (by setting +$smtpd_tls_ask_ccert = yes), any certificates in $smtpd_tls_CAfile are sent to +the client, in order to allow it to choose an identity signed by a CA you +trust. If no $smtpd_tls_CAfile is specified, no preferred CA list is sent, and +the client is free to choose an identity signed by any CA. Many clients use a +fixed identity regardless of the preferred CA list and you may be able to +reduce TLS negotiation overhead by installing client CA certificates mostly or +only in $smtpd_tls_CApath. In the latter case you need not specify a +$smtpd_tls_CAfile. + +Note, that unless client certificates are used to allow greater access to TLS +authenticated clients, it is best to not ask for client certificates at all, as +in addition to increased overhead some clients (notably in some cases qmail) +are unable to complete the TLS handshake when client certificates are +requested. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_CAfile = /etc/postfix/CAcert.pem + smtpd_tls_CApath = /etc/postfix/certs + +SSeerrvveerr--ssiiddee TTLLSS aaccttiivviittyy llooggggiinngg + +To get additional information about Postfix SMTP server TLS activity you can +increase the loglevel from 0..4. Each logging level also includes the +information that is logged at a lower logging level. + + 0 Disable logging of TLS activity. + + 1 Log TLS handshake and certificate information. + + 2 Log levels during TLS negotiation. + + 3 Log hexadecimal and ASCII dump of TLS negotiation process + + 4 Log hexadecimal and ASCII dump of complete transmission after STARTTLS + +Use loglevel 3 only in case of problems. Use of loglevel 4 is strongly +discouraged. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_loglevel = 0 + +To include information about the protocol and cipher used as well as the client +and issuer CommonName into the "Received:" message header, set the +smtpd_tls_received_header variable to true. The default is no, as the +information is not necessarily authentic. Only information recorded at the +final destination is reliable, since the headers may be changed by intermediate +servers. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_received_header = yes + +EEnnaabblliinngg TTLLSS iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr + +By default, TLS is disabled in the Postfix SMTP server, so no difference to +plain Postfix is visible. Explicitly switch it on using "smtpd_use_tls = yes". + +Example: + + /etc/postfix/main.cf: + smtpd_use_tls = yes + +With this, Postfix SMTP server announces STARTTLS support to SMTP clients, but +does not require that clients use TLS encryption. + +Note: when an unprivileged user invokes "sendmail -bs", STARTTLS is never +offered due to insufficient privileges to access the server private key. This +is intended behavior. + +You can ENFORCE the use of TLS, so that the Postfix SMTP server announces +STARTTLS and accepts no mail without TLS encryption, by setting +"smtpd_enforce_tls = yes". According to RFC 2487 this MUST NOT be applied in +case of a publicly-referenced Postfix SMTP server. This option is off by +default and should only seldom be used. + +Example: + + /etc/postfix/main.cf: + smtpd_enforce_tls = yes + +TLS is sometimes used in the non-standard "wrapper" mode where a server always +uses TLS, instead of announcing STARTTLS support and waiting for clients to +request TLS service. Some clients, namely Outlook [Express] prefer the +"wrapper" mode. This is true for OE (Win32 < 5.0 and Win32 >=5.0 when run on a +port<>25 and OE (5.01 Mac on all ports). + +It is strictly discouraged to use this mode from main.cf. If you want to +support this service, enable a special port in master.cf and specify "- +o smtpd_tls_wrappermode = yes" as an smtpd(8) command line option. Port 465 +(smtps) was once chosen for this feature. + +Example: + + /etc/postfix/master.cf: + smtps inet n - n - - smtpd + -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes + +CClliieenntt cceerrttiiffiiccaattee vveerriiffiiccaattiioonn + +To receive a remote SMTP client certificate, the Postfix SMTP server must +explicitly ask for one (any contents of $smtpd_tls_CAfile are also sent to the +client as a hint for choosing a certificate from a suitable CA). Unfortunately, +Netscape clients will either complain if no matching client certificate is +available or will offer the user client a list of certificates to choose from. +Additionally some MTAs (notably some versions of qmail) are unable to complete +TLS negotiation when client certificates are requested, and abort the SMTP +session. So this option is "off" by default. You will however need the +certificate if you want to use certificate based relaying with, for example, +the permit_tls_clientcerts feature. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_ask_ccert = no + +You may also decide to REQUIRE a remote SMTP client certificate before allowing +TLS connections. This feature is included for completeness, and implies +"smtpd_tls_ask_ccert = yes". + +Please be aware, that this will inhibit TLS connections without a proper client +certificate and that it makes sense only when non-TLS submission is disabled +(smtpd_enforce_tls = yes). Otherwise, clients could bypass the restriction by +simply not using STARTTLS at all. + +When TLS is not enforced, the connection will be handled as if only +"smtpd_tls_ask_ccert = yes" is specified, and a warning is logged. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_req_ccert = no + +A client certificate verification depth of 1 is sufficient if the certificate +is directly issued by a CA listed in the CA file. The default value (5) should +also suffice for longer chains (root CA issues special CA which then issues the +actual certificate...) + +Example: + + /etc/postfix/main.cf: + smtpd_tls_ccert_verifydepth = 5 + +SSuuppppoorrttiinngg AAUUTTHH oovveerr TTLLSS oonnllyy + +Sending AUTH data over an unencrypted channel poses a security risk. When TLS +layer encryption is required (smtpd_enforce_tls = yes), the Postfix SMTP server +will announce and accept AUTH only after the TLS layer has been activated with +STARTTLS. When TLS layer encryption is optional (smtpd_enforce_tls = no), it +may however still be useful to only offer AUTH when TLS is active. To maintain +compatibility with non-TLS clients, the default is to accept AUTH without +encryption. In order to change this behavior, set "smtpd_tls_auth_only = yes". + +Example: + + /etc/postfix/main.cf: + smtpd_tls_auth_only = no + +SSeerrvveerr--ssiiddee TTLLSS sseessssiioonn ccaacchhee + +The Postfix SMTP server and the remote SMTP client negotiate a session, which +takes some computer time and network bandwidth. By default, this session +information is cached only in the smtpd(8) process actually using this session +and is lost when the process terminates. To share the session information +between multiple smtpd(8) processes, a persistent session cache can be used. +You can specify any database type that can store objects of several kbytes and +that supports the sequence operator. DBM databases are not suitable because +they can only store small objects. The cache is maintained by the tlsmgr(8) +process, so there is no problem with concurrent access. Session caching is +highly recommended, because the cost of repeatedly negotiating TLS session keys +is high. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_session_cache_database = btree:/etc/postfix/smtpd_scache + +Cached Postfix SMTP server session information expires after a certain amount +of time. Postfix/TLS does not use the OpenSSL default of 300s, but a longer +time of 3600sec (=1 hour). RFC 2246 recommends a maximum of 24 hours. + +Example: + + /etc/postfix/main.cf: + smtpd_tls_session_cache_timeout = 3600s + +SSeerrvveerr aacccceessss ccoonnttrrooll + +Postfix TLS support introduces three additional features for Postfix SMTP +server access control: + + permit_tls_clientcerts + Allow the remote SMTP client SMTP request if the client certificate + passes verification, and if its fingerprint is listed in the list of + client certificates (see relay_clientcerts discussion below). + + permit_tls_all_clientcerts + Allow the remote client SMTP request if the client certificate passes + verification. + + check_ccert_access type:table + If the client certificate passes verification, use its fingerprint as a + key for the specified access(5) table. + +The permit_tls_all_clientcerts feature must be used with caution, because it +can result in too many access permissions. Use this feature only if a special +CA issues the client certificates, and only if this CA is listed as trusted CA. +If other CAs are trusted, any owner of a valid client certificate would be +authorized. The permit_tls_all_clientcerts feature can be practical for a +specially created email relay server. + +It is however recommended to stay with the permit_tls_clientcerts feature and +list all certificates via $relay_clientcerts, as permit_tls_all_clientcerts +does not permit any control when a certificate must no longer be used (e.g. an +employee leaving). + +Example: + + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + ... + permit_tls_clientcerts + reject_unauth_destination + ... + +The Postfix list manipulation routines give special treatment to whitespace and +some other characters, making the use of certificate names impractical. Instead +we use the certificate fingerprints as they are difficult to fake but easy to +use for lookup. Postfix lookup tables are in the form of (key, value) pairs. +Since we only need the key, the value can be chosen freely, e.g. the name of +the user or host. + +Example: + + /etc/postfix/main.cf: + relay_clientcerts = hash:/etc/postfix/relay_clientcerts + + /etc/postfix/relay_clientcerts: + D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home + +SSeerrvveerr--ssiiddee cciipphheerr ccoonnttrroollss + +To influence the Postfix SMTP server cipher selection scheme, you can give +cipherlist string. A detailed description would go to far here; please refer to +the OpenSSL documentation. If you don't know what to do with it, simply don't +touch it and leave the (openssl-)compiled in default! + +DO NOT USE " to enclose the string, specify just the string!!! + +Example: + + /etc/postfix/main.cf: + smtpd_tls_cipherlist = DEFAULT + +If you want to take advantage of ciphers with EDH, DH parameters are needed. +Instead of using the built-in DH parameters for both 1024bit and 512bit, it is +better to generate "own" parameters, since otherwise it would "pay" for a +possible attacker to start a brute force attack against parameters that are +used by everybody. For this reason, the parameters chosen are already different +from those distributed with other TLS packages. + +To generate your own set of DH parameters, use: + + % ooppeennssssll ggeennddhh --oouutt //eettcc//ppoossttffiixx//ddhh__11002244..ppeemm --22 --rraanndd //vvaarr//rruunn//eeggdd--ppooooll + 11002244 + % ooppeennssssll ggeennddhh --oouutt //eettcc//ppoossttffiixx//ddhh__551122..ppeemm --22 --rraanndd //vvaarr//rruunn//eeggdd--ppooooll 551122 + +Examples: + + /etc/postfix/main.cf: + smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem + smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem + +MMiisscceellllaanneeoouuss sseerrvveerr ccoonnttrroollss + +The smtpd_starttls_timeout parameter limits the time of Postfix SMTP server +write and read operations during TLS startup and shutdown handshake procedures. + +Example: + + /etc/postfix/main.cf: + smtpd_starttls_timeout = 300s + +SSMMTTPP CClliieenntt ssppeecciiffiicc sseettttiinnggss + +Topics covered in this section: + + * Client-side certificate and private key configuration + * Client-side TLS activity logging + * Client-side TLS session cache + * Enabling TLS in the Postfix SMTP client + * Requiring TLS encryption + * Disabling server certificate verification + * Per-site TLS policies + * Closing a DNS loophole with per-site TLS policies + * Discovering servers that support TLS + * Server certificate verification depth + * Client-side cipher controls + * Miscellaneous client controls + +CClliieenntt--ssiiddee cceerrttiiffiiccaattee aanndd pprriivvaattee kkeeyy ccoonnffiigguurraattiioonn + +During TLS startup negotiation the Postfix SMTP client may present a +certificate to the remote SMTP server. The Netscape client is rather clever +here and lets the user select between only those certificates that match CA +certificates offered by the remote SMTP server. As the Postfix SMTP client uses +the "SSL_connect()" function from the OpenSSL package, this is not possible and +we have to choose just one certificate. So for now the default is to use _no_ +certificate and key unless one is explicitly specified here. + +Both RSA and DSA certificates are supported. You can have both at the same +time, in which case the cipher used determines which certificate is presented. + +It is possible for the Postfix SMTP client to use the same key/certificate pair +as the Postfix SMTP server. If a certificate is to be presented, it must be in +"pem" format. The private key must not be encrypted, meaning: it must be +accessible without password. Both parts (certificate and private key) may be in +the same file. + +In order for remote SMTP servers to verify the Postfix SMTP client +certificates, the CA certificate (in case of a certificate chain, all CA +certificates) must be available. You should add these certificates to the +client certificate, the client certificate first, then the issuing CA(s). + +Example: the certificate for "client.example.com" was issued by "intermediate +CA" which itself has a certificate of "root CA". Create the client.pem file +with: + + % ccaatt cclliieenntt__cceerrtt..ppeemm iinntteerrmmeeddiiaattee__CCAA..ppeemm >> cclliieenntt..ppeemm + +A Postfix SMTP client certificate supplied here must be usable as SSL client +certificate and hence pass the "openssl verify -purpose sslclient ..." test. + +A server that trusts the root CA has a local copy of the root CA certificate, +so it is not necessary to include the root CA certificate here. Leaving it out +of the "client.pem" file reduces the overhead of the TLS exchange. + +If you want the Postfix SMTP client to accept remote SMTP server certificates +issued by these CAs, append the root certificate to $smtp_tls_CAfile or install +it in the $smtp_tls_CApath directory. When you configure trust in a root CA, it +is not necessary to explicitly trust intermediary CAs signed by the root CA, +unless $smtp_tls_scert_verifydepth is less than the number of CAs in the +certificate chain for the servers of interest. With a verify depth of 1 you can +only verify certificates directly signed by a trusted CA, and all trusted +intermediary CAs need to be configured explicitly. With a verify depth of 2 you +can verify servers signed by a root CA or a direct intermediary CA (so long as +the server is correctly configured to supply its intermediate CA certificate). + +RSA key and certificate examples: + + /etc/postfix/main.cf: + smtp_tls_cert_file = /etc/postfix/client.pem + smtp_tls_key_file = $smtp_tls_cert_file + +Their DSA counterparts: + + /etc/postfix/main.cf: + smtp_tls_dcert_file = /etc/postfix/client-dsa.pem + smtp_tls_dkey_file = $smtpd_tls_cert_file + +To verify a remote SMTP server certificate, the Postfix SMTP client needs to +trust the certificates of the issuing certification authorities. These +certificates in "pem" format can be stored in a single $smtp_tls_CAfile or in +multiple files, one CA per file in the $smtp_tls_CApath directory. If you use a +directory, don't forget to create the necessary "hash" links with: + + # $$OOPPEENNSSSSLL__HHOOMMEE//bbiinn//cc__rreehhaasshh //ppaatthh//ttoo//ddiirreeccttoorryy + +The $smtp_tls_CAfile contains the CA certificates of one or more trusted CAs. +The file is opened (with root privileges) before Postfix enters the optional +chroot jail and so need not be accessible from inside the chroot jail. + +Additional trusted CAs can be specified via the $smtp_tls_CApath directory, in +which case the certificates are read (with $mail_owner privileges) from the +files in the directory when the information is needed. Thus, the +$smtp_tls_CApath directory needs to be accessible inside the optional chroot +jail. + +The choice between $smtp_tls_CAfile and $smtpd_tls_CApath is a space/time +tradeoff. If there are many trusted CAs, the cost of preloading them all into +memory may not pay off in reduced access time when the certificate is needed. + +Example: + + /etc/postfix/main.cf: + smtp_tls_CAfile = /etc/postfix/CAcert.pem + smtp_tls_CApath = /etc/postfix/certs + +CClliieenntt--ssiiddee TTLLSS aaccttiivviittyy llooggggiinngg + +To get additional information about Postfix SMTP client TLS activity you can +increase the loglevel from 0..4. Each logging level also includes the +information that is logged at a lower logging level. + + 0 Disable logging of TLS activity. + + 1 Log TLS handshake and certificate information. + + 2 Log levels during TLS negotiation. + + 3 Log hexadecimal and ASCII dump of TLS negotiation process + + 4 Log hexadecimal and ASCII dump of complete transmission after STARTTLS + +Example: + + /etc/postfix/main.cf: + smtp_tls_loglevel = 0 + +CClliieenntt--ssiiddee TTLLSS sseessssiioonn ccaacchhee + +The remote SMTP server and the Postfix SMTP client negotiate a session, which +takes some computer time and network bandwidth. By default, this session +information is cached only in the smtp(8) process actually using this session +and is lost when the process terminates. To share the session information +between multiple smtp(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several kbytes and that +supports the sequence operator. DBM databases are not suitable because they can +only store small objects. The cache is maintained by the tlsmgr(8) process, so +there is no problem with concurrent access. Session caching is highly +recommended, because the cost of repeatedly negotiating TLS session keys is +high. Future Postfix SMTP servers may limit the number of sessions that a +client is allowed to negotiate per unit time. + +Example: + + /etc/postfix/main.cf: + smtp_tls_session_cache_database = btree:/etc/postfix/smtp_scache + +Cached Postfix SMTP client session information expires after a certain amount +of time. Postfix/TLS does not use the OpenSSL default of 300s, but a longer +time of 3600s (=1 hour). RFC 2246 recommends a maximum of 24 hours. + +Example: + + /etc/postfix/main.cf: + smtp_tls_session_cache_timeout = 3600s + +EEnnaabblliinngg TTLLSS iinn tthhee PPoossttffiixx SSMMTTPP cclliieenntt + +By default, TLS is disabled in the Postfix SMTP client, so no difference to +plain Postfix is visible. If you enable TLS, the Postfix SMTP client will send +STARTTLS when TLS support is announced by the remote SMTP server. + +When the server accepts the STARTTLS command, but the subsequent TLS handshake +fails, and no other server is available, the Postfix SMTP client defers the +delivery attempt, and the mail stays in the queue. After a handshake failure, +the communications channel is in an indeterminate state and cannot be used for +non-TLS deliveries. + +Example: + + /etc/postfix/main.cf: + smtp_use_tls = yes + +RReeqquuiirriinngg TTLLSS eennccrryyppttiioonn + +You can ENFORCE the use of TLS, so that the Postfix SMTP client will not +deliver mail over unencrypted connections. In this mode, the remote SMTP server +hostname must match the information in the remote server certificate, and the +server certificate must be issued by a CA that is trusted by the Postfix SMTP +client. If the remote server certificate doesn't verify or the remote SMTP +server hostname doesn't match, and no other server is available, the delivery +attempt is deferred and the mail stays in the queue. + +The remote SMTP server hostname is verified against all names provided as +dNSNames in the SubjectAlternativeName. If no dNSNames are specified, the +CommonName is checked. Verification may be turned off with the +smtp_tls_enforce_peername option which is discussed below. + +Enforcing the use of TLS is useful if you know that you will only connect to +servers that support RFC 2487 _and_ that present server certificates that meet +the above requirements. An example would be a client only sends email to one +specific mailhub that offers the necessary STARTTLS support. + +Example: + + /etc/postfix/main.cf: + smtp_enforce_tls = yes + +DDiissaabblliinngg sseerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn + +As of RFC 2487 the requirements for hostname checking for MTA clients are not +set. When TLS is required (smtp_enforce_tls = yes), the option +smtp_tls_enforce_peername can be set to "no" to disable strict remote SMTP +server hostname checking. In this case, the mail delivery will proceed +regardless of the CommonName etc. listed in the certificate. + +Despite the potential for eliminating "man-in-the-middle" and other attacks, +mandatory certificate/peername verification is not viable as a default Internet +mail delivery policy at this time. A significant fraction of TLS enabled MTAs +uses self-signed certificates, or certificates that are signed by a private +certificate authority. On a machine that delivers mail to the Internet, if you +set smtp_enforce_tls = yes, you should probably also set +smtp_tls_enforce_peername = no. You can use the per-site TLS policies (see +below) to enable full peer verification for specific destinations that are +known to have verifiable TLS server certificates. + +Example: + + /etc/postfix/main.cf: + smtp_enforce_tls = yes + smtp_tls_enforce_peername = no + +PPeerr--ssiittee TTLLSS ppoolliicciieess + +A small fraction of servers offer STARTTLS but the negotiation consistently +fails, leading to mail aging out of the queue and bouncing back to the sender. +In such cases, you can use the per-site policies to disable TLS for the problem +sites. Alternatively, you can enable TLS for just a few specific sites and not +enable it for all sites. + +The smtp_tls_per_site table is searched for a policy that matches the following +information: + + remote SMTP server hostname + This is simply the DNS name of the server that the Postfix SMTP client + connects to; this name may be obtained from other DNS lookups, such as + MX lookups or CNAME lookups. + next-hop destination + This is normally the domain portion of the recipient address, but it + may be overruled by information from the transport(5) table, from the + relayhost parameter setting, or from the relay_transport setting. When + it's not the recipient domain, the next-hop destination can have the + Postfix-specific form "[name]", [name]:port", "name" or "name:port". + +When both the hostname lookup and the next-hop lookup succeed, the host policy +does not automatically override the next-hop policy. Instead, precedence is +given to either the more specific or the more secure per-site policy as +described below. + +The smtp_tls_per_site table uses a simple "name whitespace value" format. +Specify host names or next-hop destinations on the left-hand side; no wildcards +are allowed. On the right hand side specify one of the following keywords: + + NONE + Don't use TLS at all. This overrides a less specific MMAAYY lookup result + from the alternate host or next-hop lookup key, and overrides the + global smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername + settings. + MAY + Try to use TLS if the server announces support, otherwise use the + unencrypted connection. This has less precedence than a more specific + result (including NNOONNEE) from the alternate host or next-hop lookup key, + and has less precedence than the more specific global "smtp_enforce_tls + = yes" or "smtp_tls_enforce_peername = yes". + MUST_NOPEERMATCH + Require TLS encryption, but do not require that the remote SMTP server + hostname matches the information in the remote SMTP server certificate, + or that the server certificate was issued by a trusted CA. This + overrides a less secure NNOONNEE or a less specific MMAAYY lookup result from + the alternate host or next-hop lookup key, and overrides the global + smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername settings. + MUST + Require TLS encryption, require that the remote SMTP server hostname + matches the information in the remote SMTP server certificate, and + require that the remote SMTP server certificate was issued by a trusted + CA. This overrides a less secure NNOONNEE and MMUUSSTT__NNOOPPEEEERRMMAATTCCHH or a less + specific MMAAYY lookup result from the alternate host or next-hop lookup + key, and overrides the global smtp_use_tls, smtp_enforce_tls and + smtp_tls_enforce_peername settings. + +The precedences between global (main.cf) and per-site TLS policies can be +summarized as follows: + + * When neither the remote SMTP server hostname nor the next-hop destination + are found in the smtp_tls_per_site table, the policy is based on + smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername. Note: + "smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes" imply + "smtp_use_tls = yes". + + * When both hostname and next-hop destination lookups produce a result, the + more specific per-site policy (NONE, MUST, etc) overrides the less specific + one (MAY), and the more secure per-site policy (MUST, etc) overrides the + less secure one (NONE). + + * After the per-site policy lookups are combined, the result generally + overrides the global policy. The exception is the less specific MMAAYY per- + site policy, which is overruled by the more specific global + "smtp_enforce_tls = yes" with server certificate verification as specified + with the smtp_tls_enforce_peername parameter. + +CClloossiinngg aa DDNNSS lloooopphhoollee wwiitthh ppeerr--ssiittee TTLLSS ppoolliicciieess + +As long as no secure DNS lookup mechanism is available, false hostnames in MX +or CNAME responses can change the server hostname that Postfix uses for TLS +policy lookup and server certificate verification. Even with a perfect match +between the server hostname and the server certificate, there is no guarantee +that Postfix is connected to the right server. To avoid this loophole take the +following steps: + + * Eliminate MX lookups. Specify local transport(5) table entries for + sensitive domains with explicit smtp:[mailhost] or smtp:[mailhost]:port + destinations (you can assure security of this table unlike DNS); in the + smtp_tls_per_site table specify the value MMUUSSTT for the key [mailhost] or + smtp:[mailhost]:port. This prevents false hostname information in DNS MX + records from changing the server hostname that Postfix uses for TLS policy + lookup and server certificate verification. + + * Disallow CNAME hostname overrides. In main.cf specify + "smtp_cname_overrides_servername = no". This prevents false hostname + information in DNS CNAME records from changing the server hostname that + Postfix uses for TLS policy lookup and server certificate verification. + This feature requires Postfix 2.2.9 or later. + +Example: + + /etc/postfix/main.cf: + smtp_tls_per_site = hash:/etc/postfix/tls_per_site + relayhost = [msa.example.net]:587 + + /etc/postfix/tls_per_site: + # relayhost exact nexthop match + [msa.example.net]:587 MUST + + # TLS should not be used with the example.org MX hosts. + example.org NONE + + # TLS should not be used with the host smtp.example.com. + smtp.example.com NONE + +DDiissccoovveerriinngg sseerrvveerrss tthhaatt ssuuppppoorrtt TTLLSS + +As we decide on a "per site" basis whether or not to use TLS, it would be good +to have a list of sites that offered "STARTTLS". We can collect it ourselves +with this option. + +If the smtp_tls_note_starttls_offer feature is enabled and a server offers +STARTTLS while TLS is not already enabled for that server, the Postfix SMTP +client logs a line as follows: + + postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com] + +Example: + + /etc/postfix/main.cf: + smtp_tls_note_starttls_offer = yes + +SSeerrvveerr cceerrttiiffiiccaattee vveerriiffiiccaattiioonn ddeepptthh + +When verifying a remote SMTP server certificate, a verification depth of 1 is +sufficient if the certificate is directly issued by a CA specified with +smtp_tls_CAfile or smtp_tls_CApath. The default value of 5 should also suffice +for longer chains (root CA issues special CA which then issues the actual +certificate...) + +Example: + + /etc/postfix/main.cf: + smtp_tls_scert_verifydepth = 5 + +CClliieenntt--ssiiddee cciipphheerr ccoonnttrroollss + +To influence the Postfix SMTP client cipher selection scheme, you can give +cipherlist string. A detailed description would go to far here; please refer to +the OpenSSL documentation. If you don't know what to do with it, simply don't +touch it and leave the (openssl-)compiled in default! + +DO NOT USE " to enclose the string, specify just the string!!! + +Example: + + /etc/postfix/main.cf: + smtp_tls_cipherlist = DEFAULT + +MMiisscceellllaanneeoouuss cclliieenntt ccoonnttrroollss + +The smtp_starttls_timeout parameter limits the time of Postfix SMTP client +write and read operations during TLS startup and shutdown handshake procedures. +In case of problems the Postfix SMTP client tries the next network address on +the mail exchanger list, and defers delivery if no alternative server is +available. + +Example: + + /etc/postfix/main.cf: + smtp_starttls_timeout = 300s + +TTLLSS mmaannaaggeerr ssppeecciiffiicc sseettttiinnggss + +The security of cryptographic software such as TLS depends critically on the +ability to generate unpredictable numbers for keys and other information. To +this end, the tlsmgr(8) process maintains a Pseudo Random Number Generator +(PRNG) pool. This is queried by the smtp(8) and smtpd(8) processes when they +initialize. By default, these daemons request 32 bytes, the equivalent to 256 +bits. This is more than sufficient to generate a 128bit (or 168bit) session +key. + +Example: + + /etc/postfix/main.cf: + tls_daemon_random_bytes = 32 + +In order to feed its in-memory PRNG pool, the tlsmgr(8) reads entropy from an +external source, both at startup and during run-time. Specify a good entropy +source, like EGD or /dev/urandom; be sure to only use non-blocking sources (on +OpenBSD, use /dev/arandom when tlsmgr(8) complains about /dev/urandom timeout +errors). If the entropy source is not a regular file, you must prepend the +source type to the source name: "dev:" for a device special file, or "egd:" for +a source with EGD compatible socket interface. + +Examples (specify only one in main.cf): + + /etc/postfix/main.cf: + tls_random_source = dev:/dev/urandom + tls_random_source = egd:/var/run/egd-pool + +By default, tlsmgr(8) reads 32 bytes from the external entropy source at each +seeding event. This amount (256bits) is more than sufficient for generating a +128bit symmetric key. With EGD and device entropy sources, the tlsmgr(8) limits +the amount of data read at each step to 255 bytes. If you specify a regular +file as entropy source, a larger amount of data can be read. + +Example: + + /etc/postfix/main.cf: + tls_random_bytes = 32 + +In order to update its in-memory PRNG pool, the tlsmgr(8) queries the external +entropy source again after a pseudo-random amount of time. The time is +calculated using the PRNG, and is between 0 and the maximal time specified with +tls_random_reseed_period. The default maximal time interval is 1 hour. + +Example: + + /etc/postfix/main.cf: + tls_random_reseed_period = 3600s + +The tlsmgr(8) process saves the PRNG state to a persistent exchange file at +regular times and when the process terminates, so that it can recover the PRNG +state the next time it starts up. This file is created when it does not exist. +Its default location is under the Postfix configuration directory, which is not +the proper place for information that is modified by Postfix. Instead, the file +location should probably be on the /var partition (but nnoott inside the chroot +jail). + +Examples: + + /etc/postfix/main.cf: + tls_random_exchange_name = /etc/postfix/prng_exch + tls_random_prng_update_period = 3600s + +GGeettttiinngg ssttaarrtteedd,, qquuiicckk aanndd ddiirrttyy + +The following steps will get you started quickly. Because you sign your own +Postfix public key certificate, you get TLS encryption but no TLS +authentication. This is sufficient for testing, and for exchanging email with +sites that you have no trust relationship with. For real authentication, your +Postfix public key certificate needs to be signed by a recognized Certificate +Authority, and Postfix needs to be configured with a list of public key +certificates of Certificate Authorities, so that Postfix can verify the public +key certificates of remote hosts. + +In the examples below, user input is shown in bboolldd font, and a "#" prompt +indicates a super-user shell. + + * Become your own Certificate Authority, so that you can sign your own public + keys. This example uses the CA.pl script that ships with OpenSSL. By + default, OpenSSL installs this as /usr/local/ssl/misc/CA.pl, but your + mileage may vary. The script creates a private key in ./demoCA/private/ + cakey.pem and a public key in ./demoCA/cacert.pem. + + % //uussrr//llooccaall//ssssll//mmiisscc//CCAA..ppll --nneewwccaa + CA certificate filename (or enter to create) + + Making CA certificate ... + Using configuration from /etc/ssl/openssl.cnf + Generating a 1024 bit RSA private key + ....................++++++ + .....++++++ + writing new private key to './demoCA/private/cakey.pem' + Enter PEM pass phrase:wwhhaatteevveerr + + * Create an unpassworded private key for host FOO and create an unsigned + public key certificate. + + % ooppeennssssll rreeqq --nneeww --nnooddeess --kkeeyyoouutt FFOOOO--kkeeyy..ppeemm --oouutt FFOOOO--rreeqq..ppeemm --ddaayyss + 336655 + Using configuration from /etc/ssl/openssl.cnf + Generating a 1024 bit RSA private key + ........................................++++++ + ....++++++ + writing new private key to 'FOO-key.pem' + ----- + You are about to be asked to enter information that will be + incorporated + into your certificate request. + What you are about to enter is what is called a Distinguished Name or a + DN. + There are quite a few fields but you can leave some blank + For some fields there will be a default value, + If you enter '.', the field will be left blank. + ----- + Country Name (2 letter code) [AU]:UUSS + State or Province Name (full name) [Some-State]:NNeeww YYoorrkk + Locality Name (eg, city) []:WWeessttcchheesstteerr + Organization Name (eg, company) [Internet Widgits Pty Ltd]:PPoorrccuuppiinnee + Organizational Unit Name (eg, section) []: + Common Name (eg, YOUR name) []:FFOOOO + Email Address []:wwiieettssee@@ppoorrccuuppiinnee..oorrgg + + Please enter the following 'extra' attributes + to be sent with your certificate request + A challenge password []:wwhhaatteevveerr + An optional company name []: + + * Sign the public key certificate for host FOO with the Certification + Authority private key that we created a few steps ago. + + % ooppeennssssll ccaa --oouutt FFOOOO--cceerrtt..ppeemm --iinnffiilleess FFOOOO--rreeqq..ppeemm + Uing configuration from /etc/ssl/openssl.cnf + Enter PEM pass phrase:wwhhaatteevveerr + Check that the request matches the signature + Signature ok + The Subjects Distinguished Name is as follows + countryName :PRINTABLE:'US' + stateOrProvinceName :PRINTABLE:'New York' + localityName :PRINTABLE:'Westchester' + organizationName :PRINTABLE:'Porcupine' + commonName :PRINTABLE:'FOO' + emailAddress :IA5STRING:'wietse@porcupine.org' + Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 + days) + Sign the certificate? [y/n]:yy + + 1 out of 1 certificate requests certified, commit? [y/n]yy + Write out database with 1 new entries + Data Base Updated + + * Install the host private key, the host public key certificate, and the + Certification Authority certificate files. This requires super-user + privileges. + + # ccpp ddeemmooCCAA//ccaacceerrtt..ppeemm FFOOOO--kkeeyy..ppeemm FFOOOO--cceerrtt..ppeemm //eettcc//ppoossttffiixx + # cchhmmoodd 664444 //eettcc//ppoossttffiixx//FFOOOO--cceerrtt..ppeemm //eettcc//ppoossttffiixx//ccaacceerrtt..ppeemm + # cchhmmoodd 440000 //eettcc//ppoossttffiixx//FFOOOO--kkeeyy..ppeemm + + * Configure Postfix, by adding the following to /etc/postfix/main.cf. + + smtp_tls_CAfile = /etc/postfix/cacert.pem + smtp_tls_cert_file = /etc/postfix/FOO-cert.pem + smtp_tls_key_file = /etc/postfix/FOO-key.pem + smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache + smtp_use_tls = yes + smtpd_tls_CAfile = /etc/postfix/cacert.pem + smtpd_tls_cert_file = /etc/postfix/FOO-cert.pem + smtpd_tls_key_file = /etc/postfix/FOO-key.pem + smtpd_tls_received_header = yes + smtpd_tls_session_cache_database = btree:/var/run/ + smtpd_tls_session_cache + smtpd_use_tls = yes + tls_random_source = dev:/dev/urandom + +RReeppoorrttiinngg pprroobblleemmss + +When reporting a problem, please be thorough in the report. Patches, when +possible, are greatly appreciated too. + +Please differentiate when possible between: + + * Problems in the TLS code: + * Problems in vanilla Postfix: + +CCoommppaattiibbiilliittyy wwiitthh PPoossttffiixx <<22..22 TTLLSS ssuuppppoorrtt + +Postfix version 2.2 TLS support is based on the Postfix/TLS patch by Lutz +Jänicke, but differs in a few minor ways. + + * main.cf: Specify "btree" instead of "sdbm" for TLS session cache databases. + + TLS session cache databases are now accessed only by the tlsmgr(8) process, + so there are no more concurrency issues. Although Postfix has an sdbm + client, the sdbm library (1000 lines of code) is not included with Postfix. + + TLS session caches can use any database that can store objects of several + kbytes or more, and that implements the sequence operation. In most cases, + btree databases should be adequate. + + NOTE: You cannot use dbm databases. TLS session objects are too large. + + * master.cf: Specify "unix" instead of "fifo" as the tlsmgr service type. + + The smtp(8) and smtpd(8) processes now use a client-server protocol in + order to access the tlsmgr(8) pseudo-random number generation (PRNG) pool, + and in order to access the TLS session cache databases. Such a protocol + cannot be run across fifos. + + * smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy cannot override the + global "smtp_tls_enforce_peername = yes" setting. + + * smtp_tls_per_site: a combined (NONE + MAY) lookup result for (hostname and + next-hop destination) produces counter-intuitive results for different + main.cf settings. TLS is enabled with "smtp_tls_enforce_peername = no", but + it is disabled when both "smtp_enforce_tls = yes" and + "smtp_tls_enforce_peername = yes". + +The smtp_tls_per_site limitations were removed by the end of the Postfix 2.2 +support cycle. + +CCrreeddiittss + + * TLS support for Postfix was originally developed by Lutz Jänicke at Cottbus + Technical University. + * Wietse Venema adopted the code, did some restructuring, and compiled this + part of the documentation from Lutz's documents. + * Victor Duchovni was instrumental with the re-implementation of the + smtp_tls_per_site code in terms of enforcement levels, which simplified the + implementation greatly. + diff --git a/postfix/README_FILES/TLS_README b/postfix/README_FILES/TLS_README index 2a0b0e299..dc12a8ff7 100644 --- a/postfix/README_FILES/TLS_README +++ b/postfix/README_FILES/TLS_README @@ -16,10 +16,10 @@ Transport Layer Security (TLS, formerly called SSL) provides certificate-based authentication and encrypted sessions. An encrypted session protects the information that is transmitted with SMTP mail or with SASL authentication. -Postfix version 2.2 introduces support for TLS as described in RFC 3207. TLS -Support for older Postfix versions was available as an add-on patch. The -section "Compatibility with Postfix < 2.2 TLS support" below discusses the -differences between these implementations. +This document describes a TLS user interface that was introduced with Postfix +version 2.3. Support for an older user interface is documented in +TLS_LEGACY_README, which also describes the differences between Postfix and the +third-party patch on which Postfix version 2.2 TLS support was based. Topics covered in this document: @@ -29,7 +29,6 @@ Topics covered in this document: * SMTP Client specific settings * TLS manager specific settings * Reporting problems - * Compatibility with Postfix < 2.2 TLS support * Credits And last but not least, for the impatient: @@ -1735,42 +1734,6 @@ www.postfix.org/lists.html for subscription information. When reporting a problem, please be thorough in the report. Patches, when possible, are greatly appreciated too. -CCoommppaattiibbiilliittyy wwiitthh PPoossttffiixx << 22..22 TTLLSS ssuuppppoorrtt - -Postfix version 2.2 TLS support is based on the Postfix/TLS patch by Lutz -Jänicke, but differs in a few minor ways. - - * main.cf: Specify "btree" instead of "sdbm" for TLS session cache databases. - - TLS session cache databases are now accessed only by the tlsmgr(8) process, - so there are no more concurrency issues. Although Postfix has an sdbm - client, the sdbm library (1000 lines of code) is not included with Postfix. - - TLS session caches can use any database that can store objects of several - kbytes or more, and that implements the sequence operation. In most cases, - btree databases should be adequate. - - NOTE: You cannot use DBM databases. TLS session objects are too large. - - * master.cf: Specify "unix" instead of "fifo" as the tlsmgr service type. - - The smtp(8) and smtpd(8) processes now use a client-server protocol in - order to access the tlsmgr(8) pseudo-random number generation (PRNG) pool, - and in order to access the TLS session cache databases. Such a protocol - cannot be run across fifos. - - * smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy cannot override the - global "smtp_tls_enforce_peername = yes" setting. - - * smtp_tls_per_site: a combined (NONE + MAY) lookup result for (hostname and - next-hop destination) produces counter-intuitive results for different - main.cf settings. TLS is enabled with "smtp_tls_enforce_peername = no", but - it is disabled when both "smtp_enforce_tls = yes" and - "smtp_tls_enforce_peername = yes". - -The smtp_tls_per_site limitations were removed by the end of the Postfix 2.2 -support cycle. - CCrreeddiittss * TLS support for Postfix was originally developed by Lutz Jänicke at Cottbus diff --git a/postfix/html/TLS_LEGACY_README.html b/postfix/html/TLS_LEGACY_README.html new file mode 100644 index 000000000..634c3828b --- /dev/null +++ b/postfix/html/TLS_LEGACY_README.html @@ -0,0 +1,1596 @@ + + + + + + +Postfix legacy TLS Support + + + + + + + +

Postfix legacy TLS Support +

+ +
+ +

NOTE

+ +

This document describes an old TLS user interface that is based +on a third-party TLS patch by Lutz Jänicke. As of Postfix +version 2.3, the old user interface still exists to allow migration +from earlier Postfix releases, but its functionality is frozen.

+ +

What Postfix TLS support does for you

+ +

Transport Layer Security (TLS, formerly called SSL) provides +certificate-based authentication and encrypted sessions. An +encrypted session protects the information that is transmitted with +SMTP mail or with SASL authentication. + +

Postfix version 2.2 introduces support for TLS as described in +RFC 3207. TLS Support for older Postfix versions was available as +an add-on patch. The section "Compatibility with +Postfix < 2.2 TLS support" below discusses the differences +between these implementations.

+ +

Topics covered in this document:

+ + + +

And last but not least, for the impatient:

+ + + +

How Postfix TLS support works

+ +

The diagram below shows the main elements of the Postfix TLS +architecture and their relationships. Colored boxes with numbered +names represent Postfix daemon programs. Other colored boxes +represent storage elements.

+ +
    + +

  • The smtpd(8) server implements the SMTP over TLS server +side.

    + +

  • The smtp(8) client implements the SMTP over TLS client +side.

    + +

  • The tlsmgr(8) server maintains the pseudo-random number +generator (PRNG) that seeds the TLS engines in the smtpd(8) server +and smtp(8) client processes, and maintains the TLS session key +cache files.

    + +
+ + + + + + + + + + + + +
Network->
smtpd(8)
  		+ + <---seed---

<-session->
tlsmgr(8)
  		---seed--->

<-session-> + +
smtp(8)
+  		->Network
+ + /
/
+		 |
|		 + + +
\
\
+smtpd
session
key cache 		PRNG
state
file 		smtp
session
key cache +
+ +

Building Postfix with TLS support

+ +

To build Postfix with TLS support, first we need to generate +the make(1) files with the necessary definitions. This is +done by invoking the command "make makefiles" in the Postfix +top-level directory and with arguments as shown next.

+ +

NOTE: Do not use Gnu TLS. It will spontaneously terminate +a Postfix daemon process with exit status code 2, instead of allowing +Postfix to 1) report the error to the maillog file, and to 2) provide +plaintext service where this is appropriate.

+ +
    + +

  • If the OpenSSL include files (such as ssl.h) are +in directory /usr/include/openssl, and the OpenSSL libraries +(such as libssl.so and libcrypto.so) are in +directory /usr/lib:

    + +
    +
    +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"
+
    +
    + +

  • If the OpenSSL include files (such as ssl.h) are +in directory /usr/local/include/openssl, and the OpenSSL +libraries (such as libssl.so and libcrypto.so) +are in directory /usr/local/lib:

    + +
    +
    +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+    AUXLIBS="-L/usr/local/lib -lssl -lcrypto" 
+
    +
    + +

    On Solaris, specify the -R option as shown below: + +

    +
    +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+    AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" 
+
    +
    + +
+ +

If you need to apply other customizations (such as Berkeley DB +databases, MySQL, PosgreSQL, LDAP or SASL), see the respective +Postfix README documents, and combine their "make makefiles" +instructions with the instructions above:

+ +
+
+% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS \
+    (other -D or -I options)" \
+    AUXLIBS="-lssl -lcrypto \
+    (other -l options for libraries in /usr/lib) \
+    (-L/path/name + -l options for other libraries)"
+
+
+ +

To complete the build process, see the Postfix INSTALL +instructions. Postfix has TLS support turned off by default, so +you can start using Postfix as soon as it is installed.

+ +

SMTP Server specific settings

+ +

Topics covered in this section:

+ + + +

Server-side certificate and private +key configuration

+ +

In order to use TLS, the Postfix SMTP server needs a certificate +and a private key. Both must be in "pem" format. The private key +must not be encrypted, meaning: the key must be accessible without +password. Both certificate and private key may be in the same +file.

+ +

Both RSA and DSA certificates are supported. Typically you will +only have RSA certificates issued by a commercial CA. In addition, +the tools supplied with OpenSSL will by default issue RSA certificates. +You can have both at the same time, in which case the cipher used +determines which certificate is presented. For Netscape and OpenSSL +clients without special cipher choices, the RSA certificate is +preferred.

+ +

In order for remote SMTP clients to check the Postfix SMTP +server certificates, the CA certificate (in case of a certificate +chain, all CA certificates) must be available. You should add +these certificates to the server certificate, the server certificate +first, then the issuing CA(s).

+ +

Example: the certificate for "server.dom.ain" was issued by +"intermediate CA" which itself has a certificate issued by "root +CA". Create the server.pem file with:

+ +
+
+% cat server_cert.pem intermediate_CA.pem > server.pem
+
+
+ +

A Postfix SMTP server certificate supplied here must be usable +as SSL server certificate and hence pass the "openssl verify -purpose +sslserver ..." test.

+ +

A client that trusts the root CA has a local copy of the root +CA certificate, so it is not necessary to include the root CA +certificate here. Leaving it out of the "server.pem" file reduces +the overhead of the TLS exchange.

+ +

If you want the Postfix SMTP server to accept remote SMTP client +certificates issued by these CAs, append the root certificate to +$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory. When +you configure trust in a root CA, it is not necessary to explicitly trust +intermediary CAs signed by the root CA, unless $smtpd_tls_ccert_verifydepth +is less than the number of CAs in the certificate chain for the clients +of interest. With a verify depth of 1 you can only verify certificates +directly signed by a trusted CA, and all trusted intermediary CAs need to +be configured explicitly. With a verify depth of 2 you can verify clients +signed by a root CA or a direct intermediary CA (so long as the client +is correctly configured to supply its intermediate CA certificate).

+ +

RSA key and certificate examples:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_cert_file = /etc/postfix/server.pem
+    smtpd_tls_key_file = $smtpd_tls_cert_file
+
+
+ +

Their DSA counterparts:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem
+    smtpd_tls_dkey_file = $smtpd_tls_dcert_file
+
+
+ +

To verify a remote SMTP client certificate, the Postfix SMTP +server needs to trust the certificates of the issuing certification +authorities. These certificates in "pem" format can be stored in a +single $smtpd_tls_CAfile or in multiple files, one CA per file in +the $smtpd_tls_CApath directory. If you use a directory, don't forget +to create the necessary "hash" links with:

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

The $smtpd_tls_CAfile contains the CA certificates of one or +more trusted CAs. The file is opened (with root privileges) before +Postfix enters the optional chroot jail and so need not be accessible +from inside the chroot jail.

+ +

Additional trusted CAs can be specified via the $smtpd_tls_CApath +directory, in which case the certificates are read (with $mail_owner +privileges) from the files in the directory when the information +is needed. Thus, the $smtpd_tls_CApath directory needs to be +accessible inside the optional chroot jail.

+ +

When you configure Postfix to request client certificates (by +setting $smtpd_tls_ask_ccert = yes), any certificates in +$smtpd_tls_CAfile are sent to the client, in order to allow it to +choose an identity signed by a CA you trust. If no $smtpd_tls_CAfile +is specified, no preferred CA list is sent, and the client is free +to choose an identity signed by any CA. Many clients use a fixed +identity regardless of the preferred CA list and you may be able +to reduce TLS negotiation overhead by installing client CA certificates +mostly or only in $smtpd_tls_CApath. In the latter case you need +not specify a $smtpd_tls_CAfile.

+ +

Note, that unless client certificates are used to allow greater +access to TLS authenticated clients, it is best to not ask for +client certificates at all, as in addition to increased overhead +some clients (notably in some cases qmail) are unable to complete +the TLS handshake when client certificates are requested.

+ +

Example:

+
+
+/etc/postfix/main.cf:
+    smtpd_tls_CAfile = /etc/postfix/CAcert.pem
+    smtpd_tls_CApath = /etc/postfix/certs
+
+
+ +

Server-side TLS activity logging

+ +

To get additional information about Postfix SMTP server TLS +activity you can increase the loglevel from 0..4. Each logging +level also includes the information that is logged at a lower +logging level.

+ +
+ + + + + + + + + + + + + + +
0 Disable logging of TLS activity.
1 Log TLS handshake and certificate information. +
2 Log levels during TLS negotiation.
3 Log hexadecimal and ASCII dump of TLS +negotiation process
4 Log hexadecimal and ASCII dump of complete +transmission after STARTTLS
+ +
+ +

Use loglevel 3 only in case of problems. Use of loglevel 4 is +strongly discouraged.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_loglevel = 0
+
+
+ +

To include information about the protocol and cipher used as +well as the client and issuer CommonName into the "Received:" +message header, set the smtpd_tls_received_header variable to true. +The default is no, as the information is not necessarily authentic. +Only information recorded at the final destination is reliable, +since the headers may be changed by intermediate servers.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_received_header = yes
+
+
+ +

Enabling TLS in the Postfix SMTP server

+ +

By default, TLS is disabled in the Postfix SMTP server, so no +difference to plain Postfix is visible. Explicitly switch it on +using "smtpd_use_tls = yes".

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_use_tls = yes
+
+
+ +

With this, Postfix SMTP server announces STARTTLS support to +SMTP clients, but does not require that clients use TLS encryption. +

+ +

Note: when an unprivileged user invokes "sendmail -bs", STARTTLS +is never offered due to insufficient privileges to access the server +private key. This is intended behavior.

+ +

You can ENFORCE the use of TLS, so that the Postfix SMTP server +announces STARTTLS and accepts no mail without TLS encryption, by +setting "smtpd_enforce_tls = yes". According to RFC 2487 this MUST +NOT be applied in case of a publicly-referenced Postfix SMTP server. +This option is off by default and should only seldom be used.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_enforce_tls = yes
+
+
+ +

TLS is sometimes used in the non-standard "wrapper" mode where +a server always uses TLS, instead of announcing STARTTLS support +and waiting for clients to request TLS service. Some clients, namely +Outlook [Express] prefer the "wrapper" mode. This is true for OE +(Win32 < 5.0 and Win32 >=5.0 when run on a port<>25 +and OE (5.01 Mac on all ports).

+ +

It is strictly discouraged to use this mode from main.cf. If +you want to support this service, enable a special port in master.cf +and specify "-o smtpd_tls_wrappermode = yes" as an smtpd(8) command +line option. Port 465 (smtps) was once chosen for this feature. +

+ +

Example:

+ +
+
+/etc/postfix/master.cf:
+    smtps    inet  n       -       n       -       -       smtpd
+      -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes
+
+
+ +

Client certificate verification

+ +

To receive a remote SMTP client certificate, the Postfix SMTP +server must explicitly ask for one (any contents of $smtpd_tls_CAfile +are also sent to the client as a hint for choosing a certificate +from a suitable CA). Unfortunately, Netscape clients will either +complain if no matching client certificate is available or will +offer the user client a list of certificates to choose from. +Additionally some MTAs (notably some versions of qmail) are unable +to complete TLS negotiation when client certificates are requested, +and abort the SMTP session. So this option is "off" by default. +You will however need the certificate if you want to use certificate +based relaying with, for example, the permit_tls_clientcerts +feature.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_ask_ccert = no
+
+
+ +

You may also decide to REQUIRE a remote SMTP client certificate +before allowing TLS connections. This feature is included for +completeness, and implies "smtpd_tls_ask_ccert = yes".

+ +

Please be aware, that this will inhibit TLS connections without +a proper client certificate and that it makes sense only when +non-TLS submission is disabled (smtpd_enforce_tls = yes). Otherwise, +clients could bypass the restriction by simply not using STARTTLS +at all.

+ +

When TLS is not enforced, the connection will be handled as +if only "smtpd_tls_ask_ccert = yes" is specified, and a warning is +logged.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_req_ccert = no
+
+
+ +

A client certificate verification depth of 1 is sufficient if +the certificate is directly issued by a CA listed in the CA file. +The default value (5) should also suffice for longer chains (root +CA issues special CA which then issues the actual certificate...) +

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_ccert_verifydepth = 5
+
+
+ +

Supporting AUTH over TLS only

+ +

Sending AUTH data over an unencrypted channel poses a security +risk. When TLS layer encryption is required (smtpd_enforce_tls = +yes), the Postfix SMTP server will announce and accept AUTH only +after the TLS layer has been activated with STARTTLS. When TLS +layer encryption is optional (smtpd_enforce_tls = no), it may +however still be useful to only offer AUTH when TLS is active. To +maintain compatibility with non-TLS clients, the default is to +accept AUTH without encryption. In order to change this behavior, +set "smtpd_tls_auth_only = yes".

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_auth_only = no
+
+
+ +

Server-side TLS session cache

+ +

The Postfix SMTP server and the remote SMTP client negotiate +a session, which takes some computer time and network bandwidth. +By default, this session information is cached only in the smtpd(8) +process actually using this session and is lost when the process +terminates. To share the session information between multiple +smtpd(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several +kbytes and that supports the sequence operator. DBM databases are +not suitable because they can only store small objects. The cache +is maintained by the tlsmgr(8) process, so there is no problem with +concurrent access. Session caching is highly recommended, because +the cost of repeatedly negotiating TLS session keys is high.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_session_cache_database = btree:/etc/postfix/smtpd_scache
+
+
+ +

Cached Postfix SMTP server session information expires after +a certain amount of time. Postfix/TLS does not use the OpenSSL +default of 300s, but a longer time of 3600sec (=1 hour). RFC 2246 +recommends a maximum of 24 hours.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_session_cache_timeout = 3600s
+
+
+ +

Server access control

+ +

Postfix TLS support introduces three additional features for +Postfix SMTP server access control:

+ +
+ +
+ +
permit_tls_clientcerts

Allow the remote SMTP +client SMTP request if the client certificate passes verification, +and if its fingerprint is listed in the list of client certificates +(see relay_clientcerts discussion below).

+ +
permit_tls_all_clientcerts

Allow the remote +client SMTP request if the client certificate passes verification. +

+ +
check_ccert_access type:table
+

If the client certificate passes verification, use its fingerprint +as a key for the specified access(5) table.

+ +
+ +
+ +

The permit_tls_all_clientcerts feature must be used with caution, +because it can result in too many access permissions. Use this +feature only if a special CA issues the client certificates, and +only if this CA is listed as trusted CA. If other CAs are trusted, +any owner of a valid client certificate would be authorized. +The permit_tls_all_clientcerts feature can be practical for a +specially created email relay server.

+ +

It is however recommended to stay with the permit_tls_clientcerts +feature and list all certificates via $relay_clientcerts, as +permit_tls_all_clientcerts does not permit any control when a +certificate must no longer be used (e.g. an employee leaving).

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_recipient_restrictions = 
+        ... 
+        permit_tls_clientcerts 
+        reject_unauth_destination
+        ...
+
+
+ +

The Postfix list manipulation routines give special treatment +to whitespace and some other characters, making the use of certificate +names impractical. Instead we use the certificate fingerprints as +they are difficult to fake but easy to use for lookup. Postfix +lookup tables are in the form of (key, value) pairs. Since we only +need the key, the value can be chosen freely, e.g. the name of +the user or host.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    relay_clientcerts = hash:/etc/postfix/relay_clientcerts
+
+/etc/postfix/relay_clientcerts:
+    D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home
+
+
+ +

Server-side cipher controls

+ +

To influence the Postfix SMTP server cipher selection scheme, +you can give cipherlist string. A detailed description would go +to far here; please refer to the OpenSSL documentation. If you +don't know what to do with it, simply don't touch it and leave the +(openssl-)compiled in default!

+ +

DO NOT USE " to enclose the string, specify just the string!!!

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_cipherlist = DEFAULT
+
+
+ +

If you want to take advantage of ciphers with EDH, DH parameters +are needed. Instead of using the built-in DH parameters for both +1024bit and 512bit, it is better to generate "own" parameters, +since otherwise it would "pay" for a possible attacker to start a +brute force attack against parameters that are used by everybody. +For this reason, the parameters chosen are already different from +those distributed with other TLS packages.

+ +

To generate your own set of DH parameters, use:

+ +
+
+% openssl gendh -out /etc/postfix/dh_1024.pem -2 -rand /var/run/egd-pool 1024
+% openssl gendh -out /etc/postfix/dh_512.pem -2 -rand /var/run/egd-pool 512
+
+
+ +

Examples:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem
+    smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem
+
+
+ +

Miscellaneous server controls

+ +

The smtpd_starttls_timeout parameter limits the time of Postfix +SMTP server write and read operations during TLS startup and shutdown +handshake procedures.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtpd_starttls_timeout = 300s
+
+
+ +

SMTP Client specific settings

+ +

Topics covered in this section:

+ + + +

Client-side certificate and private +key configuration

+ +

During TLS startup negotiation the Postfix SMTP client may present +a certificate to the remote SMTP server. The Netscape client is +rather clever here and lets the user select between only those +certificates that match CA certificates offered by the remote SMTP +server. As the Postfix SMTP client uses the "SSL_connect()" function +from the OpenSSL package, this is not possible and we have to choose +just one certificate. So for now the default is to use _no_ +certificate and key unless one is explicitly specified here.

+ +

Both RSA and DSA certificates are supported. You can have both +at the same time, in which case the cipher used determines which +certificate is presented.

+ +

It is possible for the Postfix SMTP client to use the same +key/certificate pair as the Postfix SMTP server. If a certificate +is to be presented, it must be in "pem" format. The private key +must not be encrypted, meaning: it must be accessible without +password. Both parts (certificate and private key) may be in the +same file.

+ +

In order for remote SMTP servers to verify the Postfix SMTP +client certificates, the CA certificate (in case of a certificate +chain, all CA certificates) must be available. You should add +these certificates to the client certificate, the client certificate +first, then the issuing CA(s).

+ +

Example: the certificate for "client.example.com" was issued by +"intermediate CA" which itself has a certificate of "root CA". +Create the client.pem file with:

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

A Postfix SMTP client certificate supplied here must be usable +as SSL client certificate and hence pass the "openssl verify -purpose +sslclient ..." test.

+ +

A server that trusts the root CA has a local copy of the root +CA certificate, so it is not necessary to include the root CA +certificate here. Leaving it out of the "client.pem" file reduces +the overhead of the TLS exchange.

+ +

If you want the Postfix SMTP client to accept remote SMTP server +certificates issued by these CAs, append the root certificate to +$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. When +you configure trust in a root CA, it is not necessary to explicitly trust +intermediary CAs signed by the root CA, unless $smtp_tls_scert_verifydepth +is less than the number of CAs in the certificate chain for the servers +of interest. With a verify depth of 1 you can only verify certificates +directly signed by a trusted CA, and all trusted intermediary CAs need to +be configured explicitly. With a verify depth of 2 you can verify servers +signed by a root CA or a direct intermediary CA (so long as the server +is correctly configured to supply its intermediate CA certificate).

+ +

RSA key and certificate examples:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_cert_file = /etc/postfix/client.pem
+    smtp_tls_key_file = $smtp_tls_cert_file
+
+
+ +

Their DSA counterparts:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
+    smtp_tls_dkey_file = $smtpd_tls_cert_file
+
+
+ +

To verify a remote SMTP server certificate, the Postfix SMTP +client needs to trust the certificates of the issuing certification +authorities. These certificates in "pem" format can be stored in a +single $smtp_tls_CAfile or in multiple files, one CA per file in +the $smtp_tls_CApath directory. If you use a directory, don't forget +to create the necessary "hash" links with:

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

The $smtp_tls_CAfile contains the CA certificates of one or more +trusted CAs. The file is opened (with root privileges) before Postfix +enters the optional chroot jail and so need not be accessible from inside the +chroot jail.

+ +

Additional trusted CAs can be specified via the $smtp_tls_CApath +directory, in which case the certificates are read (with $mail_owner +privileges) from the files in the directory when the information +is needed. Thus, the $smtp_tls_CApath directory needs to be accessible +inside the optional chroot jail.

+ +

The choice between $smtp_tls_CAfile and $smtpd_tls_CApath is +a space/time tradeoff. If there are many trusted CAs, the cost of +preloading them all into memory may not pay off in reduced access time +when the certificate is needed.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_CAfile = /etc/postfix/CAcert.pem
+    smtp_tls_CApath = /etc/postfix/certs
+
+
+ +

Client-side TLS activity logging

+ +

To get additional information about Postfix SMTP client TLS +activity you can increase the loglevel from 0..4. Each logging +level also includes the information that is logged at a lower +logging level.

+ +
+ + + + + + + + + + + + + + +
0 Disable logging of TLS activity.
1 Log TLS handshake and certificate information. +
2 Log levels during TLS negotiation.
3 Log hexadecimal and ASCII dump of TLS +negotiation process
4 Log hexadecimal and ASCII dump of complete +transmission after STARTTLS
+ +
+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_loglevel = 0
+
+
+ +

Client-side TLS session cache

+ +

The remote SMTP server and the Postfix SMTP client negotiate a +session, which takes some computer time and network bandwidth. By +default, this session information is cached only in the smtp(8) +process actually using this session and is lost when the process +terminates. To share the session information between multiple +smtp(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several +kbytes and that supports the sequence operator. DBM databases are +not suitable because they can only store small objects. The cache +is maintained by the tlsmgr(8) process, so there is no problem with +concurrent access. Session caching is highly recommended, because +the cost of repeatedly negotiating TLS session keys is high. Future +Postfix SMTP servers may limit the number of sessions that a client +is allowed to negotiate per unit time.

+ + +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_session_cache_database = btree:/etc/postfix/smtp_scache
+
+
+ +

Cached Postfix SMTP client session information expires after +a certain amount of time. Postfix/TLS does not use the OpenSSL +default of 300s, but a longer time of 3600s (=1 hour). RFC 2246 +recommends a maximum of 24 hours.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_session_cache_timeout = 3600s
+
+
+ +

Enabling TLS in the Postfix SMTP +client

+ +

By default, TLS is disabled in the Postfix SMTP client, so no +difference to plain Postfix is visible. If you enable TLS, the +Postfix SMTP client will send STARTTLS when TLS support is announced +by the remote SMTP server.

+ +

When the server accepts the STARTTLS command, but the subsequent +TLS handshake fails, and no other server is available, the Postfix SMTP +client defers the delivery attempt, and the mail stays in the queue. After +a handshake failure, the communications channel is in an indeterminate +state and cannot be used for non-TLS deliveries.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_use_tls = yes
+
+
+ +

Requiring TLS encryption +

+ +

You can ENFORCE the use of TLS, so that the Postfix SMTP client +will not deliver mail over unencrypted connections. In this mode, +the remote SMTP server hostname must match the information in the +remote server certificate, and the server certificate must be issued +by a CA that is trusted by the Postfix SMTP client. If the remote +server certificate doesn't verify or the remote SMTP server hostname +doesn't match, and no other server is available, the delivery +attempt is deferred and the mail stays in the queue.

+ +

The remote SMTP server hostname is verified against all names +provided as dNSNames +in the SubjectAlternativeName. If no dNSNames are specified, the +CommonName is checked. Verification may be turned off with the +smtp_tls_enforce_peername option which is discussed below.

+ +

Enforcing the use of TLS is useful if you know that you will +only +connect to servers that support RFC 2487 _and_ that present server +certificates that meet the above requirements. An example would +be a client only sends email to one specific mailhub that offers +the necessary STARTTLS support.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_enforce_tls = yes
+
+
+ +

Disabling server certificate +verification

+ +

As of RFC 2487 the requirements for hostname checking for MTA +clients are not set. When TLS is required (smtp_enforce_tls = yes), +the option smtp_tls_enforce_peername can be set to "no" to disable +strict remote SMTP server hostname checking. In this case, the mail +delivery will proceed regardless of the CommonName etc. listed in +the certificate.

+ +

Despite the potential for eliminating "man-in-the-middle" and +other attacks, mandatory certificate/peername verification is not +viable as a default Internet mail delivery policy at this time. A +significant fraction of TLS enabled MTAs uses self-signed certificates, +or certificates that are signed by a private certificate authority. +On a machine that delivers mail to the Internet, if you set +smtp_enforce_tls = yes, you should probably also set +smtp_tls_enforce_peername = no. You can use the per-site TLS +policies (see below) to enable full peer verification for specific +destinations that are known to have verifiable TLS server certificates. +

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_enforce_tls = yes
+    smtp_tls_enforce_peername = no
+
+
+ +

Per-site TLS policies

+ +

A small fraction of servers offer STARTTLS but the negotiation +consistently fails, leading to mail aging out of the queue and +bouncing back to the sender. In such cases, you can use the per-site +policies to disable TLS for the problem sites. Alternatively, you +can enable TLS for just a few specific sites and not enable it for +all sites.

+ + + +

The smtp_tls_per_site table is searched for a policy that matches +the following information:

+ +
+ +
+ +
remote SMTP server hostname
This is simply the DNS +name of the server that the Postfix SMTP client connects to; this +name may be obtained from other DNS lookups, such as MX lookups or +CNAME lookups.
+ +
next-hop destination
This is normally the domain +portion of the recipient address, but it may be overruled by +information from the transport(5) table, from the relayhost parameter +setting, or from the relay_transport setting. When it's not the +recipient domain, the next-hop destination can have the Postfix-specific +form "[name]", [name]:port", "name" or +"name:port".
+ +
+ +
+ +

When both the hostname lookup and the next-hop lookup succeed, +the host policy does not automatically override the next-hop policy. +Instead, precedence is given to either the more specific or the +more secure per-site policy as described below.

+ +

The smtp_tls_per_site table uses a simple "name whitespace +value" format. Specify host names or next-hop destinations on +the left-hand side; no wildcards are allowed. On the right hand +side specify one of the following keywords:

+ +
+ +
+ +
NONE
Don't use TLS at all. This overrides a less +specific MAY lookup result from the alternate host or next-hop +lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls, +and smtp_tls_enforce_peername settings.
+ +
MAY
Try to use TLS if the server announces support, +otherwise use the unencrypted connection. This has less precedence +than a more specific result (including NONE) from the alternate +host or next-hop lookup key, and has less precedence than the more +specific global "smtp_enforce_tls = yes" or "smtp_tls_enforce_peername += yes".
+ +
MUST_NOPEERMATCH
Require TLS encryption, but do not +require that the remote SMTP server hostname matches the information +in the remote SMTP server certificate, or that the server certificate +was issued by a trusted CA. This overrides a less secure NONE +or a less specific MAY lookup result from the alternate host +or next-hop lookup key, and overrides the global smtp_use_tls, +smtp_enforce_tls and smtp_tls_enforce_peername settings.
+ +
MUST
Require TLS encryption, require that the remote +SMTP server hostname matches the information in the remote SMTP +server certificate, and require that the remote SMTP server certificate +was issued by a trusted CA. This overrides a less secure NONE +and MUST_NOPEERMATCH or a less specific MAY lookup +result from the alternate host or next-hop lookup key, and overrides +the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername +settings.
+ +
+ +
+ +

The precedences between global (main.cf) and per-site TLS +policies can be summarized as follows:

+ +
    + +

  • When neither the remote SMTP server hostname nor the +next-hop destination are found in the smtp_tls_per_site table, the +policy is based on smtp_use_tls, smtp_enforce_tls and +smtp_tls_enforce_peername. Note: "smtp_enforce_tls = yes" and +"smtp_tls_enforce_peername = yes" imply "smtp_use_tls = yes".

    + +

  • When both hostname and next-hop destination lookups produce +a result, the more specific per-site policy (NONE, MUST, etc) +overrides the less specific one (MAY), and the more secure per-site +policy (MUST, etc) overrides the less secure one (NONE).

    + +

  • After the per-site policy lookups are combined, the result +generally overrides the global policy. The exception is the less +specific MAY per-site policy, which is overruled by the more +specific global "smtp_enforce_tls = yes" with server certificate +verification as specified with the smtp_tls_enforce_peername +parameter.

    + +
+ +

Closing a DNS loophole with + per-site TLS policies

+ +

As long as no secure DNS lookup mechanism is available, false +hostnames in MX or CNAME responses can change the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification. Even with a perfect match between the server hostname +and the server certificate, there is no guarantee that Postfix is +connected to the right server. To avoid this loophole take the +following steps:

+ +
    + +

  • Eliminate MX lookups. Specify local transport(5) table +entries for sensitive domains with explicit smtp:[mailhost] +or smtp:[mailhost]:port destinations (you can assure +security of this table unlike DNS); in the smtp_tls_per_site table +specify the value MUST for the key [mailhost] or +smtp:[mailhost]:port. This prevents false hostname +information in DNS MX records from changing the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification.

    + +

  • Disallow CNAME hostname overrides. In main.cf specify +"smtp_cname_overrides_servername = no". This prevents false hostname +information in DNS CNAME records from changing the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification. This feature requires Postfix 2.2.9 or later.

    + +
+ +

Example:

+ +
+/etc/postfix/main.cf:
+    smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+    relayhost = [msa.example.net]:587
+
+/etc/postfix/tls_per_site:
+    # relayhost exact nexthop match
+    [msa.example.net]:587       MUST
+
+    # TLS should not be used with the example.org MX hosts.
+    example.org                 NONE
+
+    # TLS should not be used with the host smtp.example.com.
+    smtp.example.com             NONE
+
+
+ +

Discovering servers that support +TLS

+ +

As we decide on a "per site" basis whether or not to use TLS, +it would be good to have a list of sites that offered "STARTTLS". +We can collect it ourselves with this option.

+ +

If the smtp_tls_note_starttls_offer feature is enabled and a +server offers STARTTLS while TLS is not already enabled for that +server, the Postfix SMTP client logs a line as follows:

+ +
+
+postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com]
+
+
+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_note_starttls_offer = yes
+
+
+ +

Server certificate verification depth

+ +

When verifying a remote SMTP server certificate, a verification +depth of 1 is sufficient if the certificate is directly issued by +a CA specified with smtp_tls_CAfile or smtp_tls_CApath. The default +value of 5 should also suffice for longer chains (root CA issues +special CA which then issues the actual certificate...)

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_scert_verifydepth = 5
+
+
+ +

Client-side cipher controls

+ +

To influence the Postfix SMTP client cipher selection scheme, +you can give cipherlist string. A detailed description would go +to far here; please refer to the OpenSSL documentation. If you +don't know what to do with it, simply don't touch it and leave the +(openssl-)compiled in default!

+ +

DO NOT USE " to enclose the string, specify just the string!!!

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_tls_cipherlist = DEFAULT
+
+
+ +

Miscellaneous client controls

+ +

The smtp_starttls_timeout parameter limits the time of Postfix +SMTP client write and read operations during TLS startup and shutdown +handshake procedures. In case of problems the Postfix SMTP client +tries the next network address on the mail exchanger list, and +defers delivery if no alternative server is available.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    smtp_starttls_timeout = 300s
+
+
+ +

TLS manager specific settings

+ +

The security of cryptographic software such as TLS depends +critically on the ability to generate unpredictable numbers for +keys and other information. To this end, the tlsmgr(8) process +maintains a Pseudo Random Number Generator (PRNG) pool. This is +queried by the smtp(8) and smtpd(8) processes when they initialize. +By default, these daemons request 32 bytes, the equivalent to 256 +bits. This is more than sufficient to generate a 128bit (or 168bit) +session key.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    tls_daemon_random_bytes = 32
+
+
+ +

In order to feed its in-memory PRNG pool, the tlsmgr(8) reads +entropy from an external source, both at startup and during run-time. +Specify a good entropy source, like EGD or /dev/urandom; be sure +to only use non-blocking sources (on OpenBSD, use /dev/arandom +when tlsmgr(8) complains about /dev/urandom timeout errors). +If the entropy source is not a +regular file, you must prepend the source type to the source name: +"dev:" for a device special file, or "egd:" for a source with EGD +compatible socket interface.

+ +

Examples (specify only one in main.cf):

+ +
+
+/etc/postfix/main.cf:
+    tls_random_source = dev:/dev/urandom
+    tls_random_source = egd:/var/run/egd-pool
+
+
+ +

By default, tlsmgr(8) reads 32 bytes from the external entropy +source at each seeding event. This amount (256bits) is more than +sufficient for generating a 128bit symmetric key. With EGD and +device entropy sources, the tlsmgr(8) limits the amount of data +read at each step to 255 bytes. If you specify a regular file as +entropy source, a larger amount of data can be read.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    tls_random_bytes = 32
+
+
+ +

In order to update its in-memory PRNG pool, the tlsmgr(8) +queries the external entropy source again after a pseudo-random +amount of time. The time is calculated using the PRNG, and is +between 0 and the maximal time specified with tls_random_reseed_period. +The default maximal time interval is 1 hour.

+ +

Example:

+ +
+
+/etc/postfix/main.cf:
+    tls_random_reseed_period = 3600s
+
+
+ +

The tlsmgr(8) process saves the PRNG state to a persistent +exchange file at regular times and when the process terminates, so +that it can recover the PRNG state the next time it starts up. +This file is created when it does not exist. Its default location +is under the Postfix configuration directory, which is not the +proper place for information that is modified by Postfix. Instead, +the file location should probably be on the /var partition (but +not inside the chroot jail).

+ +

Examples:

+ +
+
+/etc/postfix/main.cf:
+    tls_random_exchange_name = /etc/postfix/prng_exch
+    tls_random_prng_update_period = 3600s
+
+
+ +

Getting started, quick and dirty

+ +

The following steps will get you started quickly. Because you +sign your own Postfix public key certificate, you get TLS encryption +but no TLS authentication. This is sufficient for testing, and +for exchanging email with sites that you have no trust relationship +with. For real authentication, your Postfix public key certificate +needs to be signed by a recognized Certificate Authority, and +Postfix needs to be configured with a list of public key certificates +of Certificate Authorities, so that Postfix can verify the public key +certificates of remote hosts.

+ +

In the examples below, user input is shown in bold +font, and a "#" prompt indicates a super-user shell.

+ +
    + +

  • Become your own Certificate Authority, so that you can +sign your own public keys. This example uses the CA.pl script that +ships with OpenSSL. By default, OpenSSL installs this as +/usr/local/ssl/misc/CA.pl, but your mileage may vary. +The script creates a private key in ./demoCA/private/cakey.pem +and a public key in ./demoCA/cacert.pem.

    + +
    +
    +% /usr/local/ssl/misc/CA.pl -newca
+CA certificate filename (or enter to create)
+
+Making CA certificate ...
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 1024 bit RSA private key
+....................++++++
+.....++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase:whatever
+
    +
    + +

  • Create an unpassworded private key for host FOO and create +an unsigned public key certificate.

    + +
    +
    +% openssl req -new -nodes -keyout FOO-key.pem -out FOO-req.pem -days 365
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 1024 bit RSA private key
+........................................++++++
+....++++++
+writing new private key to 'FOO-key.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:US
+State or Province Name (full name) [Some-State]:New York
+Locality Name (eg, city) []:Westchester
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:Porcupine
+Organizational Unit Name (eg, section) []:
+Common Name (eg, YOUR name) []:FOO
+Email Address []:wietse@porcupine.org
+
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:whatever
+An optional company name []:
+
    +
    + +

  • Sign the public key certificate for host FOO with the +Certification Authority private key that we created a few +steps ago.

    + +
    +
    +% openssl ca -out FOO-cert.pem -infiles FOO-req.pem
+Uing configuration from /etc/ssl/openssl.cnf
+Enter PEM pass phrase:whatever
+Check that the request matches the signature
+Signature ok
+The Subjects Distinguished Name is as follows
+countryName           :PRINTABLE:'US'
+stateOrProvinceName   :PRINTABLE:'New York'
+localityName          :PRINTABLE:'Westchester'
+organizationName      :PRINTABLE:'Porcupine'
+commonName            :PRINTABLE:'FOO'
+emailAddress          :IA5STRING:'wietse@porcupine.org'
+Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days)
+Sign the certificate? [y/n]:y
+
+
+1 out of 1 certificate requests certified, commit? [y/n]y
+Write out database with 1 new entries
+Data Base Updated
+
    +
    + +

  • Install the host private key, the host public key certificate, +and the Certification Authority certificate files. This requires +super-user privileges.

    + +
    +
    +# cp demoCA/cacert.pem FOO-key.pem FOO-cert.pem /etc/postfix
+# chmod 644 /etc/postfix/FOO-cert.pem /etc/postfix/cacert.pem
+# chmod 400 /etc/postfix/FOO-key.pem
+
    +
    + +

  • Configure Postfix, by adding the following to +/etc/postfix/main.cf .

    + +
    +
    +smtp_tls_CAfile = /etc/postfix/cacert.pem
+smtp_tls_cert_file = /etc/postfix/FOO-cert.pem
+smtp_tls_key_file = /etc/postfix/FOO-key.pem
+smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache
+smtp_use_tls = yes
+smtpd_tls_CAfile = /etc/postfix/cacert.pem
+smtpd_tls_cert_file = /etc/postfix/FOO-cert.pem
+smtpd_tls_key_file = /etc/postfix/FOO-key.pem
+smtpd_tls_received_header = yes
+smtpd_tls_session_cache_database = btree:/var/run/smtpd_tls_session_cache
+smtpd_use_tls = yes
+tls_random_source = dev:/dev/urandom
+
    +
    + +
+ + +

Reporting problems

+ +

When reporting a problem, please be thorough in the report. +Patches, when possible, are greatly appreciated too.

+ +

Please differentiate when possible between:

+ +
    + +
  • Problems in the TLS code: <postfix_tls@aet.tu-cottbus.de> + +
  • Problems in vanilla Postfix: <postfix-users@postfix.org> + +
+ +

Compatibility with Postfix <2.2 TLS support

+ +

Postfix version 2.2 TLS support is based on the Postfix/TLS +patch by Lutz Jänicke, but differs in a few minor ways.

+ +
    + +

  • main.cf: Specify "btree" instead of "sdbm" for TLS +session cache databases.

    + +

    TLS session cache databases are now accessed only by the +tlsmgr(8) process, so there are no more concurrency issues. Although +Postfix has an sdbm client, the sdbm library (1000 +lines of code) is not included with Postfix.

    + +

    TLS session caches can use any database that can store objects +of several kbytes or more, and that implements the sequence operation. +In most cases, btree databases should be adequate.

    + +

    NOTE: You cannot use dbm databases. TLS session objects +are too large.

    + +

  • master.cf: Specify "unix" instead of "fifo" as +the tlsmgr service type.

    + +

    The smtp(8) and smtpd(8) processes now use a client-server +protocol in order to access the tlsmgr(8) pseudo-random number +generation (PRNG) pool, and in order to access the TLS session +cache databases. Such a protocol cannot be run across fifos.

    + +

  • smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy +cannot override the global "smtp_tls_enforce_peername = yes" setting. +

    + +

  • smtp_tls_per_site: a combined (NONE + MAY) lookup result +for (hostname and next-hop destination) produces counter-intuitive +results for different main.cf settings. TLS is enabled with +"smtp_tls_enforce_peername = no", but it is disabled when both +"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes". +

    + +
+ +

The smtp_tls_per_site limitations were removed by the end of +the Postfix 2.2 support cycle.

+ +

Credits

+ +
    + +
  • TLS support for Postfix was originally developed by Lutz +Jänicke at Cottbus Technical University. + +
  • Wietse Venema adopted the code, did some restructuring, and +compiled this part of the documentation from Lutz's documents. + +
  • Victor Duchovni was instrumental with the re-implementation +of the smtp_tls_per_site code in terms of enforcement levels, which +simplified the implementation greatly. + +
+ + + + diff --git a/postfix/html/TLS_README.html b/postfix/html/TLS_README.html index 43d6541eb..4ad918612 100644 --- a/postfix/html/TLS_README.html +++ b/postfix/html/TLS_README.html @@ -34,11 +34,11 @@ certificate-based authentication and encrypted sessions. An encrypted session protects the information that is transmitted with SMTP mail or with SASL authentication. -

Postfix version 2.2 introduces support for TLS as described in -RFC 3207. TLS Support for older Postfix versions was available as -an add-on patch. The section "Compatibility with -Postfix < 2.2 TLS support" below discusses the differences -between these implementations.

+

This document describes a TLS user interface that was introduced +with Postfix version 2.3. Support for an older user interface is +documented in TLS_LEGACY_README, which also describes the differences +between Postfix and the third-party patch on which Postfix version +2.2 TLS support was based.

Topics covered in this document:

@@ -56,8 +56,6 @@ between these implementations.

  • Reporting problems -
  • Compatibility with Postfix < 2.2 TLS support -
  • Credits @@ -2330,52 +2328,6 @@ See http://www.postfix.org/lists.htm When reporting a problem, please be thorough in the report. Patches, when possible, are greatly appreciated too.

    -

    Compatibility with Postfix < 2.2 TLS support

    - -

    Postfix version 2.2 TLS support is based on the Postfix/TLS -patch by Lutz Jänicke, but differs in a few minor ways.

    - -
      - -

    • main.cf: Specify "btree" instead of "sdbm" for TLS -session cache databases.

      - -

      TLS session cache databases are now accessed only by the -tlsmgr(8) process, so there are no more concurrency issues. Although -Postfix has an sdbm client, the sdbm library (1000 -lines of code) is not included with Postfix.

      - -

      TLS session caches can use any database that can store objects -of several kbytes or more, and that implements the sequence operation. -In most cases, btree databases should be adequate.

      - -

      NOTE: You cannot use DBM databases. TLS session objects -are too large.

      - -

    • master.cf: Specify "unix" instead of "fifo" as -the tlsmgr service type.

      - -

      The smtp(8) and smtpd(8) processes now use a client-server -protocol in order to access the tlsmgr(8) pseudo-random number -generation (PRNG) pool, and in order to access the TLS session -cache databases. Such a protocol cannot be run across fifos.

      - -

    • smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy -cannot override the global "smtp_tls_enforce_peername = yes" setting. -

      - -

    • smtp_tls_per_site: a combined (NONE + MAY) lookup result -for (hostname and next-hop destination) produces counter-intuitive -results for different main.cf settings. TLS is enabled with -"smtp_tls_enforce_peername = no", but it is disabled when both -"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes". -

      - -
    - -

    The smtp_tls_per_site limitations were removed by the end of -the Postfix 2.2 support cycle.

    -

    Credits

      diff --git a/postfix/html/index.html b/postfix/html/index.html index 1372fd539..350e42402 100644 --- a/postfix/html/index.html +++ b/postfix/html/index.html @@ -40,6 +40,8 @@ configuration examples
    • TLS Encryption and authentication +
    • Legacy TLS support +
    • IP Version 6 Support
    • Installation from source code diff --git a/postfix/proto/Makefile.in b/postfix/proto/Makefile.in index b76c8dc04..17b3e41e8 100644 --- a/postfix/proto/Makefile.in +++ b/postfix/proto/Makefile.in @@ -35,7 +35,7 @@ HTML = ../html/ADDRESS_CLASS_README.html \ ../html/SMTPD_POLICY_README.html \ ../html/SMTPD_PROXY_README.html \ ../html/STANDARD_CONFIGURATION_README.html \ - ../html/TLS_README.html \ + ../html/TLS_README.html ../html/TLS_LEGACY_README.html \ ../html/TUNING_README.html \ ../html/UUCP_README.html ../html/ULTRIX_README.html \ ../html/VERP_README.html ../html/VIRTUAL_README.html \ @@ -71,7 +71,7 @@ README = ../README_FILES/ADDRESS_CLASS_README \ ../README_FILES/SMTPD_ACCESS_README \ ../README_FILES/SMTPD_POLICY_README ../README_FILES/SMTPD_PROXY_README \ ../README_FILES/STANDARD_CONFIGURATION_README \ - ../README_FILES/TLS_README \ + ../README_FILES/TLS_README ../README_FILES/TLS_LEGACY_README \ ../README_FILES/TUNING_README \ ../README_FILES/UUCP_README ../README_FILES/ULTRIX_README \ ../README_FILES/VERP_README ../README_FILES/VIRTUAL_README \ @@ -264,6 +264,9 @@ clobber: ../html/TLS_README.html: TLS_README.html $(POSTLINK) $? >$@ +../html/TLS_LEGACY_README.html: TLS_LEGACY_README.html + $(POSTLINK) $? >$@ + ../README_FILES/ADDRESS_CLASS_README: ADDRESS_CLASS_README.html $(HT2READ) $? >$@ @@ -405,6 +408,9 @@ clobber: ../README_FILES/TLS_README: TLS_README.html $(HT2READ) $? >$@ +../README_FILES/TLS_LEGACY_README: TLS_LEGACY_README.html + $(HT2READ) $? >$@ + ../README_FILES/AAAREADME: ../html/index.html $(MAKEAAA) $(MAKEAAA) ../html/index.html | $(HT2READ) >$@ diff --git a/postfix/proto/TLS_LEGACY_README.html b/postfix/proto/TLS_LEGACY_README.html new file mode 100644 index 000000000..ba1dff037 --- /dev/null +++ b/postfix/proto/TLS_LEGACY_README.html @@ -0,0 +1,1596 @@ + + + + + + +Postfix legacy TLS Support + + + + + + + +

      Postfix legacy TLS Support +

      + +
      + +

      NOTE

      + +

      This document describes an old TLS user interface that is based +on a third-party TLS patch by Lutz Jänicke. As of Postfix +version 2.3, the old user interface still exists to allow migration +from earlier Postfix releases, but its functionality is frozen.

      + +

      What Postfix TLS support does for you

      + +

      Transport Layer Security (TLS, formerly called SSL) provides +certificate-based authentication and encrypted sessions. An +encrypted session protects the information that is transmitted with +SMTP mail or with SASL authentication. + +

      Postfix version 2.2 introduces support for TLS as described in +RFC 3207. TLS Support for older Postfix versions was available as +an add-on patch. The section "Compatibility with +Postfix < 2.2 TLS support" below discusses the differences +between these implementations.

      + +

      Topics covered in this document:

      + + + +

      And last but not least, for the impatient:

      + + + +

      How Postfix TLS support works

      + +

      The diagram below shows the main elements of the Postfix TLS +architecture and their relationships. Colored boxes with numbered +names represent Postfix daemon programs. Other colored boxes +represent storage elements.

      + +
        + +

      • The smtpd(8) server implements the SMTP over TLS server +side.

        + +

      • The smtp(8) client implements the SMTP over TLS client +side.

        + +

      • The tlsmgr(8) server maintains the pseudo-random number +generator (PRNG) that seeds the TLS engines in the smtpd(8) server +and smtp(8) client processes, and maintains the TLS session key +cache files.

        + +
      + + + + + + + + + + + + +
      Network->
      smtpd(8)
              		+ + <---seed---

      <-session->
      tlsmgr(8)
              		---seed--->

      <-session-> + +
      smtp(8)
      +        		->Network
      + + /
      /
      +      		 |
      |      		 + + +
      \
      \
      +smtpd
      session
      key cache       		PRNG
      state
      file       		smtp
      session
      key cache +
      + +

      Building Postfix with TLS support

      + +

      To build Postfix with TLS support, first we need to generate +the make(1) files with the necessary definitions. This is +done by invoking the command "make makefiles" in the Postfix +top-level directory and with arguments as shown next.

      + +

      NOTE: Do not use Gnu TLS. It will spontaneously terminate +a Postfix daemon process with exit status code 2, instead of allowing +Postfix to 1) report the error to the maillog file, and to 2) provide +plaintext service where this is appropriate.

      + +
        + +

      • If the OpenSSL include files (such as ssl.h) are +in directory /usr/include/openssl, and the OpenSSL libraries +(such as libssl.so and libcrypto.so) are in +directory /usr/lib:

        + +
        +
        +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS" AUXLIBS="-lssl -lcrypto"
+
        +
        + +

      • If the OpenSSL include files (such as ssl.h) are +in directory /usr/local/include/openssl, and the OpenSSL +libraries (such as libssl.so and libcrypto.so) +are in directory /usr/local/lib:

        + +
        +
        +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+    AUXLIBS="-L/usr/local/lib -lssl -lcrypto" 
+
        +
        + +

        On Solaris, specify the -R option as shown below: + +

        +
        +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS -I/usr/local/include" \
+    AUXLIBS="-R/usr/local/lib -L/usr/local/lib -lssl -lcrypto" 
+
        +
        + +
      + +

      If you need to apply other customizations (such as Berkeley DB +databases, MySQL, PosgreSQL, LDAP or SASL), see the respective +Postfix README documents, and combine their "make makefiles" +instructions with the instructions above:

      + +
      +
      +% make tidy # if you have left-over files from a previous build
+% make makefiles CCARGS="-DUSE_TLS \
+    (other -D or -I options)" \
+    AUXLIBS="-lssl -lcrypto \
+    (other -l options for libraries in /usr/lib) \
+    (-L/path/name + -l options for other libraries)"
+
      +
      + +

      To complete the build process, see the Postfix INSTALL +instructions. Postfix has TLS support turned off by default, so +you can start using Postfix as soon as it is installed.

      + +

      SMTP Server specific settings

      + +

      Topics covered in this section:

      + + + +

      Server-side certificate and private +key configuration

      + +

      In order to use TLS, the Postfix SMTP server needs a certificate +and a private key. Both must be in "pem" format. The private key +must not be encrypted, meaning: the key must be accessible without +password. Both certificate and private key may be in the same +file.

      + +

      Both RSA and DSA certificates are supported. Typically you will +only have RSA certificates issued by a commercial CA. In addition, +the tools supplied with OpenSSL will by default issue RSA certificates. +You can have both at the same time, in which case the cipher used +determines which certificate is presented. For Netscape and OpenSSL +clients without special cipher choices, the RSA certificate is +preferred.

      + +

      In order for remote SMTP clients to check the Postfix SMTP +server certificates, the CA certificate (in case of a certificate +chain, all CA certificates) must be available. You should add +these certificates to the server certificate, the server certificate +first, then the issuing CA(s).

      + +

      Example: the certificate for "server.dom.ain" was issued by +"intermediate CA" which itself has a certificate issued by "root +CA". Create the server.pem file with:

      + +
      +
      +% cat server_cert.pem intermediate_CA.pem > server.pem
+
      +
      + +

      A Postfix SMTP server certificate supplied here must be usable +as SSL server certificate and hence pass the "openssl verify -purpose +sslserver ..." test.

      + +

      A client that trusts the root CA has a local copy of the root +CA certificate, so it is not necessary to include the root CA +certificate here. Leaving it out of the "server.pem" file reduces +the overhead of the TLS exchange.

      + +

      If you want the Postfix SMTP server to accept remote SMTP client +certificates issued by these CAs, append the root certificate to +$smtpd_tls_CAfile or install it in the $smtpd_tls_CApath directory. When +you configure trust in a root CA, it is not necessary to explicitly trust +intermediary CAs signed by the root CA, unless $smtpd_tls_ccert_verifydepth +is less than the number of CAs in the certificate chain for the clients +of interest. With a verify depth of 1 you can only verify certificates +directly signed by a trusted CA, and all trusted intermediary CAs need to +be configured explicitly. With a verify depth of 2 you can verify clients +signed by a root CA or a direct intermediary CA (so long as the client +is correctly configured to supply its intermediate CA certificate).

      + +

      RSA key and certificate examples:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_cert_file = /etc/postfix/server.pem
+    smtpd_tls_key_file = $smtpd_tls_cert_file
+
      +
      + +

      Their DSA counterparts:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem
+    smtpd_tls_dkey_file = $smtpd_tls_dcert_file
+
      +
      + +

      To verify a remote SMTP client certificate, the Postfix SMTP +server needs to trust the certificates of the issuing certification +authorities. These certificates in "pem" format can be stored in a +single $smtpd_tls_CAfile or in multiple files, one CA per file in +the $smtpd_tls_CApath directory. If you use a directory, don't forget +to create the necessary "hash" links with:

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

      The $smtpd_tls_CAfile contains the CA certificates of one or +more trusted CAs. The file is opened (with root privileges) before +Postfix enters the optional chroot jail and so need not be accessible +from inside the chroot jail.

      + +

      Additional trusted CAs can be specified via the $smtpd_tls_CApath +directory, in which case the certificates are read (with $mail_owner +privileges) from the files in the directory when the information +is needed. Thus, the $smtpd_tls_CApath directory needs to be +accessible inside the optional chroot jail.

      + +

      When you configure Postfix to request client certificates (by +setting $smtpd_tls_ask_ccert = yes), any certificates in +$smtpd_tls_CAfile are sent to the client, in order to allow it to +choose an identity signed by a CA you trust. If no $smtpd_tls_CAfile +is specified, no preferred CA list is sent, and the client is free +to choose an identity signed by any CA. Many clients use a fixed +identity regardless of the preferred CA list and you may be able +to reduce TLS negotiation overhead by installing client CA certificates +mostly or only in $smtpd_tls_CApath. In the latter case you need +not specify a $smtpd_tls_CAfile.

      + +

      Note, that unless client certificates are used to allow greater +access to TLS authenticated clients, it is best to not ask for +client certificates at all, as in addition to increased overhead +some clients (notably in some cases qmail) are unable to complete +the TLS handshake when client certificates are requested.

      + +

      Example:

      +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_CAfile = /etc/postfix/CAcert.pem
+    smtpd_tls_CApath = /etc/postfix/certs
+
      +
      + +

      Server-side TLS activity logging

      + +

      To get additional information about Postfix SMTP server TLS +activity you can increase the loglevel from 0..4. Each logging +level also includes the information that is logged at a lower +logging level.

      + +
      + + + + + + + + + + + + + + +
      0 Disable logging of TLS activity.
      1 Log TLS handshake and certificate information. +
      2 Log levels during TLS negotiation.
      3 Log hexadecimal and ASCII dump of TLS +negotiation process
      4 Log hexadecimal and ASCII dump of complete +transmission after STARTTLS
      + +
      + +

      Use loglevel 3 only in case of problems. Use of loglevel 4 is +strongly discouraged.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_loglevel = 0
+
      +
      + +

      To include information about the protocol and cipher used as +well as the client and issuer CommonName into the "Received:" +message header, set the smtpd_tls_received_header variable to true. +The default is no, as the information is not necessarily authentic. +Only information recorded at the final destination is reliable, +since the headers may be changed by intermediate servers.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_received_header = yes
+
      +
      + +

      Enabling TLS in the Postfix SMTP server

      + +

      By default, TLS is disabled in the Postfix SMTP server, so no +difference to plain Postfix is visible. Explicitly switch it on +using "smtpd_use_tls = yes".

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_use_tls = yes
+
      +
      + +

      With this, Postfix SMTP server announces STARTTLS support to +SMTP clients, but does not require that clients use TLS encryption. +

      + +

      Note: when an unprivileged user invokes "sendmail -bs", STARTTLS +is never offered due to insufficient privileges to access the server +private key. This is intended behavior.

      + +

      You can ENFORCE the use of TLS, so that the Postfix SMTP server +announces STARTTLS and accepts no mail without TLS encryption, by +setting "smtpd_enforce_tls = yes". According to RFC 2487 this MUST +NOT be applied in case of a publicly-referenced Postfix SMTP server. +This option is off by default and should only seldom be used.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_enforce_tls = yes
+
      +
      + +

      TLS is sometimes used in the non-standard "wrapper" mode where +a server always uses TLS, instead of announcing STARTTLS support +and waiting for clients to request TLS service. Some clients, namely +Outlook [Express] prefer the "wrapper" mode. This is true for OE +(Win32 < 5.0 and Win32 >=5.0 when run on a port<>25 +and OE (5.01 Mac on all ports).

      + +

      It is strictly discouraged to use this mode from main.cf. If +you want to support this service, enable a special port in master.cf +and specify "-o smtpd_tls_wrappermode = yes" as an smtpd(8) command +line option. Port 465 (smtps) was once chosen for this feature. +

      + +

      Example:

      + +
      +
      +/etc/postfix/master.cf:
+    smtps    inet  n       -       n       -       -       smtpd
+      -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes
+
      +
      + +

      Client certificate verification

      + +

      To receive a remote SMTP client certificate, the Postfix SMTP +server must explicitly ask for one (any contents of $smtpd_tls_CAfile +are also sent to the client as a hint for choosing a certificate +from a suitable CA). Unfortunately, Netscape clients will either +complain if no matching client certificate is available or will +offer the user client a list of certificates to choose from. +Additionally some MTAs (notably some versions of qmail) are unable +to complete TLS negotiation when client certificates are requested, +and abort the SMTP session. So this option is "off" by default. +You will however need the certificate if you want to use certificate +based relaying with, for example, the permit_tls_clientcerts +feature.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_ask_ccert = no
+
      +
      + +

      You may also decide to REQUIRE a remote SMTP client certificate +before allowing TLS connections. This feature is included for +completeness, and implies "smtpd_tls_ask_ccert = yes".

      + +

      Please be aware, that this will inhibit TLS connections without +a proper client certificate and that it makes sense only when +non-TLS submission is disabled (smtpd_enforce_tls = yes). Otherwise, +clients could bypass the restriction by simply not using STARTTLS +at all.

      + +

      When TLS is not enforced, the connection will be handled as +if only "smtpd_tls_ask_ccert = yes" is specified, and a warning is +logged.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_req_ccert = no
+
      +
      + +

      A client certificate verification depth of 1 is sufficient if +the certificate is directly issued by a CA listed in the CA file. +The default value (5) should also suffice for longer chains (root +CA issues special CA which then issues the actual certificate...) +

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_ccert_verifydepth = 5
+
      +
      + +

      Supporting AUTH over TLS only

      + +

      Sending AUTH data over an unencrypted channel poses a security +risk. When TLS layer encryption is required (smtpd_enforce_tls = +yes), the Postfix SMTP server will announce and accept AUTH only +after the TLS layer has been activated with STARTTLS. When TLS +layer encryption is optional (smtpd_enforce_tls = no), it may +however still be useful to only offer AUTH when TLS is active. To +maintain compatibility with non-TLS clients, the default is to +accept AUTH without encryption. In order to change this behavior, +set "smtpd_tls_auth_only = yes".

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_auth_only = no
+
      +
      + +

      Server-side TLS session cache

      + +

      The Postfix SMTP server and the remote SMTP client negotiate +a session, which takes some computer time and network bandwidth. +By default, this session information is cached only in the smtpd(8) +process actually using this session and is lost when the process +terminates. To share the session information between multiple +smtpd(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several +kbytes and that supports the sequence operator. DBM databases are +not suitable because they can only store small objects. The cache +is maintained by the tlsmgr(8) process, so there is no problem with +concurrent access. Session caching is highly recommended, because +the cost of repeatedly negotiating TLS session keys is high.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_session_cache_database = btree:/etc/postfix/smtpd_scache
+
      +
      + +

      Cached Postfix SMTP server session information expires after +a certain amount of time. Postfix/TLS does not use the OpenSSL +default of 300s, but a longer time of 3600sec (=1 hour). RFC 2246 +recommends a maximum of 24 hours.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_session_cache_timeout = 3600s
+
      +
      + +

      Server access control

      + +

      Postfix TLS support introduces three additional features for +Postfix SMTP server access control:

      + +
      + +
      + +
      permit_tls_clientcerts

      Allow the remote SMTP +client SMTP request if the client certificate passes verification, +and if its fingerprint is listed in the list of client certificates +(see relay_clientcerts discussion below).

      + +
      permit_tls_all_clientcerts

      Allow the remote +client SMTP request if the client certificate passes verification. +

      + +
      check_ccert_access type:table
      +

      If the client certificate passes verification, use its fingerprint +as a key for the specified access(5) table.

      + +
      + +
      + +

      The permit_tls_all_clientcerts feature must be used with caution, +because it can result in too many access permissions. Use this +feature only if a special CA issues the client certificates, and +only if this CA is listed as trusted CA. If other CAs are trusted, +any owner of a valid client certificate would be authorized. +The permit_tls_all_clientcerts feature can be practical for a +specially created email relay server.

      + +

      It is however recommended to stay with the permit_tls_clientcerts +feature and list all certificates via $relay_clientcerts, as +permit_tls_all_clientcerts does not permit any control when a +certificate must no longer be used (e.g. an employee leaving).

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_recipient_restrictions = 
+        ... 
+        permit_tls_clientcerts 
+        reject_unauth_destination
+        ...
+
      +
      + +

      The Postfix list manipulation routines give special treatment +to whitespace and some other characters, making the use of certificate +names impractical. Instead we use the certificate fingerprints as +they are difficult to fake but easy to use for lookup. Postfix +lookup tables are in the form of (key, value) pairs. Since we only +need the key, the value can be chosen freely, e.g. the name of +the user or host.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    relay_clientcerts = hash:/etc/postfix/relay_clientcerts
+
+/etc/postfix/relay_clientcerts:
+    D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home
+
      +
      + +

      Server-side cipher controls

      + +

      To influence the Postfix SMTP server cipher selection scheme, +you can give cipherlist string. A detailed description would go +to far here; please refer to the OpenSSL documentation. If you +don't know what to do with it, simply don't touch it and leave the +(openssl-)compiled in default!

      + +

      DO NOT USE " to enclose the string, specify just the string!!!

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_cipherlist = DEFAULT
+
      +
      + +

      If you want to take advantage of ciphers with EDH, DH parameters +are needed. Instead of using the built-in DH parameters for both +1024bit and 512bit, it is better to generate "own" parameters, +since otherwise it would "pay" for a possible attacker to start a +brute force attack against parameters that are used by everybody. +For this reason, the parameters chosen are already different from +those distributed with other TLS packages.

      + +

      To generate your own set of DH parameters, use:

      + +
      +
      +% openssl gendh -out /etc/postfix/dh_1024.pem -2 -rand /var/run/egd-pool 1024
+% openssl gendh -out /etc/postfix/dh_512.pem -2 -rand /var/run/egd-pool 512
+
      +
      + +

      Examples:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem
+    smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem
+
      +
      + +

      Miscellaneous server controls

      + +

      The smtpd_starttls_timeout parameter limits the time of Postfix +SMTP server write and read operations during TLS startup and shutdown +handshake procedures.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtpd_starttls_timeout = 300s
+
      +
      + +

      SMTP Client specific settings

      + +

      Topics covered in this section:

      + + + +

      Client-side certificate and private +key configuration

      + +

      During TLS startup negotiation the Postfix SMTP client may present +a certificate to the remote SMTP server. The Netscape client is +rather clever here and lets the user select between only those +certificates that match CA certificates offered by the remote SMTP +server. As the Postfix SMTP client uses the "SSL_connect()" function +from the OpenSSL package, this is not possible and we have to choose +just one certificate. So for now the default is to use _no_ +certificate and key unless one is explicitly specified here.

      + +

      Both RSA and DSA certificates are supported. You can have both +at the same time, in which case the cipher used determines which +certificate is presented.

      + +

      It is possible for the Postfix SMTP client to use the same +key/certificate pair as the Postfix SMTP server. If a certificate +is to be presented, it must be in "pem" format. The private key +must not be encrypted, meaning: it must be accessible without +password. Both parts (certificate and private key) may be in the +same file.

      + +

      In order for remote SMTP servers to verify the Postfix SMTP +client certificates, the CA certificate (in case of a certificate +chain, all CA certificates) must be available. You should add +these certificates to the client certificate, the client certificate +first, then the issuing CA(s).

      + +

      Example: the certificate for "client.example.com" was issued by +"intermediate CA" which itself has a certificate of "root CA". +Create the client.pem file with:

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

      A Postfix SMTP client certificate supplied here must be usable +as SSL client certificate and hence pass the "openssl verify -purpose +sslclient ..." test.

      + +

      A server that trusts the root CA has a local copy of the root +CA certificate, so it is not necessary to include the root CA +certificate here. Leaving it out of the "client.pem" file reduces +the overhead of the TLS exchange.

      + +

      If you want the Postfix SMTP client to accept remote SMTP server +certificates issued by these CAs, append the root certificate to +$smtp_tls_CAfile or install it in the $smtp_tls_CApath directory. When +you configure trust in a root CA, it is not necessary to explicitly trust +intermediary CAs signed by the root CA, unless $smtp_tls_scert_verifydepth +is less than the number of CAs in the certificate chain for the servers +of interest. With a verify depth of 1 you can only verify certificates +directly signed by a trusted CA, and all trusted intermediary CAs need to +be configured explicitly. With a verify depth of 2 you can verify servers +signed by a root CA or a direct intermediary CA (so long as the server +is correctly configured to supply its intermediate CA certificate).

      + +

      RSA key and certificate examples:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_cert_file = /etc/postfix/client.pem
+    smtp_tls_key_file = $smtp_tls_cert_file
+
      +
      + +

      Their DSA counterparts:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
+    smtp_tls_dkey_file = $smtpd_tls_cert_file
+
      +
      + +

      To verify a remote SMTP server certificate, the Postfix SMTP +client needs to trust the certificates of the issuing certification +authorities. These certificates in "pem" format can be stored in a +single $smtp_tls_CAfile or in multiple files, one CA per file in +the $smtp_tls_CApath directory. If you use a directory, don't forget +to create the necessary "hash" links with:

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

      The $smtp_tls_CAfile contains the CA certificates of one or more +trusted CAs. The file is opened (with root privileges) before Postfix +enters the optional chroot jail and so need not be accessible from inside the +chroot jail.

      + +

      Additional trusted CAs can be specified via the $smtp_tls_CApath +directory, in which case the certificates are read (with $mail_owner +privileges) from the files in the directory when the information +is needed. Thus, the $smtp_tls_CApath directory needs to be accessible +inside the optional chroot jail.

      + +

      The choice between $smtp_tls_CAfile and $smtpd_tls_CApath is +a space/time tradeoff. If there are many trusted CAs, the cost of +preloading them all into memory may not pay off in reduced access time +when the certificate is needed.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_CAfile = /etc/postfix/CAcert.pem
+    smtp_tls_CApath = /etc/postfix/certs
+
      +
      + +

      Client-side TLS activity logging

      + +

      To get additional information about Postfix SMTP client TLS +activity you can increase the loglevel from 0..4. Each logging +level also includes the information that is logged at a lower +logging level.

      + +
      + + + + + + + + + + + + + + +
      0 Disable logging of TLS activity.
      1 Log TLS handshake and certificate information. +
      2 Log levels during TLS negotiation.
      3 Log hexadecimal and ASCII dump of TLS +negotiation process
      4 Log hexadecimal and ASCII dump of complete +transmission after STARTTLS
      + +
      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_loglevel = 0
+
      +
      + +

      Client-side TLS session cache

      + +

      The remote SMTP server and the Postfix SMTP client negotiate a +session, which takes some computer time and network bandwidth. By +default, this session information is cached only in the smtp(8) +process actually using this session and is lost when the process +terminates. To share the session information between multiple +smtp(8) processes, a persistent session cache can be used. You +can specify any database type that can store objects of several +kbytes and that supports the sequence operator. DBM databases are +not suitable because they can only store small objects. The cache +is maintained by the tlsmgr(8) process, so there is no problem with +concurrent access. Session caching is highly recommended, because +the cost of repeatedly negotiating TLS session keys is high. Future +Postfix SMTP servers may limit the number of sessions that a client +is allowed to negotiate per unit time.

      + + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_session_cache_database = btree:/etc/postfix/smtp_scache
+
      +
      + +

      Cached Postfix SMTP client session information expires after +a certain amount of time. Postfix/TLS does not use the OpenSSL +default of 300s, but a longer time of 3600s (=1 hour). RFC 2246 +recommends a maximum of 24 hours.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_session_cache_timeout = 3600s
+
      +
      + +

      Enabling TLS in the Postfix SMTP +client

      + +

      By default, TLS is disabled in the Postfix SMTP client, so no +difference to plain Postfix is visible. If you enable TLS, the +Postfix SMTP client will send STARTTLS when TLS support is announced +by the remote SMTP server.

      + +

      When the server accepts the STARTTLS command, but the subsequent +TLS handshake fails, and no other server is available, the Postfix SMTP +client defers the delivery attempt, and the mail stays in the queue. After +a handshake failure, the communications channel is in an indeterminate +state and cannot be used for non-TLS deliveries.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_use_tls = yes
+
      +
      + +

      Requiring TLS encryption +

      + +

      You can ENFORCE the use of TLS, so that the Postfix SMTP client +will not deliver mail over unencrypted connections. In this mode, +the remote SMTP server hostname must match the information in the +remote server certificate, and the server certificate must be issued +by a CA that is trusted by the Postfix SMTP client. If the remote +server certificate doesn't verify or the remote SMTP server hostname +doesn't match, and no other server is available, the delivery +attempt is deferred and the mail stays in the queue.

      + +

      The remote SMTP server hostname is verified against all names +provided as dNSNames +in the SubjectAlternativeName. If no dNSNames are specified, the +CommonName is checked. Verification may be turned off with the +smtp_tls_enforce_peername option which is discussed below.

      + +

      Enforcing the use of TLS is useful if you know that you will +only +connect to servers that support RFC 2487 _and_ that present server +certificates that meet the above requirements. An example would +be a client only sends email to one specific mailhub that offers +the necessary STARTTLS support.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_enforce_tls = yes
+
      +
      + +

      Disabling server certificate +verification

      + +

      As of RFC 2487 the requirements for hostname checking for MTA +clients are not set. When TLS is required (smtp_enforce_tls = yes), +the option smtp_tls_enforce_peername can be set to "no" to disable +strict remote SMTP server hostname checking. In this case, the mail +delivery will proceed regardless of the CommonName etc. listed in +the certificate.

      + +

      Despite the potential for eliminating "man-in-the-middle" and +other attacks, mandatory certificate/peername verification is not +viable as a default Internet mail delivery policy at this time. A +significant fraction of TLS enabled MTAs uses self-signed certificates, +or certificates that are signed by a private certificate authority. +On a machine that delivers mail to the Internet, if you set +smtp_enforce_tls = yes, you should probably also set +smtp_tls_enforce_peername = no. You can use the per-site TLS +policies (see below) to enable full peer verification for specific +destinations that are known to have verifiable TLS server certificates. +

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_enforce_tls = yes
+    smtp_tls_enforce_peername = no
+
      +
      + +

      Per-site TLS policies

      + +

      A small fraction of servers offer STARTTLS but the negotiation +consistently fails, leading to mail aging out of the queue and +bouncing back to the sender. In such cases, you can use the per-site +policies to disable TLS for the problem sites. Alternatively, you +can enable TLS for just a few specific sites and not enable it for +all sites.

      + + + +

      The smtp_tls_per_site table is searched for a policy that matches +the following information:

      + +
      + +
      + +
      remote SMTP server hostname
      This is simply the DNS +name of the server that the Postfix SMTP client connects to; this +name may be obtained from other DNS lookups, such as MX lookups or +CNAME lookups.
      + +
      next-hop destination
      This is normally the domain +portion of the recipient address, but it may be overruled by +information from the transport(5) table, from the relayhost parameter +setting, or from the relay_transport setting. When it's not the +recipient domain, the next-hop destination can have the Postfix-specific +form "[name]", [name]:port", "name" or +"name:port".
      + +
      + +
      + +

      When both the hostname lookup and the next-hop lookup succeed, +the host policy does not automatically override the next-hop policy. +Instead, precedence is given to either the more specific or the +more secure per-site policy as described below.

      + +

      The smtp_tls_per_site table uses a simple "name whitespace +value" format. Specify host names or next-hop destinations on +the left-hand side; no wildcards are allowed. On the right hand +side specify one of the following keywords:

      + +
      + +
      + +
      NONE
      Don't use TLS at all. This overrides a less +specific MAY lookup result from the alternate host or next-hop +lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls, +and smtp_tls_enforce_peername settings.
      + +
      MAY
      Try to use TLS if the server announces support, +otherwise use the unencrypted connection. This has less precedence +than a more specific result (including NONE) from the alternate +host or next-hop lookup key, and has less precedence than the more +specific global "smtp_enforce_tls = yes" or "smtp_tls_enforce_peername += yes".
      + +
      MUST_NOPEERMATCH
      Require TLS encryption, but do not +require that the remote SMTP server hostname matches the information +in the remote SMTP server certificate, or that the server certificate +was issued by a trusted CA. This overrides a less secure NONE +or a less specific MAY lookup result from the alternate host +or next-hop lookup key, and overrides the global smtp_use_tls, +smtp_enforce_tls and smtp_tls_enforce_peername settings.
      + +
      MUST
      Require TLS encryption, require that the remote +SMTP server hostname matches the information in the remote SMTP +server certificate, and require that the remote SMTP server certificate +was issued by a trusted CA. This overrides a less secure NONE +and MUST_NOPEERMATCH or a less specific MAY lookup +result from the alternate host or next-hop lookup key, and overrides +the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername +settings.
      + +
      + +
      + +

      The precedences between global (main.cf) and per-site TLS +policies can be summarized as follows:

      + +
        + +

      • When neither the remote SMTP server hostname nor the +next-hop destination are found in the smtp_tls_per_site table, the +policy is based on smtp_use_tls, smtp_enforce_tls and +smtp_tls_enforce_peername. Note: "smtp_enforce_tls = yes" and +"smtp_tls_enforce_peername = yes" imply "smtp_use_tls = yes".

        + +

      • When both hostname and next-hop destination lookups produce +a result, the more specific per-site policy (NONE, MUST, etc) +overrides the less specific one (MAY), and the more secure per-site +policy (MUST, etc) overrides the less secure one (NONE).

        + +

      • After the per-site policy lookups are combined, the result +generally overrides the global policy. The exception is the less +specific MAY per-site policy, which is overruled by the more +specific global "smtp_enforce_tls = yes" with server certificate +verification as specified with the smtp_tls_enforce_peername +parameter.

        + +
      + +

      Closing a DNS loophole with + per-site TLS policies

      + +

      As long as no secure DNS lookup mechanism is available, false +hostnames in MX or CNAME responses can change the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification. Even with a perfect match between the server hostname +and the server certificate, there is no guarantee that Postfix is +connected to the right server. To avoid this loophole take the +following steps:

      + +
        + +

      • Eliminate MX lookups. Specify local transport(5) table +entries for sensitive domains with explicit smtp:[mailhost] +or smtp:[mailhost]:port destinations (you can assure +security of this table unlike DNS); in the smtp_tls_per_site table +specify the value MUST for the key [mailhost] or +smtp:[mailhost]:port. This prevents false hostname +information in DNS MX records from changing the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification.

        + +

      • Disallow CNAME hostname overrides. In main.cf specify +"smtp_cname_overrides_servername = no". This prevents false hostname +information in DNS CNAME records from changing the server hostname +that Postfix uses for TLS policy lookup and server certificate +verification. This feature requires Postfix 2.2.9 or later.

        + +
      + +

      Example:

      + +
      +/etc/postfix/main.cf:
+    smtp_tls_per_site = hash:/etc/postfix/tls_per_site
+    relayhost = [msa.example.net]:587
+
+/etc/postfix/tls_per_site:
+    # relayhost exact nexthop match
+    [msa.example.net]:587       MUST
+
+    # TLS should not be used with the example.org MX hosts.
+    example.org                 NONE
+
+    # TLS should not be used with the host smtp.example.com.
+    smtp.example.com             NONE
+
      +
      + +

      Discovering servers that support +TLS

      + +

      As we decide on a "per site" basis whether or not to use TLS, +it would be good to have a list of sites that offered "STARTTLS". +We can collect it ourselves with this option.

      + +

      If the smtp_tls_note_starttls_offer feature is enabled and a +server offers STARTTLS while TLS is not already enabled for that +server, the Postfix SMTP client logs a line as follows:

      + +
      +
      +postfix/smtp[pid]: Host offered STARTTLS: [hostname.example.com]
+
      +
      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_note_starttls_offer = yes
+
      +
      + +

      Server certificate verification depth

      + +

      When verifying a remote SMTP server certificate, a verification +depth of 1 is sufficient if the certificate is directly issued by +a CA specified with smtp_tls_CAfile or smtp_tls_CApath. The default +value of 5 should also suffice for longer chains (root CA issues +special CA which then issues the actual certificate...)

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_scert_verifydepth = 5
+
      +
      + +

      Client-side cipher controls

      + +

      To influence the Postfix SMTP client cipher selection scheme, +you can give cipherlist string. A detailed description would go +to far here; please refer to the OpenSSL documentation. If you +don't know what to do with it, simply don't touch it and leave the +(openssl-)compiled in default!

      + +

      DO NOT USE " to enclose the string, specify just the string!!!

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_tls_cipherlist = DEFAULT
+
      +
      + +

      Miscellaneous client controls

      + +

      The smtp_starttls_timeout parameter limits the time of Postfix +SMTP client write and read operations during TLS startup and shutdown +handshake procedures. In case of problems the Postfix SMTP client +tries the next network address on the mail exchanger list, and +defers delivery if no alternative server is available.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    smtp_starttls_timeout = 300s
+
      +
      + +

      TLS manager specific settings

      + +

      The security of cryptographic software such as TLS depends +critically on the ability to generate unpredictable numbers for +keys and other information. To this end, the tlsmgr(8) process +maintains a Pseudo Random Number Generator (PRNG) pool. This is +queried by the smtp(8) and smtpd(8) processes when they initialize. +By default, these daemons request 32 bytes, the equivalent to 256 +bits. This is more than sufficient to generate a 128bit (or 168bit) +session key.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    tls_daemon_random_bytes = 32
+
      +
      + +

      In order to feed its in-memory PRNG pool, the tlsmgr(8) reads +entropy from an external source, both at startup and during run-time. +Specify a good entropy source, like EGD or /dev/urandom; be sure +to only use non-blocking sources (on OpenBSD, use /dev/arandom +when tlsmgr(8) complains about /dev/urandom timeout errors). +If the entropy source is not a +regular file, you must prepend the source type to the source name: +"dev:" for a device special file, or "egd:" for a source with EGD +compatible socket interface.

      + +

      Examples (specify only one in main.cf):

      + +
      +
      +/etc/postfix/main.cf:
+    tls_random_source = dev:/dev/urandom
+    tls_random_source = egd:/var/run/egd-pool
+
      +
      + +

      By default, tlsmgr(8) reads 32 bytes from the external entropy +source at each seeding event. This amount (256bits) is more than +sufficient for generating a 128bit symmetric key. With EGD and +device entropy sources, the tlsmgr(8) limits the amount of data +read at each step to 255 bytes. If you specify a regular file as +entropy source, a larger amount of data can be read.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    tls_random_bytes = 32
+
      +
      + +

      In order to update its in-memory PRNG pool, the tlsmgr(8) +queries the external entropy source again after a pseudo-random +amount of time. The time is calculated using the PRNG, and is +between 0 and the maximal time specified with tls_random_reseed_period. +The default maximal time interval is 1 hour.

      + +

      Example:

      + +
      +
      +/etc/postfix/main.cf:
+    tls_random_reseed_period = 3600s
+
      +
      + +

      The tlsmgr(8) process saves the PRNG state to a persistent +exchange file at regular times and when the process terminates, so +that it can recover the PRNG state the next time it starts up. +This file is created when it does not exist. Its default location +is under the Postfix configuration directory, which is not the +proper place for information that is modified by Postfix. Instead, +the file location should probably be on the /var partition (but +not inside the chroot jail).

      + +

      Examples:

      + +
      +
      +/etc/postfix/main.cf:
+    tls_random_exchange_name = /etc/postfix/prng_exch
+    tls_random_prng_update_period = 3600s
+
      +
      + +

      Getting started, quick and dirty

      + +

      The following steps will get you started quickly. Because you +sign your own Postfix public key certificate, you get TLS encryption +but no TLS authentication. This is sufficient for testing, and +for exchanging email with sites that you have no trust relationship +with. For real authentication, your Postfix public key certificate +needs to be signed by a recognized Certificate Authority, and +Postfix needs to be configured with a list of public key certificates +of Certificate Authorities, so that Postfix can verify the public key +certificates of remote hosts.

      + +

      In the examples below, user input is shown in bold +font, and a "#" prompt indicates a super-user shell.

      + +
        + +

      • Become your own Certificate Authority, so that you can +sign your own public keys. This example uses the CA.pl script that +ships with OpenSSL. By default, OpenSSL installs this as +/usr/local/ssl/misc/CA.pl, but your mileage may vary. +The script creates a private key in ./demoCA/private/cakey.pem +and a public key in ./demoCA/cacert.pem.

        + +
        +
        +% /usr/local/ssl/misc/CA.pl -newca
+CA certificate filename (or enter to create)
+
+Making CA certificate ...
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 1024 bit RSA private key
+....................++++++
+.....++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase:whatever
+
        +
        + +

      • Create an unpassworded private key for host FOO and create +an unsigned public key certificate.

        + +
        +
        +% openssl req -new -nodes -keyout FOO-key.pem -out FOO-req.pem -days 365
+Using configuration from /etc/ssl/openssl.cnf
+Generating a 1024 bit RSA private key
+........................................++++++
+....++++++
+writing new private key to 'FOO-key.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:US
+State or Province Name (full name) [Some-State]:New York
+Locality Name (eg, city) []:Westchester
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:Porcupine
+Organizational Unit Name (eg, section) []:
+Common Name (eg, YOUR name) []:FOO
+Email Address []:wietse@porcupine.org
+
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:whatever
+An optional company name []:
+
        +
        + +

      • Sign the public key certificate for host FOO with the +Certification Authority private key that we created a few +steps ago.

        + +
        +
        +% openssl ca -out FOO-cert.pem -infiles FOO-req.pem
+Uing configuration from /etc/ssl/openssl.cnf
+Enter PEM pass phrase:whatever
+Check that the request matches the signature
+Signature ok
+The Subjects Distinguished Name is as follows
+countryName           :PRINTABLE:'US'
+stateOrProvinceName   :PRINTABLE:'New York'
+localityName          :PRINTABLE:'Westchester'
+organizationName      :PRINTABLE:'Porcupine'
+commonName            :PRINTABLE:'FOO'
+emailAddress          :IA5STRING:'wietse@porcupine.org'
+Certificate is to be certified until Nov 21 19:40:56 2005 GMT (365 days)
+Sign the certificate? [y/n]:y
+
+
+1 out of 1 certificate requests certified, commit? [y/n]y
+Write out database with 1 new entries
+Data Base Updated
+
        +
        + +

      • Install the host private key, the host public key certificate, +and the Certification Authority certificate files. This requires +super-user privileges.

        + +
        +
        +# cp demoCA/cacert.pem FOO-key.pem FOO-cert.pem /etc/postfix
+# chmod 644 /etc/postfix/FOO-cert.pem /etc/postfix/cacert.pem
+# chmod 400 /etc/postfix/FOO-key.pem
+
        +
        + +

      • Configure Postfix, by adding the following to +/etc/postfix/main.cf .

        + +
        +
        +smtp_tls_CAfile = /etc/postfix/cacert.pem
+smtp_tls_cert_file = /etc/postfix/FOO-cert.pem
+smtp_tls_key_file = /etc/postfix/FOO-key.pem
+smtp_tls_session_cache_database = btree:/var/run/smtp_tls_session_cache
+smtp_use_tls = yes
+smtpd_tls_CAfile = /etc/postfix/cacert.pem
+smtpd_tls_cert_file = /etc/postfix/FOO-cert.pem
+smtpd_tls_key_file = /etc/postfix/FOO-key.pem
+smtpd_tls_received_header = yes
+smtpd_tls_session_cache_database = btree:/var/run/smtpd_tls_session_cache
+smtpd_use_tls = yes
+tls_random_source = dev:/dev/urandom
+
        +
        + +
      + + +

      Reporting problems

      + +

      When reporting a problem, please be thorough in the report. +Patches, when possible, are greatly appreciated too.

      + +

      Please differentiate when possible between:

      + +
        + +
      • Problems in the TLS code: <postfix_tls@aet.tu-cottbus.de> + +
      • Problems in vanilla Postfix: <postfix-users@postfix.org> + +
      + +

      Compatibility with Postfix <2.2 TLS support

      + +

      Postfix version 2.2 TLS support is based on the Postfix/TLS +patch by Lutz Jänicke, but differs in a few minor ways.

      + +
        + +

      • main.cf: Specify "btree" instead of "sdbm" for TLS +session cache databases.

        + +

        TLS session cache databases are now accessed only by the +tlsmgr(8) process, so there are no more concurrency issues. Although +Postfix has an sdbm client, the sdbm library (1000 +lines of code) is not included with Postfix.

        + +

        TLS session caches can use any database that can store objects +of several kbytes or more, and that implements the sequence operation. +In most cases, btree databases should be adequate.

        + +

        NOTE: You cannot use dbm databases. TLS session objects +are too large.

        + +

      • master.cf: Specify "unix" instead of "fifo" as +the tlsmgr service type.

        + +

        The smtp(8) and smtpd(8) processes now use a client-server +protocol in order to access the tlsmgr(8) pseudo-random number +generation (PRNG) pool, and in order to access the TLS session +cache databases. Such a protocol cannot be run across fifos.

        + +

      • smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy +cannot override the global "smtp_tls_enforce_peername = yes" setting. +

        + +

      • smtp_tls_per_site: a combined (NONE + MAY) lookup result +for (hostname and next-hop destination) produces counter-intuitive +results for different main.cf settings. TLS is enabled with +"smtp_tls_enforce_peername = no", but it is disabled when both +"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes". +

        + +
      + +

      The smtp_tls_per_site limitations were removed by the end of +the Postfix 2.2 support cycle.

      + +

      Credits

      + +
        + +
      • TLS support for Postfix was originally developed by Lutz +Jänicke at Cottbus Technical University. + +
      • Wietse Venema adopted the code, did some restructuring, and +compiled this part of the documentation from Lutz's documents. + +
      • Victor Duchovni was instrumental with the re-implementation +of the smtp_tls_per_site code in terms of enforcement levels, which +simplified the implementation greatly. + +
      + + + + diff --git a/postfix/proto/TLS_README.html b/postfix/proto/TLS_README.html index df965a3b7..0d341714b 100644 --- a/postfix/proto/TLS_README.html +++ b/postfix/proto/TLS_README.html @@ -34,11 +34,11 @@ certificate-based authentication and encrypted sessions. An encrypted session protects the information that is transmitted with SMTP mail or with SASL authentication. -

      Postfix version 2.2 introduces support for TLS as described in -RFC 3207. TLS Support for older Postfix versions was available as -an add-on patch. The section "Compatibility with -Postfix < 2.2 TLS support" below discusses the differences -between these implementations.

      +

      This document describes a TLS user interface that was introduced +with Postfix version 2.3. Support for an older user interface is +documented in TLS_LEGACY_README, which also describes the differences +between Postfix and the third-party patch on which Postfix version +2.2 TLS support was based.

      Topics covered in this document:

      @@ -56,8 +56,6 @@ between these implementations.

    • Reporting problems -
    • Compatibility with Postfix < 2.2 TLS support -
    • Credits
    @@ -2330,52 +2328,6 @@ See http://www.postfix.org/lists.html for subscription information. When reporting a problem, please be thorough in the report. Patches, when possible, are greatly appreciated too.

    -

    Compatibility with Postfix < 2.2 TLS support

    - -

    Postfix version 2.2 TLS support is based on the Postfix/TLS -patch by Lutz Jänicke, but differs in a few minor ways.

    - -
      - -

    • main.cf: Specify "btree" instead of "sdbm" for TLS -session cache databases.

      - -

      TLS session cache databases are now accessed only by the -tlsmgr(8) process, so there are no more concurrency issues. Although -Postfix has an sdbm client, the sdbm library (1000 -lines of code) is not included with Postfix.

      - -

      TLS session caches can use any database that can store objects -of several kbytes or more, and that implements the sequence operation. -In most cases, btree databases should be adequate.

      - -

      NOTE: You cannot use DBM databases. TLS session objects -are too large.

      - -

    • master.cf: Specify "unix" instead of "fifo" as -the tlsmgr service type.

      - -

      The smtp(8) and smtpd(8) processes now use a client-server -protocol in order to access the tlsmgr(8) pseudo-random number -generation (PRNG) pool, and in order to access the TLS session -cache databases. Such a protocol cannot be run across fifos.

      - -

    • smtp_tls_per_site: the MUST_NOPEERMATCH per-site policy -cannot override the global "smtp_tls_enforce_peername = yes" setting. -

      - -

    • smtp_tls_per_site: a combined (NONE + MAY) lookup result -for (hostname and next-hop destination) produces counter-intuitive -results for different main.cf settings. TLS is enabled with -"smtp_tls_enforce_peername = no", but it is disabled when both -"smtp_enforce_tls = yes" and "smtp_tls_enforce_peername = yes". -

      - -
    - -

    The smtp_tls_per_site limitations were removed by the end of -the Postfix 2.2 support cycle.

    -

    Credits

      diff --git a/postfix/src/dns/dns_lookup.c b/postfix/src/dns/dns_lookup.c index 941b7594f..764ab7298 100644 --- a/postfix/src/dns/dns_lookup.c +++ b/postfix/src/dns/dns_lookup.c @@ -100,6 +100,12 @@ /* The DNS query succeeded; the requested information was not found. /* .IP DNS_INVAL /* The DNS query succeeded; the result failed the valid_hostname() test. +/* +/* NOTE: the valid_hostname() test is skipped for results that +/* the caller suppresses explicitly. For example, when the +/* caller requests MX record lookup but specifies a null +/* resource record list argument, no syntax check will be done +/* for MX server names. /* .IP DNS_RETRY /* The query failed, or the reply was malformed. /* The problem is considered transient. diff --git a/postfix/src/global/mail_version.h b/postfix/src/global/mail_version.h index 1f8d3b091..5248081ce 100644 --- a/postfix/src/global/mail_version.h +++ b/postfix/src/global/mail_version.h @@ -20,7 +20,7 @@ * Patches change both the patchlevel and the release date. Snapshots have no * patchlevel; they change the release date only. */ -#define MAIL_RELEASE_DATE "20061224" +#define MAIL_RELEASE_DATE "20061229" #define MAIL_VERSION_NUMBER "2.4" #ifdef SNAPSHOT diff --git a/postfix/src/smtpd/smtpd_check.c b/postfix/src/smtpd/smtpd_check.c index 80d41ac25..c0a227d68 100644 --- a/postfix/src/smtpd/smtpd_check.c +++ b/postfix/src/smtpd/smtpd_check.c @@ -1142,6 +1142,7 @@ static int reject_unknown_hostname(SMTPD_STATE *state, char *name, { const char *myname = "reject_unknown_hostname"; int dns_status; + DNS_RR *dummy; if (msg_verbose) msg_info("%s: %s", myname, name); @@ -1152,15 +1153,20 @@ static int reject_unknown_hostname(SMTPD_STATE *state, char *name, #define RR_ADDR_TYPES T_A #endif - dns_status = dns_lookup_l(name, 0, (DNS_RR **) 0, (VSTRING *) 0, + dns_status = dns_lookup_l(name, 0, &dummy, (VSTRING *) 0, (VSTRING *) 0, DNS_REQ_FLAG_STOP_OK, RR_ADDR_TYPES, T_MX, 0); + if (dummy) + dns_rr_free(dummy); if (dns_status != DNS_OK) { /* incl. DNS_INVAL */ if (dns_status != DNS_RETRY) return (smtpd_check_reject(state, MAIL_ERROR_POLICY, var_unk_name_code, "4.7.1", - "<%s>: %s rejected: Host not found", - reply_name, reply_class)); + "<%s>: %s rejected: %s", + reply_name, reply_class, + dns_status == DNS_INVAL ? + "Malformed DNS server reply" : + "Host not found")); else DEFER_IF_PERMIT2(state, MAIL_ERROR_POLICY, 450, "4.7.1", @@ -1177,23 +1183,29 @@ static int reject_unknown_mailhost(SMTPD_STATE *state, const char *name, { const char *myname = "reject_unknown_mailhost"; int dns_status; + DNS_RR *dummy; if (msg_verbose) msg_info("%s: %s", myname, name); #define MAILHOST_LOOKUP_FLAGS (DNS_REQ_FLAG_STOP_OK | DNS_REQ_FLAG_STOP_INVAL) - dns_status = dns_lookup_l(name, 0, (DNS_RR **) 0, (VSTRING *) 0, + dns_status = dns_lookup_l(name, 0, &dummy, (VSTRING *) 0, (VSTRING *) 0, MAILHOST_LOOKUP_FLAGS, T_MX, RR_ADDR_TYPES, 0); + if (dummy) + dns_rr_free(dummy); if (dns_status != DNS_OK) { /* incl. DNS_INVAL */ if (dns_status != DNS_RETRY) return (smtpd_check_reject(state, MAIL_ERROR_POLICY, var_unk_addr_code, strcmp(reply_class, SMTPD_NAME_SENDER) == 0 ? "4.1.8" : "4.1.2", - "<%s>: %s rejected: Domain not found", - reply_name, reply_class)); + "<%s>: %s rejected: %s", + reply_name, reply_class, + dns_status == DNS_INVAL ? + "Malformed DNS server reply" : + "Domain not found")); else DEFER_IF_PERMIT2(state, MAIL_ERROR_POLICY, 450, strcmp(reply_class, SMTPD_NAME_SENDER) == 0 ?