Tech-invite3GPPspaceIETF RFCsSIP
in Index   Prev   Next

RFC 4871

DomainKeys Identified Mail (DKIM) Signatures

Pages: 71
Obsoletes:  4870
Obsoleted by:  6376
Updated by:  5672
Part 2 of 4 – Pages 8 to 31
First   Prev   Next

ToP   noToC   RFC4871 - Page 8   prevText

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 the individual user.
ToP   noToC   RFC4871 - Page 9
   Selectors are needed to support some important use cases.  For

   o  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.

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

   o  "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.


      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 may 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
ToP   noToC   RFC4871 - Page 10
      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 make the
   decision as to whether to associate this selector directly with the
   user name, 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 versus 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.6). 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 UTF8-encoded text in tag=value lists.
ToP   noToC   RFC4871 - Page 11
   Formally, the syntax rules are as follows:

        tag-list  =  tag-spec 0*( ";" tag-spec ) [ ";" ]
        tag-spec  =  [FWS] tag-name [FWS] "=" [FWS] tag-value [FWS]
        tag-name  =  ALPHA 0*ALNUMPUNC
        tag-value =  [ tval 0*( 1*(WSP / FWS) tval ) ]
                          ; WSP and FWS prohibited 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.  For
   example, "g=" does not mean "g=*", even though "g=*" is the default
   for that tag.

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. The rsa-sha256 algorithm is the default if no algorithm is specified. Verifiers MUST implement both rsa-sha1 and rsa-sha256. Signers MUST implement and SHOULD sign using rsa-sha256.
ToP   noToC   RFC4871 - Page 12
      INFORMATIVE NOTE: Although sha256 is strongly encouraged, some
      senders of low-security messages (such as routine newsletters) may
      prefer to use sha1 because of reduced CPU requirements to compute
      a sha1 hash.  In general, sha256 should always be used whenever

3.3.1. The rsa-sha1 Signing Algorithm

The rsa-sha1 Signing Algorithm computes a message hash as described in Section 3.7 below using SHA-1 [FIPS.180-2.2002] 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.2. The rsa-sha256 Signing Algorithm

The rsa-sha256 Signing Algorithm computes a message hash as described in Section 3.7 below using SHA-256 [FIPS.180-2.2002] 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.

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: o The practical constraint that large (e.g., 4096 bit) keys may not fit within a 512-byte DNS UDP response packet o The security constraint that keys smaller than 1024 bits are subject to off-line attacks o Larger keys impose higher CPU costs to verify and sign email
ToP   noToC   RFC4871 - Page 13
   o  Keys can be replaced on a regular basis, thus their lifetime can
      be relatively short

   o  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

Empirical evidence demonstrates that some mail servers and relay systems modify email in transit, potentially invalidating a signature. There are two competing perspectives on such modifications. For most signers, mild modification of email is immaterial to the authentication status of the email. 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 [RFC2822], 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
ToP   noToC   RFC4871 - Page 14
   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: o Convert all header field names (not the header field values) to lowercase. For example, convert "SUBJect: AbC" to "subject: AbC". o Unfold all header field continuation lines as described in [RFC2822]; 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. o 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. o Delete all WSP characters at the end of each unfolded header field value. o 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
ToP   noToC   RFC4871 - Page 15
   other changes to the message body.  In more formal terms, the
   "simple" body canonicalization algorithm converts "0*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.

3.4.4. The "relaxed" Body Canonicalization Algorithm

The "relaxed" body canonicalization algorithm: o Ignores all whitespace at the end of lines. Implementations MUST NOT remove the CRLF at the end of the line. o Reduces all sequences of WSP within a line to a single SP character. o Ignores all empty lines at the end of the message body. "Empty line" is defined in Section 3.4.3. INFORMATIVE NOTE: It should be noted that the relaxed body canonicalization algorithm may enable certain types of extremely crude "ASCII Art" attacks where a message may be conveyed by adjusting the spacing between words. If this is a concern, the "simple" body canonicalization algorithm should be used instead.

3.4.5. 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 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 may as a matter of policy accept messages having valid signatures with extraneous data. INFORMATIVE IMPLEMENTATION NOTE: Using body length limits enables an attack in which an attacker modifies a message to include content that solely benefits the attacker. It is possible for the appended content to completely replace the original content in the end recipient's eyes and to defeat duplicate message detection algorithms. To avoid this attack, signers should be wary of using
ToP   noToC   RFC4871 - Page 16
      this tag, and verifiers might wish to ignore the tag or remove
      text that appears after the specified content length, perhaps
      based on other criteria.

   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.  Signers
   of MIME messages that include a body length count SHOULD be sure that
   the length extends to the closing MIME boundary string.

      INFORMATIVE IMPLEMENTATION NOTE: A signer wishing to ensure that
      the only acceptable modifications are to add to the MIME postlude
      would use a body length count encompassing the entire final MIME
      boundary string, including the final "--CRLF".  A signer wishing
      to allow additional MIME parts but not modification of existing
      parts would use a body length count extending through the final
      MIME boundary string, omitting the final "--CRLF".  Note that this
      only works for some MIME types, e.g., multipart/mixed but not

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

   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.

3.4.6. 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>
ToP   noToC   RFC4871 - Page 17
   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

       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

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

   and a body reading:

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

3.5. The DKIM-Signature Header Field

The signature of the email is stored in the DKIM-Signature header field. This header field contains all of the signature and key- fetching data. The DKIM-Signature value is a tag-list as described in Section 3.2. The DKIM-Signature header field SHOULD be treated as though it were a trace header field as defined in Section 3.6 of [RFC2822], and hence SHOULD NOT be reordered and SHOULD be prepended to the message.
ToP   noToC   RFC4871 - Page 18
   The DKIM-Signature header field being created or verified is always
   included in the signature calculation, after the rest of the header
   fields being signed; however, when calculating or verifying the
   signature, the value of the "b=" tag (signature value) of that DKIM-
   Signature header field MUST be treated as though it were an empty
   string.  Unknown tags in the DKIM-Signature header field MUST be
   included in the signature calculation but MUST be otherwise ignored
   by verifiers.  Other DKIM-Signature header fields that are included
   in the signature should be treated as normal header fields; in
   particular, the "b=" tag is not treated specially.

   The encodings for each field type are listed below.  Tags described
   as qp-section are encoded as described in Section 6.7 of MIME Part
   One [RFC2045], with the additional conversion of semicolon characters
   to "=3B"; intuitively, this is one line of quoted-printable encoded
   text.  The dkim-quoted-printable syntax is defined in Section 2.6.

   Tags on the DKIM-Signature header field along with their type and
   requirement status are shown below.  Unrecognized tags MUST be

   v=  Version (MUST be included).  This tag defines the version of this
       specification that applies to the signature record.  It MUST have
       the value "1".  Note that verifiers must do a string comparison
       on this value; for example, "1" is not the same as "1.0".


       sig-v-tag   = %x76 [FWS] "=" [FWS] "1"

           INFORMATIVE NOTE: DKIM-Signature version numbers are expected
           to increase arithmetically as new versions of this
           specification are released.

   a=  The algorithm used to generate the signature (plain-text;
       REQUIRED).  Verifiers MUST support "rsa-sha1" and "rsa-sha256";
       signers SHOULD sign using "rsa-sha256".  See Section 3.3 for a
       description of algorithms.


       sig-a-tag       = %x61 [FWS] "=" [FWS] sig-a-tag-alg
       sig-a-tag-alg   = sig-a-tag-k "-" sig-a-tag-h
       sig-a-tag-k     = "rsa" / x-sig-a-tag-k
       sig-a-tag-h     = "sha1" / "sha256" / x-sig-a-tag-h
       x-sig-a-tag-k   = ALPHA *(ALPHA / DIGIT)   ; for later extension
       x-sig-a-tag-h   = ALPHA *(ALPHA / DIGIT)   ; for later extension
ToP   noToC   RFC4871 - Page 19
   b=  The signature data (base64; REQUIRED).  Whitespace is ignored in
       this value and MUST be ignored when reassembling the original
       signature.  In particular, the signing process can safely insert
       FWS in this value in arbitrary places to conform to line-length
       limits.  See Signer Actions (Section 5) for how the signature is


       sig-b-tag       = %x62 [FWS] "=" [FWS] sig-b-tag-data
       sig-b-tag-data  = base64string

   bh= The hash of the canonicalized body part of the message as limited
       by the "l=" tag (base64; REQUIRED).  Whitespace is ignored in
       this value and MUST be ignored when reassembling the original
       signature.  In particular, the signing process can safely insert
       FWS in this value in arbitrary places to conform to line-length
       limits.  See Section 3.7 for how the body hash is computed.


       sig-bh-tag      = %x62 %x68 [FWS] "=" [FWS] sig-bh-tag-data
       sig-bh-tag-data = base64string

   c=  Message canonicalization (plain-text; OPTIONAL, default is
       "simple/simple").  This tag informs the verifier of the type of
       canonicalization used to prepare the message for signing.  It
       consists of two names separated by a "slash" (%d47) character,
       corresponding to the header and body canonicalization algorithms
       respectively.  These algorithms are described in Section 3.4.  If
       only one algorithm is named, that algorithm is used for the
       header and "simple" is used for the body.  For example,
       "c=relaxed" is treated the same as "c=relaxed/simple".


       sig-c-tag       = %x63 [FWS] "=" [FWS] sig-c-tag-alg
                     ["/" sig-c-tag-alg]
       sig-c-tag-alg   = "simple" / "relaxed" / x-sig-c-tag-alg
       x-sig-c-tag-alg = hyphenated-word    ; for later extension

   d=  The domain of the signing entity (plain-text; REQUIRED).  This is
       the domain that will be queried for the public key.  This domain
       MUST be the same as or a parent domain of the "i=" tag (the
       signing identity, as described below), or it MUST meet the
       requirements for parent domain signing described in Section 3.8.
       When presented with a signature that does not meet these
       requirement, verifiers MUST consider the signature invalid.
ToP   noToC   RFC4871 - Page 20
   Internationalized domain names MUST be encoded as described in


       sig-d-tag       = %x64 [FWS] "=" [FWS] domain-name
       domain-name     = sub-domain 1*("." sub-domain)
                ; from RFC 2821 Domain, but excluding address-literal

   h=  Signed header fields (plain-text, but see description; REQUIRED).
       A colon-separated list of header field names that identify the
       header fields presented to the signing algorithm.  The field MUST
       contain the complete list of header fields in the order presented
       to the signing algorithm.  The field MAY contain names of header
       fields that do not exist when signed; nonexistent header fields
       do not contribute to the signature computation (that is, they are
       treated as the null input, including the header field name, the
       separating colon, the header field value, and any CRLF
       terminator).  The field MUST NOT include the DKIM-Signature
       header field that is being created or verified, but may include
       others.  Folding whitespace (FWS) MAY be included on either side
       of the colon separator.  Header field names MUST be compared
       against actual header field names in a case-insensitive manner.
       This list MUST NOT be empty.  See Section 5.4 for a discussion of
       choosing header fields to sign.


       sig-h-tag       = %x68 [FWS] "=" [FWS] hdr-name
                     0*( *FWS ":" *FWS hdr-name )
       hdr-name        = field-name

       INFORMATIVE EXPLANATION: By "signing" header fields that do not
           actually exist, a signer can prevent insertion of those
           header fields before verification.  However, since a signer
           cannot possibly know what header fields might be created in
           the future, and that some MUAs might present header fields
           that are embedded inside a message (e.g., as a message/rfc822
           content type), the security of this solution is not total.

       INFORMATIVE EXPLANATION: The exclusion of the header field name
           and colon as well as the header field value for non-existent
           header fields prevents an attacker from inserting an actual
           header field with a null value.
ToP   noToC   RFC4871 - Page 21
   i=  Identity of the user or agent (e.g., a mailing list manager) on
       behalf of which this message is signed (dkim-quoted-printable;
       OPTIONAL, default is an empty Local-part followed by an "@"
       followed by the domain from the "d=" tag).  The syntax is a
       standard email address where the Local-part MAY be omitted.  The
       domain part of the address MUST be the same as or a subdomain of
       the value of the "d=" tag.

   Internationalized domain names MUST be converted using the steps
       listed in Section 4 of [RFC3490] using the "ToASCII" function.


       sig-i-tag =   %x69 [FWS] "=" [FWS] [ Local-part ] "@" domain-name

       INFORMATIVE NOTE: The Local-part of the "i=" tag is optional
           because in some cases a signer may not be able to establish a
           verified individual identity.  In such cases, the signer may
           wish to assert that although it is willing to go as far as
           signing for the domain, it is unable or unwilling to commit
           to an individual user name within their domain.  It can do so
           by including the domain part but not the Local-part of the

       INFORMATIVE DISCUSSION: This document does not require the value
           of the "i=" tag to match the identity in any message header
           fields.  This is considered to be a verifier policy issue.
           Constraints between the value of the "i=" tag and other
           identities in other header fields seek to apply basic
           authentication into the semantics of trust associated with a
           role such as content author.  Trust is a broad and complex
           topic and trust mechanisms are subject to highly creative
           attacks.  The real-world efficacy of any but the most basic
           bindings between the "i=" value and other identities is not
           well established, nor is its vulnerability to subversion by
           an attacker.  Hence reliance on the use of these options
           should be strictly limited.  In particular, it is not at all
           clear to what extent a typical end-user recipient can rely on
           any assurances that might be made by successful use of the
           "i=" options.

   l=  Body length count (plain-text unsigned decimal integer; OPTIONAL,
       default is entire body).  This tag informs the verifier of the
       number of octets in the body of the email after canonicalization
       included in the cryptographic hash, starting from 0 immediately
       following the CRLF preceding the body.  This value MUST NOT be
       larger than the actual number of octets in the canonicalized
       message body.
ToP   noToC   RFC4871 - Page 22
       INFORMATIVE IMPLEMENTATION WARNING: Use of the "l=" tag might
           allow display of fraudulent content without appropriate
           warning to end users.  The "l=" tag is intended for
           increasing signature robustness when sending to mailing lists
           that both modify their content and do not sign their
           messages.  However, using the "l=" tag enables attacks in
           which an intermediary with malicious intent modifies a
           message to include content that solely benefits the attacker.
           It is possible for the appended content to completely replace
           the original content in the end recipient's eyes and to
           defeat duplicate message detection algorithms.  Examples are
           described in Security Considerations (Section 8).  To avoid
           this attack, signers should be extremely wary of using this
           tag, and verifiers might wish to ignore the tag or remove
           text that appears after the specified content length.

       INFORMATIVE NOTE: The value of the "l=" tag is constrained to 76
           decimal digits.  This constraint is not intended to predict
           the size of future messages or to require implementations to
           use an integer representation large enough to represent the
           maximum possible value, but is intended to remind the
           implementer to check the length of this and all other tags
           during verification and to test for integer overflow when
           decoding the value.  Implementers may need to limit the
           actual value expressed to a value smaller than 10^76, e.g.,
           to allow a message to fit within the available storage space.


   sig-l-tag    = %x6c [FWS] "=" [FWS] 1*76DIGIT

   q=  A colon-separated list of query methods used to retrieve the
       public key (plain-text; OPTIONAL, default is "dns/txt").  Each
       query method is of the form "type[/options]", where the syntax
       and semantics of the options depend on the type and specified
       options.  If there are multiple query mechanisms listed, the
       choice of query mechanism MUST NOT change the interpretation of
       the signature.  Implementations MUST use the recognized query
       mechanisms in the order presented.

   Currently, the only valid value is "dns/txt", which defines the DNS
       TXT record lookup algorithm described elsewhere in this document.
       The only option defined for the "dns" query type is "txt", which
       MUST be included.  Verifiers and signers MUST support "dns/txt".
ToP   noToC   RFC4871 - Page 23

       sig-q-tag        = %x71 [FWS] "=" [FWS] sig-q-tag-method
                      *([FWS] ":" [FWS] sig-q-tag-method)
       sig-q-tag-method = "dns/txt" / x-sig-q-tag-type
                      ["/" x-sig-q-tag-args]
       x-sig-q-tag-type = hyphenated-word  ; for future extension
       x-sig-q-tag-args = qp-hdr-value

   s=  The selector subdividing the namespace for the "d=" (domain) tag
       (plain-text; REQUIRED).


       sig-s-tag    = %x73 [FWS] "=" [FWS] selector

   t=  Signature Timestamp (plain-text unsigned decimal integer;
       RECOMMENDED, default is an unknown creation time).  The time that
       this signature was created.  The format is the number of seconds
       since 00:00:00 on January 1, 1970 in the UTC time zone.  The
       value is expressed as an unsigned integer in decimal ASCII.  This
       value is not constrained to fit into a 31- or 32-bit integer.
       Implementations SHOULD be prepared to handle values up to at
       least 10^12 (until approximately AD 200,000; this fits into 40
       bits).  To avoid denial-of-service attacks, implementations MAY
       consider any value longer than 12 digits to be infinite.  Leap
       seconds are not counted.  Implementations MAY ignore signatures
       that have a timestamp in the future.


       sig-t-tag    = %x74 [FWS] "=" [FWS] 1*12DIGIT

   x=  Signature Expiration (plain-text unsigned decimal integer;
       RECOMMENDED, default is no expiration).  The format is the same
       as in the "t=" tag, represented as an absolute date, not as a
       time delta from the signing timestamp.  The value is expressed as
       an unsigned integer in decimal ASCII, with the same constraints
       on the value in the "t=" tag.  Signatures MAY be considered
       invalid if the verification time at the verifier is past the
       expiration date.  The verification time should be the time that
       the message was first received at the administrative domain of
       the verifier if that time is reliably available; otherwise the
       current time should be used.  The value of the "x=" tag MUST be
       greater than the value of the "t=" tag if both are present.
ToP   noToC   RFC4871 - Page 24
       INFORMATIVE NOTE: The "x=" tag is not intended as an anti-replay


       sig-x-tag    = %x78 [FWS] "=" [FWS] 1*12DIGIT

   z=  Copied header fields (dkim-quoted-printable, but see description;
       OPTIONAL, default is null).  A vertical-bar-separated list of
       selected header fields present when the message was signed,
       including both the field name and value.  It is not required to
       include all header fields present at the time of signing.  This
       field need not contain the same header fields listed in the "h="
       tag.  The header field text itself must encode the vertical bar
       ("|", %x7C) character (i.e., vertical bars in the "z=" text are
       metacharacters, and any actual vertical bar characters in a
       copied header field must be encoded).  Note that all whitespace
       must be encoded, including whitespace between the colon and the
       header field value.  After encoding, FWS MAY be added at
       arbitrary locations in order to avoid excessively long lines;
       such whitespace is NOT part of the value of the header field, and
       MUST be removed before decoding.

   The header fields referenced by the "h=" tag refer to the fields in
       the RFC 2822 header of the message, not to any copied fields in
       the "z=" tag.  Copied header field values are for diagnostic use.

   Header fields with characters requiring conversion (perhaps from
       legacy MTAs that are not [RFC2822] compliant) SHOULD be converted
       as described in MIME Part Three [RFC2047].

       sig-z-tag      = %x7A [FWS] "=" [FWS] sig-z-tag-copy
                    *( [FWS] "|" sig-z-tag-copy )
   sig-z-tag-copy = hdr-name ":" qp-hdr-value
   qp-hdr-value   = dkim-quoted-printable    ; with "|" encoded

      INFORMATIVE EXAMPLE of a signature header field spread across
      multiple continuation lines:
ToP   noToC   RFC4871 - Page 25
   DKIM-Signature: a=rsa-sha256;; s=brisbane;
      c=simple; q=dns/txt;;
      t=1117574938; x=1118006938;

3.6. Key Management and Representation

Signature applications require some level of assurance that the verification public key is associated with the claimed signer. Many applications achieve this by using public key certificates issued by a trusted third party. However, DKIM can achieve a sufficient level of security, with significantly enhanced scalability, by simply having the verifier query the purported signer's DNS entry (or some security-equivalent) in order to retrieve the public key. DKIM keys can potentially be stored in multiple types of key servers and in multiple formats. The storage and format of keys are irrelevant to the remainder of the DKIM algorithm. Parameters to the key lookup algorithm are the type of the lookup (the "q=" tag), the domain of the signer (the "d=" tag of the DKIM- Signature header field), and the selector (the "s=" tag). public_key = dkim_find_key(q_val, d_val, s_val) This document defines a single binding, using DNS TXT records to distribute the keys. Other bindings may be defined in the future.

3.6.1. Textual Representation

It is expected that many key servers will choose to present the keys in an otherwise unstructured text format (for example, an XML form would not be considered to be unstructured text for this purpose). The following definition MUST be used for any DKIM key represented in an otherwise unstructured textual form. The overall syntax is a tag-list as described in Section 3.2. The current valid tags are described below. Other tags MAY be present and MUST be ignored by any implementation that does not understand them.
ToP   noToC   RFC4871 - Page 26
   v=  Version of the DKIM key record (plain-text; RECOMMENDED, default
       is "DKIM1").  If specified, this tag MUST be set to "DKIM1"
       (without the quotes).  This tag MUST be the first tag in the
       record.  Records beginning with a "v=" tag with any other value
       MUST be discarded.  Note that verifiers must do a string
       comparison on this value; for example, "DKIM1" is not the same as


       key-v-tag    = %x76 [FWS] "=" [FWS] "DKIM1"

   g=  Granularity of the key (plain-text; OPTIONAL, default is "*").
       This value MUST match the Local-part of the "i=" tag of the DKIM-
       Signature header field (or its default value of the empty string
       if "i=" is not specified), with a single, optional "*" character
       matching a sequence of zero or more arbitrary characters
       ("wildcarding").  An email with a signing address that does not
       match the value of this tag constitutes a failed verification.
       The intent of this tag is to constrain which signing address can
       legitimately use this selector, for example, when delegating a
       key to a third party that should only be used for special
       purposes.  Wildcarding allows matching for addresses such as
       "user+*" or "*-offer".  An empty "g=" value never matches any


       key-g-tag       = %x67 [FWS] "=" [FWS] key-g-tag-lpart
       key-g-tag-lpart = [dot-atom-text] ["*" [dot-atom-text] ]

   h=  Acceptable hash algorithms (plain-text; OPTIONAL, defaults to
       allowing all algorithms).  A colon-separated list of hash
       algorithms that might be used.  Signers and Verifiers MUST
       support the "sha256" hash algorithm.  Verifiers MUST also support
       the "sha1" hash algorithm.


       key-h-tag       = %x68 [FWS] "=" [FWS] key-h-tag-alg
                     0*( [FWS] ":" [FWS] key-h-tag-alg )
       key-h-tag-alg   = "sha1" / "sha256" / x-key-h-tag-alg
       x-key-h-tag-alg = hyphenated-word   ; for future extension
ToP   noToC   RFC4871 - Page 27
   k=  Key type (plain-text; OPTIONAL, default is "rsa").  Signers and
       verifiers MUST support the "rsa" key type.  The "rsa" key type
       indicates that an ASN.1 DER-encoded [ITU.X660.1997] RSAPublicKey
       [RFC3447] (see Sections 3.1 and A.1.1) is being used in the "p="
       tag.  (Note: the "p=" tag further encodes the value using the
       base64 algorithm.)


       key-k-tag        = %x76 [FWS] "=" [FWS] key-k-tag-type
       key-k-tag-type   = "rsa" / x-key-k-tag-type
       x-key-k-tag-type = hyphenated-word   ; for future extension

   n=  Notes that might be of interest to a human (qp-section; OPTIONAL,
       default is empty).  No interpretation is made by any program.
       This tag should be used sparingly in any key server mechanism
       that has space limitations (notably DNS).  This is intended for
       use by administrators, not end users.


       key-n-tag    = %x6e [FWS] "=" [FWS] qp-section

   p=  Public-key data (base64; REQUIRED).  An empty value means that
       this public key has been revoked.  The syntax and semantics of
       this tag value before being encoded in base64 are defined by the
       "k=" tag.

           INFORMATIVE RATIONALE: If a private key has been compromised
           or otherwise disabled (e.g., an outsourcing contract has been
           terminated), a signer might want to explicitly state that it
           knows about the selector, but all messages using that
           selector should fail verification.  Verifiers should ignore
           any DKIM-Signature header fields with a selector referencing
           a revoked key.


       key-p-tag    = %x70 [FWS] "=" [ [FWS] base64string ]

       INFORMATIVE NOTE: A base64string is permitted to include white
           space (FWS) at arbitrary places; however, any CRLFs must be
           followed by at least one WSP character.  Implementors and
           administrators are cautioned to ensure that selector TXT
           records conform to this specification.
ToP   noToC   RFC4871 - Page 28
   s=  Service Type (plain-text; OPTIONAL; default is "*").  A colon-
       separated list of service types to which this record applies.
       Verifiers for a given service type MUST ignore this record if the
       appropriate type is not listed.  Currently defined service types
       are as follows:

       *   matches all service types

       email   electronic mail (not necessarily limited to SMTP)

       This tag is intended to constrain the use of keys for other
       purposes, should use of DKIM be defined by other services in the


       key-s-tag        = %x73 [FWS] "=" [FWS] key-s-tag-type
                       0*( [FWS] ":" [FWS] key-s-tag-type )
       key-s-tag-type   = "email" / "*" / x-key-s-tag-type
       x-key-s-tag-type = hyphenated-word   ; for future extension

   t=  Flags, represented as a colon-separated list of names (plain-
       text; OPTIONAL, default is no flags set).  The defined flags are
       as follows:

       y   This domain is testing DKIM.  Verifiers MUST NOT treat
           messages from signers in testing mode differently from
           unsigned email, even should the signature fail to verify.
           Verifiers MAY wish to track testing mode results to assist
           the signer.

       s   Any DKIM-Signature header fields using the "i=" tag MUST have
           the same domain value on the right-hand side of the "@" in
           the "i=" tag and the value of the "d=" tag.  That is, the
           "i=" domain MUST NOT be a subdomain of "d=".  Use of this
           flag is RECOMMENDED unless subdomaining is required.


       key-t-tag        = %x74 [FWS] "=" [FWS] key-t-tag-flag
                      0*( [FWS] ":" [FWS] key-t-tag-flag )
       key-t-tag-flag   = "y" / "s" / x-key-t-tag-flag
       x-key-t-tag-flag = hyphenated-word   ; for future extension

   Unrecognized flags MUST be ignored.
ToP   noToC   RFC4871 - Page 29

3.6.2. DNS Binding

A binding using DNS TXT records as a key service is hereby defined. All implementations MUST support this binding. Namespace
All DKIM keys are stored in a subdomain named "_domainkey". Given a DKIM-Signature field with a "d=" tag of "" and an "s=" tag of "", the DNS query will be for "". INFORMATIVE OPERATIONAL NOTE: Wildcard DNS records (e.g., * do not make sense in this context and should not be used. Note also that wildcards within domains (e.g., s._domainkey.* are not supported by the DNS. Resource Record Types for Key Storage
The DNS Resource Record type used is specified by an option to the query-type ("q=") tag. The only option defined in this base specification is "txt", indicating the use of a TXT Resource Record (RR). A later extension of this standard may define another RR type. Strings in a TXT RR MUST be concatenated together before use with no intervening whitespace. TXT RRs MUST be unique for a particular selector name; that is, if there are multiple records in an RRset, the results are undefined. TXT RRs are encoded as described in Section 3.6.1.

3.7. Computing the Message Hashes

Both signing and verifying message signatures start with a step of computing two cryptographic hashes over the message. Signers will choose the parameters of the signature as described in Signer Actions (Section 5); verifiers will use the parameters specified in the DKIM- Signature header field being verified. In the following discussion, the names of the tags in the DKIM-Signature header field that either exists (when verifying) or will be created (when signing) are used. Note that canonicalization (Section 3.4) is only used to prepare the email for signing or verifying; it does not affect the transmitted email in any way. The signer/verifier MUST compute two hashes, one over the body of the message and one over the selected header fields of the message.
ToP   noToC   RFC4871 - Page 30
   Signers MUST compute them in the order shown.  Verifiers MAY compute
   them in any order convenient to the verifier, provided that the
   result is semantically identical to the semantics that would be the
   case had they been computed in this order.

   In hash step 1, the signer/verifier MUST hash the message body,
   canonicalized using the body canonicalization algorithm specified in
   the "c=" tag and then truncated to the length specified in the "l="
   tag.  That hash value is then converted to base64 form and inserted
   into (signers) or compared to (verifiers) the "bh=" tag of the DKIM-
   Signature header field.

   In hash step 2, the signer/verifier MUST pass the following to the
   hash algorithm in the indicated order.

   1.  The header fields specified by the "h=" tag, in the order
       specified in that tag, and canonicalized using the header
       canonicalization algorithm specified in the "c=" tag.  Each
       header field MUST be terminated with a single CRLF.

   2.  The DKIM-Signature header field that exists (verifying) or will
       be inserted (signing) in the message, with the value of the "b="
       tag deleted (i.e., treated as the empty string), canonicalized
       using the header canonicalization algorithm specified in the "c="
       tag, and without a trailing CRLF.

   All tags and their values in the DKIM-Signature header field are
   included in the cryptographic hash with the sole exception of the
   value portion of the "b=" (signature) tag, which MUST be treated as
   the null string.  All tags MUST be included even if they might not be
   understood by the verifier.  The header field MUST be presented to
   the hash algorithm after the body of the message rather than with the
   rest of the header fields and MUST be canonicalized as specified in
   the "c=" (canonicalization) tag.  The DKIM-Signature header field
   MUST NOT be included in its own h= tag, although other DKIM-Signature
   header fields MAY be signed (see Section 4).

   When calculating the hash on messages that will be transmitted using
   base64 or quoted-printable encoding, signers MUST compute the hash
   after the encoding.  Likewise, the verifier MUST incorporate the
   values into the hash before decoding the base64 or quoted-printable
   text.  However, the hash MUST be computed before transport level
   encodings such as SMTP "dot-stuffing" (the modification of lines
   beginning with a "." to avoid confusion with the SMTP end-of-message
   marker, as specified in [RFC2821]).

   With the exception of the canonicalization procedure described in
   Section 3.4, the DKIM signing process treats the body of messages as
ToP   noToC   RFC4871 - Page 31
   simply a string of octets.  DKIM messages MAY be either in plain-text
   or in MIME format; no special treatment is afforded to MIME content.
   Message attachments in MIME format MUST be included in the content
   that is signed.

   More formally, the algorithm for the signature is as follows:
       body-hash = hash-alg(canon_body)
       header-hash = hash-alg(canon_header || DKIM-SIG)
       signature = sig-alg(header-hash, key)

   where "sig-alg" is the signature algorithm specified by the "a=" tag,
   "hash-alg" is the hash algorithm specified by the "a=" tag,
   "canon_header" and "canon_body" are the canonicalized message header
   and body (respectively) as defined in Section 3.4 (excluding the
   DKIM-Signature header field), and "DKIM-SIG" is the canonicalized
   DKIM-Signature header field sans the signature value itself, but with
   "body-hash" included as the "bh=" tag.

      INFORMATIVE IMPLEMENTERS' NOTE: Many digital signature APIs
      provide both hashing and application of the RSA private key using
      a single "sign()" primitive.  When using such an API, the last two
      steps in the algorithm would probably be combined into a single
      call that would perform both the "hash-alg" and the "sig-alg".

3.8. Signing by Parent Domains

In some circumstances, it is desirable for a domain to apply a signature on behalf of any of its subdomains without the need to maintain separate selectors (key records) in each subdomain. By default, private keys corresponding to key records can be used to sign messages for any subdomain of the domain in which they reside; e.g., a key record for the domain can be used to verify messages where the signing identity ("i=" tag of the signature) is, or even In order to limit the capability of such keys when this is not intended, the "s" flag may be set in the "t=" tag of the key record to constrain the validity of the record to exactly the domain of the signing identity. If the referenced key record contains the "s" flag as part of the "t=" tag, the domain of the signing identity ("i=" flag) MUST be the same as that of the d= domain. If this flag is absent, the domain of the signing identity MUST be the same as, or a subdomain of, the d= domain. Key records that are not intended for use with subdomains SHOULD specify the "s" flag in the "t=" tag.

(next page on part 3)

Next Section