This Document is Obsolete and should not be used
Please see the LISTSERV Advanced Topics Manual, Chapter 12, for current DKIM documentation.

L-Soft international, Inc.

Using LISTSERV^® with DomainKeys

LISTSERV^® 14.5

February 2006

Information in this document is subject to change without notice. Companies, names, and data used in examples herein are fictitious unless otherwise noted. L-Soft international, Inc. does not endorse or approve the use of any of the product names or trademarks appearing in this document.

Permission is granted to copy this document, at no charge and in its entirety, provided that the copies are not used for commercial advantage, that the source is cited and that the present copyright notice is included in all copies, so that the recipients of such copies are equally bound to abide by the present conditions. Prior written permission is required for any commercial use of this document, in whole or in part, and for any partial reproduction of the contents of this document exceeding 50 lines of up to 80 characters, or equivalent. The title page, table of contents and index, if any, are not considered part of the document for the purposes of this copyright notice, and can be freely removed if present.

Copyright © 2005-2006, L-Soft international, Inc.

All Rights Reserved Worldwide.

LISTSERV is a registered trademark licensed to L-Soft international, Inc.

L-SOFT is a trademark of L-Soft international.

LSMTP is a registered trademark of L-Soft international, Inc.

UNIX is a registered trademark of X/Open Company Limited.

Microsoft is a registered trademark and Windows 2000, Windows 2003, Windows, Windows NT and Windows XP are trademarks of Microsoft Corporation.

All other trademarks, both marked and not marked, are the property of their respective owners.

Some of L-Soft's manuals for LISTSERV are available in ASCII-text format from LISTSERV and in PDF at ftp.lsoft.com. Many are also available on the World Wide Web at http://www.lsoft.com/manuals/index.html

L-Soft invites feedback on its manuals. Please feel free to send your comments by
e-mail to: MANUALS@LSOFT.COM

Using LISTSERV^® with DomainKeys

Last update: 28 Feb 2006

Contents

Introduction

Creating DomainKeys RSA keys and configuring DNS

LISTSERV Configuration

Starting LISTSERV with DomainKeys support

Using DomainKeys with LISTSERV

Introduction

DomainKeys support requires LISTSERV 14.5.

In order for DomainKeys support to work, we further assume that

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

Creating DomainKeys RSA keys and configuring DNS

The following is an excerpt from the controlling Internet Draft for DomainKeys.

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.

LISTSERV Configuration

LISTSERV's DomainKeys support is configured by doing two things.

1. Supply one or more private keys.

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:

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 the controlling Internet Draft for DomainKeys, 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.

2. Supply a DKIM_SIGN configuration variable.

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.

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.

Using DomainKeys with LISTSERV

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.

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.

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:

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 that in LISTSERV 14.5, 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.

*end of document*