DomainKeys is a technology developed by Yahoo! You can find information about DomainKeys at Yahoo! Anti-Spam Resource Center for DomainKeys.
To sign email with DomainKeys you need to create a private key and public key pair. Your private key should be treated as a password, and protected by your file system security. The domain keys specification requires that you use an RSA key for this process.
Java comes with a program called keytool it is located in your java installation bin directory. Run this tool to create a PKCS12 keystore, and generate an RSA key:
keytool -genkey -alias mydomainkey -keyalg rsa -keysize 1024 -validity 1024 -keystore /root/mydomainkey.p12 -storetype PKCS12
You will be prompted for a keystore password, and a private key password.
You may wish to use a different keysize, and a different validity period. The supported key sizes for DomainKeys are 512, 768, 1024, 1536, and 2048. Smaller key sizes will result in faster signing/verifying, and less DNS bandwidth usage, but are also less secure.
The PKCS12 format is a keystore format that can be read by the XMS Server. However you need to extract the public key from this file in PEM format. The java keytool program unfortunately does not provide a mechanism to extract the public key in PEM format. So for this we use openssl.
First we extract the RSA private key from our P12 file:
openssl pkcs12 -in mydomainkey.p12 -out mydomainkey.private.rsa -nocerts
Next we generate the public key from our RSA private key, and output it in PEM format:
openssl rsa -in mydomainkey.private.rsa -out mydomainkey.public.pem -pubout -outform PEM
Your public key is located inside the file mydomainkey.public.pem you can extract the key with a text editor. The keyfile will look something like this:
-----BEGIN PUBLIC KEY----- AIGfMA0GCSqGFIb3DQEBAQUAA4GNAHCBiQKBgQCa1xyzjIpIWBsr5A5Unb1HTVzz gIeb3023eGV9Bgw1IPgmOJdMAzpWDGBU0Q5iR2+oarxgeM5xaQZ6cUFXL7qCPx5w zIglK0jLpbffN8ofrGMra6HrhySFUNfYwseezQc/9fBQZi5Tck7Ic5RJIsdkFGXE lnNdbkC+yIi6QPiUVwIDAQAB -----END PUBLIC KEY-----
DomainKeys requires that you setup some TXT records in your DNS.
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:
_domainkey IN 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.
![[Note]](images/note.png) | Note |
|---|---|
| Testing mode cannot be turned off by the t tag in the policy record - thus policy cannot revert the testing mode setting of a Selector. Selector records are explained below. | |
To retrieve a policy record for a domain you can use the unix dig command:
dig _domainkey.yahoo.com TXT
Yahoo's Policy as of this writing is:
;; ANSWER SECTION: _domainkey.yahoo.com. 7200 IN TXT "t=y\; o=~\; n=http://antispam.yahoo.com/domainkeys"
You can only setup one DomainKeys policy record per domain - but you can setup multiple selector records. The selector record holds your public key. You can setup 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:
myselector._domainkey IN TXT "k=rsa; p=AIGf ... AQAB"
Note that p= section is your public key, you can take your public key file remove the -----BEGIN PUBLIC KEY-----, -----END PUBLIC KEY-----, all whitespace and new lines. If the key ends with an equals sign be sure to include it.
The tag values for selector records are as follows:
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). All Signers and verifiers support the 'rsa' key type.
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 — testing mode ('y' means that 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.
XMS uses a stream filter for creating DomainKey signatures. Your private key is used to create the signatures, and is loaded in with the KeyStore Service. Here is an example setup (in config.xml) for your keystore service:
<service class="xms.security.XMSKeyStoreService"> <keystore name="mykeystore" class="xms.security.PKCS12KeyStore" keystorepassword="pwd" privatekeypassword="pwd" path="/root/domainkey.p12" /> </service>
The DomainKeys Signature Filter can go in any service that is a filter host, but in most cases it would go inside the xms.transport.smtp.SMTPService:
<filter class="xms.filter.domainkeys.DomainKeysSignatureFilter" selector="myselector" domain="mydomain.com" headers="all" canonicalization="nofws" keystore="mykeystore" />
You may want to check out the documentation for the xms.filter.domainkeys.DomainKeysSignatureFilter filter and the xms.security.XMSKeyStoreService service.