PMDF System Manager's Guide

Sender Policy Framework (SPF) can be used to combat the problem of sender address forgery. It is a method of using special DNS records to say which systems are allowed to send mail for a given domain. PMDF's SPF implemention can be used to check the IP address of the system that PMDF is receiving a message from, against the domain name in the SMTP MAIL FROM: address to make sure the message is coming from an authorized sending system. The message can be accepted, rejected, or marked based on the results of the SPF checks.

Sender Rewriting Scheme (SRS) is an adjunct to SPF that is used by mail forwarders. SPF breaks mail forwarding because it rejects the forwarder as an unauthorized sender of the mail. If the forwarder uses SRS to rewrite the MAIL FROM: address, this problem is avoided.

For more information about SPF and SRS, see http://www.openspf.org/.

Using SPF/SRS is similar to DNS_VERIFY in that both are used to combat the problem of forged sender e-mail addresses. The same drawbacks and warnings apply (see Section 16.1.8).

As with DNS_VERIFY, SPF and SRS are supplied as a sharable images on OpenVMS (PMDF_EXE:LIBSPFSHR.EXE and PMDF_EXE:LIBSRS2SHR.EXE), and as sharable object libraries on Unix (/pmdf/lib/libspf.so and /pmdf/lib/libsrs2.so).

SPF can be called from the FROM_ACCESS, ORIG_MAIL_ACCESS, or MAIL_ACCESS mapping table. However, we recommend using the FROM_ACCESS mapping table for greatest efficiency since it is called only once, after the MAIL FROM: SMTP command instead of after every RCPT TO: SMTP command.

SRS is called from the REVERSE mapping table to encode the MAIL FROM: address when mail is forwarded. A different SRS routine is called from the FORWARD mapping table to decode RCPT TO: addresses when needed, as for example when an error response is sent back to an MAIL FROM: address that has been SRS-encoded. SPF and SRS are invoked using the routine callout described in Section 2.2.6.7, Customer-supplied Routine Substitutions, $[...].

Note that internal or trusted systems (such as mail gateways) should be excluded from SPF checks and SRS encoding by adding mapping table entries before the SPF or SRS entries in the mapping tables.

On Unix platforms, the symbols PMDF_SPF_LIBRARY and PMDF_SRS_LIBRARY are defined in /etc/pmdf_tailor to point to the SPF and SRS sharable object libraries, respectively. Similarly, on OpenVMS, the logical names PMDF_SPF_LIBRARY and PMDF_SRS_LIBRARY are defined in PMDF_STARTUP.COM to point to the sharable images. We also recommend that you install the SPF and SRS sharable images for efficiency. The following commands to do this may be put in your PMDF_COM:PMDF_SITE_STARTUP.COM file:

$ INSTALL ADD PMDF_SPF_LIBRARY/OPEN/HEAD/SHARE $ INSTALL ADD PMDF_SRS_LIBRARY/OPEN/HEAD/SHARE

16.1.9.1 Configuring SPF

LIBSPFSHR has three routines that can be called:

• spf_lookup
• spf_lookup_reject_fail
• spf_lookup_reject_softfail

These are each described in the sections below.

Note that your mapping tables with SPF callouts can be tested by using the pmdf test -mapping utility (pmdf test/mapping on OpenVMS).

16.1.9.1.1 spf_lookup Routine

This routine does the SPF lookup and adds a Received-SPF: header upon successful completion, or a header of your choice upon error (such as if there are no SPF records).

The spf_lookup routine has four arguments, separated by commas. The callout would look like this:

$[PMDF_SPF_LIBRARY,spf_lookup,sending-ip,from-address,domain-name,header]$

The parameters are as follows:

• sending-ip is the sending IP address
• from-address is the MAIL FROM: address
• domain-name is the domain name to display in the Received-SPF: headers; this is expected to be the name of the local system that is doing the SPF lookup
• header is the type of header to add upon error

The following example adds a Received-SPF: header, or in the case where there is no SPF record, a X-PMDF-SPF: header:

FROM_ACCESS TCP|*|25|*|*|SMTP*|*|tcp_*|*|* $C$[PMDF_SPF_LIBRARY,\ spf_lookup,$1,$6,example.com,X-PMDF-SPF]$E

Example Received-SPF: and X-PMDF-SPF: headers would be:

Received-SPF: pass (example.com: domain of remotesys.com designates 10.0.0.1 as permitted sender) client-ip=192.168.0.1; envelope-from=joe@remotesys.com; X-PMDF-SPF: (recv=mail.example.com, send-ip=10.0.0.2) Could not find a valid SPF record

16.1.9.1.2 spf_lookup_reject_fail and spf_lookup_reject_softfail Routines

Both of these routines do the SPF lookup and then reject the message if it gets a fail result. The spf_lookup_reject_softfail also rejects the message if it gets a softfail result. They both add a Received-SPF: header upon successful completion.

These routines have four arguments, separated by commas. The callouts would look like this (for example on Unix):

$[/pmdf/lib/libspf.so,spf_lookup_reject_fail,sending-ip,from-address,domain-name,header]$ $[/pmdf/lib/libspf.so,spf_lookup_reject_softfail,sending-ip,from-address,domain-name,text]$

The parameters are as follows:

• sending-ip is the sending IP address
• from-address is the MAIL FROM: address
• domain-name is the domain name to display in the Received-SPF: headers; this is expected to be the name of the local system that is doing the SPF lookup
• text is the rejection text to use

The following example rejects mail that fails the SPF lookup:

FROM_ACCESS TCP|*|25|*|*|SMTP*|*|tcp_*|*|* $C$[/pmdf/lib/libspf.so,\ spf_lookup_reject_softfail,$1,$6,example.com,Rejected$ by$ SPF$ lookup]$E

16.1.9.2 Configuring SRS

To configure PMDF to use SRS, changes are required to the PMDF option file pmdf_table:option.dat, configuration file pmdf_table:pmdf.cnf, and mapping file pmdf_table:mappings.

16.1.9.2.1 Option File Changes

Two options need to be added to the PMDF option file: REVERSE_ENVELOPE, and USE_REVERSE_DATABASE.

The REVERSE_ENVELOPE option needs to be set to 1 to tell PMDF to apply the REVERSE mapping table to envelope from addresses (by default the REVERSE mapping table is only applied to header addresses). The USE_REVERSE_DATABASE option should be set to a value of 266. This value turns on address reversal processing (the REVERSE mapping table in this case), as well as specifying that the destination channel be prepended to the address when probing the REVERSE mapping table.

REVERSE_ENVELOPE=1 USE_REVERSE_DATABASE=266

16.1.9.2.2 Configuration File Changes

By default, the REVERSE mapping table is checked for every destination channel. For SRS, normally you'd only want to encode the envelope from address for messages that are being forwarded to the internet, for example, being sent out the tcp_local channel.

To avoid unnecessary processing, the checking of the REVERSE mapping table can be restricted to when tcp_local is the destination channel. This is done by using the noreverse and reverse channel keywords in the pmdf.cnf file.

Place the noreverse channel keyword on the defaults line in pmdf.cnf to turn off checking of the REVERSE mapping table by default. To turn the checking on for the tcp_local channel, add the reverse channel keyword to the tcp_local channel definition. If there are any other channels you use that you wish to use SRS on, put the reverse channel keyword on those channel definitions as well.

16.1.9.2.3 Mapping File Changes

The SRS library has two routines that can be called:

• pmdf_srs_forward
• pmdf_srs_reverse

The pmdf_srs_forward routine is called from the REVERSE mapping table to encode the envelope from address. The pmdf_srs_reverse routine is called from the FORWARD mapping table to decode any SRS-encoded envelope to addresses. These routines are further described in the sections below.

Note that your mapping tables with SRS callouts can be tested by using the pmdf test -mapping utility (pmdf test/mapping on OpenVMS).

16.1.9.2.3.1 pmdf_srs_forward Routine And The REVERSE Mapping Table

The pmdf_srs_forward routine takes an address and encodes it as defined by the SRS rules. It returns the SRS-encoded address.

This routine has three arguments, separated by commas. The callout would look like this:

$[PMDF_SRS_LIBRARY,pmdf_srs_forward,from-address,secret,domain-name]$

The parameters are as follows:

1. from-address is the MAIL FROM: address to encode.
2. secret is a secret word you must specify for use by the encoding process.
3. domain-name is the local domain to use.

When adding the pmdf_srs_foward callout to the REVERSE mapping table, you must specify the $:E flag on the entry. The option.dat option REVERSE_ENVELOPE (as described above) causes PMDF to apply the REVERSE mapping table to the envelope from address as well as to header addresses. However, SRS should be applied only to the envelope address and not to header addresses. Specifying the $:E flag on your REVERSE mapping table entry achieves this.

For best efficiency, SRS should only be applied to messages going out via the tcp_local channel (or other external channel). The option.dat option USE_REVERSE_DATABASE (as described above) specified with a value of 266 causes PMDF to prepend the destination channel to the address when the REVERSE mapping table is probed. To apply the mapping table entry to only tcp_local, specify "tcp_local|" at the front of your reverse mapping table entries.

Also, SRS should only be applied to messages that are being forwarded, and not to locally-generated messages. To do this, add additional entries to the REVERSE mapping table that exempts messages that have a local envelope from address.

The following example encodes mail being forwarded by example.com:

REVERSE tcp_local|*@*example.com $N tcp_local|*@* $:E$[PMDF_SRS_LIBRARY,\ pmdf_srs_forward,$0@$1,mysecret,example.com]$E

16.1.9.2.3.2 pmdf_srs_reverse Routine And The FORWARD Mapping Table

The pmdf_srs_reverse routine takes an SRS-encoded address and decodes it back into the original address.

This routine has three arguments, separated by commas. The callout would look like this:

$[PMDF_SRS_LIBRARY,pmdf_srs_reverse,to-address,secret,domain-name]$

The parameters are as follows:

1. to-address the SRS-encoded RCPT TO: address to decode.
2. secret is the secret word that was used during the encoding process.
3. domain-name is the local domain that was used during the encoding process.

Adding a callout to the pmdf_srs_reverse routine from the FORWARD mapping table is required to decode any SRS-encoded envelope to addresses. For example, to handle responses to mail that you sent with an SRS-encoded envelope from address. Note that when you add the callout, you must also specify the $D flag on the entry, to tell PMDF to send the resulting address back through the rewrite process. This is so the mail can be forwarded on successfully to the real original sender.

Since SRS decoding should only be applied to SRS-encoded addresses, you can select for this by checking for addresses that have two equal signs in the username part.

The following example decodes SRS-encoded addresses received by example.com:

FORWARD *=*=*@example.com $[PMDF_SRS_LIBRARY,\ pmdf_srs_reverse,$0=$1=$2@example.com,mysecret,example.com]$D

16.1.9.2.4 The Secret Word

The secret word specified in the mapping table callouts is used by the SRS encoding and decoding to make sure that the SRS-encoded address is not forged. You do not have to change your secret word at all, but if you wish to do so, the decoding routine needs to know all of the secret words ever used so that it can properly decode messages that were encoded using a previous secret word.

The SRS decoding routine will check for the file pmdf_table:srs_secret.dat for a list of previous secret words. Whenever you change your secret word, add the old secret word to this file (one word per line).