Table of Contents Previous Next Index

Section 13 Using DomainKeys with LISTSERV

Section 13 Using DomainKeys with LISTSERV
In order for DomainKeys support to work with LISTSERV, the following requirements must be met:
DomainKeys support has already been configured in DNS for the domains you will be signing for, per the DomainKeys documentation. For your convenience, we have excerpted the relevant section from the Internet Draft for DomainKeys below.
DomainKeys support is available for LISTSERV Classic and HPO, on all operating systems except for VM. It is not available in LISTSERV Lite.
Note: Generally, L-Soft Support cannot assist you in setting up your DomainKeys DNS records. However, the relevant sections of the Internet Draft for DomainKeys are reproduced below for your convenience.
13.1 Creating DomainKeys RSA keys and Configuring DNS
The following is an excerpt from the controlling Internet Draft for DomainKeys (now preserved as RFC 4870).
 
3.2.2 Public-key signing and verification algorithm
 
The default signature is an RSA signed SHA1 digest of the complete email.
For ease of explanation, the openssl command is used throughout this document to describe the mechanism by which keys and signatures are managed.
One way to generate a 768 bit private-key suitable for DomainKeys, is to use openssl like this:
$ openssl genrsa -out rsa.private 768
Which results in the file rsa.private containing the key information similar to this:
-----BEGIN RSA PRIVATE KEY-----
MIIByQIBAAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6lMIgulclWjZwP56LRqdg5
ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7EXzVc+nRLWT1kwTvFNGIo
AUsFUq+J6+OprwIDAQABAmBOX0UaLdWWusYzNol++nNZ0RLAtr1/LKMX3tk1MkLH
+Ug13EzB2RZjjDOWlUOY98yxW9/hX05Uc9V5MPo+q2Lzg8wBtyRLqlORd7pfxYCn
Kapi2RPMcR1CxEJdXOkLCFECMQDTO0fzuShRvL8q0m5sitIHlLA/L+0+r9KaSRM/
3WQrmUpV+fAC3C31XGjhHv2EuAkCMQDE5U2nP2ZWVlSbxOKBqX724amoL7rrkUew
ti9TEjfaBndGKF2yYF7/+g53ZowRkfcCME/xOJr58VN17pejSl1T8Icj88wGNHCs
FDWGAH4EKNwDSMnfLMG4WMBqd9rzYpkvGQIwLhAHDq2CX4hq2tZAt1zT2yYH7tTb
weiHAQxeHe0RK+x/UuZ2pRhuoSv63mwbMLEZAjAP2vy6Yn+f9SKw2mKuj1zLjEhG
6ppw+nKD50ncnPoP322UMxVNG4Eah0GYJ4DLP0U=
-----END RSA PRIVATE KEY-----
 
(...)
 
To extract the public-key component from the private-key, use openssl like this:
$ openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM
Which results in the file rsa.public containing the key information similar to this:
-----BEGIN PUBLIC KEY-----
MHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6l
MIgulclWjZwP56LRqdg5ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7E
XzVc+nRLWT1kwTvFNGIoAUsFUq+J6+OprwIDAQAB
-----END PUBLIC KEY-----
 
This public-key data is placed in the DNS.
 
(...)
 
3.2.3 Public-key representation in the DNS
 
There is currently no standard method defined for storing public-keys in the DNS. As an interim measure, the public-key is stored as a TXT record derived from a PEM format [PEM], that is, as a Base64 representation of a DER encoded key. Here is an example of a 768 bit RSA key in PEM form:
-----BEGIN PUBLIC KEY-----
MHwwDQYJKoZIhvcNAQEBBQADawAwaAJhAKJ2lzDLZ8XlVambQfMXn3LRGKOD5o6l
MIgulclWjZwP56LRqdg5ZX15bhc/GsvW8xW/R5Sh1NnkJNyL/cqY1a+GzzL47t7E
XzVc+nRLWT1kwTvFNGIoAUsFUq+J6+OprwIDAQAB
-----END PUBLIC KEY-----
 
To save scarce DNS packet space and aid extensibility, the PEM
wrapping MUST be removed and the remaining public-key data along with other attributes relevant to DomainKeys functionality are stored as tag=value pairs separated by semicolons, e.g.:
brisbane._domainkey IN TXT "g=; k=rsa; p=MHww ... IDAQAB"
Verifiers MUST support key sizes of 512, 768, 1024, 1536 and 2048
bits. Signers MUST support at least one of the verifier supported key
sizes.
The current valid tags are:
g = granularity of the key. If present with a non-zero length
value, this value MUST exactly match the local part of the
sending address. This tag is optional.
The intent of this tag is to constrain which sending address
can legitimately use this selector. An email with a sending
address that does not match the value of this tag constitutes
a failed verification.
 
k = key type (rsa is the default). Signers and verifiers MUST
support the 'rsa' key type. This tag is optional.
 
n = Notes that may be of interest to a human. No interpretation is
made by any program. This tag is optional.
 
p = public-key data, encoded as a Base64 string. An empty value
means that this public-key has been revoked. This tag MUST be
present.
 
t = a set of flags that define boolean attributes. Valid
attributes are:
 
y = testing mode. This domain is testing DomainKeys and
unverified email MUST NOT be treated differently from
verified email. Recipient systems MAY wish to track
testing mode results to assist the sender.)
This tag is optional.
 
In general, DomainKeys also requires a policy record. Again, from RFC 4870 :
 
3.6. Policy Statement of Sending Domain
 
While the disposition of inbound email is ultimately a matter for the receiving system, the introduction of authentication in email creates a need for the sender domain to indicate their signing policy and preferred disposition of unsigned email, in particular, whether a domain is participating in DomainKeys, whether it is testing, and whether it signs all outbound email.
The sending domain policy is very simple and is expressed in the _domainkey TXT record in the DNS of the sending domain. For example, in the example.com domain, the record is called _domainkey.example.com.
The contents of this TXT record are stored as tag=value pairs separated by semicolons, for example, as in the following:
_domainkey IN TXT "t=y; o=-; n=notes; r=emailAddress"
All tags are optional. The current valid tags are as follows:
n = Notes that may be of interest to a human. No interpretation
is made by any program.
 
o = Outbound Signing policy ("-" means that this domain signs all
email; "~" is the default and means that this domain may sign
some email with DomainKeys).
 
r = A reporting email address. If present, this defines the email
address where invalid verification results are reported. This
tag is primarily intended for early implementers -- the
content and frequency of the reports will be defined in a
separate document.
 
t = a set of flags that define boolean attributes. Valid
attributes are as follows:
 
y = testing mode. This domain is testing DomainKeys, and
unverified email MUST NOT be treated differently from
verified email. Recipient systems MAY wish to track
testing mode results to assist the sender).
 
Note that testing mode cannot be turned off by this tag;
thus, policy cannot revert the testing mode setting of a
Selector.
This tag is optional.
 
(Syntax rules for the tag=value format are discussed in Appendix A.)
 
Recipient systems SHOULD only retrieve this policy TXT record to determine policy when an email fails to verify or does not include a signature. Recipient systems SHOULD not retrieve this policy TXT record for email that successfully verifies. Note that "testing mode" SHOULD also be in the Selector TXT record if the domain owner is running a DomainKeys test.
If the policy TXT record does not exist, recipient systems MUST assume the default values.
There is an important implication when a domain states that it signs all email with the "o=-" setting, namely that the sending domain prefers that the recipient system treat unsigned mail with a great deal of suspicion. Such suspicion could reasonably extend to rejecting such email. A verifying system MAY reject unverified email if a domain policy indicates that it signs all email.
Of course, nothing compels a recipient MTA to abide by the policy of the sender. In fact, during the trial, a sending domain would want to be very certain about setting this policy, as processing by recipient MTAs may be unpredictable. Nonetheless, a domain that states that it signs all email MUST expect that unverified email may be rejected by some receiving MTAs.
13.2 Testing your DomainKeys DNS Records
Once you have created your selector and policy records, you can test them at the following URLs:
Important: Please be aware that these sites are not controlled by or supported by L-Soft.
13.3 LISTSERV Configuration
LISTSERV's DomainKeys support is configured by doing two things.
1.
Each private key is stored as a text file in LISTSERV's main or home directory (that is, the directory where the *.list files are) and must be named xxx.dkim, where xxx is the arbitrary name you choose to give the key. If you only use one key, it is recommended to name it default.dkim.
The file is created in the usual openssl/RSA format, with one minor modification. Here is an example:
d=example.com; s=test
 
-----BEGIN RSA PRIVATE KEY----- MIIBywIBAAJhAM5MtvnHlLhPzQjitdBctkJTRbJ/YkbGzcxHP701mHrlMdVeTI3M
(...)
QJEE65afJ4PS8yqM10hZ0p2euKrVZGgUDDdLzgPo2w==
-----END RSA PRIVATE KEY-----
The first line in the file must include a specification for the 'd=' and 's=' parameters of the DomainKeys signature (in whatever order, as long as they are both there). Per RFC 4870, these variables specify the domain for which you are signing ("d=") and the "selector" that is used to form the query for the public key ("s="). For instance, let’s say that your public key is registered as follows in the DNS:
brisbane._domainkey.example.com IN TXT "t=y; g=; k=rsa; p=MHww ... IDAQAB"
The domain would then be d=example.com, and the selector would be s=brisbane.
Please see the DomainKeys documentation for more information.
Note: We strongly recommend the use of the "t=y" test flag when you are first trying out DomainKeys. Otherwise a simple mistake in your DomainKeys configuration could cause verification failure for mail coming from your domain, and other sites that have implemented DomainKeys will reject your mail. Always test first!
2.
In your site configuration file, add a DKIM_SIGN= variable containing a blank-separated list of domains that you are able and willing to sign for. You can use wildcards, but only of the form '*.EXAMPLE.COM'. You can't use, for instance, 'SALES.EXAMPLE.*'. For each entry in the list, specify the key to be used, as follows:
DKIM_SIGN=EXAMPLE.COM *.EXAMPLE.COM EXAMPLE.CA(CA) *.EXAMPLE.CA(CA)
(Under unix, don't forget to export DKIM_SIGN.)
By default, the key called DEFAULT is used (if one exists). So in the sample above, the key for EXAMPLE.COM will be fetched from DEFAULT.DKIM whereas the key for EXAMPLE.CA will come out of CA.DKIM.
13.4 Starting LISTSERV with DomainKeys support
LISTSERV loads the keys at startup and makes simple verifications.
8 Dec 2005 12:07:42 Loading DomainKeys private keys...
8 Dec 2005 12:07:42 -> Loaded DEFAULT (d=EXAMPLE.COM; s=TEST; RSA-768)
8 Dec 2005 12:07:42 -> Loaded CA (d=EXAMPLE.CA; s=TEST; RSA-768)
8 Dec 2005 12:07:42 DomainKeys support enabled
In particular, the 'd=' parameter in the key must match or be a parent of the domain you want to sign for. Thus the key for EXAMPLE.COM can be used to sign for EXAMPLE.COM and *.EXAMPLE.COM, but not for EXAMPLE.CA. LISTSERV will skip any invalid entries. Keys are kept in memory, so you can have as many .dkim files as you want.
If there is no DKIM_SIGN variable or if you are running a LISTSERV version without DomainKeys support, LISTSERV does not attempt to load any keys and the DomainKeys feature is bypassed.
13.5 Using DomainKeys with LISTSERV
13.5.1 With Mailing Lists
If DomainKeys support has been enabled in the configuration, LISTSERV will sign all outbound messages for mailing lists, including administrative messages, welcome messages, etc.
"Misc-Options= NO_DKIM_SIGNATURE" can be added in the list header (or made the system default via the DEFAULT_MISC_OPTIONS configuration variable) to override this.
Incoming DomainKeys or DKIM signatures submitted to a mailing list will be removed unless "Misc-Options= KEEP_DKIM_SIGNATURE" is set in the list configuration. This is necessary because these signatures almost never match after the message has been processed. The worst thing that could possibly happen to your deliverability is a DomainKeys signature that does not match and causes the message to be flagged as suspicious.
The KEEP_DKIM_SIGNATURE option is experimental and not meant for general use. As DomainKeys is specified today, signatures DO NOT survive posting to mailing lists (LISTSERV or otherwise), so LISTSERV removes them by default to avoid triggering alerts for subscribers on systems that have implemented the client side of DomainKeys. The DKIM specification may be more robust in this respect, but even DKIM signatures will probably not survive when posted through a mailing list. Use the KEEP_DKIM_SIGNATURE option at your own risk.
If desired, either or both options can be specified for all lists via the DEFAULT_MISC_OPTIONS= site configuration variable.
13.5.2 In DISTRIBUTE jobs
A new DKIM=NO|YES option has been added to DISTRIBUTE (default: NO). This will fail if running a LISTSERV version without DomainKeys support, but otherwise it always succeeds. Messages originating from domains for which LISTSERV has been configured to sign will be signed, while those originating from other domains won't be.
13.5.3 Signing Other Types of Messages
Once you have become comfortable with DomainKeys signatures, you may want to have LISTSERV sign every message that it generates, regardless of its source. Setting DKIM_SIGN_ALL=1 in the site configuration file tells LISTSERV to try to sign every message for which it has a suitable private key, as defined in the DKIM_SIGN configuration parameter. For example:
export DKIM_SIGN_ALL
13.5.4 Restrictions and Implementation Choices
LISTSERV will not sign messages that already have a DomainKeys signature. Double DomainKeys signatures are disallowed in most cases and, even when allowed, there is a risk that they may not be handled correctly by all implementations. This does not apply if the incoming DomainKeys signature has been discarded (for example, a mailing list without "Misc-Options= KEEP_DKIM_SIGNATURE"). In that case, the message can be signed without risk of false positive.
DomainKeys can be used to sign mail-merge messages; however, in this case, LISTSERV's Embedded Mail Merge (EMM) feature MUST be enabled (even if you are using LSMTP). Using EMM is the only way to guarantee that the signing engine will see the exact text being sent to the recipient, and that the signature will match.
Note: In LISTSERV 14.5 and following, Embedded Mail Merge is enabled by default, so unless it has been explicitly disabled (that is, with EMBEDDED_MAIL_MERGE=0 in the site configuration file), this will not be an issue for most sites.
 
 
 

L-Soft international, Inc.
1-800-399-5449