PMDF System Manager's Guide

In order to start using PMDF-TLS in conjunction with PMDF's servers, you must have your private key and public certificate ready and in place; these are normally obtained as described above in Section 15.2.1. Specifically, you must have the following files in the PMDF table directory:

• server-priv.pem (this file must be protected against world access; in addition, on UNIX it must be owned by the pmdf user), and
• server-pub.pem.

PMDF's TLS-related services are either enabled by use of alternate port numbers or by turning on the STARTTLS functionality. The use of alternate port numbers is discussed further in Section 15.2.2.1 below. Configuring whether and when to use or allow the STARTTLS command in the PMDF SMTP server is discussed further in Section 15.2.2.2 below. PMDF's SASL use can also be combined with TLS use, as discussed in Section 15.2.2.3 below.

15.2.2.1 Dispatcher-related Configuration for Alternate Port Numbers

[SERVICE=SMTP] PORT=25 ...

To enable TLS for such a Dispatcher service, you simply add a TLS_PORT option to the configuration for that service. For example, to add TLS support on port 465 for SMTP (the established port for SMTP TLS use), you'd use:

[SERVICE=SMTP] PORT=25 TLS_PORT=465 ...

You can similarly add TLS support for POP3, IMAP, and HTTP by adding similar lines, e.g.,

[SERVICE=POP3] PORT=110 TLS_PORT=995 ... ! [SERVICE=IMAP] PORT=143 TLS_PORT=993 ... ! [SERVICE=HTTP] PORT=7633 TLS_PORT=443 ...

Note that to use TLS for HTTP, the user must specify https:// in their browser when pointing to the PMDF web interface.

If you want to use multiple certificates, or if you want to specify use of a certificate stored in files with names other than the default server-pub.pem and server-priv.pem names, then you can set one or more instances of the TLS_CERTIFICATE Dispatcher option to specify your certificate(s). Up to five TLS_CERTIFICATE lines can be specified; each should specify a pair of files comprising a particular certificate.

Once the Dispatcher configuration modifications are complete, you must restart the Dispatcher (if it is currently running) or start it (if it is not currently running) so that the new Dispatcher configuration with the new port numbers takes effect; see Section 11.4.

15.2.2.2 TCP/IP Channel Configuration for TLS Use

Table 15-1 PMDF-TLS Channel Block keywords

Keyword	Usage
notls	The combination of notlsserver and notlsclient; this is the default
maytls	The combination of maytlsserver and maytlsclient
musttls	The combination of musttlsserver and musttlsclient
notlsserver	Do not offer the STARTTLS extension and do not accept a STARTTLS command from a remote client
maytlsserver	Offer and accept STARTTLS (if not already TLS-enabled)
musttlsserver	Offer and require STARTTLS (if not already TLS-enabled); if TLS has not been negotiated, refuse to accept any mail during this session with a "530" error
notlsclient	Do not attempt to use STARTTLS even if offered by a remote SMTP server
maytlsclient	If STARTTLS is offered by a remote SMTP server, attempt to use TLS
musttlsclient	Use STARTTLS if offered by a remote SMTP server, but if not available, this message delivery will be aborted
tlsswitchchannel channelname	If TLS is used, switch to the channel specified as the channelname parameter to this keyword
nomsexchange	Advertise (and accept) standard TLS commands; this is the default
msexchange	Advertise (and accept) broken TLS commands as used by, for instance, MS Exchange

Enabling (or requiring) the use of TLS can be of interest on dedicated channels intended for communicating sensitive information with companion systems that also support TLS.

Enabling the use of TLS for the SMTP server can also be of particular interest when SMTP SASL use has been enabled. Since with SMTP SASL use, a remote client will be sending a password over the network, then, especially if the PLAIN authentication mechanism is used (password sent "in the clear"), it can be particularly desirable to use TLS so that the entire transaction, including the password, is encrypted.

Use of the tlsswitchchannel keyword can be of interest for logging purposes, so that PMDF log entries show the message as coming in via a special channel. Use of the tlsswitchchannel keyword can also be of interest if it is desired to route messages submitted using TLS differently (using source channel specific rewrite rules) than messages submitted without TLS.

15.2.2.3 TLS Use and SASL

15.2.2.4 Sample TLS Configuration

1. The Dispatcher will be configured to automatically use TLS when connections come in on alternate, established ports for TLS use for SMTP, POP, and IMAP connections.
2. Incoming SMTP, POP, and IMAP connections will be categorized according as to whether the connection is coming from an "internal" source or an "external" source, where "internal" sources are assumed to be those in the 1.2.3.0 subnet.
3. POP and IMAP client connections from "external" sources will not be allowed to authenticate using the PLAIN or LOGIN mechanisms (which both involve sending the password "in the clear" over the network) unless at least 40 bits of TLS encryption are used by the client. That is, POP and IMAP clients connecting from "external" sources must either authenticate using the SASL CRAM-MD5 mechanism (or APOP in the case of POP), which involves encryption in the actual authentication mechanism, or must use (at least 40 bits of) TLS encryption for the overall transaction in order to use the PLAIN or LOGIN mechanisms for authentication.
4. TLS and SASL will be offered to incoming SMTP connections for clients that want to negotiate their use. "External" clients can not submit SMTP messages for relaying unless they use SASL to authenticate themselves. Further, when performing SASL authentication from "external" clients, PLAIN or LOGIN authentication (either of which involve sending the password "in the clear" over the network) will not be allowed unless at least 40 bits worth of TLS encryption are in use. That is, permitted SMTP message traffic will include:
   • Any messages submitted from "internal" clients.
   • Any messages submitted from "external" clients destined for "internal" recipients.
   • Any messages submitted from "external" clients that use SASL to authenticate themselves and TLS to encrypt that authentication (as well as the data transfer); this includes cases where the SASL authentication itself is performed using what is normally an "in the clear" mechanism such as PLAIN or LOGIN since TLS is being used to encrypt the overall message transaction.
   • Any messages submitted from "external" clients that use SASL to authenticate themselves using the CRAM-MD5 SASL mechanism.

In order to automatically allow TLS use when connecting to a TLS established alternate port, item (1) above, the Dispatcher configuration file includes TLS_PORT option settings as shown in Example 15-1 (OpenVMS) or Example 15-2 (UNIX) or Example 15-3 (Windows). Note that the samples shown are merely excerpts; a typical site is likely to have (and want) several additional services defined and several additonal options set within the individual service definitions.

Example 15-1 Excerpt of a Sample dispatcher.cnf File for TLS Ports on OpenVMS

! ! Global defaults ! MIN_PROCS=1 MAX_PROCS=5 MIN_CONNS=3 MAX_CONNS=10 MAX_SHUTDOWN=2 MAX_LIFE_TIME=86400 MAX_LIFE_CONNS=300 MAX_IDLE_TIME=600 ! ! multithreaded SMTP server ! [SERVICE=SMTP] PORT=25 TLS_PORT=465 IMAGE=PMDF_EXE:TCP_SMTP_SERVER.EXE LOGFILE=PMDF_LOG:TCP_SMTP_SERVER.LOG ! ! POP3 server ! [SERVICE=POP3] PORT=110 TLS_PORT=995 IMAGE=PMDF_EXE:POP3D.EXE LOGFILE=PMDF_LOG:POP3D.LOG ! ! IMAP server ! [SERVICE=IMAP] PORT=143 TLS_PORT=993 IMAGE=PMDF_EXE:IMAPD.EXE LOGFILE=PMDF_LOG:IMAPD.LOG

Example 15-2 Excerpt of a Sample dispatcher.cnf File for TLS Ports on UNIX

! ! Global defaults ! MIN_PROCS=1 MAX_PROCS=5 MIN_CONNS=3 MAX_CONNS=10 MAX_SHUTDOWN=2 MAX_LIFE_TIME=86400 MAX_LIFE_CONNS=300 MAX_IDLE_TIME=600 ! ! multithreaded SMTP server ! [SERVICE=SMTP] PORT=25 TLS_PORT=465 IMAGE=/pmdf/bin/tcp_smtp_server LOGFILE=/pmdf/log/tcp_smtp_server.log ! ! POP3 server ! [SERVICE=POP3] PORT=110 TLS_PORT=995 IMAGE=/pmdf/bin/pop3d LOGFILE=/pmdf/log/pop3d.log ! ! IMAP server ! [SERVICE=IMAP] PORT=143 TLS_PORT=993 IMAGE=/pmdf/bin/imapd LOGFILE=/pmdf/log/imapd.log

Example 15-3 Excerpt of a Sample dispatcher.cnf File for TLS Ports on NT

! ! Global defaults ! MIN_PROCS=1 MAX_PROCS=5 MIN_CONNS=3 MAX_CONNS=10 MAX_SHUTDOWN=2 MAX_LIFE_TIME=86400 MAX_LIFE_CONNS=300 MAX_IDLE_TIME=600 ! ! multithreaded SMTP server ! [SERVICE=SMTP] PORT=25 TLS_PORT=465 IMAGE=C:\pmdf\bin\tcp_smtp_server LOGFILE=C:\pmdf\log\tcp_smtp_server.log ! ! POP3 server ! [SERVICE=POP3] PORT=110 TLS_PORT=995 IMAGE=C:\pmdf\bin\pop3d LOGFILE=C:\pmdf\log\pop3d.log ! ! IMAP server ! [SERVICE=IMAP] PORT=143 TLS_PORT=993 IMAGE=C:\pmdf\bin\imapd LOGFILE=C:\pmdf\log\imapd.log

In order to categorize incoming SMTP, POP, and IMAP connections into those from "internal" sources (assumed to be any in the 1.2.3.0 subnet) and those from "external" sources, a PORT_ACCESS mapping table is used as shown in Example 15-4; see Section 11.5 for general background on the PORT_ACCESS mapping table and Section 14.3 for more details on categorizing incoming connections in particular.

Example 15-4 Sample PORT_ACCESS Mapping Categorizing Incoming Connections

PORT_ACCESS ! Connections from the 1.2.3.0 subnet will be considered internal ! TCP|*|*|$(1.2.3.0/24)|* $YINTERNAL ! ! Block all access to the PMDF HTTP server from external sources ! TCP|7633|*|* $N ! ! All other connections will be considered external ! TCP|*|*|*|* $YEXTERNAL

In order to enforce that connections from "external" sources that perform authentication must either use an encrypted mechanism (e.g., CRAM-MD5) for that authentication, or if using one of the PLAIN or LOGIN mechanisms must be securing the entire transaction using TLS with at least 40 bits of encryption, item (3) and part of item (4) above, a PMDF security configuration file as in Example 15-5 is used. Note that this security configuration file uses different security rulesets for "internal" and "external" connections, as selected by the PORT_ACCESS mapping shown in Example 15-4 above.

Example 15-5 Sample security.cnf File for Enforcing TLS Use with PLAIN and LOGIN Mechanisms for External Connections

[RULESET=DEFAULT] ENABLE=MSGSTORE/*,PASSDB/*,SYSTEM/* ! [RULESET=INTERNAL] ENABLE=MSGSTORE/*,PASSDB/*,SYSTEM/*,LOGIN/LOGIN ! [RULESET=EXTERNAL] ENABLE=MSGSTORE/*,PASSDB/*,SYSTEM/*,LOGIN/LOGIN RESTRICT=PLAIN:40,LOGIN:40

In order to restrict SMTP relaying from "external" sources unless they authenticate themselves using SASL, a TCP/IP channel configuration similar to that shown in Section 14.4 will be used. However, the configuration will be further tuned to allow TLS use for incoming connections. The TLS use is expected to be particularly relevant for connections from "external" sources since, due to the PORT_ACCESS mapping and PMDF security configuration file described above, "external" clients that want to SASL authenticate themselves using either of the PLAIN or LOGIN mechanisms can only do so if they also use TLS. Appropriate rewrite rules in the PMDF configuration file could be along the lines of:

.domain.com $U%$H$D@TCP-INTERNAL [1.2.3.] $U%[1.2.3.$L]@TCP-INTERNAL$E$R

with channel definitions along the lines of

tcp_local smtp mx single_sys maytls \ maysaslserver saslswitchchannel tcp_auth switchchannel TCP-DAEMON tcp_internal smtp mx single_sys maytls \ maysaslserver allowswitchchannel routelocal TCP-INTERNAL tcp_auth smtp mx single_sys maytlsserver \ mustsaslserver noswitchchannel TCP-AUTH

and with an ORIG_SEND_ACCESS mapping table along the lines of:

ORIG_SEND_ACCESS tcp_local|*|tcp_local|* $NSMTP$ relaying$ not$ permitted