conf/sample-tls.cf file.
# 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 here: # 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 # # 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
# 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
# ========================================================================== # service type private unpriv chroot wakeup maxproc command + args # (yes) (yes) (yes) (never) (50) # ========================================================================== tlsmgr fifo - - y 300 1 tlsmgr
Both example entries already contain the flags to enable SASL authentication (which may be disabled on the normal port). Since the actual service names are used, smtps and submission must be defined in /etc/services (and probably also in /var/spool/postfix/etc/services if chrooted)!!! (Use the port numbers otherwise.)
# ========================================================================== # service type private unpriv chroot wakeup maxproc command + args # (yes) (yes) (yes) (never) (50) # ========================================================================== smtps inet n - y - - smtpd -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes submission inet n - y - - smtpd -o smtpd_enforce_tls=yes -o smtpd_sasl_auth_enable=yes