# DO NOT EDIT THIS FILE. EDIT THE MAIN.CF FILE INSTEAD. THE STUFF # HERE JUST SERVES AS AN EXAMPLE. # # This file contains example settings of Postfix configuration # parameters that control the behaviour of the TLS extensions. # # We strictly seperate between server side TLS (smtpd_) and client side # TLS (smtp_), as for practical reasons we might choose differently. # Section with SMTPD specific settings # To use TLS we do need a certificate and a private key. Both must be in # "pem" format, the private key must not be encrypted, that does mean: # it must be accessable without password. Both parts (certificate and # private key) may be in the same file. # # Both RSA and DSA are certificates are supported. Typically you will only # have RSA certificates issued by a commercial CA, also the tools supplied # with OpenSSL will by default issue RSA certificates. # You can have both at the same time, in this case the cipher used decides, # which certificate is presented. For Netscape and OpenSSL clients without # special cipher choices, the RSA certificate is preferred. # # In order to check the 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 of "root CA". Create the server.pem file by # 'cat server_cert.pem intemediate_CA.pem root_CA.pem > server.pem' # # If you want to accept certificates issued by these CAs yourself, you can # also add the CA-certificates to the smtpd_tls_CAfile, in which case it is # not necessary to have them in the smtpd_tls_[d]cert_file. # # A certificate supplied here must be useable as SSL server certificate and # hence pass the "openssl verify -purpose sslserver ..." test. # smtpd_tls_cert_file = /etc/postfix/server.pem smtpd_tls_key_file = $smtpd_tls_cert_file # # Its DSA counterparts: smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem smtpd_tls_dkey_file = $smtpd_tls_dcert_file # The certificate was issued by a certification authority (CA), the CA-cert # of which must be available, if not in the certificate file. # This file may also contain the the CA certificates of other trusted CAs. # You must use this file for the list of trusted CAs if you want to use # chroot-mode. No default is supplied for this value as of now. # # smtpd_tls_CAfile = /etc/postfix/CAcert.pem # To verify the peer certificate, we need to know the certificates of # certification authorities. These certificates in "pem" format are # collected in a directory. The same CAs are offered to clients for # client verification. Don't forget to create the necessary "hash" # links with $OPENSSL_HOME/bin/c_rehash /etc/postfix/certs. A typical # place for the CA-certs may also be $OPENSSL_HOME/certs, so there is # no default and you explicitly have to set the value here! # # To use this option in chroot mode, this directory itself or a copy of it # must be inside the chroot jail. Please note also, that the CAs in this # directory are not listed to the client, so that e.g. Netscape might not # offer certificates issued by them. # # I therefore discourage the use of this option. # smtpd_tls_CApath = /etc/postfix/certs # To get additional information during the TLS setup and negotiations # you can increase the loglevel from 0..4: # 0: No output about the TLS subsystem # 1: Printout startup and certificate information # 2: 1 + Printout of levels during negotiation # 3: 2 + Hex and ASCII dump of negotiation process # 4: 3 + Hex and ASCII dump of complete transmission after STARTTLS # Use loglevel 3 only in case of problems. Use of loglevel 4 is strongly # discouraged. # # smtpd_tls_loglevel = 0 # To include information about the protocol and cipher used as well as the # client and issuer CommonName into the "Received:" header, set the # smtpd_tls_received_header variable to true. The default is no, as the # information is not necessarily authentic. Only the final destination # is reliable, since the headers might have been changed in between. # #smtpd_tls_received_header = yes # By default TLS is disabled, so no difference to plain postfix is visible. # Explicitely switch it on using "smtpd_use_tls". (Note: when invoked # via "sendmail -bs", STARTTLS is never offered due to insufficient # privileges to access the private key. This is intended behaviour.) # smtpd_use_tls = yes # You can ENFORCE the use of TLS, so that no commands (except QUIT of course) # are allowed without TLS. According to RFC2487 this MUST NOT be applied # in case of a publicly-referenced SMTP server. So this option is off # by default and should only seldom be used. Using this option implies # smtpd_use_tls = yes. (Note: when invoked via "sendmail -bs", STARTTLS # is never offered due to insufficient privileges to access the private key. # This is intended behaviour.) # # smtpd_enforce_tls = no # Besides RFC2487 some clients, namely Outlook [Express] prefer to run the # non-standard "wrapper" mode, not the STARTTLS enhancement to SMTP. # 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. Port 465 (smtps) # was once chosen for this feature. # # smtpd_tls_wrappermode = no # To receive a client certificate, the server must explicitly ask for one. # Hence netscape will either complain if no certificate is available (for # the list of CAs in /etc/postfix/certs) or will offer you client certificates # to choose from. This might be annoying, so this option is "off" by default. # You will however need the certificate if you want to to e.g. certificate # based relaying. # # smtpd_tls_ask_ccert = no # You may also decide to REQUIRE a client certificate to allow TLS connections. # I don't think it will be necessary often, it is however included here for # completeness. This option implies smtpd_tls_ask_ccert = yes # # Please be aware, that this will inhibit TLS connections without a proper # certificate and only makes sense, when normal submission is disabled and # TLS is enforced (smtpd_enforce_tls). Otherwise clients may bypass 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 would be set and an information # is logged. # # smtpd_tls_req_ccert = no # The verification depth for client certificates. A depth of 1 is sufficient, # if the certificate ist directly issued by a CA listed in the CA locations. # The default value (5) should also suffice for longer chains (root CA issues # special CA which then issues the actual certificate...) # # smtpd_tls_ccert_verifydepth = 5 # Sending AUTH data over an unencrypted channel poses a security risk. When # smtpd_tls_enforce_tls is set, AUTH will only be announced and accepted, # once the TLS layer has been activated via the STARTTLS protocol. If # TLS layer encryption is optional, it may however still be useful to only # offer AUTH, when TLS is active. To not break compatiblity with unpatched # postfix versions, the default is to accept AUTH without encryption. In # order to change this behaviour, set smtpd_tls_auth_only = yes. # # smtpd_tls_auth_only = no # The server and client negotiate a session, which takes some computer time # and network bandwidth. The session is cached only in the smtpd process # actually using this session and is lost when the process dies. # To share the session information between the smtpd processes, a disc based # session cache can be used based on the SDBM databases (routines included # in Postfix/TLS). Since concurrent writing must be supported, only SDBM # can be used. # smtpd_tls_session_cache_database = sdbm:/etc/postfix/smtpd_scache # The cached sessions time out after a certain amount of time. For Postfix/TLS # I do not use the OpenSSL default of 300sec, but a longer time of 3600sec # (=1 hour). RFC2246 recommends a maximum of 24 hours. # # smtpd_tls_session_cache_timeout = 3600s # Two additional options has been added for relay control to the UCE rules: # permit_tls_clientcerts (a) # and # permit_tls_all_clientcerts. (b) # # If one of these options is added to # smtpd_recipient_restrictions, # postfix will relay if # (a) a valid (it passed the verification) client certificate is presented # and its fingerprint is listed in the list of client certs # (relay_clientcerts), # (b) any valid (it passed the verification) client certificate is presented. # # Option (b) must only be used, if a special CA issues the certificates and # only this CA is listed as trusted CA. If other CAs are trusted, any owner # of a valid (SSL client)-certificate can relay. Option (b) can be practical # for a specically created email relay. It is however recommended to stay with # option (a) and list all certificates, as (b) does not permit any control # when a certificate must no longer be used (e.g. an employee leaving). # # smtpd_recipient_restrictions = ... permit_tls_clientcerts ... # The list of client certificates for which relaying will be allowed. # Unfortunately the routines for lists in postfix use whitespaces as # seperators and choke on special chars. So using the certificate # X509ONELINES is quite impractical. We will use the fingerprints at # this point, as they are difficult to fake but easy to use for lookup. # As postmap (when using e.g. db) insists of having a pair of key and value, # but we only need the key, the value can be chosen freely, e.g. the name # of the user or host: # D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home # # relay_clientcerts = hash:/etc/postfix/relay_clientcerts # To influence the 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, just the string!!! # # smtpd_tls_cipherlist = DEFAULT # If you want to take advantage of ciphers with EDH, DH parameters are needed. # There are built in DH parameters for both 1025bit and 512bit available. It # is however better to have "own" parameters, since otherwise it would "pay" # for a possible attacker to start a brute force attack against these # parameters commonly 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 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 # (your source for "entropy" might vary; on Linux there is /dev/random, on # other system, you might consider the "Entropy Gathering Daemon EGD", # available at http://www.lothar.com/tech/crypto/. # smtpd_tls_dh1024_param_file = /etc/postfix/dh_1024.pem smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem # The smtpd_starttls_timeout parameter limits the time in seconds to write and # read operations during TLS start and stop handhake procedures. # # smtpd_starttls_timeout = 300s # Section with SMTP specific settings # During the startup negotiation we might present a certificate to the server. # Netscape is rather clever here and lets the user select between only those # certs that will match the CAs accepted from the server. As I simply use # the integrated "SSL_connect()" from the OpenSSL package, this is not # possible by now and we have to chose just one cert. # So for now the default is to use _no_ cert and key unless explictly # set here. It is possible to use the same key/cert pair as for the server. # If a cert is to be presented, it must be in "pem" format, the private key # must not be encrypted, that does mean: it must be accessable without # password. Both parts (certificate and private key) may be in the # same file. # # In order to check the 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 "client.dom.ain" was issued by "intermediate CA" # which itself has a certificate of "root CA". Create the client.pem file by # 'cat client_cert.pem intemediate_CA.pem root_CA.pem > client.pem' # # If you want to accept certificates issued by these CAs yourself, you can # also add the CA-certificates to the smtp_tls_CAfile, in which case it is # not necessary to have them in the smtp_tls_[d]cert_file. # # A certificate supplied here must be useable as SSL client certificate and # hence pass the "openssl verify -purpose sslclient ..." test. # smtp_tls_cert_file = /etc/postfix/client.pem smtp_tls_key_file = $smtp_tls_cert_file # The certificate was issued by a certification authority (CA), the CA-cert # of which must be available, if not in the certificate file. # This file may also contain the the CA certificates of other trusted CAs. # You must use this file for the list of trusted CAs if you want to use # chroot-mode. No default is supplied for this value as of now. # smtp_tls_CAfile = /etc/postfix/CAcert.pem # To verify the peer certificate, we need to know the certificates of # certification authorities. These certificates in "pem" format are # collected in a directory. Don't forget to create the necessary "hash" # links with $OPENSSL_HOME/bin/c_rehash /etc/postfix/certs. A typical # place for the CA-certs may also be $OPENSSL_HOME/certs, so there is # no default and you explicitly have to set the value here! # # To use this option in chroot mode, this directory itself or a copy of it # must be inside the chroot jail. # smtp_tls_CApath = /etc/postfix/certs # To get additional information during the TLS setup and negotiations # you can increase the loglevel from 0..4: # 0: No output about the TLS subsystem # 1: Printout startup and certificate information # 2: 1 + Printout of levels during negotiation # 3: 2 + Hex and ASCII dump of negotiation process # 4: 3 + Hex and ASCII dump of complete transmission after STARTTLS # Use loglevel 3 only in case of problems. Use of loglevel 4 is strongly # discouraged. # smtp_tls_loglevel = 0 # The server and client negotiate a session, which takes some computer time # and network bandwidth. The session is cached only in the smtpd process # actually using this session and is lost when the process dies. # To share the session information between the smtp processes, a disc based # session cache can be used based on the SDBM databases (routines included # in Postfix/TLS). Since concurrent writing must be supported, only SDBM # can be used. # smtp_tls_session_cache_database = sdbm:/etc/postfix/smtp_scache # The cached sessions time out after a certain amount of time. For Postfix/TLS # I do not use the OpenSSL default of 300sec, but a longer time of 3600sec # (=1 hour). RFC2246 recommends a maximum of 24 hours. # # smtp_tls_session_cache_timeout = 3600s # By default TLS is disabled, so no difference to plain postfix is visible. # If you enable TLS it will be used when offered by the server. # WARNING: I didn't have access to other software (except those explicitely # listed) to test the interaction. On corresponding mailing list # there was a discussion going on about MS exchange servers offering # STARTTLS even if it is not configured, so it might be wise to not # use this option on your central mail hub, as you don't know in advance # whether you are going to hit such host. Use the recipient/site specific # options instead. # HINT: I have it switched on on my mailservers and did experience one # single failure since client side TLS is implemented. (There was one # misconfired MS Exchange server; I contacted ths admin.) Hence, I am happy # with it running all the time, but I am interested in testing anyway. # You have been warned, however :-) # # In case of failure, a "4xx" code is issued and the mail stays in the queue. # # Explicitely switch it on here, if you want it. # smtp_use_tls = yes # You can ENFORCE the use of TLS, so that only connections with TLS will # be accepted. Additionally, the hostname of the receiving host is matched # against the CommonName in the certificate. Also, the certificate must # be verified "Ok", so that a CA trusted by the client must have issued # the certificate. If the certificate doesn't verify or the hostname doesn't # match, a "4xx" will be issued and the mail stays in the queue. # The hostname used in the check is beyond question, as it must be the # principle hostname (no CNAME allowed here). # The behaviour may be changed with the smtp_tls_enforce_peername option # # This option is useful only if you are definitely sure that you will only # connect to servers supporting RFC2487 _and_ with valid certificates. # I use it for my clients which will only send email to one mailhub, which # does offer the necessary STARTTLS support. # # smtp_enforce_tls = no # As of RFC2487 the requirements for hostname checking for MTA clients are # not set. When in smtp_enforce_tls mode, the option smtp_tls_enforce_peername # can be set to "no" to disable strict peername checking. In this case, the # mail delivery will be continued, if a TLS connection was established # _and_ the peer certificate passed verification _but_ regardless of the # CommonName listed in the certificate. This option only applies to the # default setting smtp_enforce_tls_mode, special settings in the # smtp_tls_per_site table override smtp_tls_enforce_peername. # # This can make sense in closed environment where special CAs are created. # If not used carefully, this option opens the danger of a "man-in-the-middle" # attack (the CommonName of this attacker is logged). # # smtp_tls_enforce_peername = yes # As generally trying TLS can be a bad idea (some hosts offer STARTTLS but # the negotiation will fail leading to unexplainable failures, it may be # a good idea to decide based on the recipient or the mailhub to which you are # connecting. # # Deciding per recipient may be difficult, since a singe email can have # several recipients. We use the "nexthop" mechanism inside postfix. # When an email is to be delivered, the "nexthop" is obtained. If it matches # an entry in the smtp_tls_per_site list, appropriate action is taken. # Since entries in the transport table or the use of a relay_host override # the nexthop setting, in these cases the relay_host etc must be listed # in the table. In any case, the hostname of the peer to be contacted is # looked up (that is: the MX or the name of the host, if no MX is given). # # Special hint for enforcement mode: # Since there is no secure mechanism for DNS lookups available, the # recommended setup is: put the sensible domains with their mailhost # into the transport table (since you can asure security of this table # unlike DNS), then set MUST mode for this mailhost. # # Format of the table: # The keys entries are on the left hand side, no wildcards allowed. On the # right hand side the keywords NONE (don't use TLS at all), MAY (try to use # STARTTLS if offered, no problem if not), MUST (enforce usage of STARTTLS, # check server certificate CommonName against server FQDN), MUST_NOPEERMATCH # (enforce usage of STARTTLS and verify certificate, but ignore differences # between CommonName and server FQDN). # dom.ain NONE # host.dom.ain MAY # important.host MUST # some.host.dom.ain MUST_NOPEERMATCH # # If an entry is not matched, the default policy is applied; if the default # policy is "enforce", NONE explicitely switches it off, otherwise the # "enforce" mode is used even for MAY entries. # smtp_tls_per_site = hash:/etc/postfix/tls_per_site # The verification depth for server certificates. A depth of 1 is sufficient, # if the certificate ist directly issued by a CA listed in the CA locations. # The default value (5) should also suffice for longer chains (root CA issues # special CA which then issues the actual certificate...) # # smtp_tls_scert_verifydepth = 5 # As we decide on a "per site" basis, wether to use TLS or not, it would be # good to have a list of sites, that offered "STARTTLS'. We can collect it # ourselves with this option. # # If activated and TLS is not already enabled for this host, a line is added # to the logfile: # postfix/smtp[pid]: Host offered STARTTLS: [name.of.host] # smtp_tls_note_starttls_offer = yes # To influence the 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, just the string!!! # # smtp_tls_cipherlist = DEFAULT # The smtp_starttls_timeout parameter limits the time in seconds to write and # read operations during TLS start and stop handhake procedures. # # In case of problems the client does NOT try the next address on # the mail exchanger list. # # smtp_starttls_timeout = 300s # In order to seed the PRNG Pseude Random Number Generator, random data is # needed. The PRNG pool is maintained by the "tlsmgr" daemon and is used # (read) by the smtp[d] processes after adding some more entropy by stirring # in time and process id. # The file, which is from time to time rewritten by the tlsmgr, is created # if not existant. A default value is given; the default should probably # be on the /var partition but _not_ inside chroot jail. # # tls_random_exchange_name = /etc/postfix/prng_exch # To feed the PRNG pool, entropy is being read from an external source, # both at startup and during run. # Specify a good entropy source here, like EGD or /dev/urandom; make sure # to only use non-blocking sources. # In both cases, 32 bytes are read at each re-seeding event (which is an # amount of 256bits and hence good enough for 128bit symmetric keys). # You must specify the type of source: "dev:" for a device special file # or "egd:" for a source with EGD compatible socket interface. A maximum # 255 bytes is read from these sources in each step. # If you specify a normal file, a larger amount of data can be read. # # The entropy source is queried again after a certain amount of time. The # time is calculated using the PRNG, it is between 0 and the time specified, # default is a maximum of 1 hour. # # tls_random_source = dev:/dev/urandom tls_random_source = egd:/var/run/egd-pool # tls_random_bytes = 32 # tls_random_reseed_period = 3600s # The PRNG pool inside tlsmgr is used to re-generate the 1024 byte file # being read by smtp[d]. The time, after which the exchange file is # rewritten is calculated using the PRNG, it is between 0 and the time # specified, default is a maximum of 60 seconds. # # tls_random_upd_period = 60s # If you have a entropy source available, that is not easily drained (like # /dev/urandom), the daemons can also load additional entropy on startup from # the source specified. By default an amount of 32 bytes is read, the # equivalent to 256 bits. This is more than enough to generate a 128bit # (or 168bit) session key, but we may have to generate more than one. # Usage of this option may drain EGD (consider the case of 50 smtp starting # up with a full queue and "postfix start", which will request 1600bytes # of entropy). This is however not fatal, as long as "entropy" data could # be read from the exchange file. # # tls_daemon_random_source = dev:/dev/urandom tls_daemon_random_source = egd:/var/run/egd-pool # tls_daemon_random_bytes = 32