Skip to main content

3. Protocol Elements

Protocol Elements are conceptual parts of the protocol that are not specific to either Signers or Verifiers. The protocol descriptions for Signers and Verifiers are described in later sections ("Signer Actions" (Section 5) and "Verifier Actions" (Section 6)). NOTE: This section must be read in the context of those sections.

3.1. Selectors​

To support multiple concurrent public keys per signing domain, the key namespace is subdivided using "selectors". For example, selectors might indicate the names of office locations (e.g., "sanfrancisco", "coolumbeach", and "reykjavik"), the signing date (e.g., "january2005", "february2005", etc.), or even an individual user.

Selectors are needed to support some important use cases. For example:

  • Domains that want to delegate signing capability for a specific address for a given duration to a partner, such as an advertising provider or other outsourced function.

  • Domains that want to allow frequent travelers to send messages locally without the need to connect with a particular MSA.

  • "Affinity" domains (e.g., college alumni associations) that provide forwarding of incoming mail, but that do not operate a mail submission agent for outgoing mail.

Periods are allowed in selectors and are component separators. When keys are retrieved from the DNS, periods in selectors define DNS label boundaries in a manner similar to the conventional use in domain names. Selector components might be used to combine dates with locations, for example, "march2005.reykjavik". In a DNS implementation, this can be used to allow delegation of a portion of the selector namespace.

ABNF:

selector = sub-domain *( "." sub-domain )

The number of public keys and corresponding selectors for each domain is determined by the domain owner. Many domain owners will be satisfied with just one selector, whereas administratively distributed organizations can choose to manage disparate selectors and key pairs in different regions or on different email servers.

Beyond administrative convenience, selectors make it possible to seamlessly replace public keys on a routine basis. If a domain wishes to change from using a public key associated with selector "january2005" to a public key associated with selector "february2005", it merely makes sure that both public keys are advertised in the public-key repository concurrently for the transition period during which email may be in transit prior to verification. At the start of the transition period, the outbound email servers are configured to sign with the "february2005" private key. At the end of the transition period, the "january2005" public key is removed from the public-key repository.

INFORMATIVE NOTE: A key may also be revoked as described below. The distinction between revoking and removing a key selector record is subtle. When phasing out keys as described above, a signing domain would probably simply remove the key record after the transition period. However, a signing domain could elect to revoke the key (but maintain the key record) for a further period. There is no defined semantic difference between a revoked key and a removed key.

While some domains may wish to make selector values well-known, others will want to take care not to allocate selector names in a way that allows harvesting of data by outside parties. For example, if per-user keys are issued, the domain owner will need to decide whether to associate this selector directly with the name of a registered end user or make it some unassociated random value, such as a fingerprint of the public key.

INFORMATIVE OPERATIONS NOTE: Reusing a selector with a new key (for example, changing the key associated with a user's name) makes it impossible to tell the difference between a message that didn't verify because the key is no longer valid and a message that is actually forged. For this reason, Signers are ill-advised to reuse selectors for new keys. A better strategy is to assign new keys to new selectors.

3.2. Tag=Value Lists​

DKIM uses a simple "tag=value" syntax in several contexts, including in messages and domain signature records.

Values are a series of strings containing either plain text, "base64" text (as defined in [RFC2045, Section 6.8]), "qp-section" (ibid, Section 6.7), or "dkim-quoted-printable" (as defined in Section 2.11). The name of the tag will determine the encoding of each value. Unencoded semicolon (";") characters MUST NOT occur in the tag value, since that separates tag-specs.

INFORMATIVE IMPLEMENTATION NOTE: Although the "plain text" defined below (as "tag-value") only includes 7-bit characters, an implementation that wished to anticipate future standards would be advised not to preclude the use of UTF-8-encoded ([RFC3629]) text in tag=value lists.

Formally, the ABNF syntax rules are as follows:

tag-list  = tag-spec *( ";" tag-spec ) [ ";" ]
tag-spec  = [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
tag-name  = ALPHA *ALNUMPUNC
tag-value = [ tval *( 1*(WSP / FWS) tval ) ]
            ; Prohibits WSP and FWS at beginning and end
tval      = 1*VALCHAR
VALCHAR   = %x21-3A / %x3C-7E
            ; EXCLAMATION to TILDE except SEMICOLON
ALNUMPUNC = ALPHA / DIGIT / "_"

Note that WSP is allowed anywhere around tags. In particular, any WSP after the "=" and any WSP before the terminating ";" is not part of the value; however, WSP inside the value is significant.

Tags MUST be interpreted in a case-sensitive manner. Values MUST be processed as case sensitive unless the specific tag description of semantics specifies case insensitivity.

Tags with duplicate names MUST NOT occur within a single tag-list; if a tag name does occur more than once, the entire tag-list is invalid.

Whitespace within a value MUST be retained unless explicitly excluded by the specific tag description.

Tag=value pairs that represent the default value MAY be included to aid legibility.

Unrecognized tags MUST be ignored.

Tags that have an empty value are not the same as omitted tags. An omitted tag is treated as having the default value; a tag with an empty value explicitly designates the empty string as the value.

3.3. Signing and Verification Algorithms​

DKIM supports multiple digital signature algorithms. Two algorithms are defined by this specification at this time: rsa-sha1 and rsa-sha256. Signers MUST implement and SHOULD sign using rsa-sha256. Verifiers MUST implement both rsa-sha1 and rsa-sha256.

INFORMATIVE NOTE: Although rsa-sha256 is strongly encouraged, some senders might prefer to use rsa-sha1 when balancing security strength against performance, complexity, or other needs. In general, however, rsa-sha256 should always be used whenever possible.

3.3.1. The rsa-sha1 Signing Algorithm​

The rsa-sha1 Signing Algorithm computes a message hash as described in Section 3.7 using SHA-1 [FIPS-180-3-2008] as the hash-alg. That hash is then signed by the Signer using the RSA algorithm (defined in Public-Key Cryptography Standards (PKCS) #1 version 1.5 [RFC3447]) as the crypt-alg and the Signer's private key. The hash MUST NOT be truncated or converted into any form other than the native binary form before being signed. The signing algorithm SHOULD use a public exponent of 65537.

3.3.2. The rsa-sha256 Signing Algorithm​

The rsa-sha256 Signing Algorithm computes a message hash as described in Section 3.7 using SHA-256 [FIPS-180-3-2008] as the hash-alg. That hash is then signed by the Signer using the RSA algorithm (defined in PKCS#1 version 1.5 [RFC3447]) as the crypt-alg and the Signer's private key. The hash MUST NOT be truncated or converted into any form other than the native binary form before being signed. The signing algorithm SHOULD use a public exponent of 65537.

3.3.3. Key Sizes​

Selecting appropriate key sizes is a trade-off between cost, performance, and risk. Since short RSA keys more easily succumb to off-line attacks, Signers MUST use RSA keys of at least 1024 bits for long-lived keys. Verifiers MUST be able to validate signatures with keys ranging from 512 bits to 2048 bits, and they MAY be able to validate signatures with larger keys. Verifier policies may use the length of the signing key as one metric for determining whether a signature is acceptable.

Factors that should influence the key size choice include the following:

  • The practical constraint that large (e.g., 4096-bit) keys might not fit within a 512-byte DNS UDP response packet

  • The security constraint that keys smaller than 1024 bits are subject to off-line attacks

  • Larger keys impose higher CPU costs to verify and sign email

  • Keys can be replaced on a regular basis; thus, their lifetime can be relatively short

  • The security goals of this specification are modest compared to typical goals of other systems that employ digital signatures

See [RFC3766] for further discussion on selecting key sizes.

3.3.4. Other Algorithms​

Other algorithms MAY be defined in the future. Verifiers MUST ignore any signatures using algorithms that they do not implement.

3.4. Canonicalization​

Some mail systems modify email in transit, potentially invalidating a signature. For most Signers, mild modification of email is immaterial to validation of the DKIM domain name's use. For such Signers, a canonicalization algorithm that survives modest in-transit modification is preferred.

Other Signers demand that any modification of the email, however minor, result in a signature verification failure. These Signers prefer a canonicalization algorithm that does not tolerate in-transit modification of the signed email.

Some Signers may be willing to accept modifications to header fields that are within the bounds of email standards such as [RFC5322], but are unwilling to accept any modification to the body of messages.

To satisfy all requirements, two canonicalization algorithms are defined for each of the header and the body: a "simple" algorithm that tolerates almost no modification and a "relaxed" algorithm that tolerates common modifications such as whitespace replacement and header field line rewrapping. A Signer MAY specify either algorithm for header or body when signing an email. If no canonicalization algorithm is specified by the Signer, the "simple" algorithm defaults for both header and body. Verifiers MUST implement both canonicalization algorithms. Note that the header and body may use different canonicalization algorithms. Further canonicalization algorithms MAY be defined in the future; Verifiers MUST ignore any signatures that use unrecognized canonicalization algorithms.

Canonicalization simply prepares the email for presentation to the signing or verification algorithm. It MUST NOT change the transmitted data in any way. Canonicalization of header fields and body are described below.

NOTE: This section assumes that the message is already in "network normal" format (text is ASCII encoded, lines are separated with CRLF characters, etc.). See also Section 5.3 for information about normalizing the message.

3.4.1. The "simple" Header Canonicalization Algorithm​

The "simple" header canonicalization algorithm does not change header fields in any way. Header fields MUST be presented to the signing or verification algorithm exactly as they are in the message being signed or verified. In particular, header field names MUST NOT be case folded and whitespace MUST NOT be changed.

3.4.2. The "relaxed" Header Canonicalization Algorithm​

The "relaxed" header canonicalization algorithm MUST apply the following steps in order:

  • Convert all header field names (not the header field values) to lowercase. For example, convert "SUBJect: AbC" to "subject: AbC".

  • Unfold all header field continuation lines as described in [RFC5322]; in particular, lines with terminators embedded in continued header field values (that is, CRLF sequences followed by WSP) MUST be interpreted without the CRLF. Implementations MUST NOT remove the CRLF at the end of the header field value.

  • Convert all sequences of one or more WSP characters to a single SP character. WSP characters here include those before and after a line folding boundary.

  • Delete all WSP characters at the end of each unfolded header field value.

  • Delete any WSP characters remaining before and after the colon separating the header field name from the header field value. The colon separator MUST be retained.

3.4.3. The "simple" Body Canonicalization Algorithm​

The "simple" body canonicalization algorithm ignores all empty lines at the end of the message body. An empty line is a line of zero length after removal of the line terminator. If there is no body or no trailing CRLF on the message body, a CRLF is added. It makes no other changes to the message body. In more formal terms, the "simple" body canonicalization algorithm converts "*CRLF" at the end of the body to a single "CRLF".

Note that a completely empty or missing body is canonicalized as a single "CRLF"; that is, the canonicalized length will be 2 octets.

The SHA-1 value (in base64) for an empty body (canonicalized to a "CRLF") is:

uoq1oCgLlTqpdDX/iUbLy7J1Wic=

The SHA-256 value is:

frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN/XKdLCPjaYaY=

3.4.4. The "relaxed" Body Canonicalization Algorithm​

The "relaxed" body canonicalization algorithm MUST apply the following steps (a) and (b) in order:

a. Reduce whitespace:

  • Ignore all whitespace at the end of lines. Implementations MUST NOT remove the CRLF at the end of the line.

  • Reduce all sequences of WSP within a line to a single SP character.

b. Ignore all empty lines at the end of the message body. "Empty line" is defined in Section 3.4.3. If the body is non-empty but does not end with a CRLF, a CRLF is added. (For email, this is only possible when using extensions to SMTP or non-SMTP transport mechanisms.)

The SHA-1 value (in base64) for an empty body (canonicalized to a null input) is:

2jmj7l5rSw0yVb/vlWAYkK/YBwk=

The SHA-256 value is:

47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=

3.4.5. Canonicalization Examples (INFORMATIVE)​

In the following examples, actual whitespace is used only for clarity. The actual input and output text is designated using bracketed descriptors: "<SP>" for a space character, "<HTAB>" for a tab character, and "<CRLF>" for a carriage-return/line-feed sequence. For example, "X <SP> Y" and "X<SP>Y" represent the same three characters.

Example 1: A message reading:

A: <SP> X <CRLF>
B <SP> : <SP> Y <HTAB><CRLF>
<HTAB> Z <SP><SP><CRLF>
<CRLF>
<SP> C <SP><CRLF>
D <SP><HTAB><SP> E <CRLF>
<CRLF>
<CRLF>

when canonicalized using relaxed canonicalization for both header and body results in a header reading:

a:X <CRLF>
b:Y <SP> Z <CRLF>

and a body reading:

<SP> C <CRLF>
D <SP> E <CRLF>

Example 2: The same message canonicalized using simple canonicalization for both header and body results in a header reading:

A: <SP> X <CRLF>
B <SP> : <SP> Y <HTAB><CRLF>
<HTAB> Z <SP><SP><CRLF>

and a body reading:

<SP> C <SP><CRLF>
D <SP><HTAB><SP> E <CRLF>

Example 3: When processed using relaxed header canonicalization and simple body canonicalization, the canonicalized version has a header of:

a:X <CRLF>
b:Y <SP> Z <CRLF>

and a body reading:

<SP> C <SP><CRLF>
D <SP><HTAB><SP> E <CRLF>
Last updated on