diff options
Diffstat (limited to 'README_FILES/TLS_LEGACY_README')
| -rw-r--r-- | README_FILES/TLS_LEGACY_README | 1119 |
1 files changed, 1119 insertions, 0 deletions
diff --git a/README_FILES/TLS_LEGACY_README b/README_FILES/TLS_LEGACY_README new file mode 100644 index 0000000..e9f36fd --- /dev/null +++ b/README_FILES/TLS_LEGACY_README @@ -0,0 +1,1119 @@ +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 + +As of version 2.5, Postfix will no longer maintain this file in a directory +with non-Postfix ownership. As a migration aid, attempts to open such files are +redirected to the Postfix-owned $data_directory, and a warning is logged. + +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 = $smtp_tls_dcert_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 $smtp_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 + +As of version 2.5, Postfix will no longer maintain this file in a directory +with non-Postfix ownership. As a migration aid, attempts to open such files are +redirected to the Postfix-owned $data_directory, and a warning is logged. + +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 +Certification 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 Certification +Authority, and Postfix needs to be configured with a list of public key +certificates of Certification 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 Certification 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: <postfix_tls@aet.tu-cottbus.de> + * Problems in vanilla Postfix: <postfix-users@postfix.org> + +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. + |