The DKIM signature header field is a special header placed into each email message containing information about the sender, the message, and the public key location required for verification. This header field is required by all mailbox providers that use DKIM to verify your identity, including AOL, Gmail, Outlook.com, and Yahoo!.
Here’s an example of a DKIM signature header:
DKIM-Signature: v=1; a=rsa-sha256; d=example.com; s=news;
c=relaxed/relaxed; q=dns/txt; t=1126524832; x=1149015927;
h=from:to:subject:date:keywords:keywords;
bh=MHIzKDU2Nzf3MDEyNzR1Njc5OTAyMjM0MUY3ODlqBLP=;
b=hyjCnOfAKDdLZdKIc9G1q7LoDWlEniSbzc+yuU2zGrtruF00ldcF
VoG4WTHNiYwG
The DKIM signature header is made up of different informational elements that are represented by the use of tag=value pairs. The tag is usually a single letter followed by an equal sign (=). The value of each tag indicates a specific piece of information about the sender, message, and public key location.
There are numerous tags available to a sender; some tags are required and other tags are optional. Missing a required tag in the DKIM signature leads to a verification error with the mailbox provider while missing an optional tag does not.
It’s important to note that tags that are included in the DKIM signature and do not have a value associated with them are treated as having an empty value. However, tags that are not included in the DKIM signature are treated as having the default value.
Required tags
Below are the required tags of a DKIM signature header. Any DKIM signatures missing these tags will encounter an error during the verification process.
- v= indicates the version of the signature specification. The value should always be set to 1.
- a= indicates the algorithm used to generate the signature. The value should be rsa-sha256. Senders with reduced CPU capabilities may use rsa-sha1. However, using rsa-sha1 is discouraged due to potential security risks.
- s= indicates the selector record name used with the domain to locate the public key in DNS. The value is a name or number created by the sender.
- Here is an example of a DNS selector record. The tags shown in this example only appear in this record within DNS and not in the email header itself: <selector(s=)._domainkey.domain(d=)>. TXT v=DKIM1; k=rsa; p=<public key>
- b= is the hash data of the headers listed in the h= tag; this hash is also called the DKIM signature and encoded in Base64.
- bh= is the computed hash of the message body. The value is a string of characters representing the hash determined by the hash algorithm.
- d= indicates the domain used with the selector record (s=) to locate the public key. The value is a domain name owned by the sender.
- h= is a list of headers that will be used in the signing algorithm to create the hash found in the b= tag. The order of the headers in the h= tag is the order in which they were presented during DKIM signing, and therefore is also the order in which they should be presented during verification. The value is a list of header fields that won’t change or be removed.
Optional and recommended tags
Below are the optional tags that we recommend you include in a DKIM signature header. DKIM signatures missing these tags will not encounter an error during verification, but they are recommended as a means to help identify spam.
Spammers don’t normally set time values. Empty or incorrect time values, such as an expiration time dated before the email timestamp, will cause some mailbox providers to reject the message.
- t= is the DKIM signature timestamp. It is meant to indicate the time that message is sent. The format is the number of seconds from 00:00:00 on January 1, 1970 in the UTC time zone.
- x= is the DKIM signature expiration time in the same format as above. The value of the this tag must be greater than the value of the timestamp tag if both are used in the DKIM signature. DKIM signatures may be considered invalid if the verification time at the verifier is past the expiration date, so be sure not to set the expiration date too soon.
Complete testing to make sure these tags are working properly and that the expiration time is not set too soon after deployment.
Optional tags
Below are the optional tags that are not required in the DKIM signature.
- c= is the canonicalization algorithm that defines to a mailbox provider what level of modifications may be present as the email is in transit to the mailbox provider. Modifications can include whitespace or line wrapping. Some email servers make minor modifications to the email during transit which can invalidate the signature.
- Here is the value that defines what level of tolerance the destination server should have when a message has these minor modifications: value1/value2.
Value1 represents the header of the message and value2 represents the body of the message. Value1 and value2 can be labeled as “simple”, which tolerates very little, if any, modification, or “relaxed” which tolerates common modifications.
- i= indicates the identity of the user or agent. The value is an email address containing the domain or subdomain as defined in the d= tag.
Optional and not recommended tags
- l= is the number of characters from the message body that were used to compute the body hash (bh=). If this value isn’t there, then it’s assumed the whole message body was used. We don’t recommend you use this tag because it can be difficult to control and may lead to verification errors.
- z= is a list of the message’s original headers and may differ from the headers listed in the h= tag. This tag may be used by some mailbox providers in the process of diagnosing a verification error. Its value is not well defined.
Unrecognized tags
Any tags not specified in RFC 6376 are not part of the DKIM protocol and should be ignored during the verification process. Not all mailbox providers ignore unrecognized tags, so you might see an error during the verification process.
You can find full information about the DKIM signature on the DKIM website or at RFC 6376.
