# 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

