Setting Up and Using DomainKeys
Overview
Here are the six basic steps
involved in setting up and using DomainKeys. The steps are explained in more
detail in the following sections.
1. Generate a public/private key pair.
2. Publish the public key in DNS (it is published to your domain's _domainkey subdomain TXT record).
3. Copy the private key code you generated and paste it into the Private Key box on the DomainKeys page in ListManager. Add Headers and Selectors on the same page.
4. When you send email, the private key generates a digital signature of the message. (see the description of what digital signatures are on page 3.)
5. The DomainKeys-enabled receiving server extracts the digital signature and claimed From: or Sender: domain from the headers.
6. The receiving server fetches the public key from DNS and checks it against the private key. If it's a match, this proves that the claimed From: or Sender: domain is accurate and the headers and content were not altered. If the signature fails to verify, the email can be dropped, flagged or quarantined.
Details
To perform the following actions for Windows or Linux, you must have OpenSSL installed on your system.
Generating the Private Key -- Windows
In Windows:
1. Open the Command Prompt (Start > Programs > Accessories > Command Prompt).
2. Navigate to the following folder:
C:\Program Files\ListManager\tclweb\bin\certs
3. Type the following:
openssl
genrsa -out rsa.private 512
4. Press ENTER. The private key is generated and saved in a file named "rsa.private" located in the same folder.
NOTE The number "512" in the above command indicates the size of the private key. You can choose one of five sizes: 512, 758, 1024, 1536 or 2048 (these numbers represent bytes). The larger sizes offer greater security, but this is offset by a penalty in CPU performance. We recommend staying with 512.
Generating the Public Key -- Windows
1. At the command prompt, type the following:
openssl
rsa -in rsa.private -out rsa.public -pubout -outform PEM
2. Press ENTER. The public key is saved in a file named rsa.public located in the same folder.
Generating the Private Key -- Linux
1. Open the Terminal.
2. Navigate to the folder with the ListManager directory.
3. Type the following:
openssl genrsa -out rsa.private 512
4. Press ENTER. The private key is generated and saved in a file named "rsa.private" located in the same folder.
Generating the Public Key -- Linux
1. Open the Terminal.
2. Type the following:
openssl
rsa -in rsa.private -out rsa.public -pubout -outform PEM
2. Press ENTER. The public key is saved in a file named rsa.public located in the same folder.
Creating and Publishing the Domain TXT Records
Next, you must create the Domain TXT Records which you will publish to DNS. Use your favorite text editor to create the records described below. You will then copy the text from the editor into whichever program you use to publish to DNS.
Creating the DomainKeys
Policy Record
The first type of record you need to create is called your DomainKeys policy record. The policy record is stored at _domainkey.domainname.com. Here is an example record:
_domainkeyIN TXT "t=y; o=~;
r=postmaster@yourdomain.com"
Here is a list of the possible tags, and their meanings:
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 implementors—the content and frequency of the reports will be defined in a separate document.
t — testing mode ('y' means that this domain is testing DomainKeys so unsigned and unverifiable email should not be treated differently from verified email. Recipient systems may wish to track testing mode results to assist the sender.)
n — Notes that may be of interest to a human. No interpretation is made by any program.
Yahoo's Policy as of this writing is:
;; ANSWER SECTION:
_domainkey.yahoo.com.7200INTXT"t=y\; o=~\;
n=http://antispam.yahoo.com/domainkeys"
Creating the DomainKeys selector
record
You can only set up one DomainKeys policy record
per domain, but you can set up multiple selector records. The selector record
holds your public key. You can set up multiple selectors to be used on
different servers if you like, or you can use one selector for all your
outgoing email. You can also create a selector that only works for one specific
email address. Here is an example selector record:
2006._domainkey.example.com
IN TXT "k=rsa; p=MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANtlhE1vNuUrz NPKjYblYUn0kBLgRzUbnZ9JCJe4w5/ocxIoeewlp328b20S2tETjIa4krj8OJ1lJFT8VhAHLmcCAwEAAQ=="
The selector record consists of the following three sections:
1. Selector: In this example, 2006 is the selector. It must always be followed by a dot, then an underscore, then the word "domainkey," then another dot, and then the domain name.
Example:
2006._domainkey.example.com
2. Record identifier: "IN TXT"is the record identifier, and it is the same for every record.
3. Tag=value pairs: Note that this section is enclosed in quotation marks. There is only one tag=value pair that must be included—the one that lists the public key. However, there are several other tag=value pairs that are optional. The example above contains this optional pair:
k=rsa
RSA is an algorithm for public-key encryption. This tag=value pair is the same for every record. To learn about other tag=value pairs and why you might want to include them, go to:
http://tools.ietf.org/html/rfc4870
and review section 3.2.3.,"Public key Representation in the DNS."
The required tag=value pair, again, is the one that contains the public key:
p=MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANtlhE1vNuUrz
NPKjYblYUn0kBLgRzUbnZ9JCJe4w5/ocxIoeewlp328b20S2tETjIa4krj8OJ1lJFT8VhAHLmcCAwEAAQ==
To insert the public key:
a. Open the file rsa.public that you generated in the section above called "Generate the Public Key."
b. Copy the string of characters starting with the first character after "-----BEGIN PUBLIC KEY-----" and ending with the last character before "-----END PUBLIC KEY-----."
c. Type p=and then paste the string.
d. Type the closing quotation mark for the tag=value pair section. You may want to double-check to ensure that there is an opening quotation mark before the first tag=value pair (see placement of the quotation marks in the the example at the beginning of this section).
More About Selectors
The selector is an arbitrary name you create when you publish your public key to DNS. It can be any string that is considered legal in the DNS namespace and email headers; it must not contain a semicolon. When you generate a new public/private key combination, you must choose a new selector. It is a good idea to do this periodically for increased security.
You can have more than one selector active in DNS at one time. Why would you want to do this? Here's one example: let's say it's December 2006; you have a Domain TXT record (public key) published to DNS with a "2006" selector, and your outgoing email is being signed with a 2006 selector (private key). The public/private key combination is matching, and your recipients are getting their mail verified.
The new year rolls around, and you decide you want to change the public/private key pair to "2007" for security reasons. There will probably be a period during which mail that was sent in 2006 is being opened in 2007. If you only have a "2007" TXT Record in DNS, that email will fail verification. You can leave the "2006" TXT Record in DNS for a transition period, and remove it when you feel confident that all 2006 email has been opened.
Publishing the Domain TXT Record to DNS
Publishing to DNS -- Windows
1. Run Windows DNS.
2. Expand the folder for the domain you want to add DomainKeys to.
3. Right-click the folder, and then select Other New Records.
4. In the Resource Record Type dialog, select TXT.
5. Click Create Record.
6. In the Record Name field, type the selector followed by a dot, and then _domainkey. Example:
2006._domainkey
7. In the Text field, paste the full set of tag/value pairs without quotation marks. Example:
k=rsa;
p=MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBANtlhE1vNuUrz
NPKjYblYUn0kBLgRzUbnZ9JCJe4w5/ocxIoeewlp328b20S2tETjIa4krj8OJ1lJFT8VhAHLmcCAwEAAQ==
8. Click OK.
Publishing to DNS -- Linux
1. Open the zone file in the editor of your choice.
2. Paste your full public key into the zone file.
NOTES
· You can paste the public key anywhere in the zone file.
· The public key cannot have any line breaks. Make sure it is one continuous string of text.
Learn more about DomainKey Distribution Options.
Setting up DomainKeys in ListManager
DomainKeys is set up in ListManager at both the Site and List level. The Selector and Private Key must be populated at the Site level for any DomainKeys activity to take place. If these fields are not populated, the List level setting for DomainKeys will be disabled. If the List level settings for DomainKeys are set and then disabled, the List will continue to attempt to use DomainKeys signing even with invalid or missing Selectors or Private Keys.
All Lists default to "Use the site setting for this list" for their DomainKeys setting. This means that as soon as the Site level DomainKeys settings are in place, every list under that Site will begin to use DomainKeys signing if the Site "DomainKey Signatures" is set to Yes. If it is set to No, none of the Lists will use DomainKeys signing until their DomainKeys setting is changed.
Choosing Site Level Settings
1. Open ListManager.
2. In the left Navigation bar, go to Utilities : Administration : Sites.
3. Under Site Name, click the site you want.
4. Click the DomainKeys tab.
5. Next to DomainKey Signatures, choose Yes or No.
-- If set to Yes, every List within that Site will start to use DomainKeys signing immediately since the default is to use the Site Setting for this field. Each List can be changed to use this setting in the Site or ignore it using the List Settings below.
-- If set to No, every List within that Site will have to independently turn on DomainKeys using the List Settings below.
6. In the Headers box, type the header(s) you want (if any). If you type two or more, separate them with colons. To learn more, see the section "Using the Header Field" below.
7. In the Selector box, enter the selector you used when you created the Domain TXT Record.
8. In the Private Key box, insert the private key you generated earlier:
a. Open the file rsa.private that you generated in the section above called "Generating the Private Key."
b. Copy the full string of characters found in the file.
c. Paste the string into the Private Key box in ListManager.
9. Click Save.
You can enable DomainKeys at the list level, and specify whether this setting acts in conjunction with the site level setting or independent of it.
1. In the left Navigation bar, go to Utilities : List Settings: Basic Information.
2. Click the Enable Features tab.
3. Next to Enable DomainKey signatures, there is a box with a down arrow. Click the arrow to view the availableoptions:
Use the site setting for this list:
Uses DomainKeys, or not, depending on the "yes" or "no" setting you chose in the Utilities > Adminstration > Sites > New/Edit Site > DomainKeys tab (i.e., the site level setting).
Use the site setting for this list, but do not add Sender Header if signing (9.3a only): Uses the settings you chose in the DomainKeys tab, but does not include a Sender heading regardless of site/domain matching (see the note below).
Yes, enable for this list: Uses DomainKeys regardless of the the "yes" or "no" setting you chose in the Utilities > Adminstration > Sites > New/Edit Site > DomainKeys tab (i.e., the site level setting).
Yes, enable for this list, but do not add Sender Header if signing (9.3a only): Uses DomainKeys regardless of the the "yes" or "no" setting you chose in the Utilities > Adminstration > Sites > New/Edit Site > DomainKeys tab. Does not include a Sender heading regardless of site/domain matching (see the note below).
No, disable for this list : Does not use DomainKeys regardless of the "yes" or "no" setting you chose in the Utilities > Adminstration > Sites > New/Edit Site > DomainKeys tab.
NOTE re Site/Domain Matching: If the ListManager site name and the From domain match, ListManager includes the From header but not the Sender header in the digital signature. If the ListManager site name and the From domain are different, the Sender header is included.
4. Click Save.
Using the Header Field
The Header field lets you assign specific headers to be included in the digital signature. Why would you want to do this? There is evidence to suggest that some mail servers and relay systems modify email in transit. If this occurs, it is possible that the email could fail verification. When you include headers in the Header field, they cannot be altered. This provides an extra level of security.
However, the risk of alteration is low and we recommend that you keep things simple by leaving this field blank. When you do, ListManager automatically includes a single header: the Senderheader, if present; otherwise, the From header. This approach seems to work fine for most of our users. Some users choose to include crucial pieces of information that their systems rely on for further processing, such as the Message-ID or a marketing campaign ID code. When you assign headers, ListManager still automatically includes the Sender or From header.
The contents of the Headerfield in a received email can be seen in the DomainKey-Signature header as the "h" tag/value pair. In the example below, this is displayed as:
h=Date:Message-ID:From:To:Subject:MIME-Version:Reply-To:Content-type;
