Skip to main content

5. Signer Actions

5. Signer Actions​

The following steps are performed in order by Signers.

5.1. Determine Whether the Email Should Be Signed and by Whom​

A Signer can obviously only sign email for domains for which it has a private key and the necessary knowledge of the corresponding public key and selector information. However, there are a number of other reasons beyond the lack of a private key why a Signer could choose not to sign an email.

INFORMATIVE NOTE: A Signer can be implemented as part of any portion of the mail system as deemed appropriate, including an MUA, a SUBMISSION server, or an MTA. Wherever implemented, Signers should beware of signing (and thereby asserting responsibility for) messages that may be problematic. In particular, within a trusted enclave, the signing domain might be derived from the header according to local policy; SUBMISSION servers might only sign messages from users that are properly authenticated and authorized.

INFORMATIVE IMPLEMENTER ADVICE: SUBMISSION servers should not sign Received header fields if the outgoing gateway MTA obfuscates Received header fields, for example, to hide the details of internal topology.

If an email cannot be signed for some reason, it is a local policy decision as to what to do with that email.

5.2. Select a Private Key and Corresponding Selector Information​

This specification does not define the basis by which a Signer should choose which private key and selector information to use. Currently, all selectors are equal as far as this specification is concerned, so the decision should largely be a matter of administrative convenience. Distribution and management of private keys is also outside the scope of this document.

INFORMATIVE OPERATIONS ADVICE: A Signer should not sign with a private key when the selector containing the corresponding public key is expected to be revoked or removed before the Verifier has an opportunity to validate the signature. The Signer should anticipate that Verifiers can choose to defer validation, perhaps until the message is actually read by the final recipient. In particular, when rotating to a new key pair, signing should immediately commence with the new private key, and the old public key should be retained for a reasonable validation interval before being removed from the key server.

5.3. Normalize the Message to Prevent Transport Conversions​

Some messages, particularly those using 8-bit characters, are subject to modification during transit, notably conversion to 7-bit form. Such conversions will break DKIM signatures. In order to minimize the chances of such breakage, Signers SHOULD convert the message to a suitable MIME content-transfer encoding such as quoted-printable or base64 as described in [RFC2045] before signing. Such conversion is outside the scope of DKIM; the actual message SHOULD be converted to 7-bit MIME by an MUA or MSA prior to presentation to the DKIM algorithm.

If the message is submitted to the Signer with any local encoding that will be modified before transmission, that modification to canonical [RFC5322] form MUST be done before signing. In particular, bare CR or LF characters (used by some systems as a local line separator convention) MUST be converted to the SMTP-standard CRLF sequence before the message is signed. Any conversion of this sort SHOULD be applied to the message actually sent to the recipient(s), not just to the version presented to the signing algorithm.

More generally, the Signer MUST sign the message as it is expected to be received by the Verifier rather than in some local or internal form.

5.3.1. Body Length Limits​

A body length count MAY be specified to limit the signature calculation to an initial prefix of the body text, measured in octets. If the body length count is not specified, the entire message body is signed.

INFORMATIVE RATIONALE: This capability is provided because it is very common for mailing lists to add trailers to messages (e.g., instructions on how to get off the list). Until those messages are also signed, the body length count is a useful tool for the Verifier since it can, as a matter of policy, accept messages having valid signatures with extraneous data.

The length actually hashed should be inserted in the "l=" tag of the DKIM-Signature header field. (See Section 3.5.)

The body length count allows the Signer of a message to permit data to be appended to the end of the body of a signed message. The body length count MUST be calculated following the canonicalization algorithm; for example, any whitespace ignored by a canonicalization algorithm is not included as part of the body length count.

A body length count of zero means that the body is completely unsigned.

Signers wishing to ensure that no modification of any sort can occur should specify the "simple" canonicalization algorithm for both header and body and omit the body length count.

See Section 8.2 for further discussion.

5.4. Determine the Header Fields to Sign​

The From header field MUST be signed (that is, included in the "h=" tag of the resulting DKIM-Signature header field). Signers SHOULD NOT sign an existing header field likely to be legitimately modified or removed in transit. In particular, [RFC5321] explicitly permits modification or removal of the Return-Path header field in transit. Signers MAY include any other header fields present at the time of signing at the discretion of the Signer.

INFORMATIVE OPERATIONS NOTE: The choice of which header fields to sign is non-obvious. One strategy is to sign all existing, non-repeatable header fields. An alternative strategy is to sign only header fields that are likely to be displayed to or otherwise be likely to affect the processing of the message at the receiver. A third strategy is to sign only "well-known" headers. Note that Verifiers may treat unsigned header fields with extreme skepticism, including refusing to display them to the end user or even ignoring the signature if it does not cover certain header fields. For this reason, signing fields present in the message such as Date, Subject, Reply-To, Sender, and all MIME header fields are highly advised.

The DKIM-Signature header field is always implicitly signed and MUST NOT be included in the "h=" tag except to indicate that other preexisting signatures are also signed.

Signers MAY claim to have signed header fields that do not exist (that is, Signers MAY include the header field name in the "h=" tag even if that header field does not exist in the message). When computing the signature, the nonexisting header field MUST be treated as the null string (including the header field name, header field value, all punctuation, and the trailing CRLF).

INFORMATIVE RATIONALE: This allows Signers to explicitly assert the absence of a header field; if that header field is added later, the signature will fail.

INFORMATIVE NOTE: A header field name need only be listed once more than the actual number of that header field in a message at the time of signing in order to prevent any further additions. For example, if there is a single Comments header field at the time of signing, listing Comments twice in the "h=" tag is sufficient to prevent any number of Comments header fields from being appended; it is not necessary (but is legal) to list Comments three or more times in the "h=" tag.

Refer to Section 5.4.2 for a discussion of the procedure to be followed when canonicalizing a header with more than one instance of a particular header field name.

Signers need to be careful of signing header fields that might have additional instances added later in the delivery process, since such header fields might be inserted after the signed instance or otherwise reordered. Trace header fields (such as Received) and Resent-* blocks are the only fields prohibited by [RFC5322] from being reordered. In particular, since DKIM-Signature header fields may be reordered by some intermediate MTAs, signing existing DKIM-Signature header fields is error-prone.

INFORMATIVE ADMONITION: Despite the fact that [RFC5322] does not prohibit the reordering of header fields, reordering of signed header fields with multiple instances by intermediate MTAs will cause DKIM signatures to be broken; such antisocial behavior should be avoided.

INFORMATIVE IMPLEMENTER'S NOTE: Although not required by this specification, all end-user visible header fields should be signed to avoid possible "indirect spamming". For example, if the Subject header field is not signed, a spammer can resend a previously signed mail, replacing the legitimate subject with a one-line spam.

5.4.1. Recommended Signature Content​

The purpose of the DKIM cryptographic algorithm is to affix an identifier to the message in a way that is both robust against normal transit-related changes and resistant to kinds of replay attacks. An essential aspect of satisfying these requirements is choosing what header fields to include in the hash and what fields to exclude.

The basic rule for choosing fields to include is to select those fields that constitute the "core" of the message content. Hence, any replay attack will have to include these in order to have the signature succeed; however, with these included, the core of the message is valid, even if sent on to new recipients.

Common examples of fields with addresses and fields with textual content related to the body are:

  • From (REQUIRED; see Section 5.4)
  • Reply-To
  • Subject
  • Date
  • To, Cc
  • Resent-Date, Resent-From, Resent-To, Resent-Cc
  • In-Reply-To, References
  • List-Id, List-Help, List-Unsubscribe, List-Subscribe, List-Post, List-Owner, List-Archive

If the "l=" signature tag is in use (see Section 3.5), the Content-Type field is also a candidate for being included as it could be replaced in a way that causes completely different content to be rendered to the receiving user.

There are trade-offs in the decision of what constitutes the "core" of the message, which for some fields is a subjective concept. Including fields such as "Message-ID", for example, is useful if one considers a mechanism for being able to distinguish separate instances of the same message to be core content. Similarly, "In-Reply-To" and "References" might be desirable to include if one considers message threading to be a core part of the message.

Another class of fields that may be of interest are those that convey security-related information about the message, such as Authentication-Results [RFC5451].

The basic rule for choosing fields to exclude is to select those fields for which there are multiple fields with the same name and fields that are modified in transit. Examples of these are:

  • Return-Path
  • Received
  • Comments, Keywords

Note that the DKIM-Signature field is also excluded from the header hash because its handling is specified separately.

Typically, it is better to exclude other optional fields because of the potential that additional fields of the same name will be legitimately added or reordered prior to verification. There are likely to be legitimate exceptions to this rule because of the wide variety of application-specific header fields that might be applied to a message, some of which are unlikely to be duplicated, modified, or reordered.

Signers SHOULD choose canonicalization algorithms based on the types of messages they process and their aversion to risk. For example, e-commerce sites sending primarily purchase receipts, which are not expected to be processed by mailing lists or other software likely to modify messages, will generally prefer "simple" canonicalization.

Sites sending primarily person-to-person email will likely prefer to be more resilient to modification during transport by using "relaxed" canonicalization.

Unless mail is processed through intermediaries, such as mailing lists that might add "unsubscribe" instructions to the bottom of the message body, the "l=" tag is likely to convey no additional benefit while providing an avenue for unauthorized addition of text to a message. The use of "l=0" takes this to the extreme, allowing complete alteration of the text of the message without invalidating the signature. Moreover, a Verifier would be within its rights to consider a partly signed message body as unacceptable. Judicious use is advised.

5.4.2. Signatures Involving Multiple Instances of a Field​

Signers choosing to sign an existing header field that occurs more than once in the message (such as Received) MUST sign the physically last instance of that header field in the header block. Signers wishing to sign multiple instances of such a header field MUST include the header field name multiple times in the "h=" tag of the DKIM-Signature header field and MUST sign such header fields in order from the bottom of the header field block to the top. The Signer MAY include more instances of a header field name in "h=" than there are actual corresponding header fields so that the signature will not verify if additional header fields of that name are added.

INFORMATIVE EXAMPLE:

If the Signer wishes to sign two existing Received header fields, and the existing header contains:

Received: <A>
Received: <B>
Received: <C>

then the resulting DKIM-Signature header field should read:

DKIM-Signature: ... h=Received : Received :...

and Received header fields <C> and <B> will be signed in that order.

5.5. Compute the Message Hash and Signature​

The Signer MUST compute the message hash as described in Section 3.7 and then sign it using the selected public-key algorithm. This will result in a DKIM-Signature header field that will include the body hash and a signature of the header hash, where that header includes the DKIM-Signature header field itself.

Entities such as mailing list managers that implement DKIM and that modify the message or a header field (for example, inserting unsubscribe information) before retransmitting the message SHOULD check any existing signature on input and MUST make such modifications before re-signing the message.

5.6. Insert the DKIM-Signature Header Field​

Finally, the Signer MUST insert the DKIM-Signature header field created in the previous step prior to transmitting the email. The DKIM-Signature header field MUST be the same as used to compute the hash as described above, except that the value of the "b=" tag MUST be the appropriately signed hash computed in the previous step, signed using the algorithm specified in the "a=" tag of the DKIM-Signature header field and using the private key corresponding to the selector given in the "s=" tag of the DKIM-Signature header field, as chosen above in Section 5.2.

The DKIM-Signature header field MUST be inserted before any other DKIM-Signature fields in the header block.

INFORMATIVE IMPLEMENTATION NOTE: The easiest way to achieve this is to insert the DKIM-Signature header field at the beginning of the header block. In particular, it may be placed before any existing Received header fields. This is consistent with treating DKIM-Signature as a trace header field.

Last updated on