#smtps	  inet	n	-	n	-	-	smtpd

#  -o smtpd_tls_wrappermode=yes -o smtpd_sasl_auth_enable=yes

#submission	inet	n	-	n	-	-	smtpd

#  -o smtpd_enforce_tls=yes -o smtpd_sasl_auth_enable=yes

#tlsmgr	  fifo	-	-	n	300	1	tlsmgr

$daemon_directory/tlsmgr:f:root:-:755

$manpage_directory/man8/tlsmgr.8:f:root:-:644

$sample_directory/sample-tls.cf:f:root:-:644

# 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.

# THIS OPTION ONLY WORKS WITH SSL/TLS SUPPORT COMPILED IN.

#

# smtpd_tls_auth_only = no

# 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

# 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

# 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

if test -f /usr/include/netinet6/in6.h; then

	grep __KAME__ /usr/include/netinet6/in6.h 2>&1 >/dev/null

	if [ $?  = 1 ]; then

		INET6=

	else

		if [ -f /usr/local/v6/lib/libinet6.a ]; then

			INET6=kame

		else

			INET6=kame-merged

		fi

	fi

fi

if [ -z "$INET6" -a -f /usr/include/netinet/ip6.h -a -f /usr/include/linux/icmpv6.h ]; then

	INET6=linux

fi

case "$INET6" in

kame)

	CCARGS="$CCARGS -DINET6 -D__ss_family=ss_family -D__ss_len=ss_len"

	if test -f /usr/local/v6/lib/libinet6.a; then

		SYSLIBS="$SYSLIBS -L/usr/local/v6/lib -linet6"

	fi

	;;

kame-merged)

	CCARGS="$CCARGS -DINET6 -D__ss_family=ss_family -D__ss_len=ss_len"

	;;

linux)

	CCARGS="$CCARGS -DINET6 -D__ss_family=ss_family"

	if test -f /usr/include/libinet6/netinet/ip6.h -a \

		-f /usr/lib/libinet6.a; then 

		CCARGS="$CCARGS -I/usr/include/libinet6 -DUSAGI_LIBINET6"

		SYSLIBS="$SYSLIBS -linet6"

	fi

	;;

esac

.TH TLSMGR 8 

.ad

.fi

.SH NAME

tlsmgr

\-

Postfix TLS session cache and PRNG handling manager

.SH SYNOPSIS

.na

.nf

\fBtlsmgr\fR [generic Postfix daemon options]

.SH DESCRIPTION

.ad

.fi

The tlsmgr process does housekeeping on the session cache database

files. It runs through the databases and removes expired entries

and entries written by older (incompatible) versions.

The tlsmgr is responsible for the PRNG handling. The used internal

OpenSSL PRNG has a pool size of 8192 bits (= 1024 bytes). The pool

is initially seeded at startup from an external source (EGD or

/dev/urandom) and additional seed is obtained later during program

run at a configurable period. The exact time of seed query is

using random information and is equally distributed in the range of

[0-\fBtls_random_reseed_period\fR] with a \fBtls_random_reseed_period\fR

having a default of 1 hour.

Tlsmgr can be run chrooted and with dropped privileges, as it will

connect to the entropy source at startup.

The PRNG is additionally seeded internally by the data found in the

session cache and timevalues.

Tlsmgr reads the old value of the exchange file at startup to keep

entropy already collected during previous runs.

From the PRNG random pool a cryptographically strong 1024 byte random

sequence is written into the PRNG exchange file. The file is updated

periodically with the time changing randomly from

[0-\fBtls_random_prng_update_period\fR].

.SH STANDARDS

.na

.nf

.SH SECURITY

.na

.nf

.ad

.fi

Tlsmgr is not security-sensitive. It only deals with external data

to be fed into the PRNG, the contents is never trusted. The session

cache housekeeping will only remove entries if expired and will never

touch the contents of the cached data.

.SH DIAGNOSTICS

.ad

.fi

Problems and transactions are logged to the syslog daemon.

.SH BUGS

.ad

.fi

There is no automatic means to limit the number of entries in the

session caches and/or the size of the session cache files.

.SH CONFIGURATION PARAMETERS

.na

.nf

.ad

.fi

The following \fBmain.cf\fR parameters are especially relevant to

this program. See the Postfix \fBmain.cf\fR file for syntax details

and for default values. Use the \fBpostfix reload\fR command after

a configuration change.

.SH Session Cache

.ad

.fi

.IP \fBsmtpd_tls_session_cache_database\fR

Name of the SDBM file (type sdbm:) containing the SMTP server session

cache. If the file does not exist, it is created.

.IP \fBsmtpd_tls_session_cache_timeout\fR

Expiry time of SMTP server session cache entries in seconds. Entries

older than this are removed from the session cache. A cleanup-run is

performed periodically every \fBsmtpd_tls_session_cache_timeout\fR

seconds. Default is 3600 (= 1 hour).

.IP \fBsmtp_tls_session_cache_database\fR

Name of the SDBM file (type sdbm:) containing the SMTP client session

cache. If the file does not exist, it is created.

.IP \fBsmtp_tls_session_cache_timeout\fR

Expiry time of SMTP client session cache entries in seconds. Entries

older than this are removed from the session cache. A cleanup-run is

performed periodically every \fBsmtp_tls_session_cache_timeout\fR

seconds. Default is 3600 (= 1 hour).

.SH Pseudo Random Number Generator

.ad

.fi

.IP \fBtls_random_source\fR

Name of the EGD socket or device or regular file to obtain entropy

from. The type of entropy source must be specified by preceding the

name with the appropriate type: egd:/path/to/egd_socket,

dev:/path/to/devicefile, or /path/to/regular/file.

tlsmgr opens \fBtls_random_source\fR and tries to read

\fBtls_random_bytes\fR from it.

.IP \fBtls_random_bytes\fR

Number of bytes to be read from \fBtls_random_source\fR.

Default value is 32 bytes. If using EGD, a maximum of 255 bytes is read.

.IP \fBtls_random_exchange_name\fR

Name of the file written by tlsmgr and read by smtp and smtpd at

startup. The length is 1024 bytes. Default value is

/etc/postfix/prng_exch.

.IP \fBtls_random_reseed_period\fR

Time in seconds until the next reseed from external sources is due.

This is the maximum value. The actual point in time is calculated

with a random factor equally distributed between 0 and this maximum

value. Default is 3600 (= 60 minutes).

.IP \fBtls_random_prng_update_period\fR

Time in seconds until the PRNG exchange file is updated with new

pseude random values. This is the maximum value. The actual point

in time is calculated with a random factor equally distributed

between 0 and this maximum value. Default is 60 (= 1 minute).

.SH SEE ALSO

.na

.nf

smtp(8) SMTP client

smtpd(8) SMTP server

.SH LICENSE

.na

.nf

.ad

.fi

The Secure Mailer license must be distributed with this software.

.SH AUTHOR(S)

.na

.nf

#ifdef INET6

#define INET6_ADDR_LEN	16

#endif

#ifdef INET6

    case T_AAAA:

	if (fixed->length != INET6_ADDR_LEN) {

	    msg_warn("extract_answer: bad IPv6 address length: %d", fixed->length);

	    return (0);

	}

	if (fixed->length > sizeof(temp))

	    msg_panic("dns_get_rr: length %d > DNS_NAME_LEN",

		      fixed->length);

	memcpy(temp, pos, fixed->length);

	data_len = fixed->length;

	break;

#endif

pfixtls.o: pfixtls.c

pfixtls.o: ../../include/sys_defs.h

pfixtls.o: ../../include/iostuff.h

pfixtls.o: ../../include/mymalloc.h

pfixtls.o: ../../include/vstring.h

pfixtls.o: ../../include/vstream.h

pfixtls.o: ../../include/dict.h

pfixtls.o: ../../include/myflock.h

pfixtls.o: ../../include/stringops.h

pfixtls.o: ../../include/msg.h

pfixtls.o: ../../include/connect.h

pfixtls.o: mail_params.h

pfixtls.o: pfixtls.h

char   *var_tls_rand_exch_name;

char   *var_smtpd_tls_cert_file;

char   *var_smtpd_tls_key_file;

char   *var_smtpd_tls_dcert_file;

char   *var_smtpd_tls_dkey_file;

char   *var_smtpd_tls_CAfile;

char   *var_smtpd_tls_CApath;

char   *var_smtpd_tls_cipherlist;

char   *var_smtpd_tls_dh512_param_file;

char   *var_smtpd_tls_dh1024_param_file;

int     var_smtpd_tls_loglevel;

char   *var_smtpd_tls_scache_db;

int     var_smtpd_tls_scache_timeout;

char   *var_smtp_tls_cert_file;

char   *var_smtp_tls_key_file;

char   *var_smtp_tls_dcert_file;

char   *var_smtp_tls_dkey_file;

char   *var_smtp_tls_CAfile;

char   *var_smtp_tls_CApath;

char   *var_smtp_tls_cipherlist;

int     var_smtp_tls_loglevel;

char   *var_smtp_tls_scache_db;

int     var_smtp_tls_scache_timeout;

char   *var_tls_daemon_rand_source;

int     var_tls_daemon_rand_bytes;

	VAR_TLS_RAND_EXCH_NAME, DEF_TLS_RAND_EXCH_NAME, &var_tls_rand_exch_name, 0, 0,

	VAR_SMTPD_TLS_CERT_FILE, DEF_SMTPD_TLS_CERT_FILE, &var_smtpd_tls_cert_file, 0, 0,

	VAR_SMTPD_TLS_KEY_FILE, DEF_SMTPD_TLS_KEY_FILE, &var_smtpd_tls_key_file, 0, 0,

	VAR_SMTPD_TLS_DCERT_FILE, DEF_SMTPD_TLS_DCERT_FILE, &var_smtpd_tls_dcert_file, 0, 0,

	VAR_SMTPD_TLS_DKEY_FILE, DEF_SMTPD_TLS_DKEY_FILE, &var_smtpd_tls_dkey_file, 0, 0,

	VAR_SMTPD_TLS_CA_FILE, DEF_SMTPD_TLS_CA_FILE, &var_smtpd_tls_CAfile, 0, 0,

	VAR_SMTPD_TLS_CA_PATH, DEF_SMTPD_TLS_CA_PATH, &var_smtpd_tls_CApath, 0, 0,

	VAR_SMTPD_TLS_CLIST, DEF_SMTPD_TLS_CLIST, &var_smtpd_tls_cipherlist, 0, 0,

	VAR_SMTPD_TLS_512_FILE, DEF_SMTPD_TLS_512_FILE, &var_smtpd_tls_dh512_param_file, 0, 0,

	VAR_SMTPD_TLS_1024_FILE, DEF_SMTPD_TLS_1024_FILE, &var_smtpd_tls_dh1024_param_file, 0, 0,

	VAR_SMTPD_TLS_SCACHE_DB, DEF_SMTPD_TLS_SCACHE_DB, &var_smtpd_tls_scache_db, 0, 0,

	VAR_SMTP_TLS_CERT_FILE, DEF_SMTP_TLS_CERT_FILE, &var_smtp_tls_cert_file, 0, 0,

	VAR_SMTP_TLS_KEY_FILE, DEF_SMTP_TLS_KEY_FILE, &var_smtp_tls_key_file, 0, 0,

	VAR_SMTP_TLS_DCERT_FILE, DEF_SMTP_TLS_DCERT_FILE, &var_smtp_tls_dcert_file, 0, 0,

	VAR_SMTP_TLS_DKEY_FILE, DEF_SMTP_TLS_DKEY_FILE, &var_smtp_tls_dkey_file, 0, 0,

	VAR_SMTP_TLS_CA_FILE, DEF_SMTP_TLS_CA_FILE, &var_smtp_tls_CAfile, 0, 0,

	VAR_SMTP_TLS_CA_PATH, DEF_SMTP_TLS_CA_PATH, &var_smtp_tls_CApath, 0, 0,

	VAR_SMTP_TLS_CLIST, DEF_SMTP_TLS_CLIST, &var_smtp_tls_cipherlist, 0, 0,

	VAR_SMTP_TLS_SCACHE_DB, DEF_SMTP_TLS_SCACHE_DB, &var_smtp_tls_scache_db, 0, 0,

	VAR_TLS_DAEMON_RAND_SOURCE, DEF_TLS_DAEMON_RAND_SOURCE, &var_tls_daemon_rand_source, 0, 0,

 	VAR_SMTPD_TLS_LOGLEVEL, DEF_SMTPD_TLS_LOGLEVEL, &var_smtpd_tls_loglevel, 0, 0,

 	VAR_SMTP_TLS_LOGLEVEL, DEF_SMTP_TLS_LOGLEVEL, &var_smtp_tls_loglevel, 0, 0,

 	VAR_TLS_DAEMON_RAND_BYTES, DEF_TLS_DAEMON_RAND_BYTES, &var_tls_daemon_rand_bytes, 0, 0,

	VAR_SMTPD_TLS_SCACHTIME, DEF_SMTPD_TLS_SCACHTIME, &var_smtpd_tls_scache_timeout, 0, 0,

	VAR_SMTP_TLS_SCACHTIME, DEF_SMTP_TLS_SCACHTIME, &var_smtp_tls_scache_timeout, 0, 0,

#define VAR_TLS_RAND_EXCH_NAME	"tls_random_exchange_name"

#define DEF_TLS_RAND_EXCH_NAME	"${config_directory}/prng_exch"

extern char *var_tls_rand_exch_name;

#define VAR_TLS_RAND_SOURCE	"tls_random_source"

#define DEF_TLS_RAND_SOURCE	""

extern char *var_tls_rand_source;

#define VAR_TLS_RAND_BYTES	"tls_random_bytes"

#define DEF_TLS_RAND_BYTES	32

extern int var_tls_rand_bytes;

#define VAR_TLS_DAEMON_RAND_SOURCE	"tls_daemon_random_source"

#define DEF_TLS_DAEMON_RAND_SOURCE	""

extern char *var_tls_daemon_rand_source;

#define VAR_TLS_DAEMON_RAND_BYTES	"tls_daemon_random_bytes"

#define DEF_TLS_DAEMON_RAND_BYTES	32

extern int var_tls_daemon_rand_bytes;

#define VAR_TLS_RESEED_PERIOD	"tls_random_reseed_period"

#define DEF_TLS_RESEED_PERIOD	"3600s"

extern int var_tls_reseed_period;

#define VAR_TLS_PRNG_UPD_PERIOD	"tls_random_prng_update_period"

#define DEF_TLS_PRNG_UPD_PERIOD "60s"

extern int var_tls_prng_upd_period;

#define VAR_SMTP_STARTTLS_TMOUT	"smtp_starttls_timeout"

#define DEF_SMTP_STARTTLS_TMOUT	"300s"

extern int var_smtp_starttls_tmout;

#ifdef INET6

#define VAR_SMTP_BIND_ADDR6	"smtp_bind_address6"

#define DEF_SMTP_BIND_ADDR6	""

extern char *var_smtp_bind_addr6;

#endif

#define VAR_SMTPD_STARTTLS_TMOUT "smtpd_starttls_timeout"

#define DEF_SMTPD_STARTTLS_TMOUT "300s"

extern int var_smtpd_starttls_tmout;

#define VAR_SMTPD_TLS_WRAPPER	"smtpd_tls_wrappermode"

#define DEF_SMTPD_TLS_WRAPPER	0

extern bool var_smtpd_tls_wrappermode;

#define VAR_SMTPD_USE_TLS	"smtpd_use_tls"

#define DEF_SMTPD_USE_TLS	0

extern bool var_smtpd_use_tls;

#define VAR_SMTPD_ENFORCE_TLS	"smtpd_enforce_tls"

#define DEF_SMTPD_ENFORCE_TLS	0

extern bool var_smtpd_enforce_tls;

#define VAR_SMTPD_TLS_AUTH_ONLY	"smtpd_tls_auth_only"

#define DEF_SMTPD_TLS_AUTH_ONLY 0

extern bool var_smtpd_tls_auth_only;

#define VAR_SMTPD_TLS_ACERT	"smtpd_tls_ask_ccert"

#define DEF_SMTPD_TLS_ACERT	0

extern bool var_smtpd_tls_ask_ccert;

#define VAR_SMTPD_TLS_RCERT	"smtpd_tls_req_ccert"

#define DEF_SMTPD_TLS_RCERT	0

extern bool var_smtpd_tls_req_ccert;

#define VAR_SMTPD_TLS_CCERT_VD	"smtpd_tls_ccert_verifydepth"

#define DEF_SMTPD_TLS_CCERT_VD	5

extern int var_smtpd_tls_ccert_vd;

#define VAR_SMTPD_TLS_CERT_FILE	"smtpd_tls_cert_file"

#define DEF_SMTPD_TLS_CERT_FILE	""

extern char *var_smtpd_tls_cert_file;

#define VAR_SMTPD_TLS_KEY_FILE	"smtpd_tls_key_file"

#define DEF_SMTPD_TLS_KEY_FILE	"$smtpd_tls_cert_file"

extern char *var_smtpd_tls_key_file;

#define VAR_SMTPD_TLS_DCERT_FILE "smtpd_tls_dcert_file"

#define DEF_SMTPD_TLS_DCERT_FILE ""

extern char *var_smtpd_tls_dcert_file;

#define VAR_SMTPD_TLS_DKEY_FILE	"smtpd_tls_dkey_file"

#define DEF_SMTPD_TLS_DKEY_FILE	"$smtpd_tls_dcert_file"

extern char *var_smtpd_tls_dkey_file;

#define VAR_SMTPD_TLS_CA_FILE	"smtpd_tls_CAfile"

#define DEF_SMTPD_TLS_CA_FILE	""

extern char *var_smtpd_tls_CAfile;

#define VAR_SMTPD_TLS_CA_PATH	"smtpd_tls_CApath"

#define DEF_SMTPD_TLS_CA_PATH	""

extern char *var_smtpd_tls_CApath;

#define VAR_SMTPD_TLS_CLIST	"smtpd_tls_cipherlist"

#define DEF_SMTPD_TLS_CLIST	""

extern char *var_smtpd_tls_cipherlist;

#define VAR_SMTPD_TLS_512_FILE	"smtpd_tls_dh512_param_file"

#define DEF_SMTPD_TLS_512_FILE	""

extern char *var_smtpd_tls_dh512_param_file;

#define VAR_SMTPD_TLS_1024_FILE	"smtpd_tls_dh1024_param_file"

#define DEF_SMTPD_TLS_1024_FILE	""

extern char *var_smtpd_tls_dh1024_param_file;

#define VAR_SMTPD_TLS_LOGLEVEL	"smtpd_tls_loglevel"

#define DEF_SMTPD_TLS_LOGLEVEL	0

extern int var_smtpd_tls_loglevel;

#define VAR_SMTPD_TLS_RECHEAD	"smtpd_tls_received_header"

#define DEF_SMTPD_TLS_RECHEAD	0

extern bool var_smtpd_tls_received_header;

#define VAR_SMTPD_TLS_SCACHE_DB	"smtpd_tls_session_cache_database"

#define DEF_SMTPD_TLS_SCACHE_DB	""

extern char *var_smtpd_tls_scache_db;

#define VAR_SMTPD_TLS_SCACHTIME	"smtpd_tls_session_cache_timeout"

#define DEF_SMTPD_TLS_SCACHTIME	"3600s"

extern int var_smtpd_tls_scache_timeout;

#define VAR_SMTP_TLS_PER_SITE	"smtp_tls_per_site"

#define DEF_SMTP_TLS_PER_SITE	""

extern char *var_smtp_tls_per_site;

#define VAR_SMTP_USE_TLS	"smtp_use_tls"

#define DEF_SMTP_USE_TLS	0

extern bool var_smtp_use_tls;

#define VAR_SMTP_ENFORCE_TLS	"smtp_enforce_tls"

#define DEF_SMTP_ENFORCE_TLS	0

extern bool var_smtp_enforce_tls;

#define VAR_SMTP_TLS_ENFORCE_PN	"smtp_tls_enforce_peername"

#define DEF_SMTP_TLS_ENFORCE_PN	1

extern bool var_smtp_tls_enforce_peername;

#define VAR_SMTP_TLS_SCERT_VD	"smtp_tls_scert_verifydepth"

#define DEF_SMTP_TLS_SCERT_VD	5

extern int var_smtp_tls_scert_vd;

#define VAR_SMTP_TLS_CERT_FILE	"smtp_tls_cert_file"

#define DEF_SMTP_TLS_CERT_FILE	""

extern char *var_smtp_tls_cert_file;

#define VAR_SMTP_TLS_KEY_FILE	"smtp_tls_key_file"

#define DEF_SMTP_TLS_KEY_FILE	"$smtp_tls_cert_file"

extern char *var_smtp_tls_key_file;

#define VAR_SMTP_TLS_DCERT_FILE "smtp_tls_dcert_file"

#define DEF_SMTP_TLS_DCERT_FILE ""

extern char *var_smtp_tls_dcert_file;

#define VAR_SMTP_TLS_DKEY_FILE	"smtp_tls_dkey_file"

#define DEF_SMTP_TLS_DKEY_FILE	"$smtp_tls_dcert_file"

extern char *var_smtp_tls_dkey_file;

#define VAR_SMTP_TLS_CA_FILE	"smtp_tls_CAfile"

#define DEF_SMTP_TLS_CA_FILE	""

extern char *var_smtp_tls_CAfile;

#define VAR_SMTP_TLS_CA_PATH	"smtp_tls_CApath"

#define DEF_SMTP_TLS_CA_PATH	""

extern char *var_smtp_tls_CApath;

#define VAR_SMTP_TLS_CLIST	"smtp_tls_cipherlist"

#define DEF_SMTP_TLS_CLIST	""

extern char *var_smtp_tls_cipherlist;

#define VAR_SMTP_TLS_LOGLEVEL	"smtp_tls_loglevel"

#define DEF_SMTP_TLS_LOGLEVEL	0

extern int var_smtp_tls_loglevel;

#define VAR_SMTP_TLS_NOTEOFFER	"smtp_tls_note_starttls_offer"

#define DEF_SMTP_TLS_NOTEOFFER	0

extern bool var_smtp_tls_note_starttls_offer;

#define VAR_SMTP_TLS_SCACHE_DB	"smtp_tls_session_cache_database"

#define DEF_SMTP_TLS_SCACHE_DB	""

extern char *var_smtp_tls_scache_db;

#define VAR_SMTP_TLS_SCACHTIME	"smtp_tls_session_cache_timeout"

#define DEF_SMTP_TLS_SCACHTIME	"3600s"

extern int var_smtp_tls_scache_timeout;

#define VAR_LMTP_BIND_ADDR	"lmtp_bind_address"

#define DEF_LMTP_BIND_ADDR	""

extern char *var_lmtp_bind_addr;

#ifdef INET6

#define VAR_LMTP_BIND_ADDR6	"lmtp_bind_address6"

#define DEF_LMTP_BIND_ADDR6	""

extern char *var_lmtp_bind_addr6;

#endif

#define VAR_RELAY_CCERTS	"relay_clientcerts"

#define DEF_RELAY_CCERTS	""

extern char *var_relay_ccerts;

#define PERMIT_TLS_CLIENTCERTS	"permit_tls_clientcerts"

#define PERMIT_TLS_ALL_CLIENTCERTS	"permit_tls_all_clientcerts"

#define MAIL_SERVICE_TLSMGR	"tlsmgr"

#ifdef INET6

#include <sys/socket.h>

#include <netinet/in.h>

#include <netdb.h>

#endif

#ifdef INET6

    char hbuf[NI_MAXHOST];

#endif

#ifdef INET6

	struct sockaddr *sa;

#endif

#ifdef INET6

	    sa = (struct sockaddr *)&my_addr_list->addrs[i];

	    if (sa->sa_family != AF_INET) {

		if (sa->sa_family == AF_INET6)

		    vstring_sprintf_append(result, "XAATODOmynetworks ");

		continue;

	    }

	    addr = ntohl(((struct sockaddr_in *)sa)->sin_addr.s_addr);

	    mask = ntohl(((struct sockaddr_in *)&my_mask_list->addrs[i])->sin_addr.s_addr);

#else

#endif

#ifdef INET6

		    if (getnameinfo(sa, SA_LEN(sa), hbuf, sizeof(hbuf), NULL, 0,

			    NI_NUMERICHOST))

			strncpy(hbuf, "???", sizeof(hbuf));

		    msg_fatal("%s: bad address class: %s", myname, hbuf);

#else

#endif

#ifdef INET6

#include <sys/socket.h>

#include <netdb.h>

#endif

	}

#endif

		}

#ifdef INET6

		if (addr_list->addrs[nvirtual].ss_family == 

		    local_addrs.addrs[nlocal].ss_family &&

		    SS_LEN(addr_list->addrs[nvirtual]) == 

		    SS_LEN(local_addrs.addrs[nlocal]) &&

		    memcmp(&addr_list->addrs[nvirtual],

		    &local_addrs.addrs[nlocal],

		    SS_LEN(local_addrs.addrs[nlocal])) == 0) {

		    inet_addr_list_append(mask_list, (struct sockaddr *)&local_masks.addrs[nlocal]);

		    break;

		}

#else

#endif

#ifdef INET6

int     own_inet_addr(struct sockaddr * addr)

{

    int     i;

    char *p, *q;

    int l;

    struct sockaddr *sa;

    if (addr_list.used == 0)

	own_inet_addr_init(&addr_list, &mask_list);

    for (i = 0; i < addr_list.used; i++) {

	sa = (struct sockaddr *)&addr_list.addrs[i];

	if (addr->sa_family != sa->sa_family)

	    continue;

	switch (addr->sa_family) {

	case AF_INET:

	    p = (char *)&((struct sockaddr_in *)addr)->sin_addr;

	    q = (char *)&((struct sockaddr_in *)&addr_list.addrs[i])->sin_addr;

	    l = sizeof(struct in_addr);

	    break;

	case AF_INET6:

	    /* XXX scope */

	    p = (char *)&((struct sockaddr_in6 *)addr)->sin6_addr;

	    q = (char *)&((struct sockaddr_in6 *)&addr_list.addrs[i])->sin6_addr;

	    l = sizeof(struct in6_addr);

	    break;

	default:

	    continue;

	}

	if (memcmp(p, q, l) == 0)

	    return (1);

    }

    return (0);

}

#else

#endif

#ifdef INET6

#include <sys/socket.h>

#endif

#ifdef INET6

extern int own_inet_addr(struct sockaddr *);

#else

#endif

#endif

    SOCKADDR_SIZE len = sizeof(p_un);

#else

	case AF_INET:

	    peer.type = PEER_TYPE_INET;

	    if (getnameinfo(&sun, len, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD) != 0)

		peer.name = "unknown";

	    else

		peer.name = hbuf;

	    peer.addr = abuf;

	    return (&peer);

	case AF_INET6:

	    peer.type = PEER_TYPE_INET6;

	    if (getnameinfo(&sun, len, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD) != 0)

		peer.name = "unknown";

	    else

		peer.name = hbuf;

	    peer.addr = abuf;

	    return (&peer);

#endif

#ifdef INET6

#define PEER_TYPE_INET6		3

#endif

/*++

/* NAME

/*	pfixtls

/* SUMMARY

/*	interface to openssl routines

/* SYNOPSIS

/*	#include <pfixtls.h>

/*

/*	const long scache_db_version;

/*	const long openssl_version;

/*

/*	int pfixtls_serverengine;

/*

/*	int pfixtls_clientengine;

/*

/*	int pfixtls_timed_read(fd, buf, len, timeout, unused_context)

/*	int fd;

/*	void *buf;

/*	unsigned len;

/*	int timeout;

/*	void *context;

/*

/*	int pfixtls_timed_write(fd, buf, len, timeout, unused_context);

/*	int fd;

/*	void *buf;

/*	unsigned len;

/*	int timeout;

/*	void *context;

/*

/*	int pfixtls_init_serverengine(verifydepth, askcert);

/*	int verifydepth;

/*	int askcert;

/*

/*	int pfixtls_start_servertls(stream, timeout, peername, peeraddr,

/*				    tls_info, requirecert);

/*	VSTREAM *stream;

/*	int timeout;

/*	const char *peername;

/*	const char *peeraddr;

/*	tls_info_t *tls_info;

/*	int requirecert;

/*

/*	int pfixtls_stop_servertls(stream, failure, tls_info);

/*	VSTREAM *stream;

/*	int failure;

/*	tls_info_t *tls_info;

/*	

/*	int pfixtls_init_clientengine(verifydepth);

/*	int verifydepth;

/*

/*	int pfixtls_start_clienttls(stream, timeout, peername, peeraddr,

/*				    tls_info);

/*	VSTREAM *stream;

/*	int timeout;

/*	const char *peername;

/*	const char *peeraddr;

/*	tls_info_t *tls_info;

/*

/*	int pfixtls_stop_clienttls(stream, failure, tls_info);

/*	VSTREAM *stream;

/*	int failure;

/*	tls_info_t *tls_info;

/*

/* DESCRIPTION

/*	This module is the interface between Postfix and the OpenSSL library.

/*

/*	pfixtls_timed_read() reads the requested number of bytes calling

/*	SSL_read(). pfixtls_time_read() will only be called indirect

/*	as a VSTREAM_FN function.

/*	pfixtls_timed_write() is the corresponding write function.

/*

/*	pfixtls_init_serverengine() is called once when smtpd is started

/*	in order to initialize as much of the TLS stuff as possible.

/*	The certificate handling is also decided during the setup phase,

/*	so that a peer specific handling is not possible.

/*

/*	pfixtls_init_clientengine() is the corresponding function called

/*	in smtp. Here we take the peer's (server's) certificate in any

/*	case.

/*

/*	pfixtls_start_servertls() activates the TLS feature for the VSTREAM

/*	passed as argument. We expect that all buffers are flushed and the

/*	TLS handshake can begin	immediately. Information about the peer

/*	is stored into the tls_info structure passed as argument.

/*

/*	pfixtls_stop_servertls() sends the "close notify" alert via

/*	SSL_shutdown() to the peer and resets all connection specific

/*	TLS data. As RFC2487 does not specify a seperate shutdown, it

/*	is supposed that the underlying TCP connection is shut down

/*	immediately afterwards, so we don't care about additional data

/*	coming through the channel.

/*	If the failure flag is set, the session is cleared from the cache.

/*

/*	pfixtls_start_clienttls() and pfixtls_stop_clienttls() are the

/*	corresponding functions for smtp.

/*

/*	Once the TLS connection is initiated, information about the TLS

/*	state is available via the tls_info structure:

/*	protocol holds the protocol name (SSLv2, SSLv3, TLSv1),

/*	tls_info->cipher_name the cipher name (e.g. RC4/MD5),

/*	tls_info->cipher_usebits the number of bits actually used (e.g. 40),

/*	tls_info->cipher_algbits the number of bits the algorithm is based on

/*	(e.g. 128).

/*	The last two values may be different when talking to a crippled

/*	- ahem - export controled peer (e.g. 40/128).

/*

/*	The status of the peer certificate verification is available in

/*	pfixtls_peer_verified. It is set to 1, when the certificate could

/*	be verified.

/*	If the peer offered a certifcate, part of the certificate data are

/*	available as:

/*	tls_info->peer_subject X509v3-oneline with the DN of the peer

/*	tls_info->peer_CN extracted CommonName of the peer

/*	tls_info->peer_issuer  X509v3-oneline with the DN of the issuer

/*	tls_info->peer_CN extracted CommonName of the issuer

/*	tls_info->PEER_FINGERPRINT fingerprint of the certificate

/*

/* DESCRIPTION (SESSION CACHING)

/*	In order to achieve high performance when using a lot of connections

/*	with TLS, session caching is implemented. It reduces both the CPU load

/*	(less cryptograpic operations) and the network load (the amount of

/*	certificate data exchanged is reduced).

/*	Since postfix uses a setup of independent processes for receiving

/*	and sending email, the processes must exchange the session information.

/*	Several connections at the same time between the identical peers can

/*	occur, so uniqueness and race conditions have to be taken into

/*	account.

/*	I have checked both Apache-SSL (Ben Laurie), using a seperate "gcache"

/*	process and Apache mod_ssl (Ralf S. Engelshall), using shared memory

/*	between several identical processes spawned from one parent.

/*

/*	Postfix/TLS uses a database approach based on the internal "dict"

/*	interface. Since the session cache information is approximately

/*	1300 bytes binary data, it will not fit into the dbm/ndbm model.

/*	It also needs write access to the database, ruling out most other

/*	interface, leaving Berkeley DB, which however cannot handle concurrent

/*	access by several processes. Hence a modified SDBM (public domain DBM)

/*	with enhanced buffer size is used and concurrent write capability

/*	is used. SDBM is part of Postfix/TLS.

/*

/*	Realization:

/*	Both (client and server) session cache are realized by individual

/*	cache databases. A common database would not make sense, since the

/*	key criteria are different (session ID for server, peername for

/*	client).

/*

/*	Server side:

/*	Session created by OpenSSL have a 32 byte session id, yielding a

/*	64 char file name. I consider these sessions to be unique. If they

/*	are not, the last session will win, overwriting the older one in

/*	the database. Remember: everything that is lost is a temporary

/*	information and not more than a renegotiation will happen.

/*	Originating from the same client host, several sessions can come

/*	in (e.g. from several users sending mail with Netscape at the same

/*	time), so the session id is the correct identifier; the hostname

/*	is of no importance, here.

/*

/*	Client side:

/*	We cannot recall sessions based on their session id, because we would

/*	have to check every session on disk for a matching server name, so

/*	the lookup has to be done based on the FQDN of the peer (receiving

/*	host).

/*	With regard to uniqueness, we might experience several open connections

/*	to the same server at the same time. This is even very likely to

/*	happen, since we might have several mails for the same destination

/*	in the queue, when a queue run is started. So several smtp's might

/*	negotiate sessions at the same time. We can however only save one

/*	session for one host.

/*	Like on the server side, the "last write" wins. The reason is

/*	quite simple. If we don't want to overwrite old sessions, an old

/*	session file will just stay in place until it is expired. In the

/*	meantime we would lose "fresh" session however. So we will keep the

/*	fresh one instead to avoid unnecessary renegotiations.

/*

/*	Session lifetime:

/*	RFC2246 recommends a session lifetime of less than 24 hours. The

/*	default is 300 seconds (5 minutes) for OpenSSL and is also used

/*	this way in e.g. mod_ssl. The typical usage for emails might be

/*	humans typing in emails and sending them, which might take just

/*	a while, so I think 3600 seconds (1 hour) is a good compromise.

/*	If the environment is save (the cached session contains secret

/*	key data), one might even consider using a longer timeout. Anyway,

/*	since everlasting sessions must be avoided, the session timeout

/*	is done based on the creation date of the session and so each

/*	session will timeout eventually.

/*

/*	Connection failures:

/*	RFC2246 requires us to remove sessions if something went wrong.

/*	Since the in-memory session cache of other smtp[d] processes cannot

/*	be controlled by simple means, we completely rely on the disc

/*	based session caching and remove all sessions from memory after

/*	connection closure.

/*

/*	Cache cleanup:

/*	Since old entries have to be removed from the session cache, a

/*	cleanup process is needed that runs through the collected session

/*	files on regular basis. The task is performed by tlsmgr based on

/*	the timestamp created by pfixtls and included in the saved session,

/*	so that tlsmgr has not to care about the SSL_SESSION internal data.

/*

/* BUGS

/*	The memory allocation policy of the OpenSSL library is not well

/*	documented, especially when loading sessions from disc. Hence there

/*	might be memory leaks.

/*