PMDF System Manager's Guide
Previous Contents Index

15.2.2 Enabling TLS Functionality in PMDF

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:

The server-pub.pem file should preferentially be a signed certificate returned by a well-recognized Certificate Authority in response to your certificate request, as described in Section 15.2.1.2 above. However, while you are awaiting signing of your certificate by a Certificate Authority you can want to use the self-signed certificate also generated by the tls_certreq utility by renaming that server-selfsign.pem file to 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.

Note
As soon as the PMDF-TLS component is installed, and the PMDF-TLS license is enabled, PMDF assumes that you want to use TLS. TLS is automatically initialized. This means, for example, that the STARTTLS functionality is automatically turned on for IMAP and POP server use on the standard port numbers.

15.2.2.1 Dispatcher-related Configuration for Alternate Port Numbers

If you have not already configured the Dispatcher, you must do so; see the appropriate edition of the PMDF Installation Guide. Once the Dispatcher is configured, you will have services defined in sections that look something like: 


[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

PMDF supports a number of keywords on the TCP/IP channels to control whether TLS functionality is desired or required. The functions of these keywords are summarized in Table 15-1; see also Section 2.3.4.45 and Section 2.3.4.46.

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

There is some added support for TLS in SASL. Using SASL, you can restrict which password methods are available based on the strength (or existence) of the encryption being used. This is controlled via the RESTRICT option in the PMDF security configuration file; see Section 14.2.2 for details. See also Example 15-6 below for an example of use of this option.

15.2.2.4 Sample TLS Configuration

A sample configuration of enabling TLS use in PMDF will be presented for a sample PMDF-TLS site domain.com. The significant features of this sample configuration are as follows.
  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:

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-2 (OpenVMS) or Example 15-3 (UNIX) or Example 15-4 (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-2 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-3 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-4 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-5; 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-5 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-6 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-5 above.

Example 15-6 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

Previous Next Contents Index